# 钩子 (/zh-CN/api-reference/rtc/react-sdk/hooks)
> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).
## useConnectionState [#useconnectionstate]
用于获取详细的 SDK 连接状态。
#### 参数 [#参数]
| 参数名 | 类型 | 是否必选 | 描述 |
| -------- | ---------------- | -------- | ---- |
| `client` | [`IAgoraRTCClient`](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient) | `null` | 可选 | 通过 Web SDK 的 [`IAgoraRTC.createClient`](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartc#createclient) 创建。 |
#### 返回值 [#返回值]
| 类型 | 描述 |
| ----------------- | ---------------------|
| `ConnectionState` | SDK 与服务器的连接状态。详见 [`ConnectionState`](/zh-CN/api-reference/rtc/react-sdk/web-sdk/globals#connectionstate)。 |
#### 使用示例 [#使用示例]
```jsx
import { useConnectionState } from "agora-rtc-react";
function App() {
const connectionState = useConnectionState();
return
{connectionState}
;
}
```
## useIsConnected [#useisconnected]
用于获取 SDK 是否连接到服务器。
#### 参数 [#参数-1]
| 参数名 | 类型 | 是否必选 | 描述 |
| -------- | ---------------- | -------- | ---- |
| `client` | [`IAgoraRTCClient`](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient) | `null` | 可选 | 通过 Web SDK 的 [`IAgoraRTC.createClient`](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartc#createclient) 创建。 |
#### 返回值 [#返回值-1]
| 类型 | 描述 |
| ----------------- | ---------------------|
| `boolean` | [hooks-slot-3-2-1 details](#table-slot-hooks-slot-3-2-1) |
**hooks-slot-3-2-1 details**
- `true`:SDK 已连接到服务器。
- `false`:SDK 没有连接到服务器。
#### 使用示例 [#使用示例-1]
```jsx
import { useIsConnected } from "agora-rtc-react";
function App() {
const isConnected = useIsConnected();
return {isConnected}
;
}
```
## useCurrentUID [#usecurrentuid]
用于获取当前用户 UID 。
#### 参数 [#参数-2]
| 参数名 | 类型 | 是否必选 | 描述 |
| -------- | ---------------- | -------- | ---- |
| `client` | [`IAgoraRTCClient`](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient) | `null` | 可选 | 通过 Web SDK 的 [`IAgoraRTC.createClient`](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartc#createclient) 创建。 |
#### 返回值 [#返回值-2]
| 类型 | 描述 |
| ----------------- | ---------------------|
| `UID` | `undefined` | 当前用户的 UID。如果当前用户没有加入任何频道,则返回 `undefined`。 |
#### 使用示例 [#使用示例-2]
```jsx
import { useCurrentUID } from "agora-rtc-react";
function App() {
const uid = useCurrentUID();
return {uid}
;
}
```
## useNetworkQuality [#usenetworkquality]
用于获取本地用户网络质量。
#### 参数 [#参数-3]
| 参数名 | 类型 | 是否必选 | 描述 |
| -------- | ---------------- | -------- | ---- |
| `client` | [`IAgoraRTCClient`](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient) | `null` | 可选 | 通过 Web SDK 的 [`IAgoraRTC.createClient`](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartc#createclient) 创建。 |
#### 返回值 [#返回值-3]
| 类型 | 描述 |
| ----------------- | ---------------------|
| `NetworkQuality` | 本地用户的网络质量信息。详见 [`NetworkQuality`](/zh-CN/api-reference/rtc/react-sdk/data-types)。 |
#### 使用示例 [#使用示例-3]
```jsx
import { useNetworkQuality } from "agora-rtc-react";
function App() {
const networkQuality = useNetworkQuality();
return {networkQuality}
;
}
```
## useVolumeLevel [#usevolumelevel]
用于自动获取音频轨道音量级别,自动获取的频率为每秒一次。
#### 参数 [#参数-4]
| 参数名 | 类型 | 是否必选 | 描述 |
| -------- | ---------------- | -------- | ---- |
| `audioTrack` | `IRemoteAudioTrack` | `ILocalAudioTrack` | `undefined` | 可选 | 本地或远端音频轨道,其中本地音频轨道通过 [`useLocalMicrophoneTrack`](/zh-CN/api-reference/rtc/react-sdk/hooks#uselocalmicrophonetrack) 创建。如果未定义,则音量级别为 0。 |
#### 返回值 [#返回值-4]
| 类型 | 描述 |
| -------- | ----------------------------------- |
| `number` | 音频轨道的音量级别。取值范围 [0, 1],1 代表理论最大音量。通常该值大于 0.6 代表用户在持续说话。 |
#### 使用示例 [#使用示例-4]
```jsx
import { useVolumeLevel, useLocalMicrophoneTrack } from "agora-rtc-react";
function App() {
const audioTrack = useLocalMicrophoneTrack();
const volumeLevel = useVolumeLevel(audioTrack);
return {volumeLevel}
;
}
```
## useRTCClient [#usertcclient]
用于获取 `IAgoraRTCClient` 对象。
#### 参数 [#参数-5]
| 参数名 | 类型 | 是否必选 | 描述 |
| -------- | ---------------- | -------- | ---- |
| `client` | [`IAgoraRTCClient`](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient) | `null`| 可选 | 如果传入该参数,则使用传入的 `IAgoraRTCClient` 对象;如果不传入该参数,则使用从[父组件的 Context](/zh-CN/api-reference/rtc/react-sdk/components#agorartcprovider)中获取的 `IAgoraRTCClient` 对象。 |
#### 返回值 [#返回值-5]
| 类型 | 描述 |
| ----------------- | ------------------------ |
| [`IAgoraRTCClient`](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient) | `IAgoraRTCClient` 对象。 |
#### 使用示例 [#使用示例-5]
```jsx
import { useRTCClient } from "agora-rtc-react";
function App() {
const client = useRTCClient();
return <>>;
}
```
## useJoin [#usejoin]
用于加入频道。当组件准备好时加入频道,当组件卸载时自动离开频道。
你可以通过 `fetchArgs` 自定义加入频道所需的条件,例如在加入频道前执行获取 Token 等异步操作。
#### 参数 [#参数-6]
| 参数名 | 类型 | 是否必选 | 描述 |
| -------- | ---------------- | -------- | ---- |
| `fetchArgs` | `JoinOptions` | `(() => Promise)` | 必选 | 加入频道所需参数或异步函数。详见 [`JoinOptions`](/zh-CN/api-reference/rtc/react-sdk/data-types#joinoptions)。 |
| `ready` | `boolean` | 可选 | 是否准备好加入频道。默认为 `true`。 |
| `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) 创建。 |
#### 返回值 [#返回值-6]
返回一个包含以下属性的对象:
| 属性 | 类型 | 描述 |
| ----------------------| ---------------------- | ------------------------ |
| `data` | `UID` | 成功加入频道的用户 ID。如果你在传入 ` fetchArgs` 时没有指定 `uid`,则返回默认值 `0`。|
| `isLoading` | `boolean` | [hooks-slot-13-3-2 details](#table-slot-hooks-slot-13-3-2) |
| `isConnected` | `boolean` | [hooks-slot-13-4-2 details](#table-slot-hooks-slot-13-4-2) |
| `error` | `AgoraRTCReactError` | `null` | 加入频道成功则返回 `null`,加入频道失败则抛出错误。错误详见 [`AgoraRTCReactError`](/zh-CN/api-reference/rtc/react-sdk/data-types#agorartcreacterror)。 |
**hooks-slot-13-3-2 details**
- `true`:正在执行加入频道相关操作。
- `false`:已经执行加入频道相关操作,但不代表成功加入频道。
**hooks-slot-13-4-2 details**
- `true`:SDK 已连接到服务器。即加入频道成功。
- `false`:SDK 没有连接到服务器。
#### 使用示例 [#使用示例-6]
```jsx
import { useJoin } from "agora-rtc-react";
function App() {
// 传入异步函数示例
// useJoin(async () => {
// 在加入频道前执行获取 Token 的操作,注意 getData 类型必须为 fetchArgs
// const getData = await getToken();
// return getData;
// }, calling);
useJoin(
{
appid: YOUR_APPID,
channel: YOUR_CHANNEL,
token: YOUR_TOKEN,
},
ready,
);
return <>>;
}
```
## usePublish [#usepublish]
用于发布本地轨道。当组件准备好时发布,当组件卸载时取消发布。
#### 参数 [#参数-7]
| 参数名 | 类型 | 是否必选 | 描述 |
| -------- | ---------------- | -------- | ---- |
| `tracks` | `(ILocalTrack` | `null)[]` | 必选 | 本地轨道列表。 |
| `readyToPublish` | `boolean` | 可选 | 是否准备好进行发布。默认为 `true`。 |
| `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) 创建。 |
#### 返回值 [#返回值-7]
返回一个包含以下属性的对象:
| 属性 | 类型 | 描述 |
| ----------------------| ---------------------- | ------------------------ |
| `isLoading` | `boolean` | [hooks-slot-15-2-2 details](#table-slot-hooks-slot-15-2-2) |
| `error` | `AgoraRTCReactError` | `null` | 发布成功则返回 `null`,发布失败则抛出错误。错误详见 [`AgoraRTCReactError`](/zh-CN/api-reference/rtc/react-sdk/data-types#agorartcreacterror)。 |
**hooks-slot-15-2-2 details**
- `true`:正在执行发布相关操作。
- `false`:已经执行发布相关操作,但不代表成功发布。
#### 使用示例 [#使用示例-7]
```jsx
import { useLocalMicrophoneTrack, useLocalCameraTrack, usePublish } from "agora-rtc-react";
function App() {
// get audioTrack and videoTrack before publish
const audioTrack = useLocalMicrophoneTrack();
const videoTrack = useLocalCameraTrack();
usePublish([audioTrack, videoTrack]);
return <>>;
}
```
## useLocalMicrophoneTrack [#uselocalmicrophonetrack]
用于创建本地麦克风音频轨道。你可以在不同组件中调用该方法以创建多个轨道。如果要在多个组件中访问同一个轨道,请确保在多个组件中都传入同一个轨道对象。
- 在组件被销毁之前,该 Hook 只会创建一次音频轨道。
- 组件卸载后,该 Hook 创建的音频轨道会停止发布。
#### 参数 [#参数-8]
| 参数名 | 类型 | 是否必选 | 描述 |
| -------- | ---------------- | -------- | ---- |
| `ready` | `boolean` | 可选 | 是否准备好创建轨道,默认为 `true`。 |
| `audioTrackConfig` | `MicrophoneAudioTrackInitConfig` | 可选 | 麦克风音频轨道的初始化配置,默认为 `{ ANS: true, AEC: true }`。详见 [`MicrophoneAudioTrackInitConfig`](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/microphoneaudiotrackinitconfig)。 |
#### 返回值 [#返回值-8]
返回一个包含以下属性的对象:
| 属性 | 类型 | 描述 |
| ----------------------| ---------------------- | ------------------------ |
| `localMicrophoneTrack` | `IMicrophoneAudioTrack` | `null` | 创建的本地麦克风音频轨道对象。 |
| `isLoading` | `boolean` | [hooks-slot-17-3-2 details](#table-slot-hooks-slot-17-3-2) |
| `error` | `AgoraRTCReactError` | `null` | 创建轨道成功则返回 `null`,创建轨道失败则抛出错误。错误详见 [`AgoraRTCReactError`](/zh-CN/api-reference/rtc/react-sdk/data-types#agorartcreacterror)。 |
**hooks-slot-17-3-2 details**
- `true`:正在执行创建轨道相关操作。
- `false`:已经执行创建轨道相关操作,但不代表成功创建轨道。
#### 使用示例 [#使用示例-8]
```jsx
import { useLocalMicrophoneTrack } from "agora-rtc-react";
function App() {
const audioTrack = useLocalMicrophoneTrack(true, { ANS: true, AEC: true });
return <>>;
}
```
## useLocalCameraTrack [#uselocalcameratrack]
用于创建本地摄像头视频轨道。你可以在不同组件中调用该方法以创建多个轨道。如果要在多个组件中访问同一个轨道,请确保在多个组件中都传入同一个轨道对象。
- 在组件被销毁之前,该 Hook 只会创建一次视频轨道。
- 组件卸载后,该 Hook 创建的视频轨道会停止发布。
#### 参数 [#参数-9]
| 参数名 | 类型 | 是否必选 | 描述 |
| -------- | ---------------- | -------- | ---- |
| `ready` | `boolean` | 可选 | 是否准备好创建轨道,默认为 `true`。 |
| `cameraVideoTrackConfig` | `CameraVideoTrackInitConfig` | 可选 | 摄像头视频轨道的初始化配置。详见 [`CameraVideoTrackInitConfig`](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/cameravideotrackinitconfig)。 |
#### 返回值 [#返回值-9]
返回一个包含以下属性的对象:
| 属性 | 类型 | 描述 |
| ----------------------| ---------------------- | ------------------------ |
| `localCameraTrack` | `ICameraVideoTrack` | `null` | 创建的摄像头视频轨道对象。 |
| `isLoading` | `boolean` | [hooks-slot-19-3-2 details](#table-slot-hooks-slot-19-3-2) |
| `error` | `AgoraRTCReactError` | `null` | 创建轨道成功则返回 `null`,创建轨道失败则抛出错误。错误详见 [`AgoraRTCReactError`](/zh-CN/api-reference/rtc/react-sdk/data-types#agorartcreacterror)。 |
**hooks-slot-19-3-2 details**
- `true`:正在执行创建轨道相关操作。
- `false`:已经执行创建轨道相关操作,但不代表成功创建轨道。
#### 使用示例 [#使用示例-9]
```jsx
import { useLocalCameraTrack } from "agora-rtc-react";
function App() {
const videoTrack = useLocalCameraTrack();
return <>>;
}
```
## useLocalScreenTrack [#uselocalscreentrack]
用于创建本地屏幕共享的视频轨道。
- 在组件被销毁之前,该 Hook 只会创建一次视频轨道。
- 组件卸载后,该 Hook 创建的视频轨道会停止发布。
#### 参数 [#参数-10]
| 参数名 | 类型 | 是否必选 | 描述 |
| -------- | ---------------- | -------- | ---- |
| `ready` | `boolean` | 可选 | 是否准备好创建轨道,默认为 `true`。 |
| `screenVideoTrackInitConfig` | [`screenVideoTrackInitConfig`](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/screenvideotrackinitconfig) | 必选 | 屏幕共享的视频配置,包括编码配置、采集配置等。 |
| `withAudio` | `string` | 必选 | 屏幕共享时是否同时分享屏幕共享输入源的音频。支持传入 `"enable"`、`"disable"` 或 `"auto"`。详见[`createScreenVideoTrack`](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartc#createscreenvideotrack)的参数解释。 |
#### 返回值 [#返回值-10]
返回一个包含以下属性的对象:
| 属性 | 类型 | 描述 |
| ----------------------| ---------------------- | ------------------------ |
| `screenTrack` | `[ILocalVideoTrack, ILocalAudioTrack]` | `ILocalVideoTrack` | `null` | 根据传入的 `withAudio`,返回创建的屏幕共享视频轨道或者屏幕共享视频轨道和音频轨道。详见 [`createScreenVideoTrack`](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartc#createscreenvideotrack)的返回值。 |
| `isLoading` | `boolean` | [hooks-slot-21-3-2 details](#table-slot-hooks-slot-21-3-2) |
| `error` | `AgoraRTCReactError` | `null` | 创建轨道成功则返回 `null`,创建轨道失败则抛出错误。错误详见 [`AgoraRTCReactError`](/zh-CN/api-reference/rtc/react-sdk/data-types#agorartcreacterror)。 |
**hooks-slot-21-3-2 details**
- `true`:正在执行创建轨道相关操作。
- `false`:已经执行创建轨道相关操作,但不代表成功创建轨道。
#### 注意事项 [#注意事项]
- 推荐把返回值中的视频轨道对象包裹在 [`AgoraRTCScreenShareProvider`](/zh-CN/api-reference/rtc/react-sdk/components#agorartcscreenshareprovider) 中。
- 如果你从返回值中获取了视频轨道对象和音频轨道对象,但只发布了其中一个轨道,在停止屏幕共享之前还需要调用 Web SDK 的 [`ILocalTrack.close`](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/ilocaltrack#close) 方法手动关闭未发布的轨道。已发布的轨道会自动关闭。
- 由于订阅本地的屏幕共享轨道会造成重复计费,推荐你在订阅视频轨道时增加是否为本地轨道的判断。
#### 使用示例 [#使用示例-10]
**示例 1: 把屏幕共享视频轨道包裹在 AgoraRTCScreenShareProvider 中**
```jsx
import { AgoraRTCScreenShareProvider, LocalVideoTrack, useLocalScreenTrack } from "agora-rtc-react";
function App() {
const { screenTrack, error } = useLocalScreenTrack(screenShareOn, {}, "disable");
return (
);
}
```
**示例 2: 避免订阅本地屏幕共享轨道**
```jsx
import { useRemoteUsers, useRemoteVideoTracks, useRemoteAudioTracks } from "agora-rtc-react";
function App() {
const remoteUsers = useRemoteUsers();
const { videoTracks } = useRemoteVideoTracks(
// 在订阅列表中移除本地用户的屏幕共享视频轨道
remoteUsers.filter(user => user.uid !== appConfig.ShareScreenUID),
);
const { audioTracks } = useRemoteAudioTracks(
// 在订阅列表中移除本地用户的屏幕共享音频轨道
remoteUsers.filter(user => user.uid !== appConfig.ShareScreenUID),
);
return <>>;
}
```
## useRemoteVideoTracks [#useremotevideotracks]
用于自动订阅和获取远端用户视频轨道。
- 当组件卸载时,该 Hook 会停止订阅 `users` 参数对应的远端用户视频轨道。
- 当传入的 `users` 发生改变时,该 Hook 会更新订阅的视频轨道。
#### 参数 [#参数-11]
| 参数名 | 类型 | 是否必选 | 描述 |
| -------- | ---------------- | -------- | ---- |
| `users` | `IAgoraRTCRemoteUser[]` | `undefined` | 必选 | 远端用户列表。 |
| `client` | [`IAgoraRTCClient`](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient) | `null` | 可选 | 通过 Web SDK 的 [`IAgoraRTC.createClient`](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartc#createclient) 创建。 |
#### 返回值 [#返回值-11]
返回一个包含以下属性的对象:
| 属性 | 类型 | 描述 |
| ----------------------| ---------------------- | ------------------------ |
| `videoTracks` | `IRemoteVideoTrack[]` | 已订阅的远端用户视频轨道列表。 |
| `isLoading` | `boolean` | [hooks-slot-23-3-2 details](#table-slot-hooks-slot-23-3-2) |
| `error` | `AgoraRTCReactError` | `null` | 订阅成功则返回 `null`,订阅失败则抛出错误。错误详见 [`AgoraRTCReactError`](/zh-CN/api-reference/rtc/react-sdk/data-types#agorartcreacterror)。 |
**hooks-slot-23-3-2 details**
- `true`:正在执行订阅相关操作。
- `false`:已经执行订阅相关操作,但不代表成功订阅。
#### 使用示例 [#使用示例-11]
```jsx
import { useRemoteUsers, useRemoteVideoTracks } from "agora-rtc-react";
function App() {
const remoteUsers = useRemoteUsers();
const videoTracks = useRemoteVideoTracks(remoteUsers);
return <>>;
}
```
## useRemoteAudioTracks [#useremoteaudiotracks]
用于自动订阅和获取远端用户音频轨道。
- 当组件卸载时,该 Hook 会停止订阅 `users` 参数对应的远端用户音频轨道。
- 当传入的 `users` 发生改变时,该 Hook 会更新订阅的音频轨道。
#### 参数 [#参数-12]
| 参数名 | 类型 | 是否必选 | 描述 |
| -------- | ---------------- | -------- | ---- |
| `users` | `IAgoraRTCRemoteUser[]` | `undefined` | 必选 | 远端用户列表。 |
| `client` | [`IAgoraRTCClient`](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient) | `null` | 可选 | 通过 Web SDK 的 [`IAgoraRTC.createClient`](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartc#createclient) 创建。 |
#### 返回值 [#返回值-12]
返回一个包含以下属性的对象:
| 属性 | 类型 | 描述 |
| ----------------------| ---------------------- | ------------------------ |
| `audioTracks` | `IRemoteAudioTrack[]` | 已订阅的远端用户音频轨道列表。 |
| `isLoading` | `boolean` | [hooks-slot-25-3-2 details](#table-slot-hooks-slot-25-3-2) |
| `error` | `AgoraRTCReactError` | `null` | 订阅成功则返回 `null`,订阅失败则抛出错误。错误详见 [`AgoraRTCReactError`](/zh-CN/api-reference/rtc/react-sdk/data-types#agorartcreacterror)。 |
**hooks-slot-25-3-2 details**
- `true`:正在执行订阅相关操作。
- `false`:已经执行订阅相关操作,但不代表成功订阅。
#### 使用示例 [#使用示例-12]
```jsx
import { useRemoteUsers, useRemoteVideoTracks } from "agora-rtc-react";
function App() {
//get remote user list
const remoteUsers = useRemoteUsers();
const videoTracks = useRemoteVideoTracks(remoteUsers);
return <>>;
}
```
## useRemoteUserTrack [#useremoteusertrack]
用于获取远端用户音视频轨道。
#### 参数 [#参数-13]
| 参数名 | 类型 | 是否必选 | 描述 |
| -------- | ---------------- | -------- | ---- |
| `user` | `IAgoraRTCRemoteUser` | `undefined` | 必选 | 远端用户对象。 |
| `mediaType` | `"video"` | `"audio"` | 必选 | 媒体类型,支持传入 `"video"` 或 `"audio"`。 |
| `client` | [`IAgoraRTCClient`](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient) | `null` | 可选 | 通过 Web SDK 的 [`IAgoraRTC.createClient`](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartc#createclient) 创建。 |
#### 返回值 [#返回值-13]
返回一个包含以下属性的对象:
| 属性 | 类型 | 描述 |
| ----------------------| ---------------------- | ------------------------ |
| `track` | `IRemoteVideoTrack` | `IRemoteAudioTrack` | `undefined` | 远端用户的音频或视频轨道(取决于传入的 `mediaType`)。如果远端用户或音频、视频轨道不存在,则返回 `undefined`。 |
| `isLoading` | `boolean` | [hooks-slot-27-3-2 details](#table-slot-hooks-slot-27-3-2) |
| `error` | `AgoraRTCReactError` | `null` | 获取轨道成功则返回 `null`,获取轨道失败则抛出错误。错误详见 [`AgoraRTCReactError`](/zh-CN/api-reference/rtc/react-sdk/data-types#agorartcreacterror)。|
**hooks-slot-27-3-2 details**
- `true`:正在执行获取轨道相关操作。
- `false`:已经执行获取轨道相关操作,但不代表成功获取轨道。
#### 使用示例 [#使用示例-13]
```jsx
import { useRemoteUsers, useRemoteUserTrack } from "agora-rtc-react";
function App() {
const remoteUsers = useRemoteUsers();
const videoTrack = useRemoteUserTrack(remoteUsers[0], "video");
const audioTrack = useRemoteUserTrack(remoteUsers[0], "audio");
return <>>;
}
```
## useRemoteUsers [#useremoteusers]
用于获取远端用户列表。
发生以下情况时,该 Hook 的返回值会更新:
- 远端用户加入或离开频道。
- 远端用户的角色改变(比如从主播变为观众)。
- 远端用户发布或取消发布音频或视频轨道。
#### 参数 [#参数-14]
| 参数名 | 类型 | 是否必选 | 描述 |
| -------- | ---------------- | -------- | ---- |
| `client` | [`IAgoraRTCClient`](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient) | `null`| 可选 | 通过 Web SDK 的 [`IAgoraRTC.createClient`](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartc#createclient) 创建。 |
#### 返回值 [#返回值-14]
| 类型 | 描述 |
| ----------------------- | -------------- |
| `IAgoraRTCRemoteUser[]` | 远端用户列表。 |
#### 使用示例 [#使用示例-14]
```jsx
import { useRemoteUsers } from "agora-rtc-react";
function App() {
const remoteUsers = useRemoteUsers();
return <>>;
}
```
## useAutoPlayVideoTrack [#useautoplayvideotrack]
用于自动播放本地或远端视频轨道。
- 当组件挂载时,该 Hook 会根据传入的 `play` 判断是否自动播放。
- 当组件卸载时,该 Hook 会停止播放 `track` 对应的视频轨道。
#### 参数 [#参数-15]
| 参数名 | 类型 | 是否必选 | 描述 |
| -------- | ---------------- | -------- | ---- |
| `track` | `IRemoteVideoTrack` | `ILocalVideoTrack` | 必选 | 远端视频轨道对象或本地视频轨道对象。 |
| `play` | `boolean` | 可选 | [hooks-slot-30-3-3 details](#table-slot-hooks-slot-30-3-3) |
| `videoPlayerConfig` |`VideoPlayerConfig` | 可选 | 视频轨道的播放配置。可以设置播放参数(镜像/显示模式),详见 [`VideoPlayerConfig`](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/videoplayerconfig)。对于本地视频轨道,镜像模式默认开启。|
| `div` | `HTMLElement` | `null` | 可选 | 用于渲染视频轨道的 HTML 元素。只有在 `play` 为 `true` 并且传入 `div` 参数的情况下,视频才会在该元素中自动播放。其它情况则不会自动播放视频。 |
**hooks-slot-30-3-3 details**
- `true`:播放该轨道。
- `false`:停止播放该轨道。
#### 返回值 [#返回值-15]
无。
#### 使用示例 [#使用示例-15]
```jsx
import { useAutoPlayVideoTrack, useLocalCameraTrack } from "agora-rtc-react";
function App() {
const videoTrack = useLocalCameraTrack();
useAutoPlayVideoTrack(track, play, div);
return <>>;
}
```
## useAutoPlayAudioTrack [#useautoplayaudiotrack]
用于自动播放本地或远端音频轨道。
- 当组件挂载时,该 Hook 会根据传入的 `play` 判断是否自动播放。
- 当组件卸载时,该 Hook 会停止播放 `track` 对应的音频轨道。
#### 参数 [#参数-16]
| 参数名 | 类型 | 是否必选 | 描述 |
| -------- | ---------------- | -------- | ---- |
| `track` | `IRemoteAudioTrack` | `ILocalAudioTrack` | 必选 | 远端音频轨道对象或本地音频轨道对象。 |
| `play` | `boolean` | 可选 | [hooks-slot-31-3-3 details](#table-slot-hooks-slot-31-3-3) |
**hooks-slot-31-3-3 details**
- `true`:播放该轨道。
- `false`:停止播放该轨道。
#### 返回值 [#返回值-16]
无。
#### 使用示例 [#使用示例-16]
```jsx
import { useAutoPlayAudioTrack, useLocalMicrophoneTrack } from "agora-rtc-react";
function App() {
const audioTrack = useLocalMicrophoneTrack();
useAutoPlayAudioTrack(track, play);
return <>>;
}
```
## useClientEvent [#useclientevent]
用于监听 `IAgoraRTCClient` 对象的指定事件。
- 当组件挂载时,该 Hook 会注册对应的事件监听器。
- 当组件卸载时,该 Hook 会销毁对应的事件监听器。
#### 参数 [#参数-17]
| 参数名 | 类型 | 是否必选 | 描述 |
| -------- | ---------------- | -------- | ---- |
| `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) 创建。 |
| `event` | `string` | 必选 | 事件名称。支持的事件详见[`IAgoraRTCClient.on`](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient#on)。 |
| `listener` | `Function` | 必选 | 回调函数。当传入的事件触发时,该函数会被调用。支持的回调详见 [`IAgoraRTCClient.on`](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient#on)。 |
#### 返回值 [#返回值-17]
无。
#### 使用示例 [#使用示例-17]
```jsx
import { useRTCClient, useClientEvent } from "agora-rtc-react";
function App() {
const client = useRTCClient();
useClientEvent(client, "connection-state-change", () => {});
return <>>;
}
```
## useTrackEvent [#usetrackevent]
用于监听本地轨道对象或远端轨道对象的特定事件。
- 当组件挂载时,该 Hook 会注册对应的事件监听器。
- 当组件卸载时,该 Hook 会销毁对应的事件监听器。
#### 参数 [#参数-18]
| 参数名 | 类型 | 是否必选 | 描述 |
| -------- | ---------------- | -------- | ---- |
| `track` | `ITrack` | 必选 | 本地轨道对象或远端轨道对象。 |
| `event` | `string` | 必选 | 事件名称。 |
| `listener` | `Function` | 必选 | 回调函数。当传入的事件触发时,该函数会被调用。 |
不同的 `track` 对应的 `event` 和 `listener` 也不同。支持传入的参数组合如下:
| `track` | `event` 和 `listener` |
| -------- | ---------------- |
| `ILocalTrack` | `ILocalVideoTrack` | `null` | 详见 [`ILocalTrack.on`](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/ilocaltrack#on)。 |
| `IBufferSourceAudioTrack` | `null` |详见 [`IBufferSourceAudioTrack.on`](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/ibuffersourceaudiotrack#on)。 |
| `ILocalVideoTrack` | `null` | 详见 [`ILocalVideoTrack.on`](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/ilocalvideotrack#on)。 |
| `IRemoteTrack` | `null` | 详见 [`IRemoteTrack.on`](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iremotetrack#event_first_frame_decoded)。 |
#### 返回值 [#返回值-18]
无。
#### 使用示例 [#使用示例-18]
```jsx
import { useRTCClient, useLocalCameraTrack, useTrackEvent } from "agora-rtc-react";
function App() {
const videoTrack = useLocalCameraTrack();
useTrackEvent(client, "video-element-visible-status", () => {});
return <>>;
}
```