更新记录

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 后:

  1. 在插件详情页 试用/购买 并绑定当前 AppID 工程
  2. manifest.json 配置 AppID
  3. 制作自定义调试基座 → 运行到自定义基座(真机)

选图 / 拍照由前端完成;插件默认输出到应用私有目录 _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。


点击下载体验
扫码体验
扫码体验

隐私、权限声明

1. 本插件需要申请的系统权限列表:

选图/拍照由前端触发。默认输出写应用私有文档目录(_doc/ly028-watermark),一般无需额外存储授权。

2. 本插件采集的数据、发送的服务器地址、以及数据用途说明:

插件不采集任何数据。所有图片水印在设备端离线完成,不上传任何媒体数据。

3. 本插件是否包含广告,如包含需详细说明广告表达方式、展示频率:

无