更新记录

0.1.0（2026-11-07） 下载此版本

feat: UP Shot 0.1.0 首次发布

首个自研版本。按公开功能清单建立独立的能力矩阵与 API 契约，未使用对标插件的源码、组件名称、界面资源、错误码或说明文案。

• 根 API：全屏拍摄、连续逐张交付、拍后确认整组交付、已有图片加水印、设备能力查询、归属媒体删除、脱敏诊断文本导出。
• 页面内组件：uni-app x 标准模式 native-view 组件，覆盖预览生命周期、拍照、录像暂停恢复与切镜、画面控制、水印拖动与事件反馈；另提供 Vapor 蒸汽模式分支与普通 uni-app nvue 兼容入口（仅全屏，不做假预览）。
• 公共逻辑层：参数归一、能力协商与降级、水印逐行布局与占位符、图片水印校验、状态机、录像分段计划、批量会话、媒体归属登记。
• 跨语言协议：自研 key=esc(value) 键值串，两层编码；行样式串固定 16 段；原生内部码 130xx 与业务码 210xx 显式一一映射。
• 平台层：Android（CameraX + PreviewView / ImageCapture / VideoCapture / MediaMuxer）与 iOS（AVFoundation + CoreGraphics / AVMutableComposition）提供采集、绘制、输出、分段合并，并补齐 15 个事件、辅助线、水印拖动、快门反馈与深度诊断；HarmonyOS 提供自研 Camera Kit 采集适配器（ShotBridge.ets）与 builder.ets 的 XComponent 预览表面，需自定义基座，已有图片水印与分段合并分别通过 attachStamper() / attachMerger() 注入；Web 与小程序复用默认降级入口，不伪装原生预览。
• 事件编排：onEvent(name, detail) 接收全部 15 个原生事件；ready / abilitiesChange 刷新能力缓存，finalizeTick 映射 onProgress。
• 补齐阶段：针对实现深度审计列出的 11 类缺失逐项补齐——Harmony 采集与组件绑定、三端 15 个事件、水印拖动、辅助线 / 旋转 / 镜像 / 取景框裁剪、快门与震动反馈、产品化界面、深度诊断、录像成片离线烧录（iOS）与明确降级（Android）、Vapor / nvue 兼容层。
• 测试与能力诚实性：60 个自动化用例覆盖平台无关逻辑、runtime 编排、降级入口与源码一致性；先修正三端能力摘要虚报，补齐真实实现后再按实际能力恢复 drag / previewCrop / torch，统一由源码测试守门。

验证边界：自动化测试只覆盖平台无关逻辑与源码契约；Kotlin / Swift / ArkTS 原生代码尚未经过 HBuilderX 编译、自定义基座打包与真机验收，请在目标设备按 docs/acceptance.md 逐项确认。实时逐帧视频烧录、iOS 硬件快门、H5 / 小程序采集为明确降级。

平台兼容性

UP Shot

UTS 相机插件：全屏与页面内预览、照片与录像采集、文字/图片水印、拍后整组确认、录像暂停恢复与分段合并、已有图片加水印、设备能力协商、媒体归属删除与本机脱敏诊断。

本插件为独立实现。功能范围参考公开插件页面列出的能力点，但接口、协议、原生代码、界面、错误码与本文档均为自研，未使用第三方插件的源码、组件名称、说明文档或素材。

支持平台

安装与配置

1. 将 uni_modules/up-shot 放入工程的 uni_modules/ 目录。
2. Android：确认 CAMERA、RECORD_AUDIO（仅录像录音时）、VIBRATE 权限已在宿主 manifest 中声明；运行时由插件发起申请。
3. iOS：确认 Info.plist 已包含相机、麦克风、相册读写用途说明。
4. 使用自定义基座打包后运行到真机；标准基座不包含本插件的原生桥。
5. 详细步骤与权限用途见示例工程 docs/platform-setup.md。

引入方式

import {
  launchShot, launchReview, stampExistingImage,
  probeDevice, releaseMedia, exportTrace, shotViewSupported
} from '@/uni_modules/up-shot';

uni-app x 标准模式内嵌预览：

<up-shot-view ref="viewRef" :setup="setup" :autoStart="true" @event="onEvent" />

viewRef.value.capture('quality');
viewRef.value.beginVideo();
viewRef.value.holdVideo();
viewRef.value.continueVideo();
viewRef.value.endVideo();
viewRef.value.teardown();

最小示例

launchShot({
  setup: {
    mode: 'still',
    lens: 'rear',
    fallback: 'closest',
    output: { target: 'temp', conflict: 'rename' },
    overlay: {
      enabled: true,
      previewVisible: true,
      burnIntoPhoto: true,
      blocks: [{ id: 'clock', kind: 'text', text: '{{clock}}', anchor: 'rb' }]
    }
  },
  success: (media) => console.log(media.deliverable, media.effective.notes),
  fail: (err) => console.log(err.errCode, err.errMsg, err.stage),
  complete: () => console.log('回调已结算')
});

所有 API 都是回调式 options，不返回 Promise。success 与 fail 只会有一个被触发，complete 一定会执行。

结果约定

• ShotMedia.deliverable 始终指向本次最终成片，可直接交给上传逻辑。
• ShotMedia.effective 是设备实际生效的配置；请求与生效不一致时读取 effective.notes 与 effective.skippedOverlayIds。
• ShotGroup 只在整组确认时交付一次，确认前不产生对外媒体。
• 录像暂停、恢复、切镜可能产生多个片段，最终只交付一个合并后的文件，暂停时长不计入逻辑时长。

错误码

独立码段 21001–21024。常见项：

完整映射见 utssdk/unierror.uts；原生内部码 130xx 到业务码的转换表见 utssdk/runtime.uts 的 NativeToBusinessCode。

隐私与权限

• 媒体文件只写入应用沙箱或业务显式指定的可写目录，插件不采集、不上传照片与视频。
• 不读取定位、通讯录、设备唯一标识；水印中的业务信息由调用方通过 tokens 自行提供。
• 诊断日志在本机内存中生成，路径、坐标、水印文字、长标识均经脱敏，导出动作由业务主动调用。
• 保存到系统相册需要宿主按平台申请对应权限。

验证状态

60 个自动化用例覆盖平台无关逻辑、协议一致性与源码守门；UTS 编译、Kotlin / Swift / ArkTS 原生编译、自定义基座打包与真机采集效果需按示例工程 docs/acceptance.md 验收。请勿把逻辑测试通过等同于真机可用。