> For AI agents: the complete documentation index is available at /apps-plugin/docs/llms.txt, the full documentation bundle is available at /apps-plugin/docs/llms-full.txt.

# camera

相机预览与拍摄组件，提供拍照和录像能力。

<iframe src="https://developer.doubao.com/docs-preview/component-simulator/?caseId=camera"
  title="组件示例 camera"
  width="100%"
  height="700"
  loading="lazy"
  style="width:100%;height:700px;border:0;border-radius:16px;overflow:hidden;"
></iframe>

## 扫码预览

![扫码预览 camera](https://api.qrserver.com/v1/create-qr-code/?size=200x200\&data=doubao%3A%2F%2Fdoubao_apps%3Fapp_id%3Ddb_1McM5Ni%26path%3D%252Fpages%252Fcomponent%252Fcamera%252Findex)

## Props

<table>
<thead>
<tr><th width="140">属性名</th><th width="240">类型</th><th width="120">默认值</th><th width="80">必填</th><th width="360">说明</th></tr>
</thead>
<tbody>
<tr><td>className</td><td><code>string</code></td><td>-</td><td>否</td><td>组件的类名。</td></tr>
<tr><td>devicePosition</td><td><code>CameraDevicePosition</code></td><td>'front'</td><td>否</td><td>该实例持有采集会话时使用的摄像头朝向。</td></tr>
<tr><td>onError</td><td><code>(event: CameraError) =&gt; void</code></td><td>-</td><td>否</td><td>权限、配置、拍照、录像或临时文件错误时触发。</td></tr>
<tr><td>onReady</td><td><code>() =&gt; void</code></td><td>-</td><td>否</td><td>采集会话和预览启动后触发。</td></tr>
<tr><td>ref</td><td><code>Ref&lt;CameraRef&gt;</code></td><td>-</td><td>否</td><td>用于调用拍照和录像的实例方法。</td></tr>
<tr><td>style</td><td><code>CSSProperties</code></td><td>-</td><td>否</td><td>组件的样式，默认尺寸为 100% × 240px。</td></tr>
</tbody>
</table>

## Ref 方法

<table>
<thead>
<tr><th width="180">方法名</th><th width="260">类型</th><th width="360">说明</th></tr>
</thead>
<tbody>
<tr><td>requestFocus</td><td><code>() =&gt; Promise&lt;void&gt;</code></td><td>抢占共享的原生采集会话，并按当前实例的 <code>devicePosition</code> 更新预览。<br>仅前台页面的实例可以调用，后台页面调用会失败。</td></tr>
<tr><td>startRecord</td><td><code>() =&gt; Promise&lt;void&gt;</code></td><td>开始录制视频，需要相机和麦克风权限。</td></tr>
<tr><td>stopRecord</td><td><code>() =&gt; Promise&lt;CameraCaptureResult&gt;</code></td><td>停止录制，在文件写入完成后返回临时文件路径。</td></tr>
<tr><td>takePhoto</td><td><code>() =&gt; Promise&lt;CameraCaptureResult&gt;</code></td><td>拍摄一张 JPEG 照片，返回临时文件路径。</td></tr>
</tbody>
</table>

前端库版本不低于 `0.2.0`。

## 基本用法

```tsx
import { useRef, useState } from '@byted-doubao-apps/framework';
import type { CameraRef } from '@byted-doubao-apps/framework/components';

export default function CameraPage() {
  const cameraRef = useRef<CameraRef>(null);
  const [photoPath, setPhotoPath] = useState('');

  return (
    <view>
      <camera
        ref={cameraRef}
        devicePosition="front"
        style={{ width: '100%', height: '320px' }}
        onError={(error) => console.error(error.errCode, error.errMessage)}
      />
      <button text="激活相机" onClick={() => cameraRef.current?.requestFocus()} />
      <button
        text="拍照"
        onClick={async () => {
          const result = await cameraRef.current?.takePhoto();
          if (result) setPhotoPath(result.path);
        }}
      />
      {photoPath ? <image src={photoPath} mode="aspectFit" /> : null}
    </view>
  );
}
```

## 共享采集会话与焦点

全局共享一个原生采集会话和预览层，只有前台 `AppletFullPageContainer` 中的实例可以获得
焦点，同页后创建的实例默认抢占。

- 页面隐藏时解绑预览；没有前台相机时停止采集。返回页面后自动恢复该页最近获得焦点的实例，
  并触发 `onReady`。
- 后台页面调用 `requestFocus()` 会失败。切页或同页抢占会结束原实例的录制，被抢占的实例
  会收到 `onError` 并停止预览。
- 收到 `onReady` 后再拍照或录像；失焦的实例可以调用 `requestFocus()` 重新抢占，然后等待
  `onReady`。
- 非焦点实例修改 `devicePosition` 只保存自身设置，在该实例下次获得焦点时生效。
- 录像期间不能切换前后摄像头。

## 临时文件

`takePhoto` 和 `stopRecord` 返回的 `path` 是 `appletfile://temp/...` 虚拟路径。临时文件位于
当前应用插件隔离的缓存目录，在退出时清理；如需长期保存，用
`getFileSystemManager().saveFile({ tempFilePath: path })` 转存到用户目录
`appletfile://user/...`，保存后的路径由返回值的 `savedFilePath` 给出。

## 错误码

| errCode | 含义                          |
| ------- | --------------------------- |
| `1`     | 状态不允许，例如相机未 ready、重复开始或停止录像 |
| `2`     | 相机或麦克风权限被拒绝                 |
| `3`     | 摄像头或麦克风不可用                  |
| `4`     | 采集会话或输入输出配置失败               |
| `5`     | 拍照失败                        |
| `6`     | 录像失败或意外中断                   |
| `7`     | 临时文件路径创建或写入失败               |

## 注意事项

- 授权分两层。应用级：需要在 manifest 的 `permissions` 中声明 `scope.camera`，录像还要
  声明 `scope.record`，未声明时校验不通过。系统级：由客户端弹窗向用户申请，拍照只申请
  相机权限，录像会同时申请相机和麦克风权限。
- 任一层未通过都通过 `onError` 返回 `errCode: 2`，需要据此引导用户到系统设置开启。
- Web 模拟器不渲染相机画面，`ref` 上的方法也不可用，需要在真机验收。
