Hooks

useConnectionState

用于获取详细的 SDK 连接状态。

参数

参数名	类型	是否必选	描述
client	IAgoraRTCClient | null	可选	通过 Web SDK 的 IAgoraRTC.createClient 创建。

返回值

类型	描述
ConnectionState	SDK 与服务器的连接状态。详见 ConnectionState。

使用示例

React JSX

import { useConnectionState } from "agora-rtc-react";

function App() {
  const connectionState = useConnectionState();

  return <div>{connectionState}</div>;
}

useIsConnected

用于获取 SDK 是否连接到服务器。

参数

参数名	类型	是否必选	描述
client	IAgoraRTCClient | null	可选	通过 Web SDK 的 IAgoraRTC.createClient 创建。

返回值

类型	描述
boolean	true：SDK 已连接到服务器。 false：SDK 没有连接到服务器。

使用示例

React JSX

import { useIsConnected } from "agora-rtc-react";

function App() {
  const isConnected = useIsConnected();

  return <div>{isConnected}</div>;
}

useCurrentUID

用于获取当前用户 UID 。

参数

参数名	类型	是否必选	描述
client	IAgoraRTCClient | null	可选	通过 Web SDK 的 IAgoraRTC.createClient 创建。

返回值

类型	描述
UID | undefined	当前用户的 UID。如果当前用户没有加入任何频道，则返回 undefined。

使用示例

React JSX

import { useCurrentUID } from "agora-rtc-react";

function App() {
  const uid = useCurrentUID();

  return <div>{uid}</div>;
}

useNetworkQuality

用于获取本地用户网络质量。

参数

参数名	类型	是否必选	描述
client	IAgoraRTCClient | null	可选	通过 Web SDK 的 IAgoraRTC.createClient 创建。

返回值

类型	描述
NetworkQuality	本地用户的网络质量信息。详见 NetworkQuality。

使用示例

React JSX

import { useNetworkQuality } from "agora-rtc-react";

function App() {
  const networkQuality = useNetworkQuality();

  return <div>{networkQuality}</div>;
}

useVolumeLevel

用于自动获取音频轨道音量级别，自动获取的频率为每秒一次。

参数

参数名	类型	是否必选	描述
audioTrack	IRemoteAudioTrack | ILocalAudioTrack | undefined	可选	本地或远端音频轨道，其中本地音频轨道通过 useLocalMicrophoneTrack 创建。如果未定义，则音量级别为 0。

返回值

类型	描述
number	音频轨道的音量级别。取值范围 [0, 1]，1 代表理论最大音量。通常该值大于 0.6 代表用户在持续说话。

使用示例

React JSX

import { useVolumeLevel, useLocalMicrophoneTrack } from "agora-rtc-react";

function App() {
  const audioTrack = useLocalMicrophoneTrack();
  const volumeLevel = useVolumeLevel(audioTrack);

  return <div>{volumeLevel}</div>;
}

useRTCClient

用于获取 IAgoraRTCClient 对象。

参数

参数名	类型	是否必选	描述
client	IAgoraRTCClient | null	可选	如果传入该参数，则使用传入的 IAgoraRTCClient 对象；如果不传入该参数，则使用从父组件的 Context中获取的 IAgoraRTCClient 对象。

返回值

类型	描述
IAgoraRTCClient	IAgoraRTCClient 对象。

使用示例

React JSX

import { useRTCClient } from "agora-rtc-react";

function App() {
  const client = useRTCClient();

  return <></>;
}

useJoin

用于加入频道。当组件准备好时加入频道，当组件卸载时自动离开频道。

你可以通过 fetchArgs 自定义加入频道所需的条件，例如在加入频道前执行获取 Token 等异步操作。

参数

参数名	类型	是否必选	描述
fetchArgs	JoinOptions | (() => Promise<JoinOptions>)	必选	加入频道所需参数或异步函数。详见 JoinOptions。
ready	boolean	可选	是否准备好加入频道。默认为 true。
client	IAgoraRTCClient	可选	通过 Web SDK 的 IAgoraRTC.createClient 创建。

返回值

返回一个包含以下属性的对象：

属性	类型	描述
data	UID	成功加入频道的用户 ID。如果你在传入 fetchArgs 时没有指定 uid，则返回默认值 0。
isLoading	boolean	true：正在执行加入频道相关操作。 false：已经执行加入频道相关操作，但不代表成功加入频道。
isConnected	boolean	true：SDK 已连接到服务器。即加入频道成功。 false：SDK 没有连接到服务器。
error	AgoraRTCReactError | null	加入频道成功则返回 null，加入频道失败则抛出错误。错误详见 AgoraRTCReactError。

使用示例

React 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

用于发布本地轨道。当组件准备好时发布，当组件卸载时取消发布。

参数

参数名	类型	是否必选	描述
tracks	(ILocalTrack | null)[]	必选	本地轨道列表。
readyToPublish	boolean	可选	是否准备好进行发布。默认为 true。
client	IAgoraRTCClient	可选	通过 Web SDK 的 IAgoraRTC.createClient 创建。

返回值

返回一个包含以下属性的对象：

属性	类型	描述
isLoading	boolean	true：正在执行发布相关操作。 false：已经执行发布相关操作，但不代表成功发布。
error	AgoraRTCReactError | null	发布成功则返回 null，发布失败则抛出错误。错误详见 AgoraRTCReactError。

使用示例

React 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

用于创建本地麦克风音频轨道。你可以在不同组件中调用该方法以创建多个轨道。如果要在多个组件中访问同一个轨道，请确保在多个组件中都传入同一个轨道对象。

• 在组件被销毁之前，该 Hook 只会创建一次音频轨道。
• 组件卸载后，该 Hook 创建的音频轨道会停止发布。

参数

参数名	类型	是否必选	描述
ready	boolean	可选	是否准备好创建轨道，默认为 true。
audioTrackConfig	MicrophoneAudioTrackInitConfig	可选	麦克风音频轨道的初始化配置，默认为 { ANS: true, AEC: true }。详见 MicrophoneAudioTrackInitConfig。

返回值

返回一个包含以下属性的对象：

属性	类型	描述
localMicrophoneTrack	IMicrophoneAudioTrack | null	创建的本地麦克风音频轨道对象。
isLoading	boolean	true：正在执行创建轨道相关操作。 false：已经执行创建轨道相关操作，但不代表成功创建轨道。
error	AgoraRTCReactError | null	创建轨道成功则返回 null，创建轨道失败则抛出错误。错误详见 AgoraRTCReactError。

使用示例

React JSX

import { useLocalMicrophoneTrack } from "agora-rtc-react";

function App() {
  const audioTrack = useLocalMicrophoneTrack(true, { ANS: true, AEC: true });

  return <></>;
}

useLocalCameraTrack

用于创建本地摄像头视频轨道。你可以在不同组件中调用该方法以创建多个轨道。如果要在多个组件中访问同一个轨道，请确保在多个组件中都传入同一个轨道对象。

• 在组件被销毁之前，该 Hook 只会创建一次视频轨道。
• 组件卸载后，该 Hook 创建的视频轨道会停止发布。

参数

参数名	类型	是否必选	描述
ready	boolean	可选	是否准备好创建轨道，默认为 true。
cameraVideoTrackConfig	CameraVideoTrackInitConfig	可选	摄像头视频轨道的初始化配置。详见 CameraVideoTrackInitConfig。

返回值

返回一个包含以下属性的对象：

属性	类型	描述
localCameraTrack	ICameraVideoTrack | null	创建的摄像头视频轨道对象。
isLoading	boolean	true：正在执行创建轨道相关操作。 false：已经执行创建轨道相关操作，但不代表成功创建轨道。
error	AgoraRTCReactError | null	创建轨道成功则返回 null，创建轨道失败则抛出错误。错误详见 AgoraRTCReactError。

使用示例

React JSX

import { useLocalCameraTrack } from "agora-rtc-react";

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

  return <></>;
}

useLocalScreenTrack

用于创建本地屏幕共享的视频轨道。

• 在组件被销毁之前，该 Hook 只会创建一次视频轨道。
• 组件卸载后，该 Hook 创建的视频轨道会停止发布。

参数

参数名	类型	是否必选	描述
ready	boolean	可选	是否准备好创建轨道，默认为 true。
screenVideoTrackInitConfig	screenVideoTrackInitConfig	必选	屏幕共享的视频配置，包括编码配置、采集配置等。
withAudio	string	必选	屏幕共享时是否同时分享屏幕共享输入源的音频。支持传入 "enable"、"disable" 或 "auto"。详见createScreenVideoTrack的参数解释。

返回值

返回一个包含以下属性的对象：

属性	类型	描述
screenTrack	[ILocalVideoTrack, ILocalAudioTrack] | ILocalVideoTrack | null	根据传入的 withAudio，返回创建的屏幕共享视频轨道或者屏幕共享视频轨道和音频轨道。详见 createScreenVideoTrack的返回值。
isLoading	boolean	true：正在执行创建轨道相关操作。 false：已经执行创建轨道相关操作，但不代表成功创建轨道。
error	AgoraRTCReactError | null	创建轨道成功则返回 null，创建轨道失败则抛出错误。错误详见 AgoraRTCReactError。

注意事项

• 推荐把返回值中的视频轨道对象包裹在 AgoraRTCScreenShareProvider 中。
• 如果你从返回值中获取了视频轨道对象和音频轨道对象，但只发布了其中一个轨道，在停止屏幕共享之前还需要调用 Web SDK 的 ILocalTrack.close 方法手动关闭未发布的轨道。已发布的轨道会自动关闭。
• 由于订阅本地的屏幕共享轨道会造成重复计费，推荐你在订阅视频轨道时增加是否为本地轨道的判断。

使用示例

示例 1: 把屏幕共享视频轨道包裹在 AgoraRTCScreenShareProvider 中

React JSX

import { AgoraRTCScreenShareProvider, LocalVideoTrack, useLocalScreenTrack } from "agora-rtc-react";

function App() {
  const { screenTrack, error } = useLocalScreenTrack(screenShareOn, {}, "disable");

  return (
    <AgoraRTCScreenShareProvider client={client}>
      <LocalVideoTrack play style={{ width: "300px", height: "300px" }} track={screenTrack} />
    </AgoraRTCScreenShareProvider>
  );
}

示例 2: 避免订阅本地屏幕共享轨道

React 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

用于自动订阅和获取远端用户视频轨道。

• 当组件卸载时，该 Hook 会停止订阅 users 参数对应的远端用户视频轨道。
• 当传入的 users 发生改变时，该 Hook 会更新订阅的视频轨道。

参数

参数名	类型	是否必选	描述
users	IAgoraRTCRemoteUser[] | undefined	必选	远端用户列表。
client	IAgoraRTCClient | null	可选	通过 Web SDK 的 IAgoraRTC.createClient 创建。

返回值

返回一个包含以下属性的对象：

属性	类型	描述
videoTracks	IRemoteVideoTrack[]	已订阅的远端用户视频轨道列表。
isLoading	boolean	true：正在执行订阅相关操作。 false：已经执行订阅相关操作，但不代表成功订阅。
error	AgoraRTCReactError | null	订阅成功则返回 null，订阅失败则抛出错误。错误详见 AgoraRTCReactError。

使用示例

React JSX

import { useRemoteUsers, useRemoteVideoTracks } from "agora-rtc-react";

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

  return <></>;
}

useRemoteAudioTracks

用于自动订阅和获取远端用户音频轨道。

• 当组件卸载时，该 Hook 会停止订阅 users 参数对应的远端用户音频轨道。
• 当传入的 users 发生改变时，该 Hook 会更新订阅的音频轨道。

参数

参数名	类型	是否必选	描述
users	IAgoraRTCRemoteUser[] | undefined	必选	远端用户列表。
client	IAgoraRTCClient | null	可选	通过 Web SDK 的 IAgoraRTC.createClient 创建。

返回值

返回一个包含以下属性的对象：

属性	类型	描述
audioTracks	IRemoteAudioTrack[]	已订阅的远端用户音频轨道列表。
isLoading	boolean	true：正在执行订阅相关操作。 false：已经执行订阅相关操作，但不代表成功订阅。
error	AgoraRTCReactError | null	订阅成功则返回 null，订阅失败则抛出错误。错误详见 AgoraRTCReactError。

使用示例

React JSX

import { useRemoteUsers, useRemoteVideoTracks } from "agora-rtc-react";

function App() {
  //get remote user list
  const remoteUsers = useRemoteUsers();
  const videoTracks = useRemoteVideoTracks(remoteUsers);

  return <></>;
}

useRemoteUserTrack

用于获取远端用户音视频轨道。

参数

参数名	类型	是否必选	描述
user	IAgoraRTCRemoteUser | undefined	必选	远端用户对象。
mediaType	"video" | "audio"	必选	媒体类型，支持传入 "video" 或 "audio"。
client	IAgoraRTCClient | null	可选	通过 Web SDK 的 IAgoraRTC.createClient 创建。

返回值

返回一个包含以下属性的对象：

属性	类型	描述
track	IRemoteVideoTrack | IRemoteAudioTrack | undefined	远端用户的音频或视频轨道（取决于传入的 mediaType）。如果远端用户或音频、视频轨道不存在，则返回 undefined。
isLoading	boolean	true：正在执行获取轨道相关操作。 false：已经执行获取轨道相关操作，但不代表成功获取轨道。
error	AgoraRTCReactError | null	获取轨道成功则返回 null，获取轨道失败则抛出错误。错误详见 AgoraRTCReactError。

使用示例

React 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

用于获取远端用户列表。

发生以下情况时，该 Hook 的返回值会更新：

• 远端用户加入或离开频道。
• 远端用户的角色改变（比如从主播变为观众）。
• 远端用户发布或取消发布音频或视频轨道。

参数

参数名	类型	是否必选	描述
client	IAgoraRTCClient | null	可选	通过 Web SDK 的 IAgoraRTC.createClient 创建。

返回值

类型	描述
IAgoraRTCRemoteUser[]	远端用户列表。

使用示例

React JSX

import { useRemoteUsers } from "agora-rtc-react";

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

  return <></>;
}

useAutoPlayVideoTrack

用于自动播放本地或远端视频轨道。

• 当组件挂载时，该 Hook 会根据传入的 play 判断是否自动播放。
• 当组件卸载时，该 Hook 会停止播放 track 对应的视频轨道。

参数

参数名	类型	是否必选	描述
track	IRemoteVideoTrack | ILocalVideoTrack	必选	远端视频轨道对象或本地视频轨道对象。
play	boolean	可选	true：播放该轨道。 false：停止播放该轨道。
videoPlayerConfig	VideoPlayerConfig	可选	视频轨道的播放配置。可以设置播放参数（镜像/显示模式），详见 VideoPlayerConfig。对于本地视频轨道，镜像模式默认开启。
div	HTMLElement | null	可选	用于渲染视频轨道的 HTML 元素。只有在 play 为 true 并且传入 div 参数的情况下，视频才会在该元素中自动播放。其它情况则不会自动播放视频。

返回值

无。

使用示例

React JSX

import { useAutoPlayVideoTrack, useLocalCameraTrack } from "agora-rtc-react";

function App() {
  const videoTrack = useLocalCameraTrack();
  useAutoPlayVideoTrack(track, play, div);

  return <></>;
}

useAutoPlayAudioTrack

用于自动播放本地或远端音频轨道。

• 当组件挂载时，该 Hook 会根据传入的 play 判断是否自动播放。
• 当组件卸载时，该 Hook 会停止播放 track 对应的音频轨道。

参数

参数名	类型	是否必选	描述
track	IRemoteAudioTrack | ILocalAudioTrack	必选	远端音频轨道对象或本地音频轨道对象。
play	boolean	可选	true：播放该轨道。 false：停止播放该轨道。

返回值

无。

使用示例

React JSX

import { useAutoPlayAudioTrack, useLocalMicrophoneTrack } from "agora-rtc-react";

function App() {
  const audioTrack = useLocalMicrophoneTrack();
  useAutoPlayAudioTrack(track, play);

  return <></>;
}

useClientEvent

用于监听 IAgoraRTCClient 对象的指定事件。

• 当组件挂载时，该 Hook 会注册对应的事件监听器。
• 当组件卸载时，该 Hook 会销毁对应的事件监听器。

参数

参数名	类型	是否必选	描述
client	IAgoraRTCClient	必选	通过 Web SDK 的 IAgoraRTC.createClient 创建。
event	string	必选	事件名称。支持的事件详见IAgoraRTCClient.on。
listener	Function	必选	回调函数。当传入的事件触发时，该函数会被调用。支持的回调详见 IAgoraRTCClient.on。

返回值

无。

使用示例

React JSX

import { useRTCClient, useClientEvent } from "agora-rtc-react";

function App() {
  const client = useRTCClient();
  useClientEvent(client, "connection-state-change", () => {});

  return <></>;
}

useTrackEvent

用于监听本地轨道对象或远端轨道对象的特定事件。

• 当组件挂载时，该 Hook 会注册对应的事件监听器。
• 当组件卸载时，该 Hook 会销毁对应的事件监听器。

参数

参数名	类型	是否必选	描述
track	ITrack	必选	本地轨道对象或远端轨道对象。
event	string	必选	事件名称。
listener	Function	必选	回调函数。当传入的事件触发时，该函数会被调用。

不同的 track 对应的 event 和 listener 也不同。支持传入的参数组合如下：

track	event 和 listener
ILocalTrack | ILocalVideoTrack | null	详见 ILocalTrack.on。
IBufferSourceAudioTrack | null	详见 IBufferSourceAudioTrack.on。
ILocalVideoTrack | null	详见 ILocalVideoTrack.on。
IRemoteTrack | null	详见 IRemoteTrack.on。

返回值

无。

使用示例

React JSX

import { useRTCClient, useLocalCameraTrack, useTrackEvent } from "agora-rtc-react";

function App() {
  const videoTrack = useLocalCameraTrack();
  useTrackEvent(client, "video-element-visible-status", () => {});

  return <></>;
}