更新记录

1.0.0（2026-06-18） 下载此版本

第一次上传

平台兼容性

uni-app x(5.07)

其他

apex-camera 相机组件使用文档

概述

apex-camera 是一个基于 UTS 的跨平台相机组件，支持 Android、iOS 和鸿蒙三端。组件封装了拍照、录像、闪光灯控制、前后摄像头切换、保存到相册等常见相机功能，开箱即用。

文件结构

components/apex-camera/
├── apex-camera.uvue          # 简洁版风格（带照片遮罩层）
├── apex-camera copy.uvue     # 完整版风格（带顶栏、状态面板、工具面板）
├── index.uts                 # 导出入口
└── type.uts                  # 类型定义

两个 .uvue 文件提供了不同的 UI 风格，功能逻辑完全一致。可按需选用其中一个。

类型定义

ApexCameraProps（组件 Props）

type ApexCameraProps = {
  title: string                    // 标题文本，默认 "UTS 相机组件"
  subTitle: string                 // 副标题/提示文本，默认 "支持 Android + iOS + 鸿蒙"
  tipLines: string[]              // 提示信息行
  autoInit: boolean               // 是否自动初始化相机，默认 true
  autoBack: boolean               // 点击返回时是否自动返回上一页，默认 true
  maxDuration: number             // 最大录像时长（秒），默认 60
  defaultPosition: 'front' | 'back' // 默认摄像头方向，默认 'back'
  defaultFlashMode: 'off' | 'on' | 'auto' // 默认闪光灯模式，默认 'off'
  defaultSaveToAlbum: boolean     // 默认是否保存到相册，默认 false
}

ApexCameraPhotoResult（拍照结果）

type ApexCameraPhotoResult = {
  path: string        // 照片临时路径
  width: number       // 照片宽度
  height: number      // 照片高度
  savedToAlbum: boolean // 是否已保存到系统相册
}

ApexCameraVideoResult（录像结果）

type ApexCameraVideoResult = {
  path: string        // 视频临时路径
  duration: number    // 视频时长
  size: number        // 视频文件大小
  savedToAlbum: boolean // 是否已保存到系统相册
}

Props（属性）

Events（事件）

Exposed Methods（暴露方法）

组件通过 defineExpose 暴露以下方法，父组件可通过 ref 调用：

注意：cycleFlashMode 仅在简洁版（apex-camera.uvue）中暴露。

基本用法

1. 引入组件

在 pages.json 中注册组件：

{
  "easycom": {
    "autoscan": true
  }
}

或者直接 import：

<script setup>
import ApexCamera from '@/uni_modules/apex-gu-cheng-uts/components/apex-camera/apex-camera.uvue'
</script>

2. 最简单的使用

<template>
  <apex-camera
    @photo="onPhoto"
    @video="onVideo"
    @error="onError"
  />
</template>

<script setup>
const onPhoto = (res) => {
  console.log('拍照完成:', res.path)
  // res.path - 照片临时路径
  // res.savedToAlbum - 是否已保存到相册
}

const onVideo = (res) => {
  console.log('录像完成:', res.path)
  // res.path - 视频临时路径
  // res.duration - 视频时长
}

const onError = (message) => {
  uni.showToast({ title: message, icon: 'none' })
}
</script>

3. 完整配置示例

<template>
  <apex-camera
    ref="cameraRef"
    title="智能拍照"
    sub-title="请将物品对准框内"
    :auto-init="true"
    :auto-back="false"
    :max-duration="30"
    default-position="back"
    default-flash-mode="auto"
    :default-save-to-album="true"
    @ready="onReady"
    @photo="onPhoto"
    @video="onVideo"
    @error="onError"
  />
</template>

<script setup>
import { ref } from 'vue'

const cameraRef = ref(null)

const onReady = () => {
  console.log('相机已就绪')
}

const onPhoto = (res) => {
  // 拍照成功，处理照片
  uni.previewImage({
    urls: [res.path]
  })
}

const onVideo = (res) => {
  console.log('视频路径:', res.path)
}

const onError = (msg) => {
  uni.showToast({ title: msg, icon: 'none' })
}

// 可通过 ref 手动调用方法
const manualTakePhoto = () => {
  cameraRef.value?.takePhoto()
}

const switchCamera = () => {
  cameraRef.value?.toggleCamera()
}

const setFlashAuto = () => {
  cameraRef.value?.changeFlashMode('auto')
}
</script>

两种 UI 风格对比

简洁版（apex-camera.uvue）

• 全屏预览 + 照片遮罩层（可自定义遮罩图）
• 底部一栏：缩略图 + 拍照按钮 + 切换摄像头
• 左上角闪光灯切换按钮
• 适合需要自定义遮罩/引导框的场景

完整版（apex-camera copy.uvue）

• 顶部导航栏：返回按钮 + 标题 + 状态徽章
• 全屏预览 + 初始化遮罩
• 状态面板：显示摄像头方向、闪光灯、保存状态等
• 底部操作栏：切换 + 拍照 + 录像 + 状态文本
• 底部工具面板：保存到相册开关 + 闪光灯三态切换
• 适合需要完整调试信息和状态展示的场景

注意事项

1. 相机权限：使用前请确保已在各平台配置相机权限。Android 需在 AndroidManifest.xml 中声明，iOS 需在 Info.plist 中添加 NSCameraUsageDescription。
2. 相册保存：如需保存到系统相册，Android 还需 WRITE_EXTERNAL_STORAGE 权限，iOS 需 NSPhotoLibraryAddUsageDescription。
3. 临时文件：拍照/录像返回的路径为临时文件路径，如需持久保存需自行移动或上传。
4. 录像限制：通过 maxDuration 控制最大录像时长，超出后会自动停止。
5. 组件引用：通过 easycom 自动扫描引入即可，无需手动 import。

<template>
  <view class="shoot-page">
    <ApexCamera
      class="shoot-camera"
      title="UTS 相机组件"
      sub-title="支持 Android + iOS + 鸿蒙"
      :auto-init="true"
      :auto-back="false"
      :default-save-to-album="true"
      @ready="handleReady"
      @photo="handlePhoto"
      @video="handleVideo"
      @error="handleError"
    />
  </view>
</template>

<script setup>
import ApexCamera from '@/uni_modules/apex-gu-cheng-uts/components/apex-camera/apex-camera.uvue'
import { ApexCameraPhotoResult, ApexCameraVideoResult } from '@/uni_modules/apex-gu-cheng-uts/components/apex-camera/type.uts'

const handleReady = () => {
  console.log('ApexCamera ready')
}

const handlePhoto = (res : ApexCameraPhotoResult) => {
  console.log('photo result', res.path, res.width, res.height, res.savedToAlbum)
}

const handleVideo = (res : ApexCameraVideoResult) => {
  console.log('video result', res.path, res.duration, res.size, res.savedToAlbum)
}

const handleError = (message : string) => {
  console.error('camera error', message)
}
</script>

<style>
.shoot-page {
  flex: 1;
  background-color: #000;
}

.shoot-camera {
  flex: 1;
  width: 100%;
  height: 100%;
}
</style>