287 lines
8.2 KiB
Markdown
287 lines
8.2 KiB
Markdown
# 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）
|
||
|
||
```ts
|
||
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（拍照结果）
|
||
|
||
```ts
|
||
type ApexCameraPhotoResult = {
|
||
path: string // 照片临时路径
|
||
width: number // 照片宽度
|
||
height: number // 照片高度
|
||
savedToAlbum: boolean // 是否已保存到系统相册
|
||
}
|
||
```
|
||
|
||
### ApexCameraVideoResult（录像结果）
|
||
|
||
```ts
|
||
type ApexCameraVideoResult = {
|
||
path: string // 视频临时路径
|
||
duration: number // 视频时长
|
||
size: number // 视频文件大小
|
||
savedToAlbum: boolean // 是否已保存到系统相册
|
||
}
|
||
```
|
||
|
||
## Props（属性）
|
||
|
||
| 属性名 | 类型 | 默认值 | 说明 |
|
||
|--------|------|--------|------|
|
||
| `title` | `string` | `"UTS 相机组件"` | 顶栏标题（仅完整版） |
|
||
| `subTitle` | `string` | `"支持 Android + iOS + 鸿蒙"` | 初始化遮罩层的主提示文字 |
|
||
| `tipLines` | `string[]` | `[]` | 额外的提示信息行 |
|
||
| `autoInit` | `boolean` | `true` | 是否在 `onMounted` 时自动启动相机 |
|
||
| `autoBack` | `boolean` | `true` | 点击返回按钮是否自动 `navigateBack` |
|
||
| `maxDuration` | `number` | `60` | 录像最大时长（秒） |
|
||
| `defaultPosition` | `'front' \| 'back'` | `'back'` | 默认摄像头朝向 |
|
||
| `defaultFlashMode` | `'off' \| 'on' \| 'auto'` | `'off'` | 默认闪光灯模式 |
|
||
| `defaultSaveToAlbum` | `boolean` | `false` | 默认是否将结果保存到系统相册 |
|
||
|
||
## Events（事件）
|
||
|
||
| 事件名 | 参数类型 | 说明 |
|
||
|--------|----------|------|
|
||
| `ready` | 无 | 相机初始化完成 |
|
||
| `photo` | `ApexCameraPhotoResult` | 拍照完成 |
|
||
| `video` | `ApexCameraVideoResult` | 录像完成 |
|
||
| `error` | `message: string` | 发生错误（含错误信息） |
|
||
|
||
## Exposed Methods（暴露方法）
|
||
|
||
组件通过 `defineExpose` 暴露以下方法，父组件可通过 ref 调用：
|
||
|
||
| 方法名 | 签名 | 说明 |
|
||
|--------|------|------|
|
||
| `bootCamera` | `() => Promise<void>` | 手动启动/重启相机 |
|
||
| `takePhoto` | `() => void` | 触发拍照 |
|
||
| `recordVideo` | `() => void` | 触发录像（再次调用停止） |
|
||
| `toggleCamera` | `() => Promise<void>` | 切换前后摄像头 |
|
||
| `changeFlashMode` | `(mode: 'off' \| 'on' \| 'auto') => void` | 设置闪光灯模式 |
|
||
| `cycleFlashMode` | `() => void` | 循环切换闪光灯模式（off→auto→on→off） |
|
||
|
||
> 注意：`cycleFlashMode` 仅在简洁版（`apex-camera.uvue`）中暴露。
|
||
|
||
## 基本用法
|
||
|
||
### 1. 引入组件
|
||
|
||
在 `pages.json` 中注册组件：
|
||
|
||
```json
|
||
{
|
||
"easycom": {
|
||
"autoscan": true
|
||
}
|
||
}
|
||
```
|
||
|
||
或者直接 import：
|
||
|
||
```vue
|
||
<script setup>
|
||
import ApexCamera from '@/uni_modules/apex-gu-cheng-uts/components/apex-camera/apex-camera.uvue'
|
||
</script>
|
||
```
|
||
|
||
### 2. 最简单的使用
|
||
|
||
```vue
|
||
<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. 完整配置示例
|
||
|
||
```vue
|
||
<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。
|
||
|
||
```vue
|
||
<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>
|
||
|
||
``` |