更新记录

1.0.0（2026-06-30）

新增

• xviewWatermark 回调 API、xviewWatermarkAsync Promise API。
• plain 纯文本块 / card 卡片水印，支持五位置、背景、圆角、旋转、输出格式与质量等参数。
• 卡片扩展：分区背景、标题图片、左侧竖线、长文本换行。
• 平台实现：App Android / iOS / HarmonyOS、Web、微信小程序。
• UTS 类型定义、统一错误码（9020001–9020005）。
• uni-app / uni-app x 示例页（含异步调用示例）。

修复

• Web / H5、微信小程序 UniError 模块加载兼容；小程序圆角绘制兼容。
• App Android 半透明背景色显示。

平台兼容性

uni-app(5.06)

uni-app x(5.06)

其他

xview-watermark

跨平台图片水印 UTS 插件。将本地图片渲染为带文字水印的新图片，适用于现场采集、工程巡检、业务留痕等场景。

提供两种调用方式：

同一调用请二选一，不要混用 success 与 await。

特性

• 一套 API 覆盖 App 原生、Web、微信小程序；uni-app / uni-app x 均可调用。
• plain 纯文本块 / card 卡片水印，五位置、背景、圆角、旋转、输出格式与质量。
• 卡片扩展：标题 / 内容 / 页脚分区、标题图片、左侧竖线、长文本换行。
• 完整 UTS 类型定义与统一错误码（9020001–9020005）。

安装

将 uni_modules/xview-watermark 复制到项目 uni_modules 目录。App 端修改插件后需重新制作自定义基座或云打包。

快速开始

回调方式

import { xviewWatermark } from '@/uni_modules/xview-watermark'

uni.chooseImage({
    count: 1,
    success: (chooseRes) => {
        xviewWatermark({
            sourcePath: chooseRes.tempFilePaths[0],
            position: 'bottomRight',
            lines: [
                { label: '', text: 'xview-watermark', textFontSize: 34, textColor: '#FFFFFF', textStyle: 'bold' },
                { label: '时间', text: '2026-06-30 10:30', labelFontSize: 24, labelColor: '#BAE6FD', textFontSize: 24, textColor: '#E5E7EB' }
            ],
            success: (res) => console.log(res.tempFilePath),
            fail: (err) => console.log(err.errCode, err.errMsg)
        })
    }
})

Promise 方式

import { xviewWatermarkAsync } from '@/uni_modules/xview-watermark'

try {
    const res = await xviewWatermarkAsync({
        sourcePath: imagePath,
        layout: 'card',
        cardWidth: 520,
        lines: [
            { label: '', text: '工程巡检', section: 'header', textFontSize: 34, textColor: '#FFFFFF', textStyle: 'bold' },
            { label: '施工区域', text: 'A 区演示楼', section: 'content', labelFontSize: 24, textColor: '#111827' }
        ]
    })
    console.log(res.tempFilePath)
} catch (err) {
    console.log(err.errCode, err.errMsg)
}

API

xviewWatermark(options: XviewWatermarkOptions): void

回调版。成功走 success，失败走 fail，无论成败均触发 complete。

xviewWatermarkAsync(options: XviewWatermarkAsyncOptions): Promise\<XviewWatermarkResult>

Promise 版。参数与回调版相同，不含 success / fail / complete；失败时 reject，错误对象与 fail 回调一致。

参数说明

主参数

lines 配置

每行必填 label、text（无标签时 label 传 ''）；两者皆空则忽略该行。

排版规则： 换行仅发生在 text 内容列，不会回流到 label 下方。

布局模式

代码示例

完整可运行代码见仓库示例页。下表为场景与关键参数对照：

卡片 + 竖线示例：

xviewWatermark({
    sourcePath: imagePath,
    layout: 'card',
    cardWidth: 520,
    position: 'bottomLeft',
    leftLineWidth: 6,
    leftLineColor: '#22D3EE',
    headerBackgroundColor: '#CC8FB9F0',
    contentBackgroundColor: '#CCEDEBE6',
    lines: [
        { label: '', text: '工程巡检', section: 'header', textFontSize: 34, textColor: '#FFFFFF', textStyle: 'bold' },
        { label: '拍摄时间', text: '2026-06-30 11:56', section: 'content', labelFontSize: 24, textColor: '#E5E7EB' }
    ],
    success: (res) => console.log(res.tempFilePath)
})

返回值

type XviewWatermarkResult = {
    tempFilePath: string  // 输出路径（Web 为 dataURL）
    width: number
    height: number
    size: number          // 字节数
    format: string        // jpg 或 png
}

错误码

fail / catch 接收 XviewWatermarkFail，errSubject 固定为 xview-watermark：

平台差异与注意事项

App

• 修改插件后需重新打包自定义基座。
• Android 读取相册需声明 READ_MEDIA_IMAGES 或 READ_EXTERNAL_STORAGE。
• 错误对象继承 UniError；半透明色请使用 #AARRGGBB 格式。

Web

• 远程图片需满足 CORS；输出为 dataURL，大图注意内存。
• 错误对象实现 XviewWatermarkFail 接口（编译为 JS，无全局 UniError）。

微信小程序

• 依赖 OffscreenCanvas；低版本基础库可能返回 9020001。
• 圆角矩形使用手动路径绘制，兼容开发者工具与真机差异。
• 控制台 webapi_getwxaasyncsecinfo:fail 为开发者工具环境问题，与插件无关。

通用

• 多端共用同一组公开参数；plain / card、分区、竖线、换行等行为保持一致。
• 业务侧从插件根目录 import，勿直接引用 utssdk/ 内部文件。

示例工程

示例覆盖选图预览、位置切换、参数矩阵、卡片样式、异步调用与 uni.previewImage 大图查看。

类型导出

utssdk/interface.uts 导出：

XviewWatermarkOptions · XviewWatermarkAsyncOptions · XviewWatermarkTextLine · XviewWatermarkResult · XviewWatermarkFail · XviewWatermarkPosition · XviewWatermarkFormat · XviewWatermarkLayout · XviewWatermarkTextSection · XviewWatermarkTextStyle · XviewWatermark · XviewWatermarkAsync