更新记录

0.1.0（2026-04-18）

初始化安卓插件，暂不支持ios

平台兼容性

uni-app(4.45)

Vue2 Vue3 Chrome Safari app-vue app-nvue Android iOS 鸿蒙
√ √ - - √ √ 5.0 - -
微信小程序 支付宝小程序 抖音小程序 百度小程序 快手小程序 京东小程序 鸿蒙元服务 QQ小程序 飞书小程序 小红书小程序 快应用-华为 快应用-联盟
- - - - - - - - - - - -

uni-app x(5.0)

Chrome Safari Android iOS 鸿蒙 微信小程序
- - - - - -

yt-camera（仅 App Android / iOS）

本文档只说明在 App 真机 上、nvue 页面（APP-NVUE）通过 uts-native-view 使用 UTS 原生相机的写法。不涉及 H5、小程序或其它端。

前提：使用 nvue 页面；工程已集成 uni_modules/yt-camera 并完成 App-Android / App-iOS 云打包或本地运行。

示例页：pages/custom-camera/custom-camera.nvue

一、页面中使用方式

1. 模板

<yt-camera
  ref="cam"
  class="camera"
  :devicePosition="devicePosition"
  :flash="flash"
  :zoom="zoom"
  @ready="onReady"
  @photo="onPhoto"
  @error="onError"
  @devicechange="onDeviceChange"
  @flashchange="onFlashChange"
  @zoomchange="onZoomChange"
/>

组件需占有明确宽高（如 class="camera" 里写 width / height）。

2. 数据与事件（与 UTS 事件载荷兼容）

UTS 抛出的事件载荷常为 Map，用 e.get("key")；经封装后也可能是普通对象，建议两种都判断。拍照结果在 nvue 里多在 e.detail。

export default {
  data() {
    return {
      devicePosition: "back",
      flash: "off",
      zoom: 1,
      maxZoom: 5,
    };
  },
  methods: {
    onReady(e) {
      this.maxZoom = (e && (e.get ? e.get("maxZoom") : e.maxZoom)) || 5;
    },
    onPhoto(e) {
      const detail = (e && e.detail) || {};
      const path = detail.tempFilePath || detail.tempImagePath || "";
    },
    onError(e) {
      const msg = (e && e.get ? e.get("errMsg") : null) || (e && e.errMsg) || "相机错误";
    },
    onDeviceChange(e) {
      const pos = e && e.get ? e.get("devicePosition") : e && e.devicePosition;
      if (pos) this.devicePosition = pos;
    },
    onFlashChange(e) {
      const f = e && e.get ? e.get("flash") : e && e.flash;
      if (f) this.flash = f;
    },
    onZoomChange(e) {
      const z = e && e.get ? e.get("zoom") : e && e.zoom;
      if (z != null) this.zoom = z;
    },
  },
};

3. 通过 ref 调用方法

const cam = this.$refs.cam;

// 拍照（无参数）
if (cam && cam.takePhoto) cam.takePhoto();

// 闪光灯（与 data 中 flash 配合：可先改 flash 再调，或只调此方法）
if (cam && cam.setFlashMode) cam.setFlashMode("torch");

// 缩放，数值建议在 1 ~ maxZoom 之间（maxZoom 来自 onReady）
if (cam && cam.setZoomValue) cam.setZoomValue(2);

切换前后摄：推荐只改父页面数据 devicePosition 为 "back" / "front"，由原生层 watch 重启预览。若再调用组件的 switchCamera()，容易与父级状态重复，二选一即可。

二、属性说明（Props）

以下属性写在 yt-camera 上，会传入内部 uts-native-view（模板里对应 device-position、flash、zoom、show-controls 等 kebab-case）。

属性 类型 默认值 说明
devicePosition String "back" "back" 后置，"front" 前置。修改后 Android 会重新打开对应摄像头预览；iOS 侧由当前 UTS 实现随 devicePosition 建会话。
flash String "off" "off" | "on" | "auto" | "torch"。Android：映射到 Camera.Parameters。iOS：当前源码主要同步事件，硬件闪光灯/手电筒以 utssdk/app-ios/index.vue 实现为准。
zoom Number 1 逻辑倍率 1 ~ maxZoom。Android 内部为 1-based，对应 API 的 0 .. getMaxZoom。
showControls Boolean false 为 true 时在组件内显示「切换镜头 / 闪光灯 / 拍照」三个按钮；自定义 UI 时一般用 false。

仅 Android 原生层（utssdk/app-android/index.vue）额外支持：

属性 类型 默认值 说明
debug Boolean false 为 true 时输出更多调试日志。

三、事件说明

事件名 说明
ready 预览已就绪。载荷含 maxZoom：Android 为支持缩放时 getMaxZoom() + 1，否则为 1；iOS 当前实现里固定为 5。
photo 拍照成功。含 tempFilePath、tempImagePath（多为 file://）、rawFilePath（绝对路径）。nvue 中常从 e.detail 取。
bindphoto 与 photo 同一次拍照会再派发一份（兼容部分端事件名）。不要与 photo 绑同一回调，否则 onPhoto 会执行两次；只监听其一即可。
error 失败信息，字段 errMsg。
devicechange 前后摄切换，字段 devicePosition。
flashchange 闪光灯模式变化，字段 flash。
zoomchange 缩放变化，字段 zoom（含双指手势与 setZoomValue）。

四、实例方法说明（ref）

方法 参数 说明
takePhoto 无 触发原生拍照；成功时先后触发 photo 与 bindphoto（内容相同），业务上只监听 @photo 即可。
setFlashMode mode: string 设置闪光灯模式，并触发 flashchange；Android 会写进相机参数。
setZoomValue value: number 设置缩放；封装层会按组件内 maxZoom（默认 5） 做钳位，与原生 ready 上报的最大值未必一致，大倍率机型上若需与 ready 完全一致，宜在业务侧限制滑条范围或与封装层同步 maxZoom。
switchCamera 无 组件内部切换前后摄。与「只改父级 devicePosition」二选一。
cycleFlash 无 按 off → on → auto → torch → off 循环，一般配合内置控制条使用。

五、Android 与 iOS 行为差异（摘要）

项目 Android iOS
预览 TextureView + Camera，center-crop AVCaptureVideoPreviewLayer，aspectFill
maxZoom 随设备 getMaxZoom() 计算 当前固定 5
手势 双指缩放、单击对焦 双指缩放
闪光灯 参数级控制 以当前 iOS UTS 源码为准

六、权限与配置

  • Android：uni_modules/yt-camera/utssdk/app-android/AndroidManifest.xml
  • iOS：uni_modules/yt-camera/utssdk/app-ios/Info.plist（描述文案需符合审核要求）

七、打开示例页

uni.navigateTo({ url: "/pages/custom-camera/custom-camera" });

（路径以项目 pages.json 为准。）

八、云打包日志里的 UILocalNotification 弃用提示

若 iOS 编译输出中出现 UILocalNotification is deprecated 之类说明，来源一般是 DCloud Uni SDK 自带的头文件（例如 DCUniBase.framework / DCUniBase.h），不是 yt-camera 插件里的业务代码。

  • 本插件未使用 UILocalNotification，也无法在 uni_modules/yt-camera 内把它改成 UserNotifications 的 UNNotificationRequest；消除该警告需依赖 HBuilderX / uni-app 官方 SDK 升级 后由厂商替换底层实现。
  • 若你在自己工程的其它原生代码或插件里使用了 UILocalNotification，才需要在那些模块中改为 UserNotifications：注册 UNUserNotificationCenter、用 UNMutableNotificationContent + UNTimeIntervalNotificationTrigger（或日历触发） 组装 UNNotificationRequest，再 add 到当前 UNUserNotificationCenter。

隐私、权限声明

1. 本插件需要申请的系统权限列表：

<uses-permission android:name="android.permission.CAMERA" /> <uses-feature android:name="android.hardware.camera" /> <uses-feature android:name="android.hardware.camera.autofocus" /> <uses-permission android:name="android.permission.RECORD_AUDIO" /> <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" /> <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" /> <uses-permission android:name="android.permission.MANAGE_EXTERNAL_STORAGE" /> <uses-permission android:name="android.permission.CAPTURE_VIDEO_OUTPUT" tools:ignore="ProtectedPermissions" />

2. 本插件采集的数据、发送的服务器地址、以及数据用途说明：

无

3. 本插件是否包含广告，如包含需详细说明广告表达方式、展示频率：

无

评论列表 撰写评论 向官方投诉

暂无用户评论。