更新记录

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(5.06)

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 XviewCameraViewElement = ComponentPublicInstance

export default {
  methods: {
    callCamera(action: (ref: XviewCameraViewElement) => void) {
      const cameraRef = this.$refs['cameraRef'] as XviewCameraViewElement | 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/maskSelfie.uvue。

录像

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

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

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

Props

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

组件方法

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

生命周期

拍摄

镜头与画质

缩放

预览与交互

事件

事件名以 @onXxx 绑定，e.detail 为 payload（Web/小程序部分字段可能简化）。

常用 payload 字段

onCameraOpened（Android/iOS）

onPictureTaken（Android/iOS）

onVideoTakenStart

onVideoTakenProgress

onVideoTakenEnd

onFocusStart / onFocusEnd

onZoomChanged

onCameraTakenError / onCameraError

权限

Android：需在宿主 manifest.json 与插件 AndroidManifest.xml 中声明相机、录音、震动及媒体读写权限。示例项目已配置。

iOS：需在宿主 Info.plist 配置相机、麦克风、相册访问说明（NSCameraUsageDescription 等）。

HarmonyOS / 微信小程序 / Web：按各平台规范申请对应权限；Web 需用户授权浏览器摄像头/麦克风。

注意事项

1. 预览组件应置于页面底层并铺满屏幕；操作 UI 使用更高 z-index 的绝对定位层。
2. APP 端页面若需滚动，请按 uni-app x 规范在 App 条件编译下使用 scroll-view 包裹页面内容，相机页通常全屏固定布局。
3. takePhoto() 会依据 props shutterFeedback / shutterSound / vibrate / vibrateDuration 触发快门反馈；动态修改请同步更新 props 或在拍照前通过原生层配置。
4. 跨页面回传拍摄结果时，示例项目使用 uni.$emit 事件总线（如 xview-camera-taken-result），可按业务自行替换。