更新记录

1.1.0（2026-11-01）

1、兼容蒸汽模式 2、自动对焦 3、缩放 质量自定义

平台兼容性

uni-app(5.26)

uni-app x(5.26)

其他

UTS 原生相机拍照（对焦、缩放、取景框裁切）

原生相机预览、拍照与照片回调，适合证件采集和文档拍摄。附六种取景框、边框颜色与粗细设置，可点击对焦、调整缩放、JPEG 质量、输出长边及取景比例裁切。

版本 1.1.0；HBuilderX 5.26+；Android 6.0+ / iOS 15.0+。普通 uni-app Vue3 使用 austin-camera-view 的 .nvue 入口。

第 1 步：放入插件

将整个 austin-camera-x 目录放到项目的 uni_modules 下，保留 components、utssdk 和 index.uvue。

业务页面导入的是组件文件，完整路径：

import AustinCameraX from '@/uni_modules/austin-camera-x/components/austin-camera-x/austin-camera-x.uvue'

不需要直接导入 utssdk 内的平台文件。

第 2 步：接入拍照页

<template>
  <view class="page">
    <austin-camera-x ref="cameraRef" class="camera"
      cameraPosition="back" flashMode="off" focusMode="continuous"
      :zoom="1" :quality="92" :cropToPreview="false" :maxPhotoEdge="0"
      :previewCornerRadiusRate="0.12"
      @ready="onReady" @captured="onCaptured" @error="onError" />
    <button @click="takePhoto">{{ taking ? '正在拍照…' : '拍照' }}</button>
    <image v-if="previewSrc.length > 0" class="photo" :src="previewSrc" mode="aspectFit" />
  </view>
</template>

<script setup lang="uts">
import { ref, nextTick, ComponentPublicInstance } from 'vue'
import { onShow, onHide } from '@dcloudio/uni-app'
import AustinCameraX from '@/uni_modules/austin-camera-x/components/austin-camera-x/austin-camera-x.uvue'

const cameraRef = ref<ComponentPublicInstance | null>(null)
const ready = ref(false)
const taking = ref(false)
const previewSrc = ref('')

onShow(() => { nextTick(() => { cameraRef.value?.$callMethod('startPreview') }) })
onHide(() => { ready.value = false; taking.value = false; cameraRef.value?.$callMethod('stopPreview') })

function resultData(event: any | null): UTSJSONObject | null {
  if (event == null) return null
  if (event instanceof UTSJSONObject) {
    const object = event as UTSJSONObject
    return object.getJSON('detail') ?? object
  }
  return (event as UniCustomEvent<UTSJSONObject>).detail
}
function onReady(): void { ready.value = true }
function takePhoto(): void {
  if (!ready.value || taking.value) return
  taking.value = true
  cameraRef.value?.$callMethod('takePhoto')
}
function onCaptured(event: any | null): void {
  taking.value = false
  const result = resultData(event)
  if (result == null) return
  const imagePath = result.getString('imagePath') ?? ''
  const fileURL = result.getString('fileURL') ?? ''
  previewSrc.value = fileURL.length > 0 ? fileURL : (imagePath.startsWith('/') ? 'file://' + imagePath : imagePath)
  console.log(imagePath, result.getNumber('width'), result.getNumber('height'))
  // 上传、保存仍使用本次返回的原始 imagePath / uploadFilePath。
}
function onError(event: any | null): void {
  taking.value = false
  const error = resultData(event)
  uni.showToast({ title: error?.getString('errMsg') ?? '拍照失败', icon: 'none' })
}
</script>

<style>
.page { flex: 1; padding: 20px; }
.camera { width: 300px; height: 400px; }
.photo { width: 300px; height: 220px; }
</style>

组件挂载后自动准备预览并申请相机权限；收到 ready 后拍照。新照片以 captured 完成事件为准，不要轮询文件或在调用 takePhoto() 后立即读取路径。

第 3 步：权限与基座

拍照到应用自己的文件目录，不需要麦克风或相册权限。首次导入或更新原生代码后，重新制作并安装包含本插件的自定义基座，再运行页面。正式包同样包含本插件和相机用途说明。

第 4 步：打开完整演示页

在项目 pages.json 的 pages 数组中增加：

{
  "path": "uni_modules/austin-camera-x/index",
  "style": {
    "navigationBarTitleText": "原生相机拍照",
    "pageOrientation": "auto"
  }
}

选择取景框和边框样式，点击画面对焦，再拍照。拍完可查看照片、像素和文件大小，点击照片可放大；“继续拍照”回到相机。对焦方式、缩放、质量、裁切和输出长边位于可展开的“拍照设置”。

六种取景框属于演示布局。业务自行设置组件的宽高和装饰边框即可；点击对焦由原生预览处理，覆盖在相机上的装饰层应设 :flatten="false" 和 pointer-events: none，让触摸传到原生预览。

Props

ready.pictureWidth / pictureHeight 是拍摄档位参考值，未应用旋转、裁切和缩小；iOS 取当前格式的高分辨率尺寸，系统未知时为 0。最终成片以拍照结果 width / height 为准。Android 默认选择不超过 1600 万像素的可用拍摄档位以控制内存，不能将“原尺寸”理解为固定使用传感器最高像素。

裁切根据预览比例居中处理，取景框不会自动识别文档边缘；圆形或圆角仅改变预览外观，JPEG 成片仍是矩形。前摄成片沿用原版行为：Android 不额外镜像，iOS 使用镜像输出。

组件方法

uni-app x 通过 ref.$callMethod() 调用：

cameraRef.value?.$callMethod('focusAt', 0.5, 0.5)
cameraRef.value?.$callMethod('updateZoom', 2)

事件

focus 在平台支持时还会提供 pointSupported（指定区域）、meteringSupported（测光）、success（对焦回调结果）、timedOut（等待超时）。iOS 还会返回 exposureApplied（是否应用测光点）；Android 可返回 errMsg（点击对焦请求错误），zoomchange.supported 表示是否支持变焦。字段缺省时不代表成功；固定焦距前摄无法通过软件增加光学对焦能力。

ready 能力字段

拍照结果字段

扩展结果字段由原生端提供，以实际返回为准。只监听一个完成事件；需要兼容多个别名时按 imagePath 去重。

预览优先使用 fileURL；只有绝对路径时转换图片地址：

const previewSrc = imagePath.startsWith('/') ? 'file://' + imagePath : imagePath

上传仍使用本次返回的原始 imagePath / uploadFilePath。不要拼接 Pandora、AppID 或推测的沙盒目录，也不要将基座生成的旧绝对路径拿到另一次安装中复用。需要长期管理文件时，由业务保存相对标识并在当前应用目录中重新定位；插件不会自动恢复历史绝对地址。

错误码

横竖屏

演示页随窗口调整排版，所有设置和拍照按钮均可滚动查看。uni-app x 拍照页的 style.pageOrientation 设为 auto 随设备旋转，固定横屏则用 landscape。

iOS 项目若只允许竖屏，在项目根目录 Info.plist 的 <dict> 内合并以下键，并重新打基座；iPad 对应使用 UISupportedInterfaceOrientations~ipad。已有该键时只补齐横屏项。

<key>UISupportedInterfaceOrientations~iphone</key>
<array>
  <string>UIInterfaceOrientationPortrait</string>
  <string>UIInterfaceOrientationLandscapeLeft</string>
  <string>UIInterfaceOrientationLandscapeRight</string>
</array>