更新记录
1.0.1(2026-11-17)
-更新体验地址
1.0.0(2026-11-17)
-水印
平台兼容性
uni-app(4.18)
| Vue2 | Vue3 | Chrome | Safari | app-vue | app-nvue | Android | iOS | 鸿蒙 |
|---|---|---|---|---|---|---|---|---|
| √ | √ | × | × | √ | √ | 7.0 | √ | 4.18 |
| 微信小程序 | 支付宝小程序 | 抖音小程序 | 百度小程序 | 快手小程序 | 京东小程序 | 鸿蒙元服务 | QQ小程序 | 飞书小程序 | 小红书小程序 | 快应用-华为 | 快应用-联盟 |
|---|---|---|---|---|---|---|---|---|---|---|---|
| × | × | × | × | × | × | × | × | - | - | - | - |
uni-app x(4.18)
| Chrome | Safari | Android | iOS | 鸿蒙 | 微信小程序 |
|---|---|---|---|---|---|
| - | - | - | - | - | - |
其他
| 多语言 | 暗黑模式 | 宽屏模式 | 蒸汽模式 |
|---|---|---|---|
| √ | √ | √ | × |
ly028-Watermark
uni-app / uni-app x 三端图片水印 UTS 插件:给本地 / 相册 / 网络图片烧录文字与 Logo,支持多图层叠加、九宫位与坐标定位、斜铺防盗、描边阴影、背景块、日期序号占位符、批量异步与进度取消。支持 Android / iOS / HarmonyOS。
本插件是图片像素水印(对已有图片文件烧录),不是水印相机实时预览组件。选图 / 拍照由你的页面调用
uni.chooseImage等完成。
点击下载体验
扫码体验
平台支持
| 工程类型 | Android | iOS | HarmonyOS |
|---|---|---|---|
| uni-app App | ✅ | ✅ | ✅ |
| uni-app x App | ✅ | ✅ | ✅ |
| 能力 | Android | iOS | HarmonyOS |
|---|---|---|---|
| 文字 / Logo 多图层 | ✅ | ✅ | ✅ |
| 九宫位 + 绝对坐标 | ✅ | ✅ | ✅ |
| 斜铺 / 旋转 / 透明度 | ✅ | ✅ | ✅ |
| 描边 / 阴影 / 背景块 | ✅ | ✅ | ✅ |
| 日期·时间·序号占位符 | ✅ | ✅ | ✅ |
| 批量异步 + 进度 + 取消 | ✅ | ✅ | ✅ |
| 本地路径 / content URI / Base64 / http(s) | ✅ | ✅ | ✅ |
自定义字体 fontPath |
✅ | ✅ | ❌(返回 501) |
| 读取图片信息 | ✅ | ✅ | ✅ |
- 环境:uni-app 建议 HBuilderX 3.7.2+;uni-app x 建议 4.0+(鸿蒙建议 4.31+)
- 调试:UTS 原生插件必须进入 自定义调试基座 或 正式云打包包体;普通标准基座不含本插件原生代码
功能一览
| 功能 | API / 配置 | 说明 |
|---|---|---|
| 批量加水印 | addWatermarkAsync |
多图、多水印层;返回 jobId |
| 取消任务 | cancelWatermark(jobId) |
中途停止 |
| 读图信息 | getImageInfoAsync |
宽高(编码像素)、EXIF 方向 1–8、格式 |
| 文字水印 | type: 'text' |
颜色、字号、描边、阴影、加粗、旋转、透明度 |
| Logo 水印 | type: 'image' |
本地 / Base64 / 网络 Logo,按比例缩放 |
| 九宫位摆放 | layoutGravity 0–8 |
左上~居中九宫 + margin |
| 坐标摆放 | x / y + posMode |
像素或相对宽高占比 |
| 斜铺防盗 | isRepeat + gapX/gapY |
满屏重复文字 |
| 背景块 | bgColor / bgPadding / bgRadius |
半透明底,适合信息栏 |
| 自动换行 | maxWidth + maxWidthMode |
长文案按宽度折行 |
| 占位符 | {date} {time} {index} {filename} |
可配日期/时间格式 |
| 输出格式 | format / quality |
jpeg / png,质量 1–100 |
| Base64 输出 | outputBase64: true |
结果带 data URI(文件仍会写出) |
| 多语言 | setLocale / getLocale |
zh-Hans / en |
| 日志 | setLogEnabled / isLogEnabled |
调试开关 |
你想做什么
| 需求 | 建议配置 |
|---|---|
| 右下角时间戳信息栏 | 一层 text + layoutGravity: 2 + bgColor |
| 满屏斜向「机密」防盗 | 一层 text + isRepeat: true + degrees: -30 + 半透明色 |
| 打卡:斜铺时间 + 左下多行信息 | 斜铺一层 + 信息栏一层(layoutGravity: 3) |
| Logo 贴右上角 | type: 'image' + layoutGravity: 1 |
| 自由拖到任意位置后烧录 | 用 x/y + posMode: 1(相对图宽)写入坐标 |
| 只要看看原图宽高 / 方向 | getImageInfoAsync |
快速开始
1. 安装
在 DCloud 插件市场 搜索 ly028-Watermark,导入到项目 uni_modules 后:
- 在插件详情页 试用/购买 并绑定当前 AppID 工程
manifest.json配置 AppID- 制作自定义调试基座 → 运行到自定义基座(真机)
选图 / 拍照由前端完成;插件默认输出到应用私有目录 _doc/ly028-watermark,一般无需额外存储权限。
2. 最小示例
import {
addWatermarkAsync,
cancelWatermark,
getImageInfoAsync,
setLocale
} from '@/uni_modules/ly028-Watermark'
setLocale('zh-Hans') // 可选,文案语言
uni.chooseImage({
count: 9,
sizeType: ['original'],
success: (res) => {
const jobId = addWatermarkAsync(
{
paths: res.tempFilePaths,
format: 'jpeg',
quality: 92,
watermarks: [
{
type: 'text',
text: '拍摄于 {date} {time} · 第 {index} 张',
textDateFormat: 'yyyy/MM/dd',
textTimeFormat: 'HH:mm:ss',
textColor: '#FFFFFF',
textSize: 0.04,
textSizeMode: 1,
layoutGravity: 2,
margin: 0.04,
marginMode: 1,
bgColor: '#66000000',
bgPadding: 0.4,
bgRadius: 0.3,
maxWidth: 0.5,
maxWidthMode: 1
},
{
type: 'text',
text: 'CONFIDENTIAL',
textColor: '#66FF0000',
textSize: 0.08,
textSizeMode: 1,
degrees: -30,
isRepeat: true,
gapMode: 1,
gapX: 0.35,
gapY: 0.25,
opacity: 0.35
}
]
},
(progressJson) => {
const p = JSON.parse(progressJson)
// p.percent / p.current / p.total / p.phase
console.log(p.percent)
},
(resultJson) => {
const res = JSON.parse(resultJson)
if (res.code !== 0) {
uni.showToast({ title: res.msg || '失败', icon: 'none' })
return
}
const data = typeof res.data === 'string' ? JSON.parse(res.data) : res.data
// data.files[i].outputPath 可直接预览或上传
console.log(data.successCount, data.files)
}
)
// 需要中途停止:cancelWatermark(jobId)
}
})
3. 读取图片信息
getImageInfoAsync(imagePath, (resultJson) => {
const res = JSON.parse(resultJson)
if (res.code === 0) {
const info = typeof res.data === 'string' ? JSON.parse(res.data) : res.data
// info.width / height / orientation(1–8) / format
console.log(info)
}
})
API
| 方法 | 说明 | 返回 |
|---|---|---|
addWatermarkAsync(options, onProgress, onComplete) |
批量加水印 | jobId(number) |
cancelWatermark(jobId) |
取消指定任务 | boolean |
getImageInfoAsync(path, onComplete) |
读取宽高 / EXIF 方向 / 格式 | void |
setLocale(locale) |
zh-Hans / en |
void |
getLocale() |
当前语言 | string |
setLogEnabled(enabled) |
调试日志 | void |
isLogEnabled() |
是否开启日志 | boolean |
进度与完成回调均为 JSON 字符串,请先 JSON.parse。任务在后台执行,回调回到主线程,可直接更新 UI。
addWatermarkAsync 参数
options
| 字段 | 类型 | 默认 | 说明 |
|---|---|---|---|
paths |
string[] |
必填 | 原图列表。支持 _doc/、file://、content://、file://media/、http(s)://、data:image/...;base64, |
watermarks |
WatermarkLayer[] |
必填 | 水印层,按数组顺序叠绘 |
outputDir |
string |
_doc/ly028-watermark |
输出目录 |
format |
jpeg | png |
jpeg |
输出格式 |
quality |
number |
92 |
JPEG 质量 1–100 |
renamePrefix |
string |
wm_ |
输出文件名前缀 |
outputBase64 |
boolean |
false |
true 时结果带 base64 data URI(文件仍写出) |
onProgress(JSON)
| 字段 | 说明 |
|---|---|
percent |
0–100 |
current / total |
已完成 / 总张数 |
path |
当前处理路径(可能为空) |
phase |
如 start / processing / done |
onComplete 信封
{
"code": 0,
"subCode": 0,
"msg": "ok",
"data": "{ ... }"
}
| 字段 | 说明 |
|---|---|
code |
0 成功,非 0 失败 |
subCode |
细分码,见下文 |
msg |
提示(随 setLocale) |
data |
成功时多为 JSON 字符串,需再 JSON.parse |
data 解析后:
| 字段 | 说明 |
|---|---|
files |
每张图的结果数组 |
successCount / failCount |
成功 / 失败数 |
jobId |
任务 ID |
files[] 单项
| 字段 | 说明 |
|---|---|
sourcePath |
原图路径 |
outputPath |
水印后路径(失败可能为空) |
width / height |
输出宽高 |
format |
如 jpeg / png |
costMs |
单张耗时(毫秒) |
success |
是否成功 |
error |
失败说明 |
base64 |
outputBase64=true 时的 data URI |
水印层 WatermarkLayer
通用
| 字段 | 说明 |
|---|---|
type |
'text' 或 'image' |
layoutGravity |
九宫位:0左上 1右上 2右下 3左下 4左中 5上中 6右中 7下中 8居中 |
x / y |
绝对坐标(与 gravity 二选一,坐标优先) |
posMode |
坐标单位,见「尺寸模式」 |
margin / marginLeft… |
边距;marginMode 控制单位 |
degrees |
旋转角度 |
opacity |
0–1,与颜色自带 alpha 相乘 |
尺寸模式(*Mode 字段)
适用于 textSizeMode / sizeMode / marginMode / gapMode / posMode / maxWidthMode:
| 值 | 含义 |
|---|---|
0 |
像素 |
1 |
相对图宽 |
2 |
相对图高 |
3 |
相对长边 |
4 |
相对短边 |
常用:textSize: 0.04 + textSizeMode: 1 表示字号约为图宽的 4%。
文字层
| 字段 | 说明 |
|---|---|
text |
文案;支持 {date} {time} {index} {filename} |
textDateFormat / textTimeFormat |
如 yyyy-MM-dd、HH:mm:ss(token:yyyy yy MM M dd d HH H mm m ss s SSS) |
textColor |
#RGB / #RRGGBB / #AARRGGBB |
textSize + textSizeMode |
字号 |
textStyle |
0 填充 / 1 描边 / 2 先描边后填充 |
strokeWidth / strokeColor |
描边 |
shadowBlur / shadowColor |
阴影 |
fontBold |
加粗 |
fontPath |
本地 ttf/otf(鸿蒙不支持,501) |
lineSpacing |
行距 |
bgColor / bgPadding / bgRadius |
背景块;padding/radius 为字号倍数 |
maxWidth + maxWidthMode |
自动换行宽度 |
isRepeat |
是否平铺 |
gapX / gapY + gapMode |
平铺间距 |
{index} 从 1 开始;Base64 输入时 {filename} 为 base64_<index>。
Logo 层
| 字段 | 说明 |
|---|---|
imagePath |
Logo 路径:本地 / data:image/... / http(s):// |
width / height + sizeMode |
显示尺寸 |
场景示例
右下角信息栏
{
type: 'text',
text: '{date} {time}\n地址:杭州市…',
textColor: '#FFFFFF',
textSize: 0.035,
textSizeMode: 1,
layoutGravity: 2,
margin: 0.04,
marginMode: 1,
bgColor: '#8C000000',
bgPadding: 0.4,
bgRadius: 0.3,
maxWidth: 0.6,
maxWidthMode: 1
}
斜铺防盗
{
type: 'text',
text: '{date} {time}',
textColor: '#66FFFFFF',
textSize: 0.06,
textSizeMode: 1,
degrees: -22,
isRepeat: true,
gapMode: 1,
gapX: 0.4,
gapY: 0.3,
opacity: 0.45
}
Logo + 角标
[
{
type: 'image',
imagePath: logoPath,
width: 0.18,
sizeMode: 1,
layoutGravity: 1,
margin: 0.04,
marginMode: 1,
opacity: 0.9
},
{
type: 'text',
text: 'CONFIDENTIAL',
textColor: '#FFFFFFFF',
textSize: 0.03,
textSizeMode: 1,
layoutGravity: 0,
margin: 0.03,
marginMode: 1
}
]
错误码 subCode
结果形如 { code: 1, subCode, msg }:
| subCode | 含义 |
|---|---|
400 |
参数错误(如未传 paths / 图层序列化失败) |
404 |
文件不存在或无法打开 |
409 |
冲突(如任务状态冲突) |
422 |
无法处理(解码失败、已取消、低版本 HEIC 等) |
500 |
内部错误 |
501 |
当前平台不支持(如鸿蒙自定义字体) |
使用须知
| 项 | 说明 |
|---|---|
| 大图 | 原图长边超过 4096 时会等比降采样后再绘制,输出尺寸可能变小 |
| EXIF | 绘制会按 EXIF 朝向校正;getImageInfoAsync 的宽高为编码像素(未应用朝向) |
| 网络图 | paths / Logo 支持 http(s)://,需设备可访问该地址 |
| 权限 | 插件不额外申请权限;选图/拍照/读相册由你的页面处理 |
| 隐私 | 水印在设备端离线完成,不上传图片 |
常见问题
Q:标准基座里调用没反应?
A:必须使用自定义调试基座或云打包正式包。
Q:和「水印相机」有什么区别?
A:本插件对已有图片文件烧录像素水印;不提供相机实时叠字预览组件。
Q:鸿蒙自定义字体失败?
A:fontPath 在鸿蒙返回 501;请用系统默认字体,或仅在 Android / iOS 传字体路径。
Q:斜铺很密 / 很稀?
A:调节 gapX / gapY 与 gapMode;gapMode: 1 表示相对图宽。
Q:坐标和预览对不齐?
A:posMode: 1 时 x/y 均相对图宽;九宫位请用 layoutGravity + margin。
Q:取消后还会回调吗?
A:可能会收到一次完成回调,带取消相关错误信息。
更新日志
详见同目录 changelog.md。当前版本 1.1.0。
点击下载体验
扫码体验

收藏人数:
购买源码授权版(
试用
使用 HBuilderX 导入示例项目
赞赏(0)
下载 933
赞赏 0
下载 12768972
赞赏 1959
赞赏
京公网安备:11010802035340号