需要访问旧版文档站？前往旧版文档官网首页。 (在新标签页打开)
声网文档中心

钩子

  • React

更新时间不可用

useConnectionState

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

参数

参数名类型是否必选描述
clientIAgoraRTCClient | null可选通过 Web SDK 的 IAgoraRTC.createClient 创建。
表格内容超出当前宽度，可横向滚动查看更多列。

返回值

类型描述
ConnectionStateSDK 与服务器的连接状态。详见 ConnectionState。
表格内容超出当前宽度，可横向滚动查看更多列。

使用示例

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

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

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

useIsConnected

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

参数

参数名类型是否必选描述
clientIAgoraRTCClient | null可选通过 Web SDK 的 IAgoraRTC.createClient 创建。
表格内容超出当前宽度，可横向滚动查看更多列。

返回值

类型描述
boolean
  • true：SDK 已连接到服务器。
  • false：SDK 没有连接到服务器。
表格内容超出当前宽度，可横向滚动查看更多列。

使用示例

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

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

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

useCurrentUID

用于获取当前用户 UID 。

参数

参数名类型是否必选描述
clientIAgoraRTCClient | null可选通过 Web SDK 的 IAgoraRTC.createClient 创建。
表格内容超出当前宽度，可横向滚动查看更多列。

返回值

类型描述
UID | undefined当前用户的 UID。如果当前用户没有加入任何频道，则返回 undefined。
表格内容超出当前宽度，可横向滚动查看更多列。

使用示例

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

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

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

useNetworkQuality

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

参数

参数名类型是否必选描述
clientIAgoraRTCClient | null可选通过 Web SDK 的 IAgoraRTC.createClient 创建。
表格内容超出当前宽度，可横向滚动查看更多列。

返回值

类型描述
NetworkQuality本地用户的网络质量信息。详见 NetworkQuality。
表格内容超出当前宽度，可横向滚动查看更多列。

使用示例

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

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

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

useVolumeLevel

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

参数

参数名类型是否必选描述
audioTrackIRemoteAudioTrack | ILocalAudioTrack | undefined可选本地或远端音频轨道，其中本地音频轨道通过 useLocalMicrophoneTrack 创建。如果未定义，则音量级别为 0。
表格内容超出当前宽度，可横向滚动查看更多列。

返回值

类型描述
number音频轨道的音量级别。取值范围 [0, 1]，1 代表理论最大音量。通常该值大于 0.6 代表用户在持续说话。
表格内容超出当前宽度，可横向滚动查看更多列。

使用示例

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

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

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

useRTCClient

用于获取 IAgoraRTCClient 对象。

参数

参数名类型是否必选描述
clientIAgoraRTCClient | null可选如果传入该参数，则使用传入的 IAgoraRTCClient 对象；如果不传入该参数，则使用从父组件的 Context中获取的 IAgoraRTCClient 对象。
表格内容超出当前宽度，可横向滚动查看更多列。

返回值

类型描述
IAgoraRTCClientIAgoraRTCClient 对象。
表格内容超出当前宽度，可横向滚动查看更多列。

使用示例

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

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

  return <></>;
}

useJoin

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

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

参数

参数名类型是否必选描述
fetchArgsJoinOptions | (() => Promise<JoinOptions>)必选加入频道所需参数或异步函数。详见 JoinOptions。
readyboolean可选是否准备好加入频道。默认为 true。
clientIAgoraRTCClient可选通过 Web SDK 的 IAgoraRTC.createClient 创建。
表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

属性类型描述
dataUID成功加入频道的用户 ID。如果你在传入 fetchArgs 时没有指定 uid，则返回默认值 0。
isLoadingboolean
  • true：正在执行加入频道相关操作。
  • false：已经执行加入频道相关操作，但不代表成功加入频道。
isConnectedboolean
  • true：SDK 已连接到服务器。即加入频道成功。
  • false：SDK 没有连接到服务器。
errorAgoraRTCReactError | null加入频道成功则返回 null，加入频道失败则抛出错误。错误详见 AgoraRTCReactError。
表格内容超出当前宽度，可横向滚动查看更多列。

使用示例

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)[]必选本地轨道列表。
readyToPublishboolean可选是否准备好进行发布。默认为 true。
clientIAgoraRTCClient可选通过 Web SDK 的 IAgoraRTC.createClient 创建。
表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

属性类型描述
isLoadingboolean
  • true：正在执行发布相关操作。
  • false：已经执行发布相关操作，但不代表成功发布。
errorAgoraRTCReactError | null发布成功则返回 null，发布失败则抛出错误。错误详见 AgoraRTCReactError。
表格内容超出当前宽度，可横向滚动查看更多列。

使用示例

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 创建的音频轨道会停止发布。

参数

参数名类型是否必选描述
readyboolean可选是否准备好创建轨道，默认为 true。
audioTrackConfigMicrophoneAudioTrackInitConfig可选麦克风音频轨道的初始化配置，默认为 { ANS: true, AEC: true }。详见 MicrophoneAudioTrackInitConfig。
表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

属性类型描述
localMicrophoneTrackIMicrophoneAudioTrack | null创建的本地麦克风音频轨道对象。
isLoadingboolean
  • true：正在执行创建轨道相关操作。
  • false：已经执行创建轨道相关操作，但不代表成功创建轨道。
errorAgoraRTCReactError | null创建轨道成功则返回 null，创建轨道失败则抛出错误。错误详见 AgoraRTCReactError。
表格内容超出当前宽度，可横向滚动查看更多列。

使用示例

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

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

  return <></>;
}

useLocalCameraTrack

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

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

参数

参数名类型是否必选描述
readyboolean可选是否准备好创建轨道，默认为 true。
cameraVideoTrackConfigCameraVideoTrackInitConfig可选摄像头视频轨道的初始化配置。详见 CameraVideoTrackInitConfig。
表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

属性类型描述
localCameraTrackICameraVideoTrack | null创建的摄像头视频轨道对象。
isLoadingboolean
  • true：正在执行创建轨道相关操作。
  • false：已经执行创建轨道相关操作，但不代表成功创建轨道。
errorAgoraRTCReactError | null创建轨道成功则返回 null，创建轨道失败则抛出错误。错误详见 AgoraRTCReactError。
表格内容超出当前宽度，可横向滚动查看更多列。

使用示例

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

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

  return <></>;
}

useLocalScreenTrack

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

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

参数

参数名类型是否必选描述
readyboolean可选是否准备好创建轨道，默认为 true。
screenVideoTrackInitConfigscreenVideoTrackInitConfig必选屏幕共享的视频配置，包括编码配置、采集配置等。
withAudiostring必选屏幕共享时是否同时分享屏幕共享输入源的音频。支持传入 "enable"、"disable" 或 "auto"。详见createScreenVideoTrack的参数解释。
表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

属性类型描述
screenTrack[ILocalVideoTrack, ILocalAudioTrack] | ILocalVideoTrack | null根据传入的 withAudio，返回创建的屏幕共享视频轨道或者屏幕共享视频轨道和音频轨道。详见 createScreenVideoTrack的返回值。
isLoadingboolean
  • true：正在执行创建轨道相关操作。
  • false：已经执行创建轨道相关操作，但不代表成功创建轨道。
errorAgoraRTCReactError | null创建轨道成功则返回 null，创建轨道失败则抛出错误。错误详见 AgoraRTCReactError。
表格内容超出当前宽度，可横向滚动查看更多列。

注意事项

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

使用示例

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

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: 避免订阅本地屏幕共享轨道

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 会更新订阅的视频轨道。

参数

参数名类型是否必选描述
usersIAgoraRTCRemoteUser[] | undefined必选远端用户列表。
clientIAgoraRTCClient | null可选通过 Web SDK 的 IAgoraRTC.createClient 创建。
表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

属性类型描述
videoTracksIRemoteVideoTrack[]已订阅的远端用户视频轨道列表。
isLoadingboolean
  • true：正在执行订阅相关操作。
  • false：已经执行订阅相关操作，但不代表成功订阅。
errorAgoraRTCReactError | null订阅成功则返回 null，订阅失败则抛出错误。错误详见 AgoraRTCReactError。
表格内容超出当前宽度，可横向滚动查看更多列。

使用示例

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

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

  return <></>;
}

useRemoteAudioTracks

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

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

参数

参数名类型是否必选描述
usersIAgoraRTCRemoteUser[] | undefined必选远端用户列表。
clientIAgoraRTCClient | null可选通过 Web SDK 的 IAgoraRTC.createClient 创建。
表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

属性类型描述
audioTracksIRemoteAudioTrack[]已订阅的远端用户音频轨道列表。
isLoadingboolean
  • true：正在执行订阅相关操作。
  • false：已经执行订阅相关操作，但不代表成功订阅。
errorAgoraRTCReactError | null订阅成功则返回 null，订阅失败则抛出错误。错误详见 AgoraRTCReactError。
表格内容超出当前宽度，可横向滚动查看更多列。

使用示例

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

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

  return <></>;
}

useRemoteUserTrack

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

参数

参数名类型是否必选描述
userIAgoraRTCRemoteUser | undefined必选远端用户对象。
mediaType"video" | "audio"必选媒体类型，支持传入 "video" 或 "audio"。
clientIAgoraRTCClient | null可选通过 Web SDK 的 IAgoraRTC.createClient 创建。
表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

属性类型描述
trackIRemoteVideoTrack | IRemoteAudioTrack | undefined远端用户的音频或视频轨道（取决于传入的 mediaType）。如果远端用户或音频、视频轨道不存在，则返回 undefined。
isLoadingboolean
  • true：正在执行获取轨道相关操作。
  • false：已经执行获取轨道相关操作，但不代表成功获取轨道。
errorAgoraRTCReactError | null获取轨道成功则返回 null，获取轨道失败则抛出错误。错误详见 AgoraRTCReactError。
表格内容超出当前宽度，可横向滚动查看更多列。

使用示例

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 的返回值会更新：

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

参数

参数名类型是否必选描述
clientIAgoraRTCClient | null可选通过 Web SDK 的 IAgoraRTC.createClient 创建。
表格内容超出当前宽度，可横向滚动查看更多列。

返回值

类型描述
IAgoraRTCRemoteUser[]远端用户列表。
表格内容超出当前宽度，可横向滚动查看更多列。

使用示例

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

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

  return <></>;
}

useAutoPlayVideoTrack

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

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

参数

参数名类型是否必选描述
trackIRemoteVideoTrack | ILocalVideoTrack必选远端视频轨道对象或本地视频轨道对象。
playboolean可选
  • true：播放该轨道。
  • false：停止播放该轨道。
videoPlayerConfigVideoPlayerConfig可选视频轨道的播放配置。可以设置播放参数（镜像/显示模式），详见 VideoPlayerConfig。对于本地视频轨道，镜像模式默认开启。
divHTMLElement | null可选用于渲染视频轨道的 HTML 元素。只有在 play 为 true 并且传入 div 参数的情况下，视频才会在该元素中自动播放。其它情况则不会自动播放视频。
表格内容超出当前宽度，可横向滚动查看更多列。

返回值

无。

使用示例

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

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

  return <></>;
}

useAutoPlayAudioTrack

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

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

参数

参数名类型是否必选描述
trackIRemoteAudioTrack | ILocalAudioTrack必选远端音频轨道对象或本地音频轨道对象。
playboolean可选
  • true：播放该轨道。
  • false：停止播放该轨道。
表格内容超出当前宽度，可横向滚动查看更多列。

返回值

无。

使用示例

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

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

  return <></>;
}

useClientEvent

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

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

参数

参数名类型是否必选描述
clientIAgoraRTCClient必选通过 Web SDK 的 IAgoraRTC.createClient 创建。
eventstring必选事件名称。支持的事件详见IAgoraRTCClient.on。
listenerFunction必选回调函数。当传入的事件触发时，该函数会被调用。支持的回调详见 IAgoraRTCClient.on。
表格内容超出当前宽度，可横向滚动查看更多列。

返回值

无。

使用示例

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

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

  return <></>;
}

useTrackEvent

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

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

参数

参数名类型是否必选描述
trackITrack必选本地轨道对象或远端轨道对象。
eventstring必选事件名称。
listenerFunction必选回调函数。当传入的事件触发时，该函数会被调用。
表格内容超出当前宽度，可横向滚动查看更多列。

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

trackevent 和 listener
ILocalTrack | ILocalVideoTrack | null详见 ILocalTrack.on。
IBufferSourceAudioTrack | null详见 IBufferSourceAudioTrack.on。
ILocalVideoTrack | null详见 ILocalVideoTrack.on。
IRemoteTrack | null详见 IRemoteTrack.on。
表格内容超出当前宽度，可横向滚动查看更多列。

返回值

无。

使用示例

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

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

  return <></>;
}

咨询电话

400 632 6626

上海声网科技有限公司

Copyright © 2026 声网保留所有权利