更新记录

1.2.0（2026-07-19） 下载此版本

初次提交

平台兼容性

uni-app x(5.21)

其他

laoqianjunzi-camera

laoqianjunzi-camera 是一个面向 uni-app x / uni-app Vue3 项目的 UTS 相机插件，统一封装了 Android、iOS、Harmony、Web 四端的相机预览、拍照、录像、水印、绿幕和帧流能力。

本文档只描述当前插件已经提供的 API、组件和示例，不涉及旧插件、旧实现或兼容层。

功能概览

• 相机预览：支持前后镜头切换、闪光灯、缩放、预览尺寸、渲染缩放比。
• 拍照能力：支持高/中/低/原图质量、保存相册、前摄镜像、自定义文件名。
• 录像能力：支持高/中/低质量、最大时长、音频开关、暂停与恢复。
• 水印能力：支持标题、行文案、键值项面板、位置、字号、颜色、圆角、面板宽度。
• 元信息能力：支持时间、地址、业务字段拼装，可与水印面板联动展示。
• 绿幕能力：支持 HSV 范围、形态学开闭运算、腐蚀/膨胀、高斯模糊、透明预览。
• 帧流能力：支持持续回调原始帧数据，用于视觉分析、检测或自定义处理链路。
• 独立拍照页：提供 openWatermarkCapture，可直接打开插件内置的全屏水印拍照页。

适用平台

当前插件按 package.json 中的声明支持以下平台：

权限说明

插件会用到如下权限：

• Android：CAMERA、RECORD_AUDIO
• iOS：Camera、Microphone、Photo Library、Photo Library Add
• Harmony：CAMERA、MICROPHONE

如果你的业务需要保存照片或视频到相册，还需要保证目标平台的相册写入权限链路已经打通。

安装后如何验证

安装插件后，可以直接打开插件内置示例页：

• 示例页路径：uni_modules/laoqianjunzi-camera/pages/index
• 全屏水印拍照内部页：uni_modules/laoqianjunzi-camera/pages/watermark-capture/index

示例页已经覆盖以下现有能力：

• 预览打开/关闭
• 拍照与录像
• 闪光灯与镜头切换
• 缩放控制
• 帧流回调
• 全屏水印拍照

快速开始

1. 使用预览组件

插件提供了现成的 easycom 组件：<laoqianjunzi-camera />

<template>
    <laoqianjunzi-camera
        class="camera"
        :autoStart="false"
        :enableAudio="false"
        :position="'back'"
        :flashMode="'off'"
        :watermark="watermarkConfig"
        :meta="metaConfig"
        @ready="handleReady"
        @photo="handlePhoto"
        @error="handleError"
    />
</template>

页面需要滚动时，App 端请使用 scroll-view 包裹页面内容；uni-app x App 端页面默认不滚动。

2. 使用组件实例方法

组件内部已经封装了当前 API 的常用调用，适合业务页面直接通过 ref 操作：

<template>
    <laoqianjunzi-camera ref="cameraRef" class="camera" :autoStart="false" />
</template>

<script lang="uts">
export default {
    methods: {
        openPreview() {
            const camera = this.$refs.cameraRef
            camera.open()
        },
        takePhoto() {
            const camera = this.$refs.cameraRef
            camera.take({
                quality: 'high',
                saveToAlbum: false
            })
        }
    }
}
</script>

3. 直接调用顶层 API

如果你更希望通过统一上下文或顶层方法来调用，也可以直接从插件根入口导入：

import {
    openCameraPreview,
    closeCameraPreview,
    takeCameraPhoto,
    startCameraRecord,
    stopCameraRecord,
    switchCameraLens,
    setCameraFlashMode,
    setCameraZoom,
    updateCameraWatermark,
    updateCameraMeta,
    setCameraGreenScreen,
    setCameraPreviewSize,
    setCameraScalingRatio,
    startCameraFrameFeed,
    stopCameraFrameFeed,
    openWatermarkCapture,
    createLaoqianjunziCameraContext
} from '@/uni_modules/laoqianjunzi-camera'

对外能力说明

组件 Props

laoqianjunzi-camera 主要支持这些属性：

组件事件

组件实例方法

组件通过 defineExpose 暴露了以下方法，适合业务页通过 ref 直接调用：

顶层 API 清单

插件根入口当前导出了这些方法：

关键配置对象

水印配置 LaoqianjunziCameraWatermarkConfig

适用于拍照结果叠加信息面板，常用字段如下：

• enabled：是否启用
• anchor：topLeft、topRight、bottomLeft、bottomRight
• title：水印标题
• lines：多行说明文案
• items：键值项面板列表
• textColor、titleColor、detailColor：文字颜色
• backgroundColor：背景色
• padding、lineSpacing：内边距与行距
• fontSize、titleFontSize、detailFontSize：字号
• cornerRadius：圆角
• panelWidth：面板宽度

元信息配置 LaoqianjunziCameraMetaConfig

用于时间、地址、业务字段聚合展示：

• title
• timeText
• addressText
• lines
• items

组件内部会把 meta 与 watermark 合并，用于预览和输出图像的同构展示。

绿幕配置 LaoqianjunziCameraGreenScreenConfig

如果你的场景涉及抠像或替换背景，可用这些字段：

• enabled
• startColor / endColor
• morphOpen / morphClose
• dilate / erode
• gaussianBlur
• scalingRatio
• previewWidth / previewHeight
• backgroundColor
• transparentPreview

全屏水印拍照

openWatermarkCapture(options) 适合“一次打开、完成后立即返回结果”的拍照场景，例如打卡、巡检、取证。

openWatermarkCapture({
    cameraPosition: 'back',
    flashMode: 'off',
    title: '现场巡检',
    timeText: '2026-07-08 14:35:20',
    addressText: '浙江省杭州市滨江区',
    lines: ['施工点位 A-12', '责任人：张工'],
    items: [
        { label: '班组', value: '安装一组' },
        { label: '天气', value: '晴天 26°C' }
    ],
    saveToAlbum: false,
    closeAfterCapture: true,
    success: (result) => {
        console.log('拍照成功', result.tempFilePath)
    }
})

openWatermarkCapture 主要参数

返回结果

预览就绪 LaoqianjunziCameraReadyResult

拍照结果 LaoqianjunziCameraPhotoResult

录像结果 LaoqianjunziCameraRecordStopResult

错误码

插件当前定义了统一错误码：

开发注意事项

• uni-app x App 端页面默认不可滚动，示例页这类长页面请使用 scroll-view 包裹。
• 使用 display: flex 时，请显式声明 flex-direction，避免和 Web 默认值混淆。
• uni-app x App 端样式以 class 选择器为主，不要依赖标签选择器、#id 选择器或复杂层级选择器。
• 文本样式不会从父容器继承，请把字号、颜色、行高直接写在 <text> 上。
• 帧流回调频率较高，业务层建议自行节流或只在需要时开启。
• 录像开启音频时，要确保对应平台麦克风权限已经授权。
• Web 端的录像容器和相机权限行为受浏览器实现限制，建议优先在 Chrome / Safari 最新版本验证。

示例页对应文件

• 示例页：uni_modules/laoqianjunzi-camera/pages/index.uvue
• 全屏水印拍照页：uni_modules/laoqianjunzi-camera/pages/watermark-capture/index.uvue
• 组件：uni_modules/laoqianjunzi-camera/components/laoqianjunzi-camera/laoqianjunzi-camera.uvue
• 类型定义：uni_modules/laoqianjunzi-camera/utssdk/interface.uts