更新记录

0.1.0(2026-11-20)

  • 定义水印/装饰数据结构(文字、logo、锚点、旋转、描边、底色)
  • Android 实现落地:原生 AAR(native-facade/watermark-camera-facade,Kotlin + CameraX)
    • 全屏相机页:CameraX 预览 + 实时水印覆盖层(所见即所得)
    • 拍照合成:EXIF 摆正 → Canvas 绘制水印 → 写 App 私有目录 → "photo" 回调
    • 前后摄切换、闪光灯(auto/on/off)、720p/1080p
    • 授权:RSA-SHA256 公钥验签(WcLicense),未授权出图叠加试用水印
  • iOS 兼容 功能一致

平台兼容性

uni-app x(5.32)

Chrome Safari Android Android插件版本 iOS iOS插件版本 鸿蒙 鸿蒙插件版本 微信小程序
- - 9.0 1.0.0 12 1.0.0 26 1.0.0 -

其他

多语言 暗黑模式 宽屏模式 蒸汽模式
× × × √

bgyx-utscamera —— 自定义水印相机

调用后打开相机拍照,照片出图即合成水印/装饰;水印内容、位置、样式、旋转全部由调用方配置。

平台:App-Android / App-iOS(iOS 待 Mac 端实现)。 授权:插件市场付费插件模式,无需授权码(license/scope 参数保留但已忽略)。


一、功能范围

第一期(当前目标)

  • 打开全屏原生相机(前后摄、闪光灯、720p/1080p)
  • 实时预览即显示水印效果,所见即所得
  • 拍照后按配置合成到照片,回传出图路径
  • 通用元素树:任意内容皆可叠加,元素类型支持 text(文字)/ logo(图片)/ rect(矩形/色块/描边框)/ line(线条), 每个元素均可配置锚点、偏移、旋转、透明度
  • 文字支持:字号(按照片宽度百分比自适应)、颜色、加粗/斜体、旋转角度、 描边、透明度、底色、内边距
  • 矩形支持:宽高(百分比)、填充色、边框色/宽、圆角、透明度
  • 运行中动态更新:wcSetOverlay(items) 随时刷新,页面 state 变化即可实时驱动预览
  • 位置:九宫格锚点 + 自定义偏移

第二期(后续)

  • 时间、日期、经纬度、地址等动态字段(自动填充)
  • 水印模板(一键套用)
  • 相册选图后再加水印

二、架构

沿用本仓库已验证的 「原生 AAR + UTS 薄壳」 模式(与 screen-rtmp 同构):

业务代码
  └─ import { wcOpenCamera, wcTakePhoto, ... } from "@/uni_modules/bgyx-utscamera"
        │  (UTS 薄壳:整理参数、转发回调)
        ▼
  utssdk/app-android/index.uts
        │  (调用原生)
        ▼
  native-facade/watermark-camera-facade(android.library,AAR)
        ├─ CameraX:Preview + ImageCapture
        ├─ 水印绘制:Canvas 把各元素画到照片 Bitmap(参考 screen-rtmp 的 applyTrialWatermark)
        └─ 出图:写 App 私有目录 → 回调路径

为什么走 AAR:相机预览 + 实时合成涉及 Activity 生命周期与大量原生回调,UTS 直写成本高; 本仓库已有成熟范式(screen-rtmp-facade),复用可显著提速。


三、接口

详见 utssdk/index.uts(双端共享契约,签名不得改动)。

方法 说明
wcOpenCamera(options) 打开全屏相机
wcTakePhoto() 拍照并合成,出图走 "photo" 回调
wcSwitchCamera() 前后摄切换
wcSetFlash(flash) auto / on / off
wcSetWatermarks(items) 运行中动态更新水印(元素树,含 text/logo/rect/line)
wcSetOverlay(items) 同 wcSetWatermarks,语义化别名;供「页面 state 驱动实时刷新」使用
wcClose() 关闭并释放
wcSetResultCallback(cb) 事件回调

事件:ready / photo(data=路径) / error / closed / denied


四、用法示例

import { wcOpenCamera, wcTakePhoto, wcSetOverlay, wcClose, wcSetResultCallback } from "@/uni_modules/bgyx-utscamera"

wcSetResultCallback((event: string, data: string) => {
  if (event == "photo") {
    console.log("出图:", data)   // data 为文件路径
  } else if (event == "error") {
    console.log("出错:", data)
  }
})

wcOpenCamera({
  cameraId: "back",
  flash: "off",
  resolution: "1080p",
  license: "",                    // 授权码;留空 = 试用(出图带水印)
  scope: "bgyx-utscamera", // 受众标识(授权码按此匹配)
  watermarks: [
    {
      type: "rect",              // 半透明背景条
      anchor: "bottomLeft",
      offsetX: 18,
      offsetY: 18,
      angle: 0,
      text: null,
      logo: null,
      rect: {
        width: 44,               // 照片宽度百分比
        height: 9,               // 照片高度百分比
        color: "#66000000",
        borderColor: "",
        borderWidth: 0,
        cornerRadius: 8,
        alpha: 1
      },
      line: null
    },
    {
      type: "text",
      anchor: "bottomLeft",
      offsetX: 24,
      offsetY: 24,
      angle: 0,
      text: {
        text: "2026-11-16 09:30  工地A区",
        fontSize: 4,              // 照片宽度的 4%
        color: "#FFFFFF",
        bold: true,
        italic: false,
        angle: 0,
        strokeColor: "#000000",
        strokeWidth: 2,
        alpha: 1,
        background: "",
        padding: 0
      },
      logo: null,
      rect: null,
      line: null
    },
    {
      type: "text",
      anchor: "center",
      offsetX: 0,
      offsetY: 0,
      angle: 0,
      text: {
        text: "仅供项目部存档",
        fontSize: 8,
        color: "#FFFFFF",
        bold: true,
        italic: false,
        angle: -30,               // 旋转 -30°
        strokeColor: "#000000",
        strokeWidth: 3,
        alpha: 0.5,
        background: "",
        padding: 0
      },
      logo: null,
      rect: null,
      line: null
    }
  ]
})

// 运行中页面 state 变化 → 实时刷新覆盖层(拍照会抓取当时合成图像):
// wcSetOverlay([ ...上同结构元素树 ])

// 用户点击拍照后由相机页内部触发,也可由外部按钮调用:
// wcTakePhoto()
// wcClose()

五、授权(已改为付费插件模式)

  • 已改为插件市场付费插件模式,不再校验授权码。
  • 恒为已授权,不会输出试用水印。
  • license / scope 参数仅为向后兼容而保留,传不传都不影响。

六、双端分工

端 负责人 内容
Android Windows CameraX 预览 + 拍照 + Canvas 合成 + AAR
iOS Mac AVFoundation 预览 + UIGraphicsImageRenderer 合成
契约 共同 utssdk/index.uts 的接口与类型

iOS 具体任务清单见 IOS-TODO.md 与仓库根 IOS-HANDOFF.md。


七、当前状态

  • [x] 接口契约冻结
  • [x] 目录骨架
  • [x] 权限/依赖声明(CameraX 1.3.4 + exifinterface 1.3.7 + lifecycle-runtime 2.6.2)
  • [x] Android 实现(CameraX 预览 + 覆盖层 + 拍照合成 + 试用水印,AAR 已就位)
  • [x] 通用元素树(text / logo / rect / line)+ wcSetOverlay 动态更新
  • [ ] iOS 实现(Mac 端)
  • [x] 示例页(demo/pages/index/index.uvue)

原生实现位置:native-facade/watermark-camera-facade/(Kotlin + CameraX), 产物 utssdk/app-android/libs/watermark-camera-facade.aar。 修改 Kotlin 后需重新 assembleRelease 并覆盖该 aar。

隐私、权限声明

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

摄像头

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

无

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

无

暂无用户评论。