更新记录

1.0.0（2026-09-30）

• 首次发布：uni-app x 标准模式 UVC 摄像头组件
  • 打开 / 关闭摄像头、预览、拍照、录像
  • 设备列表获取与切换、分辨率获取与设置、旋转与镜像
  • UVC 参数读写（绝对值 / 百分比）、亮度与对比度调节

平台兼容性

uni-app x(4.27)

其他

zy-uvc-x

USB 摄像头（UVC）uni-app x 标准模式组件（uts-vue-component）。

• 仅实现 Android（iOS / HarmonyOS 提供占位实现，调用回传 9010010 当前平台暂不支持）
• 回调式 API：方法入参传 { success, fail }，同时通过 @onResult 事件回传相同内容

功能

• 打开 / 关闭摄像头，开启 / 关闭预览
• 获取设备列表、按设备名 / id / 产品名 / 索引切换摄像头
• 获取 / 设置预览分辨率、旋转、镜像，获取预览配置
• 拍照（可选时间戳水印、自定义文件名）、录像 / 停止录像（含录音开关、码率、帧率）
• 读写全部 UVC 参数（亮度、对比度、饱和度等 25 项），支持绝对值与百分比

快速开始

easycom 规范，无需 import 即可直接使用：

<template>
    <view class="page">
        <zy-uvc-x ref="uvcRef" class="camera" @load="onload" @onResult="onResult" @onDeviceState="onDeviceState"></zy-uvc-x>
        <button @click="open">打开摄像头</button>
    </view>
</template>

<script setup lang="uts">
    const uvcRef = ref<ComponentPublicInstance | null>(null)

    function onload() {
        console.log("组件初始化完成")
    }

    function open() {
        uvcRef.value?.$callMethod('openCamera', {
            success: (result) => {
                // result: { code: 0, msg: "摄像头已打开", data: { deviceName, previewing } }
                console.log(result.msg + " " + JSON.stringify(result.data))
            },
            fail: (error) => {
                // error: { code: 9010001, message: "未发现USB摄像头设备" }
                console.log(error.code + " " + error.message)
            }
        })
    }

    function onResult(e: UniNativeViewEvent) {
        // 与 success / fail 回调内容一致：{ type: "openCamera", data: { code, msg, data } }
        console.log(JSON.stringify(e.detail))
    }

    function onDeviceState(e: UniNativeViewEvent) {
        // { type: "onCameraOpen" | "onCameraClose" | "onDetach" | "onCancel" | "onError", ... }
        console.log(JSON.stringify(e.detail))
    }
</script>

<style>
    .camera {
        width: 100%;
        height: 300px;
    }
</style>

调用说明

• 组件已通过 defineExpose 显式暴露全部方法，vapor 模式下使用 $callMethod('方法名', options) 调用。
• success / fail 每次调用最多触发一次，回调在主线程派发。
• 未传 success / fail 时，仍可从 @onResult 事件中拿到 type 与结果。
• 部分方法（openCamera、switchCamera、takePicture、startRecord、stopRecord）为异步原生流程，结果可能在调用后的下一个事件循环返回。

预览控制

openCamera 默认 autoPreview: true，打开成功后自动开始预览。若只想暂停画面而不拔出摄像头，用 stopPreview / startPreview：

// 停止预览（摄像头仍保持打开）
uvcRef.value?.$callMethod('stopPreview', {
    success: (result) => {
        // result.data = { previewing: false }
        console.log(result.msg)
    }
})

// 恢复预览
uvcRef.value?.$callMethod('startPreview', {
    success: (result) => {
        // result.data = { previewing: true }
        console.log(result.msg)
    }
})

• 摄像头未打开时调用回传 9010006；原生启动 / 停止预览失败回传 9010008。
• 预览是否正在输出可用 isCameraOpen 查询（isPreviewing 字段）。
• 停止预览期间拍照、录像、参数读写仍需摄像头处于打开状态，与预览开关无关。
• 重新调用 startPreview 或切换分辨率（setResolution）都会重新启动预览。

读取全部可调参数（标准 TS 取值）

getAllParams 的 data 是 UTSJSONObject，推荐 JSON.stringify + JSON.parse<T> 转成类型化对象后直接按属性访问：

uvcRef.value?.$callMethod('getAllParams', {
    success: (result) => {
        const data: ParamsData | null = JSON.parse<ParamsData>(JSON.stringify(result.data))
        if (data == null || data.params == null) return
        const params = data.params
        for (let i = 0; i < params.length; i++) {
            const p = params[i]
            if (p.supported != true) continue
            console.log(p.label + " " + p.current + " [" + p.min + "," + p.max + "]")
        }
    }
})

type ParamRaw = {
    name: string
    label: string
    supported: boolean
    isBool: boolean
    current: number
    percent: number
    min: number
    max: number
    def: number
}
type ParamsData = {
    count: number
    params?: ParamRaw[]
}

个别参数（如部分摄像头的 brightness、autoExposureMode）可能 supported = true 但 min === max（驱动未上报范围），生成滑块前请先判断 max > min。

API

方法

所有方法的 success 收到 UvcResult { code, msg, data }，fail 收到 UvcError { code, message }。

类型定义见 utssdk/interface.uts。

Options 类型

每个 Options 均可携带 success / fail 回调（下表最后两行统一说明，其余类型不再重复列出含义）。

success.data 结构

ParamRaw 字段：name / label / supported / isBool / current / percent / min / max / def。

UVC 参数

是否支持由摄像头固件决定，以返回的 supported 字段为准。

绝对值 vs 百分比

换算规则：

• 数值参数：percent = round((value - min) * 100 / (max - min))，写入时 value = min + round(percent * (max - min) / 100)，结果截断在 [min, max] 内。
• 布尔参数：current != 0 → 100，否则 0；写入时 percent >= 50 → 1，否则 0。
• getBrightnessPercent / setBrightnessPercent、getContrastPercent / setContrastPercent 是 brightness / contrast 的百分比快捷方法，等价于 getParamPercent / setParamPercent。
• 四个方法均要求摄像头已打开且参数 supported，否则回传 9010006（未打开）或 9010007（不支持的参数）。

事件

错误码

权限

组件已在 utssdk/app-android/AndroidManifest.xml 中声明：

• android.permission.CAMERA
• android.permission.RECORD_AUDIO
• <uses-feature android:name="android.hardware.usb.host" />

首次调用 openCamera 会自动申请运行时权限，被拒绝时回传 9010014。录像需额外的录音权限，被拒绝时同样回传 9010014。

注意事项

• 依赖原生 AAR（utssdk/app-android/libs/libuvccamera-release.aar），运行至标准基座时原生部分不生效，需使用自定义基座。
• <native-view> 不能作为带兄弟节点的元素的子节点，组件自身需具备宽高（width / height），且不支持 background / border 等样式。
• 拍照、录像文件保存在应用私有目录 uvcX 下，success.data 中返回 path（绝对路径）与 uri。
• setRotation 仅接受 0 / 90 / 180 / 270，setMirror 仅接受 0 / 1 / 2 / 3，取值非法回传 9010009。
• 拔出 USB 设备会触发 @onDeviceState 的 onDetach，并回传 9010001。
• 组件在 onUnmounted 时自动释放原生资源，页面卸载前无需手动调用销毁方法。

目录结构

zy-uvc-x/
├── components/zy-uvc-x/zy-uvc-x.uvue   # easycom 组件（方法转发 + defineExpose）
├── utssdk/
│   ├── interface.uts                   # 类型定义（Options / UvcResult / UvcError）
│   ├── app-android/
│   │   ├── index.uts                   # Android 实现
│   │   ├── utils.uts                   # 参数、设备、分辨率工具
│   │   ├── AndroidManifest.xml         # 权限与 USB feature 声明
│   │   └── libs/*.aar                  # libuvccamera
│   ├── app-ios/index.uts               # 占位实现（9010010）
│   └── app-harmony/index.uts           # 占位实现（9010010）
├── changelog.md
└── readme.md

参考

• UTS 语法
• UTS 插件
• UTS 插件-标准模式组件
• UTSJSONObject