更新记录

1.0.0（2026-11-06）

• Android uni-app x 原生可嵌入 CameraX 相机组件，显式启动与权限申请。
• JPEG拍照、真实MP4录像（默认静默）、前后摄、缩放、对焦与补光；拍照/录像各两UseCase。
• 实际显示预览帧 PNG 与规范化坐标取色，明确预览分辨率/旋转镜像边界。
• 严格拍摄模板与有界产物，每个成功输出计算真实字节SHA256并提交证据JSON。
• 自有UseCase生命周期、录制Finalize、代际取消、回调隔离与缓存预留。

平台兼容性

uni-app(4.84)

uni-app x(4.84)

其他

Nexus 自定义相机

Nexus Wang · Android uni-app x · 1.0.0

把真实相机预览嵌入自己的页面，在预览旁放置业务按钮与说明。支持 JPEG 拍照、MP4 录像、前后摄、缩放、对焦、补光、实际预览帧抓取与像素取色。提供严格拍摄模板和每份产物的 SHA256 证据侧车。

普通授权 ¥29.90，源码授权 ¥299.00。仅 Android uni-app x 标准模式，Android 6.0 / API 23+；其他平台、普通 uni-app、后台或隐藏拍摄未实现。正式机型的相机、编码器与分辨率能力由设备决定。

接入与权限

依赖 CameraX 1.6.1（camera-core/camera-camera2/camera-lifecycle/camera-view/camera-video），由 app-android/config.json 声明。宿主 Activity 必须实现 LifecycleOwner。新增依赖/权限后重建调试基座。Manifest 声明 CAMERA 与 RECORD_AUDIO；运行时只在显式 requestCameraPermissions 时申请，audio 未设或 false 不申请录音权限。

<template>
  <view style="height: 320px;">
    <nexus-camera-core :cameraId="cameraId" @ready="onReady" @statechange="onState" />
  </view>
  <button @click="start">启动预览</button>
</template>
<script setup lang="uts">
import * as Camera from '@/uni_modules/nexus-camera-core'
import { CameraOptions } from '@/uni_modules/nexus-camera-core'
const cameraId = 'order-camera'
function onReady(res: UTSJSONObject): void { console.log('mounted', res) }
function onState(res: UTSJSONObject): void { console.log('actual state', res) }
function start(): void {
  const permission: CameraOptions = {
    cameraId,
    success: (res: UTSJSONObject) => {
      const options: CameraOptions = { cameraId, mode: 'PHOTO' }
      Camera.startCamera(options)
    },
    fail: (err: UTSJSONObject) => { console.log(err) }
  }
  Camera.requestCameraPermissions(permission)
}
onUnload(() => {
  const options: CameraOptions = { cameraId }
  Camera.destroyCamera(options)
})
</script>

组件 ready 仅表示已挂载，不自动请求权限或启动镜头；需要先等待 ready，再由用户操作启动。cameraId 在一个组件生命周期内固定，不通过响应式改 ID 复用组件。公开 API 必须从模块根目录导入。演示位于 example/uniappx/camera-demo.uvue，没有宿主日志组件依赖，也没有自动拍摄流程。叠加 UI 由宿主布局实现，不内置快门样式。

公开 API

createCameraId() 同步生成 UUID 镜头 ID；除其与 mountCameraView（使用 CameraMountOptions）外，其余函数使用同一个具名 CameraOptions，所有调用须填写 cameraId。回调统一 { code, message, data }；success 或 fail 之一与 complete 各至多一次，在主线程投递，业务回调抛异常不会变成第二次 API 失败。录制的 startCameraRecording 特别在最终文件与证据就绪后才 success，开始时监听组件 recordstart。

组件事件：ready、statechange（实际状态）、recordstart、recordcomplete（完整终态 envelope）、error（挂载错误）。组件 ref 使用框架 ComponentPublicInstance / $callMethod；主要业务建议直接按 cameraId 调公开 API。defineExpose 提供 start(options)、pause/resume/stop/dispose。

拍摄模板

CameraTemplate 可选字段如下，未知字段、错误类型、小数整数参数、超界值均拒绝，不静默扩大限制。JSON null 使用默认/继承值。

PHOTO 只绑定 Preview+ImageCapture；VIDEO 只绑定 Preview+VideoCapture，不组合四个 UseCase。不声称固定输出像素尺寸、精确帧率、视频裁切后处理或传感器原始数据。到达时长/文件限制的 CameraX Finalize 视为预期停止，仍须真实 MP4 可读、非空且不超过字节限制，stopReason 返回原生终态码。其他终态错误删除输出并 fail。

图像方向与证据边界

预览帧和取色来自屏幕上 PreviewView 的实际 bitmap，包含其显示旋转、裁剪与前摄镜像；分辨率是预览控件像素，不是传感器全分辨率。JPEG 可能用 EXIF 标记方向，读取 exifOrientation 正确显示；JPEG/MP4 不额外做前摄镜像，视频实际旋转返回 metadata.rotation。像素颜色来自预览图像处理结果，不作传感器/色卡的校准色值。

每份成功输出写应用私有随机文件，同时提交 .evidence.json（临时 part→rename）。包括输出真实字节数/SHA256、类型、时间、请求模板与实际媒体 metadata；返回 evidencePath。SHA 只证明与该文件字节的一致性，不是签名、时间戳公证或内容真实性证明。不上传、不写公共相册、不覆盖调用方文件。缓存文件可被系统回收，需业务自行复制到持久业务目录。

最多四个挂载视图；后台输出单工作线程、等待队列 4。整个插件缓存设 512MiB / 128文件保守预留（每个待输出预留模板字节上限、2文件与64KiB侧车预算，实际文件和预留可重复计入而提前拒绝）。此为插件的保守预留/最终提交限制，不是操作系统硬磁盘配额；CameraX 写入过程中仍可能出现短暂额外磁盘占用。超限明确失败，不自动删除已交付图片。单次预览 bitmap 上限 8MP、边长4096；超限拒绝，不强行申请大图。CameraX 的设备端编码/内存仍受硬件资源约束，多预览并发可能不支持。

生命周期与验收

必须是已附着、可见、处于前台的组件才可启动/拍摄。Activity ON_STOP 自动停止自己的录制并释放自己的用例；返回页面不会自动恢复。卸载/销毁后旧代际回调不再交付照片/预览帧；未交付文件会清理。录像暂停/停止时先完成 Finalize，销毁时取消未交付产物；从不调用 unbindAll。控件命令异步完成时校验代际。

错误码：9071001 入参/状态/忙碌，9071002 权限桥，9071003 绑定/控制失败，9071004 工作队列（部分路径以9071006返回输出失败），9071005 取消，9071006 输出/录像失败。请以 code!=0 判失败并展示 message，不把挂载或绑定成功当作真实拍摄成功。

本轮验收记录（2026-11-06）

Android 14 / Redmi 22101317C，HBuilderX 5.34、uni-app x：23条相机原生核心检查通过；公开UTS驱动24条后摄操作断言通过，28次被跟踪API调用逐一确认success/fail互斥、complete一次且调用/回调均在主线程。范围包含PHOTO/VIDEO实际OPEN+STREAMING、JPEG、预览PNG、取色、1/2倍缩放、中心对焦控制、补光开关、录像期间模式切换拒绝、静音录像Finalize、暂停/恢复与销毁API状态。挂载事件不计入28次API回调数。

照片2448×1836、实际控件预览帧981×880、H.264 MP4 720×406约2.63秒（计时在真实recordstart后约3秒发起停止），视频无音轨。三份真实产物已从应用私有目录独立读回，解码、真实字节大小、SHA256与证据侧车均一致；分辨率和时长只代表本机本次样本。生产演示页截图是未启动镜头的真实默认状态，不是录像画面。

暂停/停止验证了当前会话解绑命令和引用状态；state.cameraState在无引用时为CLOSED，不据此宣称独立观察到了硬件关闭事件。未测试前摄产物、有声录制、全部质量档位、60秒/存储极限、多视图并发和长期资源稳定性；其他机型/系统与普通uni-app未验收。对焦返回值按设备实际结果读取，不保证所有场景对焦命中。测试前由使用者准备无隐私画面，再显式授权与拍摄。

官方依据：CameraX 录像架构、PreviewView API、UTS 插件。CameraX 使用 Apache 2.0 开源许可。