更新记录

0.0.1（2026-10-29） 下载此版本

• 初始版本：H5 / 微信·支付宝小程序 / App(Android·iOS) 多端图片水印
• 多水印、九宫格定位、比例/像素单位、旋转、平铺、描边、多行文本
• 体积守卫：自适应 JPEG 质量二分，加水印后体积严格不超原图

平台兼容性

uni-app(4.73)

ant-watermark 自定义图片水印

自定义图片水印插件，一套 API 适配 H5、微信/支付宝小程序、App(Android/iOS)，纯 JS 实现、无需原生插件与额外依赖。

核心承诺：加水印后图片体积不变大。 输出分辨率与原图一致，插件会自动二分搜索 JPEG 质量上限，保证输出体积 ≤ 原图体积。

特性

• 🖼️ 多端统一：H5 / 微信小程序（canvas 2d）/ 支付宝小程序 / App 全覆盖
• 📐 任意位置：九宫格 layoutGravity + 四方向 marginLeft/Right/Top/Bottom 边距
• 🔤 文字样式：字号（像素或宽/高/长边/短边比例）、颜色、描边、加粗、斜体、透明度、字族
• 🌀 旋转与平铺：任意角度 degrees，isRepeat 一键平铺整图
• 📄 多行文本：\n 换行 + lineSpacing 行间距
• ➕ 多水印：一个水印对象数组同时叠加任意多个水印
• 📦 体积守卫：自适应 JPEG 质量二分，输出体积严格不超原图（分辨率不变）

快速上手

<!-- 小程序 / App 端需要：页面中放置画布载体（H5 端不需要，放置也无害） -->
<ant-watermark-canvas />

import { addWatermark } from '@/uni_modules/ant-watermark'

const res = await addWatermark({
    src: '/storage/xxx/photo.jpg',       // 原图：本地路径 / 临时路径 / 网络地址
    watermarks: [{
        text: '@蚂蚁工作室',
        layoutGravity: 5,                  // 右下角
        textSizeMode: 1,                   // 字号按图片宽度比例
        textSize: 0.05,                    // 宽度的 5%
        textColor: '#FFFFFF',
        textStyle: 2,                      // 实心+描边
        strokeWidth: 2,
        marginMode: 1,
        marginRight: 0.04,
        marginBottom: 0.04
    }]
})

// res.tempFilePath  加水印后的图片路径
// res.size          输出体积（字节）
// res.originalSize  原图体积（字节）
// res.sizeGuard     'pass' | 'fallback' | 'none' | 'failed'

也支持回调风格：addWatermark({ ..., success(res) {}, fail(err) {} })。

API

addWatermark(options)

watermarks[i] 水印项

返回值 res

体积为什么不会变大

1. 输出画布分辨率与原图一致（仅在超出 maxCanvasSize 时等比缩小），不放大、不无谓重采样；
2. 导出为 JPEG 时在 [5%, 92%] 质量区间二分搜索，取「体积 ≤ 原图」的最大质量；照片类图片通常一次或两三次即命中；
3. 原图体积通过各端文件系统直接读取（H5 用 fetch/blob），字节级对比，不靠估算。

极端情况（如几 KB 的强压缩小图）最低质量仍略超原图时，返回历史最小结果并标记 sizeGuard: 'failed'。

平台差异说明

示例

完整示例见 pages/index/index.vue（右下角标识 / 斜向平铺 / 多行描边 / 组合水印四种方案）。