更新记录

1.0.2（2026-08-07）

• Android Kotlin 根包由 com.xview.camera 调整为 com.xview.cameraview，目录同步为 com/xview/cameraview，与插件名 xview-camera-view 对齐

1.0.1（2026-08-07）

• 方法命名统一：change* → set*（如 changeFlash → setFlash、changeFacing → setFacing）；takeVideo → startVideo，destroyCamera → destroy。
• 抽取 shared.uts，组件事件透传 detail JSON。
• 修复 iOS 拍照与 HarmonyOS 编译、权限、录像问题。
• 新增 getCameraCapabilities()（含 boundCameraId）；优化 Android 超广角切换与逻辑多摄连续变焦。

1.0.0（2026-07-02）

新增

• 首发 xview-camera-view（Android / iOS / HarmonyOS / 微信小程序 / Web），统一 easycom 与跨平台事件。
• 方法：open · reopen · close · destroyCamera · isOpened · openAppSettings · takePhoto · takeVideo · stopVideo · changeFacing · changeFlash · changeMode · changePhotoFormat · changeResolution · changeSaveToAlbum · changeWhiteBalance · changeHdr · changeExposure · changeAudio · changeLinearZoom · changeZoomRatio · switchUltraWide · resetZoom · changeGrid · changeCorner · changePreviewRotate · changeZoomGesture · changeTapFocus · changeTargetSize · changeKeyShortcut · changeRecordSound · changeFeedback

平台兼容性

uni-app x(5.06)

xview-camera-view

xview-camera-view 是面向 uni-app x 的标准模式相机组件，提供 Android CameraX、iOS AVFoundation、HarmonyOS CameraKit、微信小程序内置 <camera>，以及 Web 浏览器原生摄像头能力。

仅支持 uni-app x（.uvue + UTS）。普通 uni-app / nvue 不在支持范围内。

能力概览

• easycom 组件：<xview-camera-view />，放入 uni_modules 后无需手动注册
• 统一事件回调：打开/关闭、拍照、录像进度、聚焦、缩放、状态变化与异常
• 默认插槽：可在预览层之上叠加遮罩、按钮等人机界面（见示例「自拍遮罩」「身份证遮罩」）
• 组件挂载后自动 open()；页面 onShow 可配合 reopen() / close() 管理生命周期

基础用法

组件需占满可用预览区域（建议绝对定位铺满父容器）。在 Options API 页面中，通过 ref + $callMethod 调用组件方法：

<template>
  <view class="page">
    <xview-camera-view
      ref="cameraRef"
      class="camera-view"
      facing="back"
      flash="off"
      photo-format="jpg"
      grid="draw_3X3"
      :save-to-album="false"
      @onPictureTaken="onPictureTaken"
      @onCameraError="onCameraError"
      @onCameraTakenError="onCameraTakenError"
    />
    <image class="shutter" src="/static/camera/shutter.png" @click="takePhoto" />
  </view>
</template>

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

export default {
  methods: {
    callCamera(action: (ref: CameraViewElement) => void) {
      const cameraRef = this.$refs['cameraRef'] as CameraViewElement | null
      if (cameraRef != null) {
        action(cameraRef)
      }
    },
    takePhoto() {
      this.callCamera((ref) => {
        ref.$callMethod('takePhoto')
      })
    },
    onPictureTaken(e: any) {
      // Android/iOS 原生层：e.detail 含 path、width、height、isFront 等
      console.log('picture taken', e.detail)
    },
    onCameraError(e: any) {
      console.log('camera error', e.detail)
    }
  }
}
</script>

<style>
.page {
  position: absolute;
  top: 0;
  left: 0;
  right: 0;
  bottom: 0;
  background: #000;
}
.camera-view {
  position: absolute;
  top: 0;
  left: 0;
  right: 0;
  bottom: 0;
}
</style>

插槽与遮罩

组件提供默认插槽，内容渲染在预览层之上，适合实现取景框、水印、操作栏：

<xview-camera-view ref="cameraRef" class="camera-view" facing="front">
  <!-- 遮罩层放在插槽外同级亦可，示例项目多采用绝对定位 overlay -->
</xview-camera-view>
<view class="camera-mask">
  <image src="/static/mask/touxiang.png" />
</view>

遮罩层 z-index 应低于操作按钮，避免拦截快门点击。可参考 pages/camera/mask-selfie.uvue。

示例入口

本项目为 uni-app x 示例工程，示例目录遵循 DESIGN.md：

pages/
  index/index.uvue          # 示例主页（导航与能力概览）
  camera/*.uvue             # 按功能划分的相机示例页

在 HBuilderX 运行后，首页 pages/index/index 可进入各子示例。

录像

// 开始录像（maxDuration 为最大时长毫秒数，0 或不传表示不限时，需手动 stopVideo）
ref.$callMethod('startVideo', 0)

// 定时录像（10 秒后自动停止）
ref.$callMethod('startVideo', 10000)

// 停止录像
ref.$callMethod('stopVideo')

Props

多数 props 支持运行时响应；也可通过同名 set* 方法动态修改。

组件方法

通过 ref.$callMethod('methodName', ...args) 调用。组件销毁前建议调用 destroy()。

生命周期

getCameraCapabilities() 建议在 onCameraOpened 后调用，返回：

{
  facing: 'front' | 'back',
  ready: boolean,
  boundCameraId: string, // 当前实际绑定的镜头 id；Android 为 Camera2 cameraId
  minZoomRatio: number,
  maxZoomRatio: number,
  linearZoom: number,
  zoomRatio: number,
  supportsZoom: boolean,
  supportsUltraWide: boolean,
  lenses: LensInfo[] // Android：仅 CameraX 可 bind 镜头，与 boundCameraId 同源
}

查询接口始终返回完整结构：相机未打开时 ready 为 false、boundCameraId 为空字符串；Web、微信和 HarmonyOS 当前不支持组件内物理超广角切换，因此 supportsUltraWide 为 false。

Android：lenses 仅包含默认逻辑镜头组与 switchUltraWide() 的 rebind 目标（与 boundCameraId 切换一致），不会列出其它 back-facing CameraInfo 中的 physical id（如华为 id=8）。请用 boundCameraId 判断当前预览实际绑定的镜头。

拍摄

镜头与画质

缩放

预览与交互

事件

事件名以 @onXxx 绑定，e.detail 为 payload；五端字段名已对齐 Android（path/width/height/duration、zoom 四元组、progress 时间字段）。

平台能力矩阵（硬限制）

不支持的能力统一通过 onCameraError 返回错误码 9010003（能力不支持）或 9010004（设备未就绪），不会再用空 stub 或伪成功 onCameraChange。

常用 payload 字段

onCameraOpened（Android/iOS）

onPictureTaken（Android/iOS）

onVideoTakenStart

onVideoTakenProgress

onVideoTakenEnd

onFocusStart / onFocusEnd

onZoomChanged

onCameraTakenError / onCameraError