# 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>

```