更新记录

1.0.0（2026-09-01）

• 首次发布 Android、iOS 原生自定义相机能力，支持 uni-app 与 uni-app x。
• 提供任意尺寸嵌入式原生预览组件和内置全屏相机 API。
• 支持拍照、快速拍照、录像、暂停恢复、录制进度、最大时长和录像中切换摄像头后合并为单文件。
• 支持前后摄、设备允许时的超广角、闪光灯、手电筒、点击对焦、双指缩放、代码缩放、曝光、白平衡和 HDR。
• 支持文本、时间、位置字段、自定义字段和图片 Logo 的照片/视频水印预览与最终烧录。
• 支持缓存、应用持久目录、系统相册和应用可写自定义目录，并提供命名冲突、原文件保留和媒体删除能力。
• 返回客户请求配置与设备实际生效配置，不支持的能力按 nearest 或 strict 策略明确降级或失败。

平台兼容性

uni-app(4.84)

uni-app x(4.84)

lizhao-camera-pro

面向 uni-app 与 uni-app x App 的原生自定义相机插件，提供任意尺寸嵌入预览、内置全屏相机、拍照、分段录像、录像中切换镜头、结构化水印和安全媒体存储。

功能特色

• Android 使用 CameraX，iOS 使用 AVFoundation，核心能力不依赖 uni 相机组件。
• 同时提供 <lizhao-camera-pro> 嵌入组件和 openCamera() 全屏 API。
• 支持拍照、快速拍照、录像、暂停/恢复、最大时长和录像中切换前后摄；最终交付一个视频文件。
• low / medium / high / uhd 会参与真实录像档位选择；最终以 appliedConfig 为准，不会把请求值冒充生效值。
• 文本、时间、自定义字段和本地图片可预览并烧录到照片或视频；录像水印中的时间和录制时长会动态更新。
• 支持 cache / files / album / custom 四种输出目标、同名策略、带水印时保留原文件及插件归属媒体删除。
• 所有媒体结果都包含 requestedConfig 与 appliedConfig，可明确识别 nearest 降级或 strict 失败。

适用场景

• 巡检、工程留痕、工单、考勤、执法记录等需要时间或业务字段水印的拍摄。
• 需要把原生相机嵌入表单、卡片、弹层或自定义操作界面的 App。
• 需要暂停录像、录像中切镜头，同时仍向业务层交付单个视频文件的场景。
• 需要把媒体安全保存到缓存、应用目录、系统相册或业务授权目录，并可按插件返回标识删除的场景。

快速开始

嵌入页面

在 .nvue 或 .uvue 页面中直接使用 easycom 标签。页面可自由覆盖业务按钮，核心预览仍由原生组件提供。

<template>
  <view class="camera-box">
    <lizhao-camera-pro
      ref="camera"
      class="camera"
      mode="mixed"
      camera-position="back"
      :auto-start="true"
      @ready="onReady"
      @photo="onPhoto"
      @recordfinished="onRecordFinished"
      @error="onError"
    />
    <text @click="takePhoto">拍照</text>
  </view>
</template>

<script>
export default {
  methods: {
    takePhoto() {
      this.$refs.camera.takePhoto({
        success: (result) => console.log('照片地址', result.path, result.uri),
        fail: (error) => console.log('拍照失败', error)
      })
    },
    onReady(event) { console.log('真实能力', event.detail || event) },
    onPhoto(event) { console.log('照片事件', event.detail || event) },
    onRecordFinished(event) { console.log('视频事件', event.detail || event) },
    onError(event) { console.log('相机错误', event.detail || event) }
  }
}
</script>

内置全屏相机

所有 UTS API 都从插件根目录导入。

import { openCamera } from '@/uni_modules/lizhao-camera-pro'

openCamera({
  mode: 'mixed',
  cameraPosition: 'back',
  config: {
    videoQuality: 'high',
    outputOptions: { target: 'cache', conflictPolicy: 'rename' }
  },
  success(result) {
    console.log('媒体结果', result.path, result.uri)
    console.log('请求/生效', result.requestedConfig, result.appliedConfig)
  },
  fail(error) {
    console.log('相机失败', error.errCode, error.stage)
  },
  complete(result) {
    console.log('全屏相机已结算', result)
  }
})

核心配置

以下字段可作为组件属性，也可放入全屏 API 的 config；单次拍照或录像参数会覆盖对应字段。

outputOptions

watermarkOptions.items[]

插件不会主动申请定位权限。位置、项目、人员等内容请由业务侧写入 fields，再在文本中用同名占位符引用。

接入方式选择

增强示例

动态水印与双输出

const watermarkOptions = {
  enabled: true,
  fields: { project: '项目 A', operator: '张三' },
  items: [
    {
      id: 'business',
      type: 'text',
      text: '{project} · {operator} · {timestamp} · {recordingDuration}',
      anchor: 'bottomLeft',
      color: '#FFFFFFFF',
      backgroundColor: '#66000000',
      padding: 10
    }
  ],
  previewVisible: true,
  burnIntoPhoto: true,
  burnIntoVideo: true
}

camera.takePhoto({
  watermarkOptions,
  outputOptions: { target: 'files', keepOriginal: true, conflictPolicy: 'rename' },
  success(result) {
    console.log(result.originalPath, result.watermarkedPath)
  }
})

暂停、恢复与录像中切镜头

camera.startRecording({
  videoQuality: 'high',
  videoFrameRate: 30,
  outputOptions: { target: 'cache' },
  success(started) { console.log('逻辑录像', started.recordingId) },
  fail(error) { console.log(error) }
})

camera.pauseRecording()
camera.resumeRecording()
camera.switchCamera('front')
camera.stopRecording()

暂停时间不计入逻辑时长；切镜头会安全结束当前片段、切换输入并继续新片段，最终处理阶段合并为一个文件。

四种输出目标

const cacheOutput = { target: 'cache' }
const filesOutput = { target: 'files', fileName: 'work.jpg', conflictPolicy: 'rename' }
const albumOutput = { target: 'album', albumName: '工作留痕', conflictPolicy: 'rename' }
const customOutput = {
  target: 'custom',
  directory: '/业务已授权的可写目录',
  fileName: 'work.jpg',
  conflictPolicy: 'error'
}

完整页面请查看插件随附的 example/uniapp 与 example/uniappx 示例。

组件 API

<lizhao-camera-pro /> 属性

组件方法

组件方法要求页面已挂载；异步结果通过传入回调和对应组件事件返回。destroyCamera() 后不要继续复用旧实例。

全屏 API

openCamera(options)

getCameraCapabilities(options)

import { getCameraCapabilities } from '@/uni_modules/lizhao-camera-pro'

getCameraCapabilities({
  position: 'back',
  success(capabilities) {
    console.log(capabilities.videoQualities, capabilities.videoResolutions)
  },
  fail(error) { console.log(error) }
})

deleteCameraMedia(options)

import { deleteCameraMedia } from '@/uni_modules/lizhao-camera-pro'

deleteCameraMedia({
  path: result.path,
  uri: result.uri,
  albumIdentifier: result.albumIdentifier,
  success(deleted) { console.log(deleted) },
  fail(error) { console.log(error) }
})

事件

返回值

CameraMediaResult

调用是否被接受和媒体是否最终成功是两个阶段。录像开始由 startRecording.success / recordstart 确认，最终视频只能以 recordfinished.result 或全屏 openCamera.success 为准。

错误码

CameraFail 还包含 stage、retryable、sessionId、generation 和精简的 nativeMessage，便于定位权限、打开、拍照、录像、合并、水印、保存或删除阶段。

支持平台

App 运行包必须包含本插件的原生代码。修改或升级插件后，请重新制作对应平台的自定义基座或正式包。

注意事项

• 首次打开会请求相机权限；只有 recordAudio=true 的录像才按需申请麦克风权限；保存或删除系统相册媒体时由平台按实际操作申请相应权限。
• nearest 会选择设备可用的最接近配置，并在 appliedConfig.fallbackReasons 说明原因；strict 无法精确满足时返回 9081010。
• iOS 的原生录像片段通常先写为 MOV，客户请求 MP4 时在最终处理阶段转换；Android 通常直接使用 MP4。最终容器与 MIME 以结果为准。
• custom.directory 必须是应用可写的绝对目录或已授权 URI。插件不会自行扩大目录权限，也不会覆盖无法确认归属的客户文件。
• overwrite 只覆盖插件可确认归属的同名媒体；事务失败会恢复旧文件或撤销新媒体。不要绕过返回结果自行猜测中间文件路径。
• keepOriginal=true 只有在水印实际烧录时才可能产生双输出；请同时检查 originalPath/originalUri 与 watermarkedPath/watermarkedUri。
• 暂停、恢复、切镜和最终处理均为异步状态机。按钮应依据 statechange、recordstart、recordpause、recordresume 和 finalizeprogress 控制，避免重复提交。
• 完整页面用法见随插件提供的三个示例；示例中的 custom 路径需替换为业务真实获得的可写位置。