更新记录

1.0.9(2026-11-07)

  • 文档 / 示例:明确 nvue 下兼容模式 UTS 多词 props 必须 camelCase(如 flashMode、:tapFocus、:autoMacro);写成 kebab-case(flash-mode、:tap-focus)时原生侧收不到,会一直停在默认值(例如闪光灯一直是 off)
  • 修复 iOS:NVLoaded 时若仍读到默认 prop,短延迟后再同步 flashMode / silent / 手势 / autoMacro / devicePosition,避免只靠 watch 漏同步
  • 示例页与 readme 已改为 camelCase 写法
  • 升级后须重新打自定义基座(含 iOS 组件同步逻辑)

1.0.8(2026-11-02)

  • 修复 Android / iOS:拍照成片比预览视野更宽(对准取景后拍出来像被放大一圈);iOS 按预览 resizeAspectFill 可见区域裁切成片
  • 修复 iOS:连续自动对焦在 iOS 26 / 27 不可用
  • 修复 iOS 自动微距不生效:NVLoaded 默认 false 开预览时 prop 晚到会停在广角;设置页只改绑定未调引擎。现暴露 updateAutoMacro、就绪后再同步,并用 DiscoverySession 回退选 Triple/DualWide/超广角
  • 升级后须重新打自定义基座

1.0.6(2026-10-13)

相对插件市场 1.0.1 的累计更新(含下方 1.0.2~1.0.5,升级后须重新打自定义基座):

  • 裁剪:同步 API cropCameraPhoto(path, rect): string,另存 mz_crop_*.jpg;rect 为 "x,y,width,height" 字符串;失败返回 ""
  • 录像:startRecord / stopRecord,事件 recordstart / recordstop;需麦克风权限与 NSMicrophoneUsageDescription
  • 视频管理:目录 mz-custom-video;getCameraVideoList / getVideoCover / deleteCameraVideo
  • 照片管理:getCameraPhotoList / importCameraPhoto / deleteCameraPhoto;列表项含 source(camera / album / crop)
  • 手势 / 无声:tap-focus、pinch-zoom、@tapfocus;silent / updateSilent
  • 修复:Android 切摄主线程 rebind;iOS 18 无声快门音
查看更多

平台兼容性

uni-app(3.99)

Vue2 Vue3 Chrome Safari app-vue app-nvue Android iOS 鸿蒙
√ √ × × √ √ 5.0 √ ×
微信小程序 支付宝小程序 抖音小程序 百度小程序 快手小程序 京东小程序 鸿蒙元服务 QQ小程序 飞书小程序 小红书小程序 快应用-华为 快应用-联盟
× × × × × × × × × × × ×

uni-app x(4.25)

Chrome Safari Android iOS 鸿蒙 微信小程序
- - 5.0 √ - -

其他

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

mz-custom-camera

UTS 自定义相机组件:Android 使用 CameraX,iOS 使用 AVFoundation。原生只负责相机预览层,快门、取景框、相册、返回等 UI 由业务页自行覆盖实现。

平台 原生能力 最低版本
Android CameraX Preview + ImageCapture API 21+
iOS AVFoundation Session + PreviewLayer + PhotoOutput iOS 12+
宿主 uni-app App-nvue(兼容模式 UTS 组件) HBuilderX ≥ 4.25

不支持:H5、小程序、普通 vue 页内嵌相机组件(必须 nvue)。非 uni-app x 专用组件语法。


功能特性

  • 后置 / 前置摄像头切换
  • 闪光灯:off / on / auto
  • 点击对焦、双指缩放(可选,默认关闭)
  • iOS 可选后置自动微距(autoMacro)
  • 无声拍照(可选,默认关闭;主要作用于 iOS)
  • 录像(含麦克风):startRecord / stopRecord,输出本地 MP4(目录与照片分开)
  • 拍照输出本地 JPG 路径(见「注意事项 · 路径」)
  • 读取已拍照片列表,无需业务侧保存路径(getCameraPhotoList)
  • 读取已录视频列表(getCameraVideoList)
  • 提取视频第一帧封面(getVideoCover)
  • 删除已拍照片 / 已录视频文件(deleteCameraPhoto / deleteCameraVideo)
  • 导入相册图片到插件拍照目录,与拍照统一管理(importCameraPhoto)
  • 裁剪照片并另存(cropCameraPhoto)
  • 权限检测 / 主动申请(iOS 主动申请见「API 用法」中的已知问题)
  • 设备前后摄可用性探测
  • UI 完全自定义(插件不内置业务控件)
  • Android CameraX 1.4.2,适配 Google Play 16KB 内存页

快速开始

1. 导入插件

将本插件放入项目 uni_modules/mz-custom-camera(或从插件市场导入)。

2. 配置权限

Android(manifest.json → App 模块权限,或插件 Manifest 合并):

  • android.permission.CAMERA

iOS(manifest.json → iOS 隐私信息访问描述):

NSCameraUsageDescription = 需要使用相机进行拍照,请允许访问相机

若用到相册,另配 NSPhotoLibraryUsageDescription。若用到录像,另配:

NSMicrophoneUsageDescription = 需要使用麦克风进行录像配音,请允许访问麦克风

Android 录像还需 android.permission.RECORD_AUDIO(插件 Manifest 已声明,业务工程建议同步勾选)。建议在「App 模块配置」中勾选 Camera。

3. 制作自定义基座

本插件为 UTS 原生插件,标准基座无法运行。

  1. HBuilderX → 运行 → 制作自定义调试基座
  2. 勾选 mz-custom-camera
  3. 用自定义基座真机运行

正式发版请云打包并包含本插件。修改原生代码后需重新制作基座。

4. 新建 nvue 页面

在 pages.json 注册 nvue 页(建议全屏、关闭原生标题栏):

{
  "path": "pages/camera/custom-ui",
  "style": {
    "navigationStyle": "custom",
    "app-plus": {
      "titleNView": false,
      "bounce": "none",
      "background": "#000000"
    }
  }
}

完整示例:

  • example/custom-ui.nvue(Vue2 / Vue3 双路径快门、点击对焦框、相册导入、读取已拍照片)
  • example/custom-ui-vue3.nvue(Vue3 精简写法)

Vue2 / Vue3 怎么用

组件模板相同;差别在「怎么触发拍照、怎么拿 path」。

Vue2 Vue3 nvue
触发拍照 this.$refs.camera.takePhoto() takeCameraPhoto({ success, fail })
拿图片路径 @capture → e.detail.path success(res) → res.path
说明 $refs 调 UTS 方法可用 $refs.takePhoto 常无效,请用 API
<mz-custom-camera
  ref="camera"
  class="preview"
  devicePosition="back"
  flashMode="off"
  :autoPreview="true"
  @ready="onReady"
  @error="onError"
  @capture="onCapture"
/>

Vue2

methods: {
  onReady() {
    this.ready = true
  },
  onCapture(e) {
    const d = (e && e.detail) || e
    const path = d.path || (d.detail && d.detail.path) || ''
    // 使用 path
  },
  onShutter() {
    if (!this.ready) return
    this.$refs.camera && this.$refs.camera.takePhoto()
  }
}

Vue3

import { takeCameraPhoto } from '@/uni_modules/mz-custom-camera'

methods: {
  onReady() {
    this.ready = true
  },
  onCapture(e) {
    // 可选备份
    const d = (e && e.detail) || e
    const path = d.path || (d.detail && d.detail.path) || ''
    if (path) { /* 使用 path */ }
  },
  onShutter() {
    if (!this.ready) return
    takeCameraPhoto({
      success: (res) => {
        // res.path
      },
      fail: (err) => {
        uni.showToast({ title: err.errMsg || '拍照失败', icon: 'none' })
      }
    })
  }
}

takeCameraPhoto 会先回调 success / fail,再 $emit('capture'|'error')。Vue3 请以 success 为准。


组件用法

<template>
  <div class="page">
    <mz-custom-camera
      ref="camera"
      class="preview"
      devicePosition="back"
      flashMode="off"
      :autoPreview="true"
      @ready="onReady"
      @error="onError"
      @capture="onCapture"
    />
    <div class="shutter" @click="onShutter"></div>
  </div>
</template>

<script>
export default {
  data() {
    return { ready: false }
  },
  methods: {
    onReady(e) {
      this.ready = true
      const d = (e && e.detail) || e
      console.log('facing', d.facing)
    },
    onError(e) {
      const d = (e && e.detail) || e
      uni.showToast({ title: d.message || '相机错误', icon: 'none' })
    },
    onCapture(e) {
      const d = (e && e.detail) || e
      console.log('path', d.path)
    },
    onShutter() {
      if (!this.ready) return
      // Vue2;Vue3 见上文 takeCameraPhoto
      this.$refs.camera && this.$refs.camera.takePhoto()
    }
  }
}
</script>

<style>
.page { flex: 1; background-color: #000000; }
.preview {
  position: absolute;
  left: 0; top: 0; right: 0; bottom: 0;
}
</style>

Props

属性 类型 默认 说明
devicePosition back | front back 初始摄像头
flashMode off | on | auto off 闪光灯:关闭 / 开启 / 自动(见下方说明)
autoPreview Boolean true 加载后是否自动开预览
tapFocus Boolean false 点击预览区域对焦并测光(见下方说明)
pinchZoom Boolean false 双指缩放(见下方说明)
silent Boolean false 无声拍照,抑制系统快门音(见下方说明)
autoMacro Boolean false iOS 后置自动微距(见下方说明);Android 忽略

nvue 写法注意(兼容模式 UTS):多词 props 必须写 camelCase(如 flashMode、:tapFocus="true"、:autoMacro="true")。写成 kebab-case(flash-mode、:tap-focus)时,原生侧收不到属性,会一直停在默认值(例如 flashMode 一直是 off)。单词如 silent 不受影响。

无声模式

默认关闭,不开启时行为与之前一致(系统可播快门音)。开启后拍照时尽量不发出快门音。

<!-- 旧写法:仍可用,有系统快门音 -->
<mz-custom-camera class="preview" />

<!-- 推荐需要静音时开启 -->
<mz-custom-camera class="preview" :silent="true" />

运行中切换:

this.$refs.camera.updateSilent(true)  // 开
this.$refs.camera.updateSilent(false) // 关

说明:

  • iOS:拍照前在 willCapturePhotoFor 中处置系统快门音(1108);iOS 18+ 同时设置官方 isShutterSoundSuppressionEnabled(需 isShutterSoundSuppressionSupported 为 true)。部分国家/地区法规禁止关闭快门音时可能仍有声音。
  • Android:CameraX 本身一般不播放快门音;属性与 iOS 对齐,部分机型若受系统政策强制有声则无法关闭。
  • 示例工程设置弹窗内有「无声模式」开关,见 pages/camera/custom-ui.nvue。

闪光灯

三种模式:

值 含义
off 关闭
on 开启(拍照时强制闪光)
auto 自动(由系统按环境光决定)

初始模式用属性绑定;运行中切换请调用 updateFlashMode(不要调用 setFlashMode,会与 prop 的原生 setter 冲突):

<mz-custom-camera ref="camera" class="preview" :flashMode="flashMode" />
data() {
  return { flashMode: 'off' } // 'off' | 'on' | 'auto'
},
methods: {
  setFlashMode(mode) {
    this.flashMode = mode
    const cam = this.$refs.camera
    if (cam && typeof cam.updateFlashMode === 'function') {
      cam.updateFlashMode(mode) // 'off' 关闭 / 'on' 开启 / 'auto' 自动
    }
  }
}

说明:

  • 前置摄像头多数机型不支持闪光灯,设置后可能无效果,属设备限制。
  • 示例工程拍照页右上角「设置」里有三段选择(关闭 / 开启 / 自动),见 pages/camera/custom-ui.nvue。

对焦与缩放

不开启 tapFocus 时,插件仍会启用连续自动对焦:Android(CameraX)默认连续自动对焦;iOS 在会话启动时显式设置(不支持连续对焦时回退单次自动对焦)。

推荐开启 tapFocus 和 pinchZoom:近距离、拍文字或证件时,默认对焦可能对不准主体,点击对焦可以明显减少拍糊。旧写法不加这两个属性仍照常工作,行为不变。

<!-- 旧写法:仍可用,仅系统默认自动对焦 -->
<mz-custom-camera class="preview" devicePosition="back" />

<!-- 推荐写法(nvue 须 camelCase) -->
<mz-custom-camera class="preview" devicePosition="back" :tapFocus="true" :pinchZoom="true" />
  • 点击对焦:Android 调用 CameraControl.startFocusAndMetering(对焦 + 测光 + 白平衡),5 秒后自动回到连续自动对焦;iOS 设置 focusPointOfInterest / exposurePointOfInterest 单次对焦,画面明显变化后自动回到画面中心的连续自动对焦。
  • 双指缩放:Android 在 ZoomState 的最小~最大倍数之间缩放;iOS 在设备可用范围内缩放,上限 10 倍。切换前后摄后缩放会重置为 1 倍。
  • 插件不绘制对焦框。点击对焦时会触发 @tapfocus 事件,带点击位置 x / y(相对预览左上角,单位与 nvue 的 px 一致),业务页可据此叠加对焦框,完整示例(含缩放动画)见 example/custom-ui.nvue:
<mz-custom-camera class="preview" :tapFocus="true" @tapfocus="onTapFocus" />
<div v-if="focusVisible" class="focus-box" :style="{ left: (focusX - 40) + 'px', top: (focusY - 40) + 'px' }"></div>
onTapFocus(e) {
  const d = (e && e.detail) || e
  const p = d.detail || d
  this.focusX = p.x
  this.focusY = p.y
  this.focusVisible = true
  setTimeout(() => { this.focusVisible = false }, 1000)
}
  • 开启后预览区域会消费触摸事件;覆盖在预览之上的业务按钮不受影响。
  • 两个属性都可以在运行中动态切换。

自动微距(iOS)

默认关闭,不开启时后置仍使用广角镜头,行为与之前一致。开启后,在支持多摄虚拟设备的 iPhone(常见为 13 Pro 及更新 Pro 系列)上,靠近主体时可由系统自动切换到超广角微距。

<!-- 旧写法:仍可用,无自动微距 -->
<mz-custom-camera class="preview" devicePosition="back" />

<!-- 需要微距时开启(仅 iOS 生效;nvue 须 camelCase) -->
<mz-custom-camera class="preview" devicePosition="back" :autoMacro="true" :tapFocus="true" />

说明:

  • 仅 iOS;Android 同名属性忽略。
  • 依赖 builtInTripleCamera / builtInDualWideCamera;不支持的设备开启后静默回退广角,不报错。
  • 运行中可通过绑定 :autoMacro 开关;变更会重新配置相机会话。
  • 须写 :autoMacro="true"(属性默认 false);仅改代码后须重新制作自定义基座。
  • 1.0.7 在 NVLoaded 早于 prop 写入时可能选不到多摄设备,1.0.8 已修。

方法($refs,主要 Vue2)

方法 说明
startPreview() 开始预览
stopPreview() 停止预览
takePhoto() 拍照,成功触发 @capture
switchCamera() 前后摄切换
updateFlashMode(mode) 改闪光灯,mode 为 'off' / 'on' / 'auto'。勿用 setFlashMode(与 prop 冲突)
updateSilent(silent) 开关无声模式,silent 为 true / false
updateAutoMacro(enabled) 运行时开关 iOS 后置自动微距;Android 忽略。设置页请调方法,不要只改 prop
startRecord() 开始录像(含麦克风;需麦克风权限)
stopRecord() 停止录像,成功触发 @recordstop

录像

默认不录像,仅调用 startRecord / stopRecord 时才会录。视频保存在独立目录(与照片分开):

  • Android:filesDir/mz-custom-video/mz_vid_<毫秒>.mp4
  • iOS:_doc/mz-custom-video/mz_vid_<毫秒>.mp4(回退 Documents/mz-custom-video)
// 开始
this.$refs.camera.startRecord()
// 停止
this.$refs.camera.stopRecord()
<mz-custom-camera
  ref="camera"
  @recordstart="onRecordStart"
  @recordstop="onRecordStop"
  @error="onError"
/>
onRecordStart() { /* 更新 UI:录制中 */ },
onRecordStop(e) {
  const d = (e && e.detail) || e
  const p = d.detail || d
  console.log(p.path) // Android 绝对路径;iOS 多为 _doc/mz-custom-video/xxx.mp4
}

说明:

  • 需要相机 + 麦克风权限。Android 用系统 RECORD_AUDIO;iOS 首次 startRecord 时若未授权会弹麦克风授权框。
  • 录制中不可切换前后摄。
  • 部分机型无法同时绑定拍照与录像用例时,Android 会回退为仅拍照,此时 startRecord 会报 RECORD_UNSUPPORTED。
  • 完整示例见演示工程(仓库)pages/camera/record.nvue;历史列表见 getCameraVideoList / pages/history/video-history.vue。插件包内基础示例:example/custom-ui.nvue。

读取已录视频 getCameraVideoList

直接扫描插件录像目录,按录制时间倒序。同步返回 { list }(与 getCameraPhotoList 相同,避免 iOS 直接返回对象数组丢字段)。

import { getCameraVideoList } from '@/uni_modules/mz-custom-camera'

const { list } = getCameraVideoList()
// list: [{ path: '_doc/mz-custom-video/mz_vid_1760000000000.mp4', time: 1760000000000 }, ...]
字段 类型 说明
path String 与 @recordstop 返回的 path 一致
time Number 录制时间(毫秒),从文件名解析,失败为 0

提取视频封面 getVideoCover

传入本地视频路径,提取第一帧为 JPEG 封面。封面缓存在同目录(mz_cover_<时间戳>.jpg),再次调用直接返回缓存;删除视频时会一并删除对应封面。

import { getVideoCover } from '@/uni_modules/mz-custom-camera'

getVideoCover({
  path: videoPath, // 录像返回的 path,带不带 file:// 均可
  success: (res) => {
    // res.path → 封面图本地路径,可直接用于 <image :src="...">
    console.log(res.path)
  },
  fail: (err) => {
    // err.errCode === 9101008 提取失败
  }
})

历史列表示例见 pages/history/video-history.vue(封面 + 点击进入 pages/camera/video-preview 播放)。

删除视频 deleteCameraVideo

删除插件录像目录中的文件(Android filesDir/mz-custom-video;iOS _doc/mz-custom-video)。用法同 deleteCameraPhoto。

import { deleteCameraVideo } from '@/uni_modules/mz-custom-camera'

deleteCameraVideo({ paths: [pathA, pathB] })
deleteCameraVideo() // 全部删除

事件

事件 字段 说明
ready facing 预览就绪
error code, message 错误(含 NO_MIC_PERMISSION / RECORD_FAILED 等)
capture path 拍照成功
tapfocus x, y 点击对焦(需开启 tapFocus),点击位置相对预览左上角
recordstart — 开始录像
recordstop path 录像结束,本地 mp4 路径

事件取值:

const d = (e && e.detail) || e
// d.path / d.facing / d.code / d.message

API 用法

import {
  checkCameraPermission,
  isCameraAvailable,
  takeCameraPhoto
} from '@/uni_modules/mz-custom-camera'

const info = isCameraAvailable()
// { available, hasFront, hasBack }

checkCameraPermission({
  request: true,
  success: (res) => console.log(res.granted),
  fail: (err) => console.log(err.errCode, err.errMsg)
})

// Vue3 推荐;须已有预览中的 <mz-custom-camera>
takeCameraPhoto({
  success: (res) => console.log(res.path),
  fail: (err) => console.log(err.errCode, err.errMsg)
})
// 也可 takeCameraPhoto(null),仅发起并依赖 @capture

建议在页 onLoad 先申请权限,再依赖 autoPreview 或手动 startPreview()。

iOS 已知问题:checkCameraPermission 的 request: true 在 iOS 上不生效(传到原生端变成 false),未授权时不会弹系统授权框,而是直接 success({ granted: false })。Android 不受影响。

iOS 上可以在 granted: false 时照常进入相机页:<mz-custom-camera> 启动预览时,如果用户还没决定过授权,组件会自己弹系统授权框;用户拒绝或之前已拒绝时触发 @error(code 为 NO_PERMISSION),可引导用户去系统设置开启。

读取已拍照片 getCameraPhotoList

插件拍照成功后照片会自动保存在插件拍照目录,无需业务侧保存路径。直接调用即可拿到全部已拍照片,按拍摄时间倒序(最新在前)。同步返回 { list }。

import { getCameraPhotoList } from '@/uni_modules/mz-custom-camera'

const { list } = getCameraPhotoList()
// list: [{ path: '_doc/mz-custom-camera/mz_cam_1760000000000.jpg', time: 1760000000000, source: 'camera' }, ...]

list 每项字段:

字段 类型 说明
path String 与拍照回调返回的 path 格式一致:Android 为绝对路径;iOS 多为 _doc/mz-custom-camera/xxx.jpg。可直接传给 deleteCameraPhoto({ paths })
time Number 拍摄或导入时间(毫秒时间戳),从文件名解析,解析失败为 0
source String 'camera' 插件拍照;'album' 通过 importCameraPhoto 导入;'crop' 通过 cropCameraPhoto 裁剪另存

说明:

  • 包含插件拍的照片、importCameraPhoto 导入图、cropCameraPhoto 裁剪另存图;直接用 uni.chooseImage 拿到、未导入的图片不在列表中。
  • 读取的是文件本身,用 deleteCameraPhoto 删除后不会再出现在列表中。

裁剪照片 cropCameraPhoto

按方向校正后位图像素矩形裁剪,另存为 mz_crop_<毫秒>.jpg(不覆盖原图)。同步两参数 API,无 success / fail 回调。坐标系由业务页换算(演示工程 pages/camera/crop.vue)。推荐:拍完 → 裁剪页(可跳过)→ 预览。

import { cropCameraPhoto } from '@/uni_modules/mz-custom-camera'

// rect 须为字符串(勿拆成四个 number:iOS 桥会丢掉值为 0 的数字字段)
const outPath = cropCameraPhoto(photoPath, '100,80,800,800')
if (outPath) {
  // 新图 path,格式同拍照;原图仍在 getCameraPhotoList
} else {
  // 失败:参数无效 / 读图失败 / 写盘失败
}
参数 / 返回 类型 说明
path String 源图路径,带不带 file:// 均可
rect String "x,y,width,height",相对正向位图像素;宽高须大于 0
返回值 String 成功为新图 path(Android 绝对路径;iOS 多为 _doc/mz-custom-camera/mz_crop_*.jpg);失败为 ""

导入图片 importCameraPhoto

把本地图片(如 uni.chooseImage 选的相册图)复制进插件拍照目录,之后可被 getCameraPhotoList 读取、deleteCameraPhoto 删除。uni.chooseImage 返回的是临时文件,可能被系统清理,导入后的副本不会失效。同步执行,返回是否成功。

import { importCameraPhoto } from '@/uni_modules/mz-custom-camera'

uni.chooseImage({
  sourceType: ['album'],
  success: (res) => {
    importCameraPhoto({
      paths: res.tempFilePaths,
      success: (r) => console.log(r.paths), // 导入后的新路径,与传入顺序一一对应
      fail: (err) => console.log(err.errCode, err.errMsg)
    })
  }
})
参数 类型 说明
paths String[] 必填。本地图片路径数组,带不带 file:// 均可;相对路径(如 _doc/xxx)会先转换为绝对路径。空数组 → fail(9101002)
success Function { paths }:导入后的新路径,格式同拍照返回的 path
fail Function 9101002 参数错误;9101007 导入失败(源文件不存在或复制失败,errMsg 末尾带失败的路径);9101010 无 App Context(Android)
complete Function 成功或失败都会调用

说明:

  • 新文件命名为 mz_album_<毫秒时间戳>.<原后缀>,后缀沿用原文件,不做格式转换。
  • 多张中任一导入失败则整体失败,本次已复制的文件会被删除。
  • 导入的是副本,原图片不受影响;会额外占用一份存储空间。
  • 后续用导入后返回的新路径(而不是原临时路径)做展示、上传、删除。

删除照片 deleteCameraPhoto

删除插件拍摄的照片文件(Android filesDir/mz-custom-camera;iOS _doc/mz-custom-camera 及回退目录 Documents/mz-custom-camera)。同步执行,返回是否成功。

import { deleteCameraPhoto } from '@/uni_modules/mz-custom-camera'

// 按完整路径删除(拍照返回的 path,带不带 file:// 均可),一张也传数组
deleteCameraPhoto({
  paths: [pathA, pathB],
  success: () => console.log('已删除'),
  fail: (err) => console.log(err.errCode, err.errMsg)
})

// 删除插件拍照目录下全部照片
deleteCameraPhoto()

// 删除全部,并接收回调
deleteCameraPhoto({ success: () => {}, fail: (err) => {} })
参数 类型 说明
paths String[] 拍照返回的完整路径数组。不传参数或不传 paths = 删除全部;空数组,或数组中任一路径不在插件拍照目录下 → fail(9101002),不会删除任何文件
success Function { paths },全部删除时 paths 为 null
fail Function 9101002 路径不合法;9101006 删除失败;9101010 无 App Context(Android)
complete Function 成功或失败都会调用

说明:

  • 只能删除插件拍照目录下的文件(插件拍的照片、importCameraPhoto 导入的图片),其它路径会被拒绝。
  • 文件本就不存在时视为成功;多张中有任一删除失败则回调 fail(9101006),其余文件仍会删除。
  • 只删文件,不会修改业务侧保存的历史记录;如有记录需自行同步删除(示例工程见下文「拍照历史记录」)。
  • 删除后该路径的 <image> 将无法显示,上传等操作请在删除前完成。

拍照历史记录

推荐改用插件 API 管理照片,不再自己保存路径。 旧的保存路径方式仍然可用,但需要业务侧维护记录,相册选的临时文件还可能被系统清理导致失效。改用插件 API 后,列表直接读取文件,删除文件后列表自动同步。

// 旧写法:拍照 / 选图后自己存路径
pushPhotoSearchHistory(path)
const list = getPhotoSearchHistory()

// 推荐写法:拍照无需处理;相册选图先导入,再统一读取
importCameraPhoto({ paths: res.tempFilePaths, success: (r) => { /* 用 r.paths */ } })
const { list } = getCameraPhotoList() // list: [{ path, time, source }]
deleteCameraPhoto({ paths: [path] })

插件包内的 example/custom-ui.nvue 已改为推荐写法(含点击对焦框)。

以下为旧方式的说明:示例工程原先的「我拍过的」由 utils/photoSearchHistory.js 实现(不在插件包内,需要时复制到自己的项目)。记录存于 uni.setStorageSync('mzCustomCameraHistory'),每条为 { path, time },新图置顶、按 path 去重,最多 20 条。

import {
  getPhotoSearchHistory,
  pushPhotoSearchHistory,
  deletePhotoSearchHistory
} from '@/utils/photoSearchHistory.js'

pushPhotoSearchHistory(path)          // 记录一张图
const list = getPhotoSearchHistory()  // [{ path, time }]

删除历史记录 deletePhotoSearchHistory

// 全部删除
deletePhotoSearchHistory()

// 按图片完整路径删除(即拍照返回的 path,带不带 file:// 均可)
deletePhotoSearchHistory('_doc/mz-custom-camera/mz_cam_1760000000000.jpg')

// 一次删除多条
deletePhotoSearchHistory([pathA, pathB])

// 只删记录,保留图片文件
deletePhotoSearchHistory(path, { deleteFile: false })
deletePhotoSearchHistory({ deleteFile: false }) // 全部删除,保留文件
参数 类型 说明
path String | String[] 图片完整路径;不传则删除全部。传了但为空(undefined / '')时不删除任何记录
options.deleteFile Boolean 默认 true:同时调用插件 deleteCameraPhoto 删除图片文件。按路径删除时只删插件拍照目录下的文件(插件拍的照片、importCameraPhoto 导入的图片),未导入的相册选图不动;全部删除时清空整个插件拍照目录(包括已不在历史记录里的旧照片)

返回值:删除后的历史列表(同步)。文件删除失败不影响记录删除。


自定义 UI 布局

┌─────────────────────────────┐
│  nvue 自定义层(绝对定位)     │  ← 返回 / 取景框 / 快门 / 相册
├─────────────────────────────┤
│  <mz-custom-camera>         │  ← 仅原生预览,铺满全屏
└─────────────────────────────┘

插件不绘制业务控件。


错误码

API fail

errCode 含义
9101001 无相机权限 / 用户拒绝
9101002 参数错误
9101003 无可用摄像头
9101004 预览绑定失败
9101005 拍照失败
9101006 删除照片失败
9101007 导入照片失败
9101008 提取视频封面失败
9101009 裁剪照片失败(预留;cropCameraPhoto 为同步 API,失败返回 "",不走本表 fail)
9101010 未知错误

组件 @error

常见:NO_PERMISSION、NOT_READY、BIND_FAILED、CAPTURE_FAILED 等,带 message。


注意事项

  1. 必须自定义基座 / 云打包包含本插件,标准基座无法使用。
  2. 相机组件只能放在 nvue 页;结果预览等可用普通 vue 页。
  3. Vue2 / Vue3 拍照方式不同,见上文对照表;Vue3 请用 takeCameraPhoto({ success })。
  4. 拍照视野:Android 用 CameraX ViewPort、iOS 按预览层宽高比裁切,成片与 FILL_CENTER / resizeAspectFill 预览所见一致(1.0.8)。
  5. 路径
    • iOS:多为 _doc/mz-custom-camera/xxx.jpg(vue / nvue 均可直接或按需转换后给 <image>)
    • Android:绝对路径(展示时按需加 file://)
    • 上传可用 uni.uploadFile;普通 vue 页若绝对路径显示异常,可转 _doc 或参考示例 resolveVueImageSrc
  6. iOS 混编 Swift:同目录类型直接使用,不要写 import { Xxx } from './Xxx'。
  7. 上架 Google Play:建议 HBuilderX ≥ 4.81,AAB 渠道;勿引入未适配 16KB 的其它 native 库。
  8. 闪光灯:取值 off(关闭)/ on(开启)/ auto(自动);运行时用 updateFlashMode,不要调用 setFlashMode。

隐私说明

  • 仅本地预览、拍照与录像,不会自动上传或采集其它隐私数据
  • 权限:相机;录像时另需麦克风(相册由业务自行 uni.chooseImage)

兼容与依赖

项 说明
HBuilderX ≥ 4.25;上架 Google Play 建议 ≥ 4.81
Android androidx.camera:*:1.4.2(见 utssdk/app-android/config.json)
Vue Vue2:$refs.takePhoto;Vue3:takeCameraPhoto({ success })

参考:UTS 插件 · 兼容模式组件 · 原生混编

隐私、权限声明

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

CAMERA、RECORD_AUDIO(录像时)

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

本插件仅在本地使用相机进行预览、拍照与录像,不会上传任何隐私数据

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

无