更新记录

1.0.0（2026-10-16）

• 新增 Android、iOS 本地证件照制作能力，支持 uni-app、uni-app x，照片处理无需业务服务器。
• 新增单人人像会话、人脸分析与前景分割，支持本地 JPEG/PNG 照片及系统选图。
• 新增毫米/像素尺寸换算、DPI 设置、常用规格与自定义尺寸，返回实际成片像素和读取到的 DPI 元数据。
• 新增白、蓝、红等底色与自定义颜色，支持原生编辑器及直接 API 预览、导出。
• 新增海军蓝西装、炭灰西装与领带本地透明模板，支持自动定位建议和移动、缩放、旋转调整。
• 新增局部前景保护、原衣物清理、撤销重做、重置、原图对比及成片确认。
• 新增 JPEG/PNG 本地文件导出、文件体积限制、任务取消、会话和结果释放及统一回调、错误码。
• 新增 uni-app、uni-app x 完整示例，提供参数设置、编辑器、直接 API 制作及完整诊断报告分段复制。
• 调整同步错误合同：resolveIdPhotoSizeSync、cancelPhotoTask统一返回ok/result/error结果对象；客户需先检查ok，再读取原成功结果或完整错误快照，替换原直接读取和业务try/catch写法。合法accepted=false仍为成功取消回执，原异步任务终态不变。
• 修复iOS共享UTS的数值/可空值、诊断时间、错误字段与报告表达式生成边界；保留原尺寸限制、诊断脱敏及完整报告。

平台兼容性

uni-app(5.26)

uni-app x(5.26)

其他

证件照制作UTS插件【安卓 IOS】离线处理、尺寸、换底色与本地模板换装

介绍

lizhao-id-photo 是面向 uni-app、uni-app x 的证件照制作 UTS 插件。在 Android、iOS 手机本地把单人人像制作成指定尺寸与 DPI 的证件照，提供换底色、本地透明服装模板换装与原生编辑界面，适用于报名、入职及日常证件照制作。

支持 Android 6.0 / API 23 及以上、iOS 15 及以上的本地 App 实现。照片处理不依赖业务服务器；Android 使用随包 ML Kit 模型，iOS 使用系统 Vision。人物识别、发丝与领口效果需要按实际照片检查，平台与接入边界见“注意事项”。

功能特色

• 宽高支持mm/px，独立设置DPI；返回精确像素、文件字节和实际读取的DPI元数据。
• Android使用随包ML Kit人像分割/人脸检测，iOS使用系统Vision；照片处理无需业务服务器。
• 内置海军蓝西装、炭灰西装与领带两件原创透明模板；自动定位后可移动、缩放和旋转。
• 原生编辑器包含规格、底色、自定义色、前景保护/原衣物清理、撤销/重做/重置、按住原图对比和成片确认。
• 可直接调用会话、分析、预览和导出API。异步操作返回taskId，统一先success/fail再complete。
• 两种宿主示例都有底部日志、完整诊断、固定快照分段复制及手动复制备用内容。

人物分割与自动保护区域不等于头发、皮肤、衣领语义识别。长发、复杂旧衣领、侧脸和遮挡可能需要修补；模板不能补出被遮住的真实脖颈。提交前检查发丝、领口、边缘和接收机构要求。

适合哪些场景

下载与导入

1. 在 HBuilderX 中将本插件导入自己的 uni-app 或 uni-app x 项目；也可将作者提供的完整源码目录放入项目 uni_modules/。

2. 保留完整的 uni_modules/lizhao-id-photo/ 目录和插件名称，不单独复制 utssdk。

3. 页面只从插件根目录导入：@/uni_modules/lizhao-id-photo。uni-app 使用 .vue 页面，uni-app x 使用 .uvue 与 UTS；按下面的实际文件路径查看对应写法。

4. 在项目 pages.json 注册示例页面路径，路由不带 .vue 或 .uvue 扩展名。首次加入原生插件或原生依赖、权限、资源变化后，重新原生联编或制作并安装匹配的自定义基座；只更新页面资源无法给旧基座补入原生能力。

接入方式选择

将完整uni_modules/lizhao-id-photo放入项目，页面只从插件根目录import。uni-app示例使用Vue3；Vue2宿主调用链尚未实际验收。

完整示例路径

• 原创模板来源与许可：uni_modules/lizhao-id-photo/ASSETS.json、uni_modules/lizhao-id-photo/ASSET-LICENSE.md

示例提供拍照/选图、规格、底色、原生编辑器、直接API制作、成片预览、独立保存相册、取消、释放及诊断复制。

从基础到进阶：按业务模块使用

基础：打开原生制作界面

下面可作为uni-app x页面；uni-app Vue3使用同样的根import和回调。

<template><button @click="makePhoto">制作证件照</button></template>
<script setup lang="uts">
import { openIdPhotoEditor } from '@/uni_modules/lizhao-id-photo'
function makePhoto(): void {
  openIdPhotoEditor({
    initialSize: { unit: 'mm', width: 25, height: 35, dpi: 300 },
    initialBackgroundColor: '#FFFFFF',
    success: (file) => {
      console.log('文件已生成', file.path, file.widthPx, file.heightPx, file.bytes)
      // 另设保存按钮；success不代表相册保存成功。
    },
    fail: (error) => uni.showToast({ title: error.errMsg, icon: 'none' }),
    complete: (result) => console.log(result.taskId, result.status)
  })
}
</script>

首次接入必须原生联编或重打Android/iOS自定义基座。appResource/wgt不能把Kotlin、Swift、依赖和模板资源加入旧基座。

模块一：从相册或相机取得照片

通过宿主拍照或选图：

import { openIdPhotoEditor } from '@/uni_modules/lizhao-id-photo'
uni.chooseImage({
  count: 1, sourceType: ['camera', 'album'], sizeType: ['original'],
  success: (selected) => {
    if (selected.tempFilePaths.length == 0) return
    openIdPhotoEditor({
      sourcePath: selected.tempFilePaths[0],
      initialSize: { unit: 'px', width: 600, height: 800, dpi: 300 },
      initialBackgroundColor: '#438EDB',
      format: 'jpeg', maxBytes: 200000,
      success: (file) => console.log(file.path, file.resultId),
      fail: (error) => console.error(error.errSubject, error.errCode, error.errMsg),
      complete: (result) => console.log(result.status)
    })
  },
  fail: (error) => console.error(error.errMsg)
})

模块二：按毫米或像素换算规格

import { resolveIdPhotoSizeSync } from '@/uni_modules/lizhao-id-photo'
const outcome = resolveIdPhotoSizeSync({ unit: 'mm', width: 25, height: 35, dpi: 300 })
if (outcome.ok && outcome.result != null) {
  const size = outcome.result!
  console.log(size.widthPx, size.heightPx, size.dpi)
  // 295×413px；实际回算约24.9767×34.9673mm，像素为权威。
} else if (outcome.error != null) {
  const error = outcome.error!
  console.error(error.errSubject, error.errCode, error.errMsg)
}

上述为uni-app x的UTS写法。uni-app的JavaScript调用同一根入口，读取时无需非空断言：

import { resolveIdPhotoSizeSync } from '@/uni_modules/lizhao-id-photo'
const outcome = resolveIdPhotoSizeSync({ unit: 'mm', width: 25, height: 35, dpi: 300 })
if (outcome.ok && outcome.result != null) {
  console.log(outcome.result.widthPx, outcome.result.heightPx, outcome.result.dpi)
} else if (outcome.error != null) {
  console.error(outcome.error.errSubject, outcome.error.errCode, outcome.error.errMsg)
}

同步调用的迁移

resolveIdPhotoSizeSync和cancelPhotoTask保留名称、输入，统一返回{ ok, result, error }。旧代码直接读取resolveIdPhotoSizeSync(...).widthPx、cancelPhotoTask(...).accepted，或依靠try/catch接收这两个API的业务失败，均需迁移：先检查ok，成功再读取result，失败读取error。失败不再抛同步业务异常，也不会返回替代尺寸或伪取消回执。

error为可跨原生/JS桥接的IdPhotoOutcomeError数据快照，保留原错误的errSubject、errCode、errMsg、operation、sessionId、taskId、nativeType、nativeCause、nativeStack。异步API的IdPhotoFail和success/fail/complete保持原合同；同步快照不冒充JavaScript Error实例，其异常原因和堆栈边界读取nativeCause、nativeStack。

模块三：取消任务并释放会话与成片

使用结束调用releasePhotoSession({sessionId, fail, complete})及releasePhotoResult({resultId, fail, complete})，身份使用真实结果值。会话只持有插件复制的输入、蒙版和预览，不删除原始输入。导出文件独立持有，释放会话后仍有效；不要提前释放仍在预览或保存的结果。

预览路径属于会话，下一次成功预览会替换旧文件，释放会话后不可再用。会话不能跨进程恢复；下次启动只回收插件拥有的旧临时会话。导出结果保存在应用私有文件目录，两端可恢复原resultId供releasePhotoResult释放；调用方应保存结果编号和路径，并在使用前确认文件仍存在。清除应用数据或卸载会删除结果；保存到系统相册需另调宿主API。

Android对插件拥有的结果及在途预留共限制16份、256MiB，iOS限制32份、128MiB；达到上限报9316005，需先释放不用的结果。Android遇到缺失或不完整的结果拥有权登记时保留文件并计入容量，避免误删已交付照片。

cancelPhotoTask(taskId)先判断结果对象的ok，成功后再读取result.accepted。accepted仅表示取消请求已受理，原任务fail/complete才表示终态；合法的accepted=false或alreadySettled=true仍是ok=true的真实回执。不支持取消返回ok=false/error.errCode=9316001；畸形回执或桥接异常返回9316016，错误中的taskId保持调用方原值。

下面的uni-app x函数可接收createPhotoSession、openIdPhotoEditor等API真实返回的taskId，在业务取消按钮中调用：

import { cancelPhotoTask } from '@/uni_modules/lizhao-id-photo'
function cancelEditing(taskId: string): void {
  const outcome = cancelPhotoTask(taskId)
  if (!outcome.ok) {
    const error = outcome.error!
    console.error(error.errSubject, error.errCode, error.errMsg, error.nativeType, error.nativeCause, error.nativeStack)
    return
  }
  const receipt = outcome.result!
  console.log(receipt.taskId, receipt.accepted, receipt.alreadySettled)
}

uni-app的JavaScript调用保留相同分支，移除上述函数参数、返回类型及!类型断言。完整可运行页面分别为uni_modules/lizhao-id-photo/example/uniapp/index.vue和uni_modules/lizhao-id-photo/example/uniappx/index.uvue，均保留真实取消、原任务终态处理和底部完整诊断报告。

已受理的资源清理可能不可撤回，cancel会按真实阶段拒绝受理，不承诺恢复已删除的临时文件。Android会话/结果释放及iOS已受理会话释放采用不可撤回清理；以accepted与alreadySettled回执为准。

模块四：在自有界面控制制作流程

依次使用 createPhotoSession、analyzePortrait、renderPhotoPreview、exportPhoto。保存创建结果的 sessionId，使用分析建议建立实际编辑快照；预览与导出传入同一业务确认的快照，成功后保存 resultId 和路径。完整的参数组装、回调和失败路径见 uni_modules/lizhao-id-photo/example/uniapp/index.vue 与 uni_modules/lizhao-id-photo/example/uniappx/index.uvue。

API 用途速查

异步参数均有可选success/fail/complete和taskId。不传taskId自动生成；taskId须为1–128个英文字母、数字、下划线或连字符，同一在途身份不能复用。取消走fail(9316012)后complete.status='cancelled'。全部类型见uni_modules/lizhao-id-photo/utssdk/interface.uts。

两个同步结果对象的字段如下。ok=true时result为原真实结果、error为null；ok=false时result为null、error为原失败语义的完整数据快照。

设置maxBytes时，JPEG按5级逐步降低质量；Android降到min(初始质量,35)，iOS降到min(初始质量,10)。达到该下限仍超出体积则报9316014，PNG直接按实际字节判定。两端编码器不同，同尺寸、质量参数不保证字节数或像素颜色完全一致；请以返回文件和warnings为准。

模板为实际透明PNG，widthPx/heightPx与解码一致，带id/name/imagePath/assetVersion/licenseId及归一化neckLeft/neckRight/shoulderLeft/shoulderRight锚点；minScale/maxScale为有限正数。调用者负责自有模板许可。

keep将原始头发/皮肤区域保护在服装前；erase清理原衣物残留。自动定位只是初始建议，需要检查肩宽/领口。

预览含sessionId/taskId/revision/path/widthPx/heightPx/bytes/warnings。导出另有resultId、format、requestedDpi、actualDpiX/actualDpiY、dpiMetadataWritten；实际DPI不可读时返回null与警告，不把请求值冒充实际值。输出最长边4096/800万像素；输入最长边8192/1600万像素/64MiB。

错误码说明

errSubject固定为lizhao-id-photo。fail保留operation/sessionId/taskId和可获取的脱敏nativeType/nativeCause/nativeStack。

注意事项

权限、平台差异与基座

上述为插件提供的实现范围，不能代替目标宿主与系统上的实际验收。两宿主使用相同UTS API；完整示例分别为Vue3和uvue，Vue2/nvue未附独立示例，完整调用链尚未实际验收。resolveIdPhotoSizeSync是纯UTS尺寸换算，其他端可用该辅助能力，不表示支持照片分割、换装或导出。

Android已进行原生联编和MuMu部分实际照片测试；存在小人脸检出失败、发丝边缘与换装领口衔接问题，不能保证任意输入照片都能获得合格证件照。iOS仍需Apple SDK编译、匹配基座和设备验收。编辑器使用中文界面，未提供自动暗色主题、多语言资源或专门宽屏布局。

Android bundled Selfie Segmentation和Face Detection版本固定在config.json。SDK有自身指标采集规则，照片本地处理不代表第三方SDK绝不联网；见ML Kit数据披露。iOS无第三方AI模型依赖。图片和模板不默认下载，照片和日志不默认上传。

内置选图使用系统picker；宿主chooseImage拍照处理相机权限，saveImageToPhotosAlbum独立处理保存。PHPicker无需全相册授权；iOS带隐私清单，拍照/保存用途说明由宿主manifest按实际业务配置。

本地导出成功与保存相册成功应分别处理。本项目MuMu当前容器调用uni.saveImageToPhotosAlbum出现过UTSCallback到Function1的回调类型转换异常，保存未完成；接入时需核对HBuilderX资源与原生包，并检查真实保存回调和相册文件，不能只凭导出成功提示“已保存”。

原生源码、依赖/模型、Manifest/Info.plist、配置或模板变化需重新联编/自定义基座。只改示例样式或客户文档通常不需重打，但仍须匹配原生标记。

诊断sourcePreparationHBuilderXVersion来自源码准备期，不代表安装包编译器。真实包、运行时、基座等字段不可得时为unknown。复现后底部“一键复制日志”逐段发送同一编号；复制失败可重试或手动长按备用内容，不清原日志。

日志中的任务/会话编号采用稳定ref代号以免调用方个人编号明文进入诊断缓存；同一编号可跨原生、UTS和示例关联。业务回执和cancelPhotoTask仍使用原始taskId。代号不是加密或匿名性保证，请勿把个人信息、凭据作为业务编号。

• 先按接收机构要求选择尺寸、底色与文件体积，再检查实际成片。
• 自动分析和模板适配提供制作建议，长发、遮挡或旧衣领可能需要人工修补。
• 导出成功只表示本地文件已生成；保存到系统相册是另一次操作。
• 不提前释放正在预览、保存或上传的结果；缓存与应用私有目录不能代替业务长期保存。

作者系列 UTS 插件

以下为作者已在 DCloud 插件市场上架的 UTS 插件，可按业务场景组合使用。最新发布内容可查看作者主页。