x-camrea-u 原生相机

原生相机预览。拍照、录像、闪光灯、变焦、水印，以及预览帧输出（给人脸 / OCR 等）。

插件目录名是 camrea，按这个拼写引用。

兼容性

Harmony	IOS	Android	WEB	小程序
支持	支持	支持	支持	支持

调用

<x-camrea-u
  ref="cameraRef"
  resolution="medium"
  device-position="back"
  flash="off"
  :auto-open="true"
  @done="onCameraDone"
  @frame="onFrame"
></x-camrea-u>

cameraRef.value?.takePhoto({
  format: "jpg",
  quality: 85,
  success: (r) => {
    console.log(r.tempFilePath)
  }
})

cameraRef.value?.startRecord({ withAudio: true })
cameraRef.value?.stopRecord({
  success: (r) => {
    console.log(r.tempFilePath, r.duration)
  }
})

参数

字段	说明	默认
resolution	low / medium / high	medium
devicePosition	front / back	back
flash	auto / on / off / torch	off
frameSize	预览档 small / medium / large	medium
autoOpen	初始化后自动开相机	true
enableFrame	是否输出预览帧	false
frameThrottle	帧最小间隔 ms，0 不限	100

事件

名称	参数	说明
done	{ state, resolution, devicePosition, flash, frameSize, flashSupported, minZoom, maxZoom }	相机就绪
stop	{ state, reason }	关闭、销毁或出错停止。reason 为 close / destroy / error
error	{ errSubject, errCode, errMsg }	打开或运行失败
frame	{ width, height, format, rotation, mirrored, timestamp, data }	预览帧，仅 enableFrame。format：Android nv21，iOS bgra，鸿蒙 rgba

方法

名称	需要	说明
open	可选 success / fail / complete	打开相机
close	可选 success / fail / complete	关闭相机
takePhoto	format?（jpg/png，默认 jpg）、compressed?（默认 true）、quality?（1~100，默认 85）、maxWidth? / maxHeight?（0 不限）、success	拍照，成功返回 tempFilePath、宽高、大小
startRecord	format?（mp4）、withAudio?（默认 true）、success	开始录像
stopRecord	可选 success / fail / complete	停止录像，成功返回 tempFilePath、duration
setZoom	zoom: number（1 为不缩放）	设置变焦，成功返回当前 / 最小 / 最大倍率
setWatermarks	items[]：icon?、text?、fontSize?、color?、position?（四角）、margin?	设置预览和成片水印
getState	无	返回当前状态：idle / opening / ready / recording / stopped / destroyed

平台差异

1. Web 无真闪光灯和变焦（minZoom=maxZoom=1）。
2. 鸿蒙图标水印不烧录到成片。

版本

版权归https://xui.tmui.design你不得修改及二次开发，仅供TMUI4会员商用使用。不得转给非VIP会员使用，一经查实数倍赔偿，并追究法律责任。

更新日志

1.1.0（2026-07-31）

• 新增 setWatermarks Ref 方法：图标（左）+ 文字（右）水印，支持四角位置、字号、颜色
• 水印在预览层实时显示，拍照后按「输出图片宽度 / 预览宽度」等比合成，预览与成图占比一致
• 有水印时拍照跳过未压缩直出快速通道，保证水印必然合成

1.0.0

• Android CameraX 原生预览
• 支持分辨率、摄像头朝向、闪光灯和预览帧尺寸属性
• 支持相机初始化、终止和错误事件
• 支持 JPEG/PNG 拍照、压缩质量和目标尺寸
• 支持 MP4 录像及可选麦克风录音
• 支持线性相机倍率控制
• 使用 DCloud 风格 success/fail/complete 方法回调
• 媒体文件保存到应用专属外部目录
• 无闪光灯摄像头使用 auto/off 时可正常初始化
• 关闭或销毁会取消尚未结束的权限请求，避免旧回调重启相机