更新记录

1.2（2026-09-30）

新增录像（暂停/继续、画质/限时/限大小）、水印预览与成片烧录（地理钉/多图标/斜向平铺）、连拍、人脸框与抓脸、微距、超广角、缩放/曝光/对焦 API、HDR·夜景成像增强与成片锐

1.1（2024-10-22）

支持设换摄像头 支持声音设置

1.0（2024-04-10）

• 支持任意自定义界面
• 支持手势缩放
• 支持裁剪（手势拖动、比例设置、旋转）
• 支持自定义保存路径

平台兼容性

原生插件通用使用流程：

1. 购买插件，选择该插件绑定的项目。
2. 在HBuilderX里找到项目，在manifest的app原生插件配置中勾选模块，如需要填写参数则参考插件作者的文档添加。
3. 根据插件作者的提供的文档开发代码，在代码中引用插件，调用插件功能。
4. 打包自定义基座，选择插件，得到自定义基座，然后运行时选择自定义基座，进行log输出测试。
5. 开发完毕后正式云打包

付费原生插件目前不支持离线打包。
Android 离线打包原生插件另见文档 https://nativesupport.dcloud.net.cn/NativePlugin/offline_package/android
iOS 离线打包原生插件另见文档 https://nativesupport.dcloud.net.cn/NativePlugin/offline_package/ios

注意事项：使用HBuilderX2.7.14以下版本，如果同一插件且同一appid下购买并绑定了多个包名，提交云打包界面提示包名绑定不一致时，需要在HBuilderX项目中manifest.json->“App原生插件配置”->”云端插件“列表中删除该插件重新选择

自定义相机插件（组件版）Ba-CameraView

简介

Ba-CameraView 是一款自定义相机原生组件，可在任意 nvue 界面嵌入使用。支持拍照、裁剪、水印、微距、录像、连拍、缩放/曝光、视频流、人脸抓拍等能力。

核心能力

1. 任意自定义界面（组件模式） — 相机只占一块预览区，全屏/半屏/卡片均可；上下左右任意叠业务控件
2. 取景控制 — 前后摄、闪光灯、手势/API 缩放、曝光、点击对焦、微距、超广角
3. 拍照 — 自定义路径、JPEG 画质、前摄镜像、拍后裁剪、连拍
4. 录像 — 开始 / 暂停 / 继续 / 停止；画质档位、限时、限大小、有声/无声
5. 水印 — Ba-WatermarkView 预览 + 成片烧录（所见即所得）；地理钉、多图标、斜向平铺
6. 人脸 — 原生框检测；captureFace 抓整帧 + 人脸图（可多人脸）
7. 画质增强 — HDR/夜景等成像增强（机型支持时）、成片锐化
8. 预览对齐 — ViewPort 预览与成片 FOV 一致；支持全屏 / 9:16 / 1:1 等比例布局

注意：原生组件请使用 nvue

兼容说明：保留旧版基础用法（load / takePicture / switchCamera / setListener），旧业务一般无需改代码；新增能力为可选扩展。

有建议和需要，请联系QQ：2579546054

也可关注博客，实时更新最新插件：

uniapp 常用原生插件大全

一、组件说明

功能一览

二、快速开始

Demo 提供两种布局（API 相同，仅容器不同）：

1）全屏布局

<template>
    <view class="container">
        <Ba-CameraView ref="cameraView" class="camera-view" :load="loadData"></Ba-CameraView>
        <!-- 水印预览（可选）：叠在相机区域上 -->
        <!-- <Ba-WatermarkView ref="watermarkView" class="watermark-view"></Ba-WatermarkView> -->
    </view>
</template>

.container { flex: 1; height: 100%; }
.camera-view { flex: 1; width: 750rpx; }

2）半屏嵌入

<template>
    <view class="page">
        <!-- 上方业务内容 -->
        <text class="tip">标题 / 表单等</text>
        <view class="camera-box" :style="{ height: cameraH + 'px' }">
            <Ba-CameraView ref="cameraView" class="camera-view" :load="loadData"></Ba-CameraView>
        </view>
        <!-- 下方快门、说明等 -->
    </view>
</template>

.camera-box {
    width: 702rpx;
    /* height 由脚本设为约半屏，如 windowHeight * 0.42 */
    border-radius: 20rpx;
    overflow: hidden;
    background-color: #000;
}
.camera-view { flex: 1; width: 702rpx; }

3）基础调用示例

export default {
    data() {
        return {
            loadData: {
                isToast: true,
                isShowVibrate: true, // 拍照落盘 / 录像结束时震动
                isShowBeep: true,    // 拍照落盘 / 录像结束时提示音
                zoom: true           // 手势捏合缩放
            }
        }
    },
    onReady() {
        this.$refs.cameraView.setListener((res) => {
            if (res.action === 'error') {
                console.log(res.msg)
            }
        })
    },
    methods: {
        onTakePicture() {
            this.$refs.cameraView.takePicture((res) => {
                // res.ok / res.msg / res.data.path
                console.log(JSON.stringify(res))
            })
        },
        switchCamera() {
            this.$refs.cameraView.switchCamera((res) => {
                console.log(res.msg)
            })
        },
        openLight() {
            this.$refs.cameraView.openLight((res) => {})
        },
        closeLight() {
            this.$refs.cameraView.closeLight((res) => {})
        }
    }
}

统一回调格式

三、load 配置

loadData: {
    isToast: true,
    isShowVibrate: true,
    isShowBeep: true,
    zoom: true,
    facingFront: false,
    targetSize: 0,
    jpegQuality: 95,
    mirrorFront: false
}

四、拍照 API

takePicture(callback, options)

预览宽高比：见下文「推荐：预览比例与成片对齐」。原生通过 CameraX ViewPort 让预览与成片 FOV 一致；scaleFlag:0（full）时成片即预览可见区域。指定其它比例（或 scaleW/H）会在此基础上再裁；若预览框比例与传入不一致，可能出现「方预览、竖成片」等所见非所得。

jpegQuality：CameraX 在绑定 ImageCapture 时固定压缩质量。运行中 setJpegQuality / takePicture({ jpegQuality }) 只写入偏好，当前这一张仍用绑定时的质量；下次绑定（如切摄像头、重新进页）才用新值。进页即生效请用 load.jpegQuality。

回调 data

takeBurst(callback, options) 连拍

成功时 data.paths 为路径数组，data.count 为张数。

推荐：预览比例与成片对齐（必读）

原生用 CameraX ViewPort + UseCaseGroup，预览与拍照共享同一可视裁切。业务侧请理解两套概念：

推荐做法（多数业务）

默认使用 full（scaleFlag: 0），用布局把 Ba-CameraView（及水印）做成目标比例：

• 全屏铺满 → 容器 flex:1 全屏 + scaleFlag: 0
• 半屏方块 / 卡片 → 容器做成正方形或你需要的比例 + scaleFlag: 0
• 竖屏条（9:16）→ 容器做成 9:16 + scaleFlag: 0

这样 成片 FOV = 预览框所见，水印坐标也同一框，所见即所得。

// 推荐：布局已是目标比例时
this.$refs.cameraView.takePicture(cb, { scaleFlag: 0 })
// 或不传 scaleFlag（内部默认按预览区域）

何时传固定比例（9:16 / 1:1 等）

仅当 预览框也会做成同一比例，并明确要强制成片为该比时，再传 scaleFlag: 1~4 或 scaleW/H。Demo 的 previewAspect 会同时改容器尺寸并传入对应参数。

设置 full 时，容器不同会怎样

full 不会强行铺满整屏；只表示「成片跟当前 PreviewView 实际大小对齐」。

结论：布局做成啥比例，在 full 下预览和成片就一起变成啥比例。

错配会怎样（避免）

一句话：要所见即所得 → 优先 full，比例交给容器；只有成片必须强制某比且预览框也按该比做时，再设固定 scaleFlag。

水印叠层

Ba-WatermarkView 必须与相机放在同一容器内叠放（position: absolute 盖住预览），不要盖住整页（含顶部按钮区），否则「左上」会画到按钮上。

.camera-wrap { flex: 1; position: relative; overflow: hidden; }
.camera-view { flex: 1; }
.watermark-view { position: absolute; top: 0; left: 0; right: 0; bottom: 0; }

Demo：previewAspect（预览宽高比）

Demo 按场景隔离存储：ba_camera_demo_settings__{scene}，字段 previewAspect。

各场景默认（恢复默认后生效；本地已存配置需点「恢复默认」）：

• 设置页：场景专属项在上方；前摄 / JPEG / 缩放等在底部 「更多参数」→ 展开
• 综合效果 / 水印 / 水印相机：顶栏也可切换预览比例
• 业务侧若不走 Demo：自行约束预览容器宽高；推荐 scaleFlag: 0，或传与容器一致的 scaleFlag / scaleW/H

const PREVIEW_ASPECTS = {
    'full': { scaleFlag: 0 },
    '9:16': { scaleFlag: 1 },
    '3:4': { scaleFlag: 2 },
    '1:1': { scaleFlag: 3 },
    '4:3': { scaleFlag: 4 },
    '16:9': { scaleFlag: 0, scaleW: 16, scaleH: 9 }
}
// 仅当预览框已是 9:16 时再这样传
this.$refs.cameraView.takePicture(cb, Object.assign({
    jpegQuality: 95
}, PREVIEW_ASPECTS['9:16']))

switchCamera / setSessionMode / setFlashMode / cycleFlashMode / openLight / closeLight

切换前后摄像头（录像中不可切换）。

拍照 / 录像会话（推荐，类似系统相机）：setSessionMode(cb, { mode: 'photo'|'video' })。

• photo：只绑预览+拍照，偏好高像素成片
• video：绑预览+拍照+录像，保证能录
  切换会短暂重载预览。默认进入为 photo；系统相机 Demo 在切「拍照/录像」Tab 时会调用。纯录像页可在就绪后调一次 video，或依赖 startRecord 内自动 ensureVideoBound。
  成功时 data.sessionMode / videoAvailable。

拍照闪光：setFlashMode(cb, { mode: 'auto'|'off'|'on'|'torch' })，默认建议 auto；cycleFlashMode 按 自动→开启→常亮→关闭 循环。
成功时 data.flashMode。常亮 torch 会打开 Torch；其余模式关闭 Torch。
openLight / closeLight / toggleLight 仍可用于单独控制常亮。
getCameraState 含 hasFlash / flashMode / torchOn / sessionMode。

缩放 / 曝光 / 状态

成像增强：基于 CameraX Extensions，效果取决于厂商实现，不等同系统相机 HDR+。录像会话会忽略增强（切回 photo 后生效）。
用 getCaptureEnhance 看：available=本机支持列表；applied=当前是否真正绑上；fallback=true 表示请求了但未生效（原因见 reason）。
成片锐化：软件后处理，不依赖 OEM；默认约 0.35，可按观感调低或关闭。

五、微距 API

五.1、人脸框 API

基于 CameraX ImageAnalysis + ML Kit Face Detection。开启后原生在预览上绘制四角框；坐标也会通过 setListener 回调。

startFaceDetect / setFaceDetectOptions

captureFace options

captureFace 回调 data

listener face 的 data.faces[]

// 推荐：拍照会话下做人脸（勿与录像会话强行四开）
this.$refs.cameraView.setSessionMode(() => {}, { mode: 'photo' })
this.$refs.cameraView.startFaceDetect((res) => {
  console.log(res.ok, res.data)
}, {
  boxColor: '#FFFFFFFF',
  intervalMs: 200,
  analysisWidth: 480,
  analysisHeight: 360,
  cropPad: 0.18
})
this.$refs.cameraView.setFaceDetectOptions((res) => {}, { intervalMs: 250, boxColor: '#FF4ADE80' })
this.$refs.cameraView.setListener((res) => {
  if (res.action === 'face') {
    // res.data.count / res.data.faces[]
  }
})
this.$refs.cameraView.captureFace((res) => {
  // res.data.framePath 整帧；res.data.paths 人脸；res.data.count
}, { all: true, waitMs: 3500 })
this.$refs.cameraView.stopFaceDetect(() => {})

注意：

• 依赖 ML Kit Face Detection，会增加 APK 体积；需可访问 Google ML Kit 模型（部分无 GMS 环境需自行验证）
• 建议在 **sessionMode: photo** 下使用；与录像四用例（预览+拍照+录像+分析）并存时，部分机型会绑失败并降级
• Demo「人脸框」页：设置可改框色 / 间隔 / 分析分辨率 / 裁切外扩；自动抓节奏（稳定时长、抓取间隔）为 Demo 逻辑，非原生必选参数
• captureFace 默认在 waitMs（3500）内持续等待有人脸的分析帧再裁切；超时才返回失败（预览有框但瞬间无分析帧时，多数情况可等出来）
• all:true 时同一分析帧裁多张，避免多次调用抓到不同时刻
• 提高 analysisWidth/Height 可能更准但更卡；改分辨率需重绑
• 抓取结果来自分析流分辨率，清晰度通常低于 takePicture 成片

六、录像 API

startRecord options

注意：录像过程中无法切换摄像头 / 切换画质。

七、事件监听 setListener

八、水印（Ba-WatermarkView + 拍照烧录）

预览与成片共用同一套样式字段；推荐 一份 cfg 同步两边：

1. Ba-WatermarkView.updateConfig(cfg) → 屏幕预览叠层
2. Ba-CameraView.setWaterMark(cfg) → 成片烧录缓存
3. takePicture / takeBurst 可不传 waterMark（沿用第 2 步）；仍传则会覆盖本次。

load.waterMark 仅初始化成片侧，不会自动更新 Ba-WatermarkView 预览。

推荐用 items[] 描述多元素（多图标、图文组合、全屏斜向平铺、任意坐标）。
旧字段 texts / lines / position / icon 仍兼容，等价于单个图文块。

waterMark 顶层配置

items[] 元素

Demo「自定义」可开启 叠加斜向平铺（type=tile），参数与「全屏斜向工牌」共用，并在设置页标出字段名：text / textSize / textColor / bold / angle / gapX / gapY。

// 斜向平铺
items: [{
  type: 'tile',
  text: '张三 · 工号 10086',
  textSize: 13,
  textColor: '#55FFFFFF', // 支持透明度
  bold: false,
  angle: -32,   // 旋转角（度）
  gapX: 200,    // 水平间距（设计宽360）
  gapY: 110     // 垂直间距（设计宽360）
}]

// 自定义图文 + 底层斜向平铺（items 里同时放 tile 与 group）
items: [
  { type: 'tile', text: '…', angle: -32, gapX: 200, gapY: 110, textSize: 13, textColor: '#55FFFFFF' },
  { type: 'group', text: '地点', position: 0, /* … */ }
]

示例 1：时间地点 + 多图标任意位

const waterMark = {
    visible: true,
    items: [
        {
            type: 'group',
            icon: 'location',
            backgroundColor: '#00000000',
            x: 0.04, y: 0.93, anchor: 'leftBottom',
            lines: [
                { text: '河北省衡水市……初级中学', textSize: 14, textColor: '#ffffff' },
                { text: '2026-09-25 16:20 星期五', textSize: 12, textColor: '#CCFFFFFF' }
            ]
        },
        { type: 'icon', icon: 'check', iconSize: 18, x: 0.94, y: 0.93, anchor: 'rightBottom' }
    ]
}
this.$refs.watermarkView.updateConfig(waterMark)
this.$refs.cameraView.setWaterMark(() => {}, waterMark)
this.$refs.cameraView.takePicture(cb)

示例 2：全屏斜向工牌（姓名·工号）

const waterMark = {
    visible: true,
    items: [{
        type: 'tile',
        text: '张三 · 工号 10086',
        angle: -32,
        textSize: 13,
        textColor: '#55FFFFFF',
        gapX: 200,
        gapY: 110
    }]
}

Ba-WatermarkView 方法

setWatermarkTexts / updateConfig / getConfig / setVisible / setTextColor / setBackgroundColor / setTextSize / setPosition / clearWatermark / refresh

Ba-CameraView 水印方法

九、权限说明

十、示例 Demo

• 各场景配置独立（ba_camera_demo_settings__{scene}）
• 进页绑定（前摄 / targetSize / jpegQuality / 启动微距）：总览 → 初始化页修改 →「进入演示」；页内只读
• 运行参数（缩放手势、震动、镜像、比例、水印等）：页内 ⚙ 可改，返回即刷新；多数场景在 「更多参数」 折叠区
• 预览宽高比：优先布局 + scaleFlag:0；Demo 可用顶栏 / 设置切换（见上文「推荐：预览比例与成片对齐」）

十一、常见问题

Q：为什么必须用 nvue？
A：原生组件在 vue 页面中叠层与事件兼容性较差，推荐 nvue。

Q：业务接入预览比例怎么设？一定要传 9:16 吗？
A：多数情况建议 full（scaleFlag: 0），用布局控制相机容器比例，成片跟预览框对齐。只有预览框也做成同一比例、且必须强制成片为该比时，再传 scaleFlag / scaleW/H。详见「推荐：预览比例与成片对齐」。

Q：设置了 full，页面容器是正方形或 9:16 会怎样？
A：full 表示成片跟 当前 PreviewView 实际大小 对齐，不额外固定裁切。容器是方 → 成片取景≈方；容器是 9:16 → 成片≈竖条。不会因为写了 full 就强制全屏。

Q：设置了 9:16，但界面相机仍是正方形？
A：预览方、成片可能按 9:16 再裁（竖图），所见非所得。请让容器比例与拍照参数一致，或改用 full + 正确布局。

Q：水印预览有了，成片没有 / 不一致？
A：预览与烧录是两条通道。推荐同一份 cfg：watermarkView.updateConfig(cfg) + cameraView.setWaterMark(cfg)，之后 takePicture 可不传 waterMark。仍兼容旧写法：拍时再传 { waterMark: cfg }。水印组件须叠在相机区域内，勿盖整页。

Q：预览宽高比 Demo 怎么设？水印默认多少？
A：Demo 在对应场景设置里改 previewAspect，或顶栏切换。水印 / 水印相机默认 **9:16**（恢复默认后）；其它多数场景默认 full。各场景配置独立，可删存储键 ba_camera_demo_settings__{scene}。

Q：点击对焦白框位置不对 / 看不见？
A：对焦框由原生 FocusRingView 绘制（与点击同一坐标系）。不要用 nvue position:fixed 再叠一层，坐标系会错位；请使用最新 AAR（对焦框在 PreviewView 外层兄弟叠层）。

Q：裁剪取消后 takePicture 一直没回调？连点快门挂住？
A：已修复。取消裁剪会回调 ok:false, msg:'用户取消裁剪'；连点会立刻回调 正在拍照，请稍候（不会覆盖上一笔）。裁剪过程中也会挡住再次拍照，直到完成或取消。

Q：jpegQuality / setJpegQuality 改了，这张照片怎么没变？
A：正常。质量在绑定相机时定死，运行中只记偏好，下次绑定才生效。要用指定质量进页，请设 load.jpegQuality；运行中改完可切一次前后摄或重新进入页面。不会为改质量立刻 rebind，以免拍照报 Not bound。

Q：拍照报 Not bound to a valid Camera [ImageCapture]？
A：多为绑定后再次 rebind 导致。当前版本改 jpegQuality 不会立刻重绑；请使用最新 AAR。若仍出现，检查是否在录像/切换过程中连续调用会解绑的接口。

Q：提示当前设备不支持录像？
A：部分机型无法同时绑定预览+拍照+录像，会自动降级；已加强 SD 回退。若仍失败，可在设置里把录像画质改为 SD 再试。

Q：❀ 小花是什么？
A：微距模式开关，开启后会拉近焦距便于近拍。

Q：右下角按钮是什么？
A：前后摄像头翻转；录像中不可切换。

Q：facingFront 改了不生效？
A：属启动配置，需重新进入页面；演示里可在设置中修改后返回，必要时再进一次该场景页。

Q：录像中切换摄像头失败？
A：设计如此，请先 stopRecord 再切换。

Q：人脸框开了，录像或四开失败？
A：人脸依赖 ImageAnalysis。建议 setSessionMode({ mode:'photo' }) 后再 startFaceDetect。与录像同时开时，部分机型无法绑定「预览+拍照+录像+分析」，会降级或启用人脸失败。

Q：预览有人脸框，captureFace 却超时失败？
A：框来自检测，抓图要再等一帧做 YUV→Bitmap 裁切。默认 waitMs:3500 内会重试；仍失败可增大 waitMs，或确认未在录像中、分析流已成功绑定（startFaceDetect 返回 ok）。

Q：抓到的人脸不如 takePicture 清晰？
A：正常。captureFace 来自低分辨率分析流（默认约 480×360 量级），用于框选/留证；高清成片请用 takePicture。

Q：裁剪比例不生效 / 成片比预览多一圈？
A：原生已用 ViewPort 对齐预览与成片。scaleFlag:0（推荐默认）时成片即预览可见区域。若要固定比例，请同时约束预览框并传对应 scaleFlag / scaleW/scaleH。isCrop: true 走的是拍后交互式裁剪库，与 ViewPort 自动对齐是两回事。