更新记录

1.0.1（2026-05-25）

新增功能

• pages是uni-app的示例
• pagesx是uni-app x的示例

问题修复 无

功能优化 无

1.0.0（2026-05-24）

新增功能

• 新增方法：open、reopen、close、destroyCamera、takePhoto、takePhotoSnapshot、takeVideo、takeVideoSnapshot、stopVideo、changeZoom、setCameraZoom、changeWideAngle、changeZoomNormal、changeExposure、changeWhiteBalance、changeHdr、changeFacing、changeMode、changeOrientation、changeGrid、changeFlash、changeAudio、changeSuffix、changeSizeSelectors、changePreviewCorner、changeGallery、changePinchZoom、changeTapToFocus、openAppSettings、isOpened
• 新增事件：onCamera、onCameraOpened、onCameraClosed、onPictureTaken、onVideoTakenStart、onVideoTakenEnd、onVideoTakenProgress、onFocusStart、onAutoFocusStart、onFocusEnd、onZoomChanged、onCameraChange、onOrientationChanged、onCameraTakenError、onCameraError
• android端的所有功能已完成开发、测试
• harmony端兼容式组件不支持
• 初始版

问题修复 无

功能优化 无

平台兼容性

uni-app(4.81)

uni-app x(4.81)

其他

原生自定义相机拍照、视频录制 （ima-camerax-view）

原生自定义相机拍照、视频录制 （ima-camerax-view）是基于原生相机开发的UTS插件，支持相机拍照、视频录制 、可实现点击聚焦、手势缩放、 自定义布局、自定义蒙版（用于人脸拍照，身份证拍照等）。

原生自定义相机拍照、视频录制 （ima-camerax-view）

原生自定义相机拍照、视频录制 （ima-camerax-view）是基于原生相机开发的UTS插件，支持相机拍照、视频录制 、可实现点击聚焦、手势缩放、 自定义布局、自定义蒙版（用于人脸拍照，身份证拍照等）。

⚠️注意️

• ima-camerax-view【本插件】：插件地址
• ima-camera-view【老插件】：插件地址【继续维护，只修复现存的一些bug，不再新增新功能】

新增 ima-camerax-view 原因：

• 1、底层 CameraView 库（com.otaliastudios:cameraview）自 2021-10-27 发布 v2.7.2 后长期无新版本，难以跟进 Android 新系统与新机型
• 2、主要是 CameraView 版无法使用一些相机的新特性，如：超广角镜头切换（0.5x，changeWideAngle）、按倍率缩放（setCameraZoom，如 0.5 / 1.0 / 2.0）、多摄逻辑镜头切换、Camera2 白平衡 / HDR / 曝光补偿、录像进度（onVideoTakenProgress）与设备方向变化（onOrientationChanged）回调等
• 3、CameraX 为 Google 官方 Jetpack 组件，生命周期、预览/拍照/录像 UseCase 组合更规范，长期维护有保障
• 4、可通过 Camera2 Interop 扩展超广角切换、光学/数码缩放、白平衡、HDR、曝光等能力，可扩展性更强
• 5、与旧版 ima-camera-view 组件 API 保持基本一致，便于从 CameraView 版平滑迁移

支持功能

• open：打开摄像头预览
• reopen：关闭后重新打开摄像头预览
• close：关闭摄像头预览
• destroyCamera：销毁相机预览视图
• isOpened：查询摄像头预览是否已打开
• takePhoto：拍照（标准拍照流程，含快门声/震动）
• takePhotoSnapshot：快照拍照（快速拍照，含快门声/震动）
• takeVideo：开始录制视频（可选 duration 最大时长，单位 ms，0 表示不限制）
• takeVideoSnapshot：快照方式录制视频（可选 duration）
• stopVideo：停止视频录制
• changeZoom：设置线性缩放（0～1，对应 CameraX setLinearZoom）
• setCameraZoom：设置光学/数码缩放倍数（如 0.5、1.0、2.0，对应 CameraX setZoomRatio）
• changeWideAngle：切换至超广角镜头（0.5x）
• changeZoomNormal：恢复标准主摄 1.0x 缩放
• changeExposure：设置曝光补偿（-2～2）
• changeWhiteBalance：设置白平衡（auto / incandescent / fluorescent / daylight / cloudy）
• changeHdr：设置 HDR 模式（off / on）
• changeFacing：切换前后摄像头（back / front）
• changeMode：切换相机模式（预留，当前未实现）
• changeOrientation：设置预览/输出方向（auto / portrait / landscape）
• changeGrid：设置预览网格及颜色（off / draw_3X3 / draw_4x4 / draw_phi）
• changeFlash：设置闪光灯模式（off / on / auto / torch）
• changeAudio：设置录像音频（on / off / mono / stereo）
• changeSuffix：设置照片输出格式（jpeg / jpg 等）
• changeSizeSelectors：设置目标分辨率比例（width、height、tolerance）
• changePreviewCorner：设置预览圆角（固定像素 radius 或比例 radiusRate）
• changeGallery：设置是否保存至系统相册
• changePinchZoom：开启/关闭手势双指缩放
• changeTapToFocus：开启/关闭点击对焦
• openAppSettings：打开系统应用设置（权限被永久拒绝时引导用户授权）

自定义调整

• 自定义调整页面地址：uni_modules/ima-camerax-view/utssdk/app-android/index.vue
• 蓝牙自拍杆、手机快捷键的自定义，可以参考文件中的shortcutListener方法
• 设置拍照、录制视频的声音，可以参考文件中的photoSound、videoSound方法

需要权限

• 摄像头、音频、文件读取、文件写入、震动

"android.permission.CAMERA",
"android.permission.RECORD_AUDIO",
"android.permission.VIBRATE"
"android.permission.READ_EXTERNAL_STORAGE"
"android.permission.WRITE_EXTERNAL_STORAGE"

• 即：在manifest.json中的distribute.android.permissions加入

// 拍摄照片和视频时需要
<uses-permission android:name="android.permission.CAMERA" /> 
// 拍摄视频时需要Audio.ON（默认）
<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.VIBRATE" />

快门声音素材

• 将需要的快门声音放在uni_modules/ima-camerax-view/utssdk/app-android/assets下即可
• 熊猫办公
• 站长素材

使用示例【此示例的代码只实现了相机拍照的逻辑，更多示例请导入项目】

• 新建一个camera.nvue的文件
• ⚠️注意️：只能在.nvue、.uvue的文件后缀下才生效，不支持.vue

<template>
    <view class="ima-camera" :style="{ width: windowWidth, height: windowHeight }">
        <ima-camerax-view
            ref="cameraRef"
            class="camera-view"
            :style="{ width: windowWidth + 'px', height: windowHeight + 'px' }"
            flash="on"
            @onPictureTaken="onPictureTaken"
            onFocusStart="onFocusStart"
        />
        <view class="camera-menu">
            <!--返回键-->
            <cover-image @tap="back" class="camera-menu-button back" src="/static/camera/back.png" />
            <!--快门键-->
            <cover-image
                @tap="takePhoto"
                class="camera-menu-button shutter"
                src="/static/camera/shutter.png"
            />
            <!--反转键-->
            <cover-image @tap="flip" class="camera-menu-button flip" src="/static/camera/flip.png" />
        </view>
    </view>
</template>

<script>
let _this = null
export default {
    data() {
        return {
            windowWidth: '', //屏幕可用宽度
            windowHeight: '', //屏幕可用高度
            facing: 'back'
        }
    },
    onLoad() {
        _this = this
        this.initCamera()
    },
    methods: {
        //初始化相机
        initCamera() {
            console.log('初始化相机')
            uni.getSystemInfo({
                success: (res) => {
                    _this.windowWidth = res.windowWidth
                    _this.windowHeight = res.windowHeight
                }
            })
        },
        onFocusStart(e) {
            console.log('聚焦', e)
        },
        takePhoto() {
            console.log('拍照', this.facing)
            this.$refs.cameraRef.takePhoto()
        },
        //返回
        back() {
            console.log('返回上一页', this.facing)
            uni.navigateBack()
        },
        //反转
        flip() {
            console.log('镜头反转', this.facing)
            this.facing = this.facing === 'back' ? 'front' : 'back'
            this.$refs.cameraRef.changeFacing(this.facing)
        },
        onPictureTaken(e) {
            console.log('拍照结果', e.detail)
            _this.snapshotsrc = e.detail?.path || ''
            _this.getTakenRes()
            uni.navigateBack()
        },
        //设置
        getTakenRes() {
            console.log('返回结果给上一页')
            let pages = getCurrentPages()
            let prevPage = pages[pages.length - 2] //上一个页面
            //直接调用上一个页面的setImage()方法，把数据存到上一个页面中去
            prevPage.$vm.setImage({ path: _this.snapshotsrc })
        }
    }
}
</script>

<style lang="scss">
.ima-camera {
    justify-content: center;
    align-items: center;

    .camera-view {
        width: 100%;
        background: #111;
    }

    .camera-menu {
        position: absolute;
        left: 0;
        bottom: 0;
        width: 750rpx;
        height: 180rpx;
        z-index: 98;
        align-items: center;
        justify-content: center;

        &-button {
            width: 80rpx;
            height: 80rpx;
            position: absolute;
            bottom: 50rpx;
            z-index: 99;
            align-items: center;
            justify-content: center;
        }

        .back {
            left: 30rpx;
        }

        .shutter {
            width: 130rpx;
            height: 130rpx;
            left: 310rpx;
            bottom: 25rpx;
        }

        .flip {
            right: 30rpx;
        }
    }
}
</style>

常见的比例的定义（widthRatio，heightRatio）

// 正方形
AspectRatio.of(1, 1)      // 1:1

// 竖屏比例
AspectRatio.of(9, 16)     // 9:16 (手机竖屏)
AspectRatio.of(3, 4)      // 3:4
AspectRatio.of(2, 3)      // 2:3
AspectRatio.of(10, 16)    // 10:16 (5:8)

// 横屏比例
AspectRatio.of(16, 9)     // 16:9 (宽屏)
AspectRatio.of(4, 3)      // 4:3 (传统)
AspectRatio.of(3, 2)      // 3:2 (照片)
AspectRatio.of(16, 10)    // 16:10 (8:5)
AspectRatio.of(21, 9)     // 21:9 (超宽屏)

// 建议比例
const AspectRatios = {
  // 1:1 正方形
  SQUARE: AspectRatio.of(1, 1),
  // 9:16 竖屏（手机默认）
  PORTRAIT: AspectRatio.of(9, 16),
  // 16:9 横屏
  LANDSCAPE: AspectRatio.of(16, 9),
  // 3:4 传统照片比例
  THREE_FOUR: AspectRatio.of(3, 4),
  // 4:3 传统相机比例
  FOUR_THREE: AspectRatio.of(4, 3)
}

不同场景的推荐值（tolerance）

const TOLERANCE = {
  STRICT: 0.01.toFloat(),    // 非常严格，几乎精确匹配
  STANDARD: 0.05.toFloat(),  // 标准，推荐使用
  FLEXIBLE: 0.1.toFloat(),   // 灵活，兼容更多设备
  LOOSE: 0.2.toFloat()       // 宽松，可能匹配到意外比例
}

Api

方法

事件