更新记录

1.0.0（2026-06-26）

新版本发布

平台兼容性

uni-app(4.0)

yzj-camera-watermark

uni-app 原生水印相机 UTS 插件，支持在相机预览层显示动态水印，并在拍照完成后把水印写入最终图片。

适合巡检拍照、工单取证、现场打卡、工程留痕、物业记录等需要“所见即所得”水印成图的场景。

功能特性

• 打开 App 原生相机拍照
• 预览层实时显示文字水印
• 支持多行文本水印
• 支持结构化信息面板水印
• 支持自定义位置、颜色、字号、边距、行距
• 支持自定义返回按钮和拍照按钮图标
• 支持返回临时图片路径
• 支持拍照后保存到系统相册

兼容性

• 支持项目：uni-app Vue2、uni-app Vue3
• 支持平台：App-Android、App-iOS
• 不支持：H5、各类小程序、uni-app x
• 最低要求：uni-app 4.0+、HBuilderX 5.0+
• Android 最低系统版本：21（Android 5.0）
• iOS 最低系统版本：12.0
• 调试方式：需要使用 UTS 和自定义基座

平台说明

Android

• 使用自定义原生相机页
• 预览层可直接显示动态水印
• 拍照后会先纠正方向，再按最长边约 1920 输出
• 支持 /static/... 图标路径传入原生层使用
• 适合继续扩展前后摄切换、闪光灯等原生能力

iOS

• 使用 AVCaptureSession + UIViewController 自定义相机页
• 预览层可直接显示动态水印
• 拍照后会继续把水印绘制进最终图片
• 输出图同样按最长边约 1920 控制尺寸
• 已内置相机和相册权限声明

权限说明

• 相机权限：用于拍照
• 相册权限：用于保存图片到系统相册

安装后目录

uni_modules/
└─ yzj-camera-watermark/

导入方式

import { openWatermarkCamera } from '@/uni_modules/yzj-camera-watermark'

API

openWatermarkCamera(options)

打开原生水印相机。

参数类型

type WatermarkPanelItem = {
  label: string
  value: string
}

type WatermarkPanelOptions = {
  title?: string
  items?: WatermarkPanelItem[]
  width?: number
  cornerRadius?: number
  titleColor?: string
  detailColor?: string
  titleFontSize?: number
  detailFontSize?: number
}

type WatermarkCameraUiOptions = {
  backIcon?: string
  captureIcon?: string
}

type OpenWatermarkCameraOptions = {
  watermarkTexts?: string[]
  position: string
  textColor: string
  backgroundColor: string
  fontSize: number
  padding: number
  lineSpacing: number
  saveToAlbum: boolean
  outputFileName: string
  panel?: WatermarkPanelOptions
  ui?: WatermarkCameraUiOptions
  success?: (res: OpenWatermarkCameraResult) => void
  fail?: (res: WatermarkCameraFail) => void
  complete?: (res: any) => void
}

type OpenWatermarkCameraResult = {
  errMsg: string
  tempFilePath: string
  savedUri: string
  base64str: string
  width: number
  height: number
}

常用参数说明

• watermarkTexts：普通文本水印内容，类型为 string[]。数组中的每一项代表一行文字，按传入顺序从上到下显示。适合简单场景，例如“时间 + 地址 + 人员”。如果同时传了 panel，通常优先使用 panel 做结构化展示。
• position：水印显示位置，类型为 string。常用值有 bottomLeft、bottomRight，建议优先把水印放在底部区域，避免遮挡画面主体。如果你的业务拍摄内容主要集中在中下区域，建议改用另一侧位置降低遮挡。
• textColor：文字颜色，类型为 string。支持十六进制颜色值和 rgba(...) 格式，例如 #FFFFFF、rgba(255,255,255,0.92)。如果背景较复杂，建议使用浅色文字搭配半透明深色底。
• backgroundColor：水印背景色，类型为 string。支持纯色和透明色，例如 #000000、rgba(39,47,66,0.82)。推荐使用半透明深色背景，这样在白天、夜间、室内外等场景下都更容易保证文字可读性。
• fontSize：普通文本字号，类型为 number。用于控制 watermarkTexts 模式下的文字大小。常用范围建议在 11 到 16 之间；如果信息较多、行数较多，建议用较小字号，避免大面积遮挡画面。
• padding：水印内边距，类型为 number。控制文字与背景边框之间的留白，值越大，水印块越宽松。常用范围建议在 10 到 18 之间；如果你的内容较短但希望视觉更稳，可以适当调大。
• lineSpacing：多行文本行距，类型为 number。仅对多行文本水印效果明显，用于控制上下两行文字之间的间隔。常用范围建议在 2 到 6 之间；信息密集时建议适当减小，强调展示感时可以适当增大。
• saveToAlbum：是否保存到系统相册，类型为 boolean。传 true 表示拍照后除了返回结果，还会尝试把图片写入系统相册；传 false 则只返回临时文件路径。若业务只做上传或页面预览，通常可以设为 false，减少额外权限干扰。
• outputFileName：导出文件名，类型为 string。用于控制生成图片的文件名，例如 clockin_001.jpg、inspect_20260626.jpg。建议只使用英文、数字、下划线或中划线，并保留图片后缀名，避免因特殊字符影响兼容性。
• panel：结构化面板水印配置，类型为 WatermarkPanelOptions。适合巡检、工单、打卡、取证等字段明确的业务场景。相比 watermarkTexts，panel 更适合展示“标题 + 多条键值对”形式的信息，成图效果也更像业务化模板。
• panel.title：面板标题，类型为 string。一般用于展示业务名称，例如“工程巡检”“现场取证”“到岗打卡”。标题建议简短明确，避免占用过多水印区域。
• panel.items：面板字段列表，类型为 WatermarkPanelItem[]。每一项包含 label 和 value，例如“拍摄时间 / 2026-06-26 09:30:00”。适合传入时间、地点、人员、项目名、任务点位、备注等结构化数据。
• panel.width：面板基础宽度，类型为 number。用于控制整个结构化面板的宽度。数值过大可能在小屏设备上显得拥挤，建议结合你的字段数量和文字长度做测试；如果你追求双端更稳定的视觉比例，建议不要设置得过宽。
• panel.cornerRadius：面板圆角，类型为 number。用于控制背景卡片圆角大小。常用范围建议在 10 到 18 之间，数值适中时会更像业务卡片样式。
• panel.titleColor：面板标题颜色，类型为 string。建议与整体主题保持统一，常见写法是白色或高亮浅色。
• panel.detailColor：面板明细文字颜色，类型为 string。用于 items 中字段内容展示，建议使用比标题稍弱一点的浅色，增强层次感。
• panel.titleFontSize：面板标题字号，类型为 number。通常可以略大于明细字号，建议在 14 到 18 之间。
• panel.detailFontSize：面板明细字号，类型为 number。建议在 11 到 14 之间，保证多字段情况下依然有较好的可读性。
• ui：原生相机页面按钮样式配置，类型为 WatermarkCameraUiOptions。用于替换默认返回按钮和拍照按钮图标，适合做品牌化、业务化界面统一。
• ui.backIcon：返回按钮图标路径，类型为 string。建议传项目 static 目录中的 PNG 资源路径，例如 /static/camera/back.png。图标建议使用透明底、浅色主图形，便于叠加在深色半透明按钮背景上。
• ui.captureIcon：拍照按钮图标路径，类型为 string。建议传项目 static 目录中的 PNG 资源路径，例如 /static/camera/capture.png。如果传了该值，插件会优先使用你的自定义按钮图形，因此建议直接准备接近最终视觉效果的完整图标资源。

返回值说明

openWatermarkCamera 成功回调的返回结构在 Android 和 iOS 上保持一致：

type OpenWatermarkCameraResult = {
  errMsg: string
  tempFilePath: string
  savedUri: string
  base64str: string
  width: number
  height: number
}

字段说明

• errMsg：调用成功时固定为 openWatermarkCamera:ok。
• tempFilePath：最终水印成图的输出路径，可用于页面预览、上传或后续业务处理。字段名统一，但 Android 和 iOS 的路径格式不同，详见下方平台差异说明。
• savedUri：当 saveToAlbum 为 true 且保存成功时，返回系统相册中的资源标识；未保存或保存失败时通常为空字符串。该字段更适合用来判断是否写入相册成功，不建议直接当作普通文件路径处理。
• base64str：最终输出图片的 Base64 字符串。适合少量场景下做即时上传、接口透传或临时预览；如果图片较大，不建议在列表页或高频流程中长期持有该值。
• width：最终输出图片宽度，单位为像素。
• height：最终输出图片高度，单位为像素。

Android 返回值说明

• tempFilePath：返回本地绝对文件路径，通常是 App 可访问的临时输出文件，例如应用沙盒或缓存目录下的 JPG 文件。
• savedUri：如果保存到系统相册成功，返回 content://... 形式的 MediaStore 资源地址；如果未保存，则为空字符串。
• base64str：基于最终输出文件生成的 Base64 字符串。
• width / height：来自最终写入完成后的成图尺寸。Android 端会先纠正方向，再按最长边约 1920 做缩放后输出，因此这里返回的是处理后的最终尺寸，不是相机原始分辨率。

Android 成功返回示例：

{
  errMsg: 'openWatermarkCamera:ok',
  tempFilePath: '/data/user/0/xxx/cache/yzj_camera/watermark_20260626_093000.jpg',
  savedUri: 'content://media/external/images/media/12345',
  base64str: '...base64...',
  width: 1440,
  height: 1920
}

iOS 返回值说明

• tempFilePath：返回 _doc/yzj_camera/xxx.jpg 形式的路径，属于插件写入到应用可访问目录中的成图路径，适合前端直接回显或上传。
• savedUri：如果保存到系统相册成功，返回 ph://... 形式的相册资源标识；如果未保存，则为空字符串。
• base64str：基于最终输出文件生成的 Base64 字符串。
• width / height：来自最终输出图片尺寸。iOS 端同样会在绘制水印前控制最长边约 1920，因此这里也是处理后的最终成图尺寸。

iOS 成功返回示例：

{
  errMsg: 'openWatermarkCamera:ok',
  tempFilePath: '_doc/yzj_camera/watermark_20260626_093000.jpg',
  savedUri: 'ph://A1B2C3D4-1234-5678-9ABC-DEF012345678/L0/001',
  base64str: '...base64...',
  width: 1440,
  height: 1920
}

使用建议

• 如果你的业务只是做页面回显、上传服务器或表单提交，优先使用 tempFilePath。
• 如果你的业务只关心是否保存到系统相册，可以通过判断 savedUri 是否为空来确认结果。
• 不要把 savedUri 当作普通本地文件路径使用，因为 Android 返回的是 content://...，iOS 返回的是 ph://...，两端都属于系统资源标识。
• 如果业务不需要 Base64，建议不要长期缓存 base64str，避免额外占用内存。
• width 和 height 建议用于展示、压缩策略或服务端元数据记录，不要假设它一定等于原始拍照分辨率。

基础用法

import { openWatermarkCamera } from '@/uni_modules/yzj-camera-watermark'

openWatermarkCamera({
  watermarkTexts: ['考勤打卡', '2026-06-26 09:30:00', '城管执法大队中心一楼'],
  position: 'bottomLeft',
  textColor: '#FFFFFF',
  backgroundColor: 'rgba(39,47,66,0.82)',
  fontSize: 12,
  padding: 14,
  lineSpacing: 4,
  saveToAlbum: true,
  outputFileName: `watermark_${Date.now()}.jpg`,
  success(res) {
    console.log('拍照成功', res.tempFilePath, res.width, res.height)
  },
  fail(err) {
    console.log('拍照失败', err.errCode, err.errMsg)
  }
})

面板水印示例

import { openWatermarkCamera } from '@/uni_modules/yzj-camera-watermark'

openWatermarkCamera({
  watermarkTexts: [],
  position: 'bottomLeft',
  textColor: '#FFFFFF',
  backgroundColor: 'rgba(39,47,66,0.82)',
  fontSize: 12,
  padding: 14,
  lineSpacing: 4,
  saveToAlbum: false,
  outputFileName: `inspect_${Date.now()}.jpg`,
  ui: {
    backIcon: '/static/camera/back.png',
    captureIcon: '/static/camera/capture.png'
  },
  panel: {
    title: '外勤打卡',
    width: 220,
    cornerRadius: 14,
    titleColor: '#FFFFFF',
    detailColor: 'rgba(255,255,255,0.94)',
    titleFontSize: 16,
    detailFontSize: 12,
    items: [
      { label: '打卡时间', value: '2026-06-26 09:30:00' },
      { label: '打卡地点', value: '城管执法大队中心一楼' },
      { label: '拍摄人', value: '张三' },
      { label: '经度', value: '129.265456564' },
      { label: '纬度', value: '41.256465465' },
    ]
  },
  success(res) {
    console.log('拍照成功', res.tempFilePath)
  }
})

水印行为说明

• panel.items 数量可动态传入
• panel 为空时，自动使用普通文本水印模式
• panel.items、panel.title、watermarkTexts 都为空时，会回退默认文案
• panel.width 建议优先使用比例感更稳定的值，不要一味设置过大

图标资源建议

• 建议把资源放在项目 static 目录
• 建议优先传入 /static/... 路径
• backIcon 建议使用透明底 PNG
• captureIcon 建议使用接近正方形的透明底 PNG
• 若未传图标，插件会回退到默认按钮样式

推荐目录：

static/
└─ camera/
   ├─ back.png
   └─ capture.png

注意事项

• 插件仅支持 uni-app 的 App 原生运行，不支持 H5 和小程序
• 首次调用时会触发系统权限申请
• 若修改 utssdk/**/*.uts、utssdk/app-android/*.kt、utssdk/app-ios/*.swift，通常需要重新制作自定义基座验证
• Android 和 iOS 输出图片尺寸会按最长边压缩到接近 1920
• 如果你希望双端按钮视觉一致，最稳妥的方式是直接共用同一套 PNG 图标

错误码

• 9011001：当前环境没有可用的 Activity
• 9011002：相机任务正在执行中，请勿重复打开
• 9011003：插件参数解析失败
• 9011004：缺少相机或存储权限
• 9011005：当前平台暂不支持原生相机插件
• 9011006：用户取消拍照
• 9011007：拍照或水印写入失败

适用场景

• 工程巡检拍照
• 物业巡查留痕
• 到岗打卡拍照
• 施工现场取证
• 设备安装验收留档

目录说明

• uni_modules/yzj-camera-watermark/utssdk/interface.uts：插件接口定义
• uni_modules/yzj-camera-watermark/utssdk/unierror.uts：错误码定义
• uni_modules/yzj-camera-watermark/utssdk/app-android/index.uts：Android UTS 桥接层
• uni_modules/yzj-camera-watermark/utssdk/app-android/WatermarkCameraNative.kt：Android 原生实现
• uni_modules/yzj-camera-watermark/utssdk/app-ios/index.uts：iOS UTS 桥接层
• uni_modules/yzj-camera-watermark/utssdk/app-ios/WatermarkCameraNative.swift：iOS 原生实现