更新记录

1.0.0（2026-10-09）

首个版本。

• 文字水印（watermarkAsync），九宫格位置、平铺模式、不透明度、底条
• 图片水印（watermarkImage），支持自定义水印宽度与平铺
• 文字位图单独渲染（renderTextBitmap），供自定义排版使用
• 平铺时默认 -30 度斜排（可显式覆盖）
• 文字渲染统一在 JS 层用 canvas 完成，三端输出一致
• 三端原生实现：
  • Android —— Canvas.drawBitmap + PorterDuff alpha
  • Harmony —— readPixelsSync 逐像素 source-over 混合
  • iOS —— CIImage.composited + AffineTransform 翻转定位

平台兼容性

uni-app(3.99)

其他

czg-imgwm 图片水印

文字与图片水印，支持九宫格位置、斜排平铺、不透明度与底条。

平台支持

三端行为完全一致。原因是文字渲染统一放在 JS 层（见下）。

为什么文字渲染放在 JS 层

iOS 类型库未暴露 NSString.stringWithString / sizeWithAttributes / drawAtPoint，唯一可用的 showTextAtPoint 签名是 UnsafePointer<CChar>，UTS 里无法安全构造 C 字符串指针。Harmony 的 PixelMap 也没有文字绘制 API。

所以三端统一走：JS 用 createCanvasContext 把文字渲染成透明底 PNG → 原生只做位图合成。好处不只是绕开限制，而是三端输出一致，且排版能力更强（换行、对齐、行高都能在 canvas 层做）。

Android 原生其实能直接 drawText（Canvas.drawText + Paint 都齐），插件故意不用，就是为了保证同一份代码在三个平台看起来一样。

API

watermarkAsync(path, options) —— 推荐

文字水印，异步。

import { watermarkAsync } from '@/uni_modules/czg-imgwm/index.js'

const r = await watermarkAsync('/path/photo.jpg', {
  text: '内部资料 禁止外传',
  fontSize: 36,
  color: '#FFFFFF',
  opacity: 0.4,
  position: 'bottom-right',
  margin: 30,
  rotate: -30,
  tile: 'diagonal',        // 对角密排（防盗图常用）
  bgColor: '#000000',      // 底条（不传则无）
  bgOpacity: 0.35,
  format: 'jpg',
  quality: 90,
  outPath: '/path/out.jpg'
})
// { path: '/path/out.jpg', size: 45678, width: 1920, height: 1080, format: 'jpg', count: 12 }

options

位置：top-left top top-right left center right bottom-left bottom bottom-right

tile 不为 none 且未指定 rotate 时，默认 -30度（斜排）。不斜排的网格水印防盗意义不大。

返回值里的 count 是实际绘制的水印数量，可用来确认平铺生效。

watermark(path, options, markPath)

文字水印，同步版。必须自备 markPath（预渲染的文字位图路径）。

因为文字位图要靠 canvas 异步导出，同步接口无法自己准备。多数情况请直接用 watermarkAsync。

import { renderTextBitmap, watermark } from '@/uni_modules/czg-imgwm/index.js'

const mark = await renderTextBitmap('机密', 36, '#FFF', 'bold', '#000', 0.35, 0)
const r = watermark('/path/photo.jpg', { position: 'center' }, mark.path)

watermarkImage(path, options)

图片水印，同步，三端通用。

const r = watermarkImage('/path/photo.jpg', {
  markPath: '/path/logo.png',
  opacity: 0.4,
  position: 'bottom-right',
  margin: 24,
  rotate: 0,
  width: 160,        // 不传则按底图宽的 25% 等比缩放
  tile: 'none',
  format: 'jpg'
})

renderTextBitmap(text, fontSize, color, fontWeight, bgColor, bgOpacity, rotate)

单独渲染文字位图，返回 { path, width, height }。给需要自定义排版的场景用。

错误处理

抛出的 Error 带 error.code：

隐私

全部处理在本机完成，不联网、不采集、不上传任何图片。

价格

普通授权版由 DCloud 对 uts 源码加密保护，运行时经云端解密编译；源码授权版提供完整 uts 源码，可自行修改与扩展，同样享受后续版本升级。

隐私说明

本插件全部图片处理在本机完成，不联网、不采集、不上传任何图片或数据。插件不主动读取相册与存储目录，输入完全由调用方通过参数传入。隐私声明详见 package.json 的 dcloudext.declaration。

更新日志

见 changelog.md

开源协议

MIT