更新记录

1.0.0（2026-08-07）

• 首发兼容模式相机组件（Android / iOS）；公开 API 统一 apply* 前缀（兼容模式 iOS 桥接中 set* 会与同名 prop 的 ObjC setter 冲突，故不用 set*）
• 双轨示例：pages/（nvue）、pagesx/（uvue）
• 修复 nvue 多词 props 须 camelCase（如 :keyShortcut），否则快捷键不生效
• 修复 Android 恢复前台后快捷键监听丢失

平台兼容性

uni-app(5.06)

uni-app x(5.06)

其他

xview-camera-viewer

xview-camera-viewer 是面向 uni-app / uni-app x 的兼容模式原生相机组件，提供 Android CameraX 与 iOS AVFoundation 能力。

组件标签：<xview-camera-viewer />。需在 nvue（uni-app）或 uvue（uni-app x）页面中使用。Web / 微信小程序源码已预留，当前 package.json 矩阵未宣称组件可用。

能力概览

• 兼容模式组件：通过 utssdk/app-android|ios/index.vue 提供原生预览
• 统一事件回调：打开/关闭、拍照、录像进度、聚焦、缩放、状态变化与异常
• 默认插槽：可在预览层之上叠加遮罩、按钮等人机界面
• 组件布局完成后自动 open()；页面 onShow 可配合 reopen() / close() 管理生命周期

基础用法

uni-app x（uvue）

<template>
  <view class="page">
    <xview-camera-viewer
      ref="cameraRef"
      class="camera-view"
      facing="back"
      flash="off"
      photoFormat="jpg"
      grid="draw_3X3"
      :saveToAlbum="false"
      @onPictureTaken="onPictureTaken"
      @onCameraError="onCameraError"
    />
    <image class="shutter" src="/static/camera/shutter.png" @click="takePhoto" />
  </view>
</template>

<script lang="uts">
type CameraRef = ComponentPublicInstance

export default {
  methods: {
    takePhoto() {
      const ref = this.$refs['cameraRef'] as CameraRef | null
      ref?.$callMethod('takePhoto')
    },
    onPictureTaken(e: any) {
      console.log('[xview-camera-viewer] picture', e.detail)
    },
    onCameraError(e: any) {
      console.log('[xview-camera-viewer] error', e.detail)
    }
  }
}
</script>

uni-app（nvue）

重要：兼容模式 Android/iOS 原生组件的多词 props 在 nvue 中必须使用 camelCase（如 :keyShortcut="true"、:previewRotate="90"）。
使用 kebab-case（:key-shortcut）时，编译产物仍保留连字符，无法命中 @WXComponentProp(name="keyShortcut")，属性会静默失效。

<xview-camera-viewer
  ref="cameraRef"
  flash="off"
  :keyShortcut="true"
  @onPictureTaken="onPictureTaken"
/>

this.$refs.cameraRef.takePhoto()
this.$refs.cameraRef.applyFacing('front')
this.$refs.cameraRef.applyKeyShortcut(true)

Props

组件方法

通过 ref.$callMethod('methodName', ...args)（uni-app x）或 ref.methodName(...args)（uni-app nvue）调用。

兼容模式说明：与 props 同名的方法在 iOS ObjC 桥接中会与 prop setter 冲突，因此所有公开配置类方法统一使用 apply* 前缀（如 applyFacing、applyFlash、applyZoomRatio、applyTargetSize）。原生层 Manager.set* / CameraBridge.set* 为内部实现，不对外暴露。

生命周期

拍摄

镜头与画质

applyFacing · applyFlash · applyMode · applyPhotoFormat · applyResolution · applySaveToAlbum · applyWhiteBalance · applyHdr · applyExposure · applyAudio

缩放

applyLinearZoom · applyZoomRatio · switchUltraWide · resetZoom

预览与交互

applyGrid · applyCorner · applyPreviewRotate · applyZoomGesture · applyTapFocus · applyTargetSize · applyKeyShortcut · applyRecordSound · applyFeedback

事件

错误码