更新记录

1.0.0（2026-08-04）

初次发布

平台兼容性

uni-app(3.8.1)

uni-app x(3.8.1)

其他

kongbai-camera

面向 App 的原生实时水印相机组件。预览直接嵌入 .nvue 页面布局，不会打开新的相机页面；拍照、录像、扫码、水印、应用沙盒存储和权限处理均在插件内部完成。

核心能力

• 实时写入视频帧：水印在原生视频采集与编码链路中逐帧合成，直接写入最终视频文件；不是录像结束后再导出、转码或批量处理。录制过程中调用 setWatermark(text)，后续视频帧会立即使用新水印。
• 专业级高性能实时处理：预览、实时水印合成与视频录制协同运行，边采集边处理、边录制边写入；编码收尾和文件封装异步执行，减少对页面流畅度、交互响应和持续录制稳定性的影响。
• 适合高频采集场景：支持连续拍摄、长时间录像、边预览边写入水印，适用于现场取证、工程巡检、工地施工记录、物流签收、设备维护、质检验收、巡店拍摄和作业留痕。
• 本地闭环：照片、视频、视频首帧缩略图和媒体记录均写入应用沙盒；插件不采集、不上传用户数据，结果文件可直接交给业务层继续上传、归档或审核。

实际帧率、处理速度和文件大小受设备性能、摄像头规格、分辨率、码率、存储空间和同时启用的音频能力影响；可通过 videoBitrate、videoFrameRate、videoWidth 和 videoHeight 按业务场景调整输出规格。

最简单用法

<template>
  <kongbai-camera :options="cameraOptions" :show-ui="true" @result="onResult" @scan="onScan" @error="onError" @latest-media="onLatestMedia" />
</template>

<script setup lang="ts">
import { reactive } from 'vue'
import type { KBCameraEvent, KBCameraMediaRecord, KBCameraOptions } from '@/uni_modules/kongbai-camera/utssdk/interface.uts'

const cameraOptions = reactive<KBCameraOptions>({
  watermarkText: '现场采集\n请勿篡改',
  initialMode: 'photo',
  autoCloseOnResult: false
})

function onResult(event: KBCameraEvent): void {
  console.log(event.result?.path)
}
function onScan(event: KBCameraEvent): void {
  console.log(event.scanResult)
}
function onError(event: KBCameraEvent): void {
  console.log(event.message)
}
function onLatestMedia(record: KBCameraMediaRecord): void {
  console.log(record)
}
</script>

组件默认挂载后立即启动，页面卸载时自动关闭。项目内 pages/index/index.nvue 是可直接运行的示例。

拍照或录像完成后，插件会将最终媒体写入应用沙盒；写入成功才触发 photo / video 结果事件，保存失败触发 error 事件。结果路径是带 file:// 前缀的 uni-app 可访问路径。

两种界面

无界面模式示例：

<kongbai-camera ref="cameraRef" :options="cameraOptions" :show-ui="false" />

cameraRef 提供 takePhoto()、startRecord()、stopRecord()、setMode(mode)、setFlash(mode)、setWatermark(text)、switchCamera()、open()、close() 和 refreshLatestMedia()。

插件还提供媒体记录 API：getKongbaiMediaList() 获取本地列表，deleteKongbaiMedia(idOrPath) 删除记录中的单个媒体及视频缩略图，deleteKongbaiMediaByPath(path) 按指定路径删除文件（如果路径属于历史记录，会同步删除对应记录及视频缩略图），clearKongbaiMedia() 删除全部媒体。每条记录包含 id、type、path、thumbnailPath（视频）、size、width、height、duration、createdAt 和 watermarkApplied。

开启内置界面时，组件会在闪光灯上方显示历史记录中的最新照片或视频缩略图；点击预览触发 latest-media 事件，回调参数是完整的 KBCameraMediaRecord。拍照或录像完成后预览会自动更新。

无界面模式下可将组件和任意页面控件放进同一个容器，按钮、状态栏、模式切换和水印预览都由业务页面自行布局；相机预览只占用组件自身的尺寸，不会覆盖整个页面。

options

watermarkText 是唯一必传项。其余常用字段：initialMode（photo / video / scan）、initialFlash、cameraPosition、maxDuration、enableAudio、autoCloseOnResult、videoBitrate、videoFrameRate、videoWidth、videoHeight。enableAudio 默认 false；需要录制声音时显式设为 true。

watermarkText 改变后，组件会自动更新后续视频帧的实时水印。

平台

Android 7.0+ 和 iOS 15.0+ 支持拍照、实时水印录像和扫码。媒体文件只写入当前应用的沙盒目录，不申请额外存储权限。

result.path 和 result.thumbnailPath 都是可供业务继续使用的 file:// 本地路径；业务层不要假设具体的沙盒物理目录。

Android 扫码依赖 com.google.mlkit:barcode-scanning:17.3.0，首次运行或修改依赖后必须重新制作包含该插件依赖的自定义调试基座；标准调试基座不能动态增加 ML Kit。