更新记录
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 原生插件,标准基座无法运行。
- HBuilderX → 运行 → 制作自定义调试基座
- 勾选
mz-custom-camera - 用自定义基座真机运行
正式发版请云打包并包含本插件。修改原生代码后需重新制作基座。
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。
注意事项
- 必须自定义基座 / 云打包包含本插件,标准基座无法使用。
- 相机组件只能放在 nvue 页;结果预览等可用普通 vue 页。
- Vue2 / Vue3 拍照方式不同,见上文对照表;Vue3 请用
takeCameraPhoto({ success })。 - 拍照视野:Android 用 CameraX ViewPort、iOS 按预览层宽高比裁切,成片与
FILL_CENTER/resizeAspectFill预览所见一致(1.0.8)。 - 路径
- iOS:多为
_doc/mz-custom-camera/xxx.jpg(vue / nvue 均可直接或按需转换后给<image>) - Android:绝对路径(展示时按需加
file://) - 上传可用
uni.uploadFile;普通 vue 页若绝对路径显示异常,可转_doc或参考示例resolveVueImageSrc
- iOS:多为
- iOS 混编 Swift:同目录类型直接使用,不要写
import { Xxx } from './Xxx'。 - 上架 Google Play:建议 HBuilderX ≥ 4.81,AAB 渠道;勿引入未适配 16KB 的其它 native 库。
- 闪光灯:取值
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 }) |

收藏人数:
购买普通授权版(
试用
使用 HBuilder 导入示例项目
赞赏(0)
下载 63
赞赏 0
下载 12779170
赞赏 1960
赞赏
京公网安备:11010802035340号