# 钩子 (/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 <>; } ```