# 组件 (/zh-CN/api-reference/rtc/react-sdk/components)

> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).

<a id="agorartcprovider"></a>
## AgoraRTCProvider [#agorartcprovider]

该组件向子组件[提供 Context](https://react.dev/learn/passing-data-deeply-with-context)，让 `children` 内的各个组件都能读取你传入的 `client` 属性。

#### Props [#props]

| 属性名     | 类型              | 默认值 | 描述                                                                                                                                          |
| ---------- | ----------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `client`   | [`IAgoraRTCClient`](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient) | 无     | 通过 Web SDK 的 [`IAgoraRTC.createClient`](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartc#createclient) 创建。 |
| `children` | `ReactNode`       | 无     | 需要展示的 React 节点。                                                                                                                       |

#### 使用示例 [#使用示例]

```jsx
import AgoraRTC, { AgoraRTCProvider } from "agora-rtc-react"

function App({ children }) {
  const [client] = useState(() => AgoraRTC.createClient({ mode: "rtc", codec: "vp8" }));
  return <AgoraRTCProvider client={client}>{children}</AgoraRTCProvider>;
}
```

<a id="agorartcscreenshareprovider"></a>
## AgoraRTCScreenShareProvider [#agorartcscreenshareprovider]

该组件向子组件[提供 Context](https://react.dev/learn/passing-data-deeply-with-context)，让 `children` 内的各个组件都能读取你传入的用于屏幕共享的 `client` 属性。

#### Props [#props-1]

| 属性名     | 类型              | 默认值 | 描述                                                                                                                                          |
| ---------- | ----------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `client`   | [`IAgoraRTCClient`](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient) | 无      | 通过 Web SDK 的 [`IAgoraRTC.createClient`](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartc#createclient) 创建。 |
| `children` | `ReactNode`       | 无      | 需要展示的 React 节点。                                                                                                                       |

#### 注意事项 [#注意事项]

你可以同时使用 `AgoraRTCScreenShareProvider` 和 `AgoraRTCProvider` ，但二者不会共享 `client` 属性。

#### 使用示例 [#使用示例-1]

```jsx
import AgoraRTC, { AgoraRTCScreenShareProvider } from "agora-rtc-react";

function App({ children }) {
  const [client] = useState(() => AgoraRTC.createClient({ mode: "rtc", codec: "vp8" }));
  return <AgoraRTCScreenShareProvider client={client}>{children}</AgoraRTCScreenShareProvider>;
}
```

<a id="localaudiotrack"></a>
## LocalAudioTrack [#localaudiotrack]

该组件用于播放本地音频轨道，播放设备为用户在浏览器中选择的设备。

如果你需要自行设置麦克风设备，可使用 Web SDK 的 [`IMicrophoneAudioTrack.setDevice`](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/imicrophoneaudiotrack#setdevice) 方法。
#### Props [#props-2]

| 属性名     | 类型               | 默认值  | 描述                                                                                                                                                                                                     |
| ---------- | ------------------ | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `track`    | `ILocalAudioTrack` | 无      | 要播放的本地音频轨道。通过 [`useLocalMicrophoneTrack`](/zh-CN/api-reference/rtc/react-sdk/hooks#uselocalmicrophonetrack) 创建。 |
| `play` | `boolean` | `false` | [components-slot-2-3-3 details](#table-slot-components-slot-2-3-3) |
| `volume`   | `number`           | 无      | 音量大小。取值范围 [0, 1000]，0 代表静音，100 代表原始音量。100 以上会使用 [Web Audio API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API) 进行音量增益。          |
| `disabled` | `boolean` | `false` | [components-slot-2-5-3 details](#table-slot-components-slot-2-5-3) |
| `muted` | `boolean` | `false` | [components-slot-2-6-3 details](#table-slot-components-slot-2-6-3) |
| `children` | `ReactNode`        | 无      | 需要展示的 React 节点。                                                                                                                                                                                  |

<a id="table-slot-components-slot-2-3-3"></a>

**components-slot-2-3-3 details**

- `true`：播放该轨道。
- `false`：停止播放该轨道。

<a id="table-slot-components-slot-2-5-3"></a>

**components-slot-2-5-3 details**

- `true`：禁用该轨道。禁用后，SDK 将停止播放和发布该轨道。
- `false`：启用该轨道。

<a id="table-slot-components-slot-2-6-3"></a>

**components-slot-2-6-3 details**

- `true`：暂停发送该轨道的媒体数据。
- `false`：恢复发送该轨道的媒体数据。

#### 注意事项 [#注意事项-1]

设置 `disabled` 和 `muted` 属性时其实是调用了 Web SDK 的 [`setEnabled`](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/ilocaltrack#setenabled) 方法和 [`setMuted`](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/ilocaltrack#setmuted) 方法，因此：

- 与设置 `disabled` 属性相比，设置 `muted` 属性的响应速度更快且不影响音频采集状态。
- 不能同时设置 `muted` 属性和 `disabled` 属性。

#### 使用示例 [#使用示例-2]

```jsx
import { LocalAudioTrack, useLocalAudioTrack } from "agora-rtc-react";

function App() {
  const audioTrack = useLocalAudioTrack();
  return <LocalAudioTrack track={audioTrack} play />;
}
```

<a id="localvideotrack"></a>
## LocalVideoTrack [#localvideotrack]

该组件用于播放本地视频轨道，播放设备为用户在浏览器中选择的设备。

如果你需要自行设置摄像头设备，可使用 Web SDK 的 [`ICameraVideoTrack.setDevice`](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/icameravideotrack#setdevice) 方法。

#### Props [#props-3]

| 属性名     | 类型               | 默认值 | 描述                                                                                                |
| ---------- | ------------------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `track`    | `ILocalVideoTrack` |  无    | 要播放的本地视频轨道。通过 [`useLocalCameraTrack`](/zh-CN/api-reference/rtc/react-sdk/hooks#uselocalcameratrack) 或 Web SDK 的 [`IAgoraRTC.createScreenVideoTrack`](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartc#createscreenvideotrack) 创建。 |
| `play` | `boolean` | `false` | [components-slot-3-3-3 details](#table-slot-components-slot-3-3-3) |
| `disabled` | `boolean` | `false` | [components-slot-3-4-3 details](#table-slot-components-slot-3-4-3) |
| `muted` | `boolean` | `false` | [components-slot-3-5-3 details](#table-slot-components-slot-3-5-3) |
| `videoPlayerConfig`  |`VideoPlayerConfig` | 无 | 视频轨道的播放配置。可以设置播放参数（镜像/显示模式），详见 [`VideoPlayerConfig`](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/videoplayerconfig)。对于本地视频轨道，镜像模式默认开启。|

<a id="table-slot-components-slot-3-3-3"></a>

**components-slot-3-3-3 details**

- `true`：播放该轨道。
- `false`：停止播放该轨道。

<a id="table-slot-components-slot-3-4-3"></a>

**components-slot-3-4-3 details**

- `true`：禁用该轨道。禁用后，SDK 将停止播放和发布该轨道。
- `false`：启用该轨道。

<a id="table-slot-components-slot-3-5-3"></a>

**components-slot-3-5-3 details**

- `true`：暂停发送该轨道的媒体数据。
- `false`：恢复发送该轨道的媒体数据。

#### 注意事项 [#注意事项-2]

设置 `disabled` 和 `muted` 属性时其实是调用了 Web SDK 的 [`setEnabled`](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/ilocaltrack#setenabled) 方法和 [`setMuted`](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/ilocaltrack#setmuted) 方法，因此：

- 与设置 `disabled` 属性相比，设置 `muted` 属性的响应速度更快且不影响视频采集状态。
- 不能同时设置 `muted` 属性和 `disabled` 属性。

#### 使用示例 [#使用示例-3]

```jsx
import { LocalVideoTrack, useLocalCameraTrack } from "agora-rtc-react";

function App() {
  const videoTrack = useLocalCameraTrack();
  return <LocalVideoTrack track={videoTrack} play />;
}
```

<a id="localuser"></a>
## LocalUser [#localuser]

该组件用于播放本地用户的摄像头视频轨道和麦克风音频轨道，播放设备为用户在浏览器中选择的设备。

当视频轨道停止播放时，该组件会展示封面图片。

如果你需要自行设置麦克风或摄像头设备，可使用 Web SDK 的 [`IMicrophoneAudioTrack.setDevice`](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/imicrophoneaudiotrack#setdevice) 或 [`ICameraVideoTrack.setDevice`](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/icameravideotrack#setdevice) 方法。

#### Props [#props-4]

| 属性名       | 类型                    | 默认值                     | 描述                                                                                                                                                                                                       |
| ------------ | ----------------------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `micOn` | `boolean` | `false` | [components-slot-4-2-3 details](#table-slot-components-slot-4-2-3) |
| `cameraOn` | `boolean` | `false` | [components-slot-4-3-3 details](#table-slot-components-slot-4-3-3) |
| `audioTrack` | `IMicrophoneAudioTrack` | 无      | 要播放的麦克风音频轨道。通过 [`useLocalMicrophoneTrack`](/zh-CN/api-reference/rtc/react-sdk/hooks#uselocalmicrophonetrack) 创建。 |
| `videoTrack` | `ICameraVideoTrack`     | 无      | 要播放的摄像头视频轨道。通过 [`useLocalCameraTrack`](/zh-CN/api-reference/rtc/react-sdk/hooks#uselocalcameratrack) 创建。         |
| `playAudio` | `boolean` | `false` | [components-slot-4-6-3 details](#table-slot-components-slot-4-6-3) |
| `playVideo` | `boolean` | `false` | [components-slot-4-7-3 details](#table-slot-components-slot-4-7-3) |
| `volume`     | `number`                | 无      | 音量大小。取值范围 [0, 1000]，0 代表静音，100 代表原始音量。100 以上会使用 [Web Audio API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API) 进行音量增益。           |
| `cover`      | `string`                | 无      | 当 `playVideo` 为 `false`时要渲染的封面图片，用于替代视频画面显示。支持传入在线图片的 URL 或本地图片的相对路径。                                                                                                                                                            |
| `children`   | `ReactNode`             | 无      | 需要展示的 React 节点。                                                                                                                                                                                    |

<a id="table-slot-components-slot-4-2-3"></a>

**components-slot-4-2-3 details**

- `true`：打开本地用户的麦克风。
- `false`：关闭本地用户的麦克风。

<a id="table-slot-components-slot-4-3-3"></a>

**components-slot-4-3-3 details**

- `true`：打开本地用户的摄像头。
- `false`：关闭本地用户的摄像头。

<a id="table-slot-components-slot-4-6-3"></a>

**components-slot-4-6-3 details**

- `true`：播放本地用户的音频轨道。
- `false`：停止播放本地用户的音频轨道。

<a id="table-slot-components-slot-4-7-3"></a>

**components-slot-4-7-3 details**

- `true`：播放本地用户的视频轨道。
- `false`：停止播放本地用户的视频轨道。

#### 使用示例 [#使用示例-4]

```jsx
import { LocalUser, useLocalAudioTrack, useLocalCameraTrack } from "agora-rtc-react";

function App() {
  const audioTrack = useLocalAudioTrack();
  const videoTrack = useLocalCameraTrack();

  return (
    <LocalUser
      audioTrack={audioTrack}
      cameraOn
      cover={COVER_IMAGE_URL}
      micOn
      playAudio
      playVideo
      videoTrack={videoTrack}
    />
  );
}
```

<a id="remoteaudiotrack"></a>
## RemoteAudioTrack [#remoteaudiotrack]

该组件用于播放远端用户的音频轨道，并且支持指定播放设备。

#### Props [#props-5]

| 属性名             | 类型                | 默认值 | 描述                                        |
| ------------------ | ------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `track`            | [`IRemoteAudioTrack`](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iremoteaudiotrack) | 无      | 要播放的远端音频轨道。                                                                                                                                   |
| `play` | `boolean` | 无 | [components-slot-5-3-3 details](#table-slot-components-slot-5-3-3) |
| `playbackDeviceId` | `string`            | 无      | 要使用的播放设备 ID，例如扬声器。设备 ID 通过 [`IAgoraRTC.getPlaybackDevices`](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartc#getplaybackdevices) 获取。该属性仅支持桌面端的 Chrome 浏览器，在其它浏览器上修改该属性的值将会抛出 `NOT_SUPPORTED` 错误。 |
| `volume`           | `number`            | 无      | 音量大小。取值范围 [0, 100]，0 代表静音，100 代表原始音量。         |
| `children`         | `ReactNode`         | 无      | 需要展示的 React 节点。                     |

<a id="table-slot-components-slot-5-3-3"></a>

**components-slot-5-3-3 details**

- `true`：播放该轨道。
- `false`：停止播放该轨道。

#### 使用示例 [#使用示例-5]

```jsx
import { RemoteAudioTrack, useJoin, useRemoteAudioTracks, useRemoteUsers } from "agora-rtc-react";

function App() {
  const remoteUsers = useRemoteUsers();
  const audioTracks = useRemoteAudioTracks(remoteUsers);

  return (
    <>
      {audioTracks.map(track => (
        <RemoteAudioTrack key={track.getUserId()} play track={track} />
      ))}
    </>
  );
}
```

<a id="remotevideotrack"></a>
## RemoteVideoTrack [#remotevideotrack]

该组件用于播放远端用户的视频轨道，并且不支持指定播放设备。

#### Props [#props-6]

| 属性名  | 类型                | 默认值 | 描述                                                                                                                                                                |
| ------- | ------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `track` | [`IRemoteVideoTrack`](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iremotevideotrack) | 无      | 远端视频轨道对象。 |
| `play` | `boolean` | 无 | [components-slot-6-3-3 details](#table-slot-components-slot-6-3-3) |
| `videoPlayerConfig`  |`VideoPlayerConfig` | 无 | 视频轨道的播放配置。可以设置播放参数（镜像/显示模式），详见 [`VideoPlayerConfig`](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/videoplayerconfig)。|

<a id="table-slot-components-slot-6-3-3"></a>

**components-slot-6-3-3 details**

- `true`：播放该轨道。
- `false`：停止播放该轨道。

#### 使用示例 [#使用示例-6]

```jsx
import { RemoteVideoTrack, useJoin, useRemoteVideoTracks, useRemoteUsers } from "agora-rtc-react";

function App() {
  const remoteUsers = useRemoteUsers();
  const videoTracks = useRemoteVideoTracks(remoteUsers);

  return (
    <>
      {audioTracks.map(track => (
        <RemoteVideoTrack key={track.getUserId()} play track={track} />
      ))}
    </>
  );
}
```

<a id="remoteuser"></a>
## RemoteUser [#remoteuser]

该组件用于播放远端用户的视频和音频轨道，并且仅支持指定使用的音频设备、不支持指定使用的视频设备。

#### Props [#props-7]

| 属性名             | 类型                          | 默认值                                                                                                                                                     | 描述                                        |
| ------------------ | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `user`             | [`IAgoraRTCRemoteUser`](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcremoteuser)         | 无                                                                                                                                                          | 远端用户对象。                          |
| `playVideo` | `boolean` | [user.hasVideo](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcremoteuser#hasvideo) 属性的值 | [components-slot-7-3-3 details](#table-slot-components-slot-7-3-3) |
| `playAudio` | `boolean` | [user.hasAudio](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcremoteuser#hasaudio) 属性的值 | [components-slot-7-4-3 details](#table-slot-components-slot-7-4-3) |
| `playbackDeviceId` | `string`                      | 无                                                                                                                                                          | 要使用的播放设备 ID，例如扬声器。设备 ID 通过 [`IAgoraRTC.getPlaybackDevices`](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartc#getplaybackdevices) 获取。该属性仅支持桌面端的 Chrome 浏览器，在其它浏览器上修改该属性的值将会抛出 `NOT_SUPPORTED` 错误。 |
| `volume`           | `number`                      | 无                                                                                                                                                          | 音量大小。取值范围 [0, 100]，0 代表静音，100 代表原始音量。                                                           |
| `cover`            | `string` &VerticalLine; `() => ReactNode` | 无                                                                                                                                                          | 当 `playVideo` 为 `false`时要渲染的封面图片或自定义组件，用于替代视频画面显示。支持传入在线图片的 URL 或本地图片的相对路径。                                                                                                                                                                                                                            |
| `children`         | `ReactNode`                   | 无                                                                                                                                                          | 需要展示的 React 节点。                     |
| `videoPlayerConfig`  |`VideoPlayerConfig` | 无 | 视频轨道的播放配置。可以设置播放参数（镜像/显示模式），详见 [`VideoPlayerConfig`](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/videoplayerconfig)。 |

<a id="table-slot-components-slot-7-3-3"></a>

**components-slot-7-3-3 details**

- `true`：播放远端用户的视频轨道。
- `false`：停止播放远端用户的视频轨道。

<a id="table-slot-components-slot-7-4-3"></a>

**components-slot-7-4-3 details**

- `true`：播放远端用户的音频轨道。
- `false`：停止播放远端用户的音频轨道。

#### 使用示例 [#使用示例-7]

```jsx
import { RemoteUser, useRemoteUsers } from "agora-rtc-react";

function App() {
  const remoteUsers = useRemoteUsers();

  return (
    <>
      {remoteUsers.map(user => (
        <RemoteUser key={user.uid} user={user} />
      ))}
    </>
  );
}
```