更新记录

1.1.2（2026-05-27）

补充文档

1.1.0（2026-05-27）

新增能力（Android、ios）：

• 点击聚焦 + AF 区域回切连续对焦
• 双指缩放焦距，自动映射 setZoomPercent(0~100) 到设备 maxZoom
• 新 props：default-camera、tap-focus、pinch-zoom、flash-mode
• 闪光灯 4 模式：off / torch / on / auto
• 拍照 4 档画质预设：low / medium / high / ultra
• 视频录制 4 档画质：QUALITY_LOW / 480P / 720P / 1080P
• 视频录制最大时长限制（maxDurationMs），到时自动停止
• 视频录制可选关闭音频（withAudio: false）
• 视频输出格式：mp4 / 3gp
• 音频处理（AEC / NS / AGC），best-effort 模式，自动检测设备能力并在结果中返回
• 新 actions：focusOnPoint、setZoomPercent、getZoomInfo、`setFlas

平台兼容性

uni-app(4.72)

uni-app x(4.72)

hl-custom-photo

hl-custom-photo 当前提供两类能力：

• 原生相机预览组件：预览、拍照、录像、切换摄像头、闪光灯、曝光、缩放、对焦、取帧、取色
• 模块 API：compressImage 图片压缩

当前状态

快速接入

1. 挂载组件

<template>
  <hl-custom-photo
    v-if="cameraMounted"
    class="camera-view"
    :autoStart="autoStartFlag"
    :scale="scale"
    :tapFocus="tapFocusFlag"
    :pinchZoom="pinchZoomFlag"
    :command="commandStr"
    @result="onCameraResult"
    @log="onCameraLog"
  />
</template>

2. 通过 command 下发动作

import { ref } from 'vue'

const commandStr = ref('')
const cameraMounted = ref(true)
const autoStartFlag = ref('1')
const tapFocusFlag = ref('1')
const pinchZoomFlag = ref('1')
const scale = ref('4:3')

let seq = 0
const pendingCallbacks = {}

function sendCommand(action, options, callback) {
  seq += 1
  if (callback) {
    pendingCallbacks[seq] = callback
  }
  commandStr.value = JSON.stringify({
    action,
    options: options || {},
    seq
  })
}

function normalizeEventPayload(event) {
  const detail = event?.detail ?? event

  if (detail?.dynamicJSONFields) {
    return detail.dynamicJSONFields
  }

  const payloadJson = detail?.payloadJson ?? detail?.__json
  if (typeof payloadJson === 'string' && payloadJson.length > 0) {
    try {
      return JSON.parse(payloadJson)
    } catch (e) {
      console.warn('[hl-custom-photo] payloadJson parse failed:', e)
    }
  }

  return detail
}

function onCameraResult(event) {
  const payload = normalizeEventPayload(event)
  const currentSeq = payload?.seq
  if (currentSeq != null && pendingCallbacks[currentSeq]) {
    const cb = pendingCallbacks[currentSeq]
    delete pendingCallbacks[currentSeq]
    cb(payload)
  }
}

function onCameraLog(event) {
  const payload = normalizeEventPayload(event)
  console.log('[native]', payload?.level, payload?.tag, payload?.msg)
}

sendCommand('takePhoto', {
  qualityPreset: 'high',
  returnFile: true
}, (result) => {
  console.log('photo result:', result)
})

3. 如果权限弹窗后预览没有恢复

nvue 页面里可直接卸载再挂载组件：

import { nextTick } from 'vue'

function restartCameraAfterPermission() {
  cameraMounted.value = false
  nextTick(() => {
    cameraMounted.value = true
  })
}

事件

常见返回码约定：

command 动作一览

下面这些 action 当前已经在 Android 和 iOS 的 dispatchAction 里接好，可以直接通过 command 使用。

基础控制

拍照

补充：

• qualityPreset 支持：low、medium、high、ultra
• crop 是百分比裁剪，格式 [x, y, w, h]
• cropPx 是像素裁剪，格式 [x, y, w, h]
• returnFile: true 时通常返回文件路径，否则通常返回 base64

视频录制

audioProcessing 结构示例：

{
  aec: true,
  ns: true,
  agc: false
}

闪光灯 / 曝光 / 缩放 / 对焦

iOS 额外兼容：

• setZoomPercent({ percent, silent: true })
• getZoomInfo({ silent: true })

silent: true 会执行原生动作，但不回发 @result。

取帧 / 取色

注意事项：

• getFrameData 前必须先调 startFrameListen
• getColor.point 建议传 0~100 的百分比坐标
• getColor 取的是单像素，不是区域平均色
• 返回格式通常是 color: "r,g,b"，例如 145,144,163

直接 expose 方法

除了 command，组件还直接暴露了一批方法，例如：

• openCamera
• setCameraConfigAndStart
• setCropOption
• startRealtimeFrame
• pauseRealtimeFrame
• setLogSink

但建议把这些当作高级用法：

• 对业务页面，优先使用 command
• 不是所有 expose 方法都已经映射进 command
• 如果你新增了原生能力，并希望页面统一通过 command 使用，需要同步修改对应平台的 dispatchAction

画质映射

拍照 qualityPreset

视频 quality

设备不支持目标档位时，通常会返回 201。

compressImage API

用法

import * as CustomPhoto from '@/uni_modules/hl-custom-photo'

CustomPhoto.compressImage(
  {
    path: '/storage/emulated/0/DCIM/Camera/test.jpg',
    maxWidth: 1080,
    maxHeight: 1920,
    quality: 80,
    format: 'webp',
    targetPath: '/storage/emulated/0/Android/data/xxx/cache/out.webp'
  },
  (result) => {
    if (result.code === 200) {
      console.log(result.path, result.width, result.height, result.size)
    }
  }
)

参数

返回结果

平台差异

1. @result / @log 事件对象

• Android 端一般可以直接读取 event.detail
• Android 若经过 UTS 包装，通常也能从 event.detail.dynamicJSONFields 拿到 plain object
• iOS 端当前更稳妥的做法是优先读 payloadJson，其次兼容旧的 __json
• 如果 iOS 页面看到的是空对象，不要先怀疑原生没执行，先排查事件解包逻辑

2. takePhoto

• Android 更接近原生静态拍照输出
• iOS 当前稳定实现更偏“预览帧截图后再加工”
• 这意味着 iOS 最终分辨率上限受当前预览帧影响，不完全等同于传感器原图能力

3. 缩放

• Android 适合直接走 getZoomInfo -> setZoomPercent
• iOS 按钮式缩放更建议页面自己维护缩放状态，再调用 setZoomPercent
• iOS 的 silent: true 适合“只下发控制，不关心本次回调”的场景

4. getColor

• Android 当前更接近“开关式”取色
• iOS 当前更接近“单次调用，单次返回”
• 如果业务想两端交互一致，建议页面层统一封装成“点一次，回一次”