---
name: "Camera"
mode: "component"
versionRequirements:
  - { name: "@ray-js/ray", version: "0.6.9" }
title: "Camera - 系统相机"
---

## Camera

> [VERSION] @ray-js/ray >= 0.6.9

### 描述

系统相机组件，用于预览与拍摄。

### 属性

| 属性 | 类型 | 必填 | 默认值 | 描述 |
| --- | --- | --- | --- | --- |
| `mode` | `"normal"` | 否 | `"normal"` | 应用模式，只在初始化时有效，不能动态变更 |
| `resolution` | `"low" \| "medium" \| "high"` | 否 | `"medium"` | 分辨率，不支持动态修改 |
| `devicePosition` | `"front" \| "back"` | 否 | `"back"` | 摄像头朝向 |
| `flash` | `"auto" \| "on" \| "off" \| "torch"` | 否 | `"auto"` | 闪光灯模式 |
| `borderWidth` | `number` | 否 | `0` | 边框宽度，单位 px |
| `borderStyle` | `"solid" \| "dashed"` | 否 | `"solid"` | 边框样式 |
| `borderColor` | `string` | 否 | `"#ffffff"` | 边框颜色，须为十六进制格式 |
| `borderRadius` | `number` | 否 | `0` | 边框圆角，单位 px |
| `borderRadiusTopLeft` | `number` | 否 | - | 边框左上角圆角，单位 px |
| `borderRadiusTopRight` | `number` | 否 | - | 边框右上角圆角，单位 px |
| `borderRadiusBottomLeft` | `number` | 否 | - | 边框左下角圆角，单位 px |
| `borderRadiusBottomRight` | `number` | 否 | - | 边框右下角圆角，单位 px |
| `backgroundColor` | `string` | 否 | `"#ffffff"` | 背景颜色，须为十六进制格式 |
| `onBindstop` | `(event: CameraStopEvent) => void` | 否 | - | 摄像头在非正常终止时触发，如退出后台等情况 |
| `onError` | `(event: CameraErrorEvent) => void` | 否 | - | 用户不允许使用摄像头时触发 |
| `onInitdone` | `(event: CameraInitdoneEvent) => void` | 否 | - | 相机初始化完成时触发 |
| `updateLayout` | `unknown` | 否 | - | 用来异层组件通知容器层样式更新 |

### 引用对象

##### `interface` CameraStopEvent

```typescript
export interface CameraStopEvent extends BaseEvent {
  /** 事件类型 */
  type: 'stop';
}
```

##### `interface` CameraErrorEvent

| 属性 | 类型 | 描述 |
| --- | --- | --- |
| `detail` | `CameraErrorEventDetail` | 事件详情 |

##### `interface` CameraInitdoneEvent

| 属性 | 类型 | 描述 |
| --- | --- | --- |
| `detail` | `CameraInitdoneEventDetail` | 事件详情 |

##### `interface` BaseEvent

| 属性 | 类型 | 描述 |
| --- | --- | --- |
| `type` | `string` | 事件类型 |
| `timeStamp` | `number` | 页面打开到触发事件所经过的毫秒数 |
| `target` | `Target` | 触发事件的源组件 |
| `currentTarget` | `Target` | 当前组件的一些属性值集合 |
| `mark` | `any` | 事件标记数据 |

##### `interface` CameraErrorEventDetail

| 属性 | 类型 | 描述 |
| --- | --- | --- |
| `errMsg` | `string` | 错误信息 |

##### `interface` CameraInitdoneEventDetail

| 属性 | 类型 | 描述 |
| --- | --- | --- |
| `maxZoom` | `number` | 最大缩放倍数 |

##### `interface` Target

| 属性 | 类型 | 描述 |
| --- | --- | --- |
| `id` | `string` | 事件源组件的id |
| `dataset` | `Record<string, unknown>` | 事件源组件上的 `dataset` 自定义属性组成的集合 |


### 合法值

##### `resolution` 合法值

| 值 | 说明 |
| --- | --- |
| `"low"` | 低分辨率 |
| `"medium"` | 中分辨率 |
| `"high"` | 高分辨率 |

##### `devicePosition` 合法值

| 值 | 说明 |
| --- | --- |
| `"front"` | 前置摄像头 |
| `"back"` | 后置摄像头 |

##### `flash` 合法值

| 值 | 说明 |
| --- | --- |
| `"auto"` | 自动闪光灯 |
| `"on"` | 开启闪光灯 |
| `"off"` | 关闭闪光灯 |
| `"torch"` | 手电筒模式 |

##### `borderStyle` 合法值

| 值 | 说明 |
| --- | --- |
| `"solid"` | 实线边框 |
| `"dashed"` | 虚线边框 |


### 示例代码

#### 基础用法

```tsx
import React from 'react';
import { Camera, View, Text } from '@ray-js/ray';

export default function () {
  return (
    <View style={{ padding: '20px' }}>
      <Text style={{ marginBottom: '10px' }}>相机预览</Text>
      <Camera
        style={{ width: '100%', height: '300px' }}
        devicePosition="back"
        flash="auto"
        resolution="high"
        onInitdone={(e) => console.log('初始化完成, 最大缩放:', e.detail.maxZoom)}
        onError={(e) => console.log('相机错误:', e.detail.errMsg)}
        onBindstop={() => console.log('相机非正常终止')}
      />
    </View>
  );
}
```

#### 自定义边框

```tsx
import React, { useState } from 'react';
import { Camera, View, Button } from '@ray-js/ray';

export default function () {
  const [position, setPosition] = useState<'back' | 'front'>('back');

  return (
    <View style={{ padding: '20px' }}>
      <Camera
        style={{ width: '100%', height: '300px' }}
        devicePosition={position}
        flash="off"
        resolution="medium"
        borderWidth={2}
        borderStyle="dashed"
        borderColor="#1890ff"
        borderRadius={16}
        backgroundColor="#000000"
        onInitdone={(e) => console.log('初始化完成:', e.detail)}
      />
      <Button
        style={{ marginTop: '10px' }}
        onClick={() => setPosition(position === 'back' ? 'front' : 'back')}
      >
        切换摄像头（当前: {position === 'back' ? '后置' : '前置'}）
      </Button>
    </View>
  );
}
```


### 相关链接

相关 API：[createCameraContext](/cn/miniapp/develop/miniapp/api/media/camera/createCameraContext)。这是基于异层渲染的原生组件, 请注意 [原生组件使用限制](/cn/miniapp/develop/miniapp/component/native-component/native-component)。

<DemoBlock 
  githubUrl="https://github.com/Tuya-Community/tuya-miniapp-demo/tree/master/rayCamera" 
  qrCodeUrl="/images/qrCode/rayCamera.png" 
  lang="zh">
</DemoBlock>

### 常见问题

1. 同一页面只能插入一个 `camera` 组件。
2. Tuya MiniApp IDE 上不支持。
3. 相关原理请参考 [基于异层渲染的原生组件](/cn/miniapp/develop/miniapp/component/native-component/native-component)。
4. 请注意 [原生组件使用限制](/cn/miniapp/develop/miniapp/component/native-component/native-component)。