本页面基于 基本实现指南。请确保您已先阅读该指南。
本页面上的代码示例假设您已导入必要的包并初始化了 SDK。
UI Kit 组件之所以能够相互理解并同步,是因为它们嵌套在 RtkMeeting 组件下。RtkMeeting 组件充当中央协调器,确保其下的所有组件在会议状态、参与者更新和其他实时更改方面保持同步。
UI Kit 组件之所以能够相互理解并同步,是因为它们嵌套在 rtk-meeting 组件下。rtk-meeting 组件充当中央协调器,确保其下的所有组件在会议状态、参与者更新和其他实时更改方面保持同步。
UI Kit 组件之所以能够相互理解并同步,是因为它们嵌套在 rtk-meeting 组件下。rtk-meeting 组件充当中央协调器,确保其下的所有组件在会议状态、参与者更新和其他实时更改方面保持同步。
Android UI Kit 在内部管理组件通信。当您使用 RealtimeKitUIBuilder 构建 UI Kit 时,它会创建并协调所有必要的 UI 组件。要从您的应用程序观察会议状态更改,请将事件监听器附加到核心 SDK (Core SDK) 的 meeting 对象上。
iOS UI Kit 通过 RealtimeKitUI 模块在内部管理组件通信。要从您的应用程序观察会议状态更改,请实现事件监听器协议并将它们注册到核心 SDK (Core SDK) 的 meeting 对象上。
React Native UI Kit 组件之所以能够相互通信并同步,是因为它们嵌套在 RtkMeeting 组件下,并封装在 RealtimeKitProvider 和 RtkUIProvider 中。要观察状态更改,请使用来自核心 SDK (Core SDK) 的 Hook,例如 useRealtimeKitSelector。
以下是打开参与者侧边栏时状态同步如何工作的示例:
flowchart LR
accTitle: Sidebar State Synchronization Example
accDescr: Example showing how clicking participants toggle updates sidebar through meeting coordination
Toggle["👤 ParticipantsToggle<br/>(User clicks)"]
Meeting["Meeting Component<br/>(State Coordinator)"]
Sidebar["Sidebar<br/>(Opens/Closes)"]
App["Your App<br/>(Gets notified)"]
Toggle -->|"emits rtkStateUpdate<br/>{activeSidebar: true,<br/>sidebar: 'participants'}"|Meeting
Meeting -->|"propagates state"|Sidebar
Meeting -->|"emits rtkStatesUpdate"|App
style Meeting fill:#F48120,stroke:#333,stroke-width:2px,color:#fff
style App fill:#0051C3,stroke:#333,stroke-width:2px,color:#fff
- 子组件触发状态更新:当任何 UI 组件需要更新状态时,它会触发
rtkStateUpdate事件 - 会议组件监听并协调:会议组件监听其子组件的所有这些状态更新事件
- 状态传播:会议组件将更新后的状态传播给所有其他子组件,以使它们保持同步
- 外部通知:会议组件还会触发
rtkStatesUpdate事件,您的应用程序可以监听该事件以更新自定义 UI 或根据状态更改执行操作
- UI Kit 管理内部状态:UI Kit 在内部处理所有组件通信和状态同步
- 您的应用注册事件监听器:您将事件监听器(例如
RtkMeetingRoomEventListener和RtkSelfEventListener)附加到核心 SDK (Core SDK) 的meeting对象上 - 回调在状态改变时触发:当会议状态发生变化时(例如,参与者加入或音频切换),相应的监听器回调会被调用
- 您更新您的 UI:使用回调数据来更新您应用程序的 UI 或触发其他操作
- UI Kit 管理内部状态:
RtkMeeting组件在内部处理所有组件通信和状态同步 - 您的应用通过 Hook 观察状态:使用
useRealtimeKitSelector选择特定的会议属性,并在其发生变化时重新渲染 - React 在变更时重新渲染:当选定的值更改时,React 会自动使用新状态重新渲染组件
- 您更新您的 UI:使用观察到的状态值来条件性地渲染 UI 元素或触发副作用
要根据会议状态的更改构建自定义 UI 或执行操作,您需要观察来自 UI Kit 的状态更新。
监听会议组件触发的 rtkStatesUpdate 事件。此事件为您提供 UI Kit 的当前状态,包括侧边栏状态、屏幕共享状态、视图类型等。
将事件监听器附加到核心 SDK (Core SDK) 的 meeting 对象上,以观察会议状态的变化。移动 UI Kit 处理其自身的内部状态,您的应用直接与底层的 meeting 对象进行交互。
使用来自 @cloudflare/realtimekit-react-native 的 useRealtimeKitSelector Hook 来观察 meeting 对象上的特定属性。每当选定的值更改时,该 Hook 就会重新渲染您的组件,类似于选择器在状态管理库中的工作方式。
对于 React,您可以使用 RtkMeeting 组件上的 onRtkStatesUpdate 属性来监听状态更新。
import {
RealtimeKitProvider,
useRealtimeKitClient,
} from "@cloudflare/realtimekit-react";
import { RtkMeeting } from "@cloudflare/realtimekit-react-ui";
import { useEffect, useState } from "react";
function App() {
const [meeting, initMeeting] = useRealtimeKitClient();
const [authToken, setAuthToken] = useState("<participant_auth_token>");
const [states, setStates] = useState({});
useEffect(() => {
if (authToken) {
initMeeting({
authToken: authToken,
});
}
}, [authToken]);
return (
<RealtimeKitProvider value={meeting}>
<RtkMeeting
showSetupScreen={true}
meeting={meeting}
onRtkStatesUpdate={(e) => {
// Update states when rtk-meeting emits state updates
setStates(e.detail);
// Example: Access various state properties
console.log("Meeting state:", e.detail.meeting); // 'idle', 'setup', 'joined', 'ended', 'waiting'
console.log("Is sidebar active:", e.detail.activeSidebar);
console.log("Current sidebar section:", e.detail.sidebar);
console.log("Is screen sharing:", e.detail.activeScreenShare);
}}
/>
{/* Use states to build custom UI */}
<div className="custom-ui">
<p>Meeting State: {states.meeting}</p>
<p>Sidebar Open: {states.activeSidebar ? "Yes" : "No"}</p>
</div>
</RealtimeKitProvider>
);
}替代方案:使用 Ref(多个会议)
如果您正在构建在同一页面上包含多个会议或连续会议的体验,建议使用 Ref 以避免不同会议实例之间的状态冲突:
import {
RealtimeKitProvider,
useRealtimeKitClient,
} from "@cloudflare/realtimekit-react";
import { RtkMeeting } from "@cloudflare/realtimekit-react-ui";
import { useEffect, useState, useRef } from "react";
function App() {
const [meeting, initMeeting] = useRealtimeKitClient();
const [authToken, setAuthToken] = useState("<participant_auth_token>");
const [states, setStates] = useState({});
const meetingRef = useRef(null);
useEffect(() => {
if (authToken) {
initMeeting({
authToken: authToken,
});
}
}, [authToken]);
useEffect(() => {
if (!meetingRef.current) return;
const handleStatesUpdate = (e) => {
setStates(e.detail);
console.log("Meeting state:", e.detail.meeting);
console.log("Is sidebar active:", e.detail.activeSidebar);
};
// Add event listener via ref
meetingRef.current.addEventListener("rtkStatesUpdate", handleStatesUpdate);
// Cleanup listener when component unmounts or meeting changes
return () => {
meetingRef.current?.removeEventListener(
"rtkStatesUpdate",
handleStatesUpdate,
);
};
}, [meetingRef.current]);
return (
<RealtimeKitProvider value={meeting}>
<RtkMeeting ref={meetingRef} showSetupScreen={true} meeting={meeting} />
{/* Use states to build custom UI */}
<div className="custom-ui">
<p>Meeting State: {states.meeting}</p>
<p>Sidebar Open: {states.activeSidebar ? "Yes" : "No"}</p>
</div>
</RealtimeKitProvider>
);
}对于 Web Components,您需要为 rtk-meeting 组件添加一个事件监听器以监听 rtkStatesUpdate 事件。
<body>
<rtk-meeting id="meeting-component"></rtk-meeting>
</body>
<script type="module">
import RealtimeKitClient from "https://cdn.jsdelivr.net/npm/@cloudflare/realtimekit@latest/dist/index.es.js";
const meeting = await RealtimeKitClient.init({
authToken: "<participant_auth_token>",
});
// Add <rtk-meeting id="meeting-component" /> to your HTML, otherwise you will get error
const meetingComponent = document.querySelector("#meeting-component");
// Listen for state updates from rtk-meeting
meetingComponent.addEventListener("rtkStatesUpdate", (event) => {
console.log("RTK states updated:", event.detail);
// Store states to update your custom UI
const states = event.detail;
// Example: Access various state properties
console.log("Meeting state:", states.meeting); // 'idle', 'setup', 'joined', 'ended', 'waiting'
console.log("Is sidebar active:", states.activeSidebar);
console.log("Current sidebar section:", states.sidebar); // 'chat', 'participants', 'polls', etc.
console.log("Is screen sharing:", states.activeScreenShare);
// Update your custom UI based on states
// For example: Show/hide elements based on meeting state
if (states.meeting === "joined") {
// Show meeting controls
}
});
meetingComponent.showSetupScreen = true;
meetingComponent.meeting = meeting;
</script>对于 Angular,您需要为 rtk-meeting 组件添加一个事件监听器以监听 rtkStatesUpdate 事件。
import {
Component,
ElementRef,
OnInit,
OnDestroy,
ViewChild,
} from "@angular/core";
@Component({
selector: "app-meeting",
template: `
<rtk-meeting #meetingComponent id="meeting-component"></rtk-meeting>
<!-- Use states to build custom UI -->
<div class="custom-ui" *ngIf="states">
<p>Meeting State: {{ states.meeting }}</p>
<p>Sidebar Open: {{ states.activeSidebar ? "Yes" : "No" }}</p>
<div *ngIf="states.meeting === 'joined'" class="meeting-controls">
<!-- Show meeting controls when joined -->
<p>Meeting controls would go here</p>
</div>
</div>
`,
styleUrls: ["./meeting.component.css"],
})
export class MeetingComponent implements OnInit, OnDestroy {
@ViewChild("meetingComponent", { static: true }) meetingElement!: ElementRef;
meeting: any;
states: any = {};
private authToken = "<participant_auth_token>";
private stateUpdateListener?: (event: any) => void;
async ngOnInit() {
// Import RealtimeKit client dynamically
const RealtimeKitClient = await import(
"https://cdn.jsdelivr.net/npm/@cloudflare/realtimekit@latest/dist/index.es.js"
);
// Initialize the meeting
this.meeting = await RealtimeKitClient.default.init({
authToken: this.authToken,
});
// Set up the meeting component
const meetingComponent = this.meetingElement.nativeElement;
// Create the event listener
this.stateUpdateListener = (event: any) => {
console.log("RTK states updated:", event.detail);
// Store states to update your custom UI
this.states = event.detail;
// Example: Access various state properties
console.log("Meeting state:", this.states.meeting); // 'idle', 'setup', 'joined', 'ended', 'waiting'
console.log("Is sidebar active:", this.states.activeSidebar);
console.log("Current sidebar section:", this.states.sidebar); // 'chat', 'participants', 'polls', etc.
console.log("Is screen sharing:", this.states.activeScreenShare);
// Update your custom UI based on states
// For example: Show/hide elements based on meeting state
if (this.states.meeting === "joined") {
// Show meeting controls
console.log("Meeting joined - showing controls");
}
};
// Listen for state updates from rtk-meeting
meetingComponent.addEventListener(
"rtkStatesUpdate",
this.stateUpdateListener,
);
// Configure the meeting component
meetingComponent.showSetupScreen = true;
meetingComponent.meeting = this.meeting;
}
ngOnDestroy() {
// Clean up event listener when component is destroyed
if (this.stateUpdateListener && this.meetingElement) {
this.meetingElement.nativeElement.removeEventListener(
"rtkStatesUpdate",
this.stateUpdateListener,
);
}
}
}对于 Android,将事件监听器附加到 meeting 对象上以观察状态更改。使用 RtkMeetingRoomEventListener 监听会议生命周期事件,使用 RtkSelfEventListener 监听本地参与者状态更改。
import android.os.Bundle
import android.util.Log
import androidx.appcompat.app.AppCompatActivity
class MeetingActivity : AppCompatActivity() {
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
// After initializing the meeting and UI Kit (see Getting Started guide),
// add event listeners to observe state changes.
// Listen for meeting room state changes
meeting.addMeetingRoomEventListener(object : RtkMeetingRoomEventListener {
override fun onMeetingRoomJoinStarted() {
Log.d("Meeting", "Join started")
}
override fun onMeetingRoomJoinCompleted(meeting: RealtimeKitClient) {
Log.d("Meeting", "Joined the meeting")
// Update UI to show meeting controls
}
override fun onMeetingRoomJoinFailed(exception: Exception) {
Log.e("Meeting", "Join failed: ${exception.message}")
}
override fun onMeetingRoomLeaveStarted() {
Log.d("Meeting", "Leave started")
}
override fun onMeetingRoomLeft() {
Log.d("Meeting", "Left the meeting")
}
override fun onMeetingEnded() {
Log.d("Meeting", "Meeting ended for all participants")
}
override fun onActiveTabUpdate(activeTab: ActiveTab) {
Log.d("Meeting", "Active tab changed: $activeTab")
}
})
// Listen for local participant state changes
meeting.addSelfEventListener(object : RtkSelfEventListener {
override fun onAudioUpdate(isEnabled: Boolean) {
Log.d("Meeting", "Audio: ${if (isEnabled) "on" else "off"}")
}
override fun onVideoUpdate(isEnabled: Boolean) {
Log.d("Meeting", "Video: ${if (isEnabled) "on" else "off"}")
}
override fun onRemovedFromMeeting() {
Log.d("Meeting", "Removed from meeting by host")
}
})
}
}对于 iOS,实现事件监听器协议并将它们注册到 meeting 对象上。使用 RtkMeetingRoomEventListener 监听会议生命周期事件,使用 RtkSelfEventListener 监听本地参与者状态更改。
// Listen for meeting room state changes
extension MeetingViewModel: RtkMeetingRoomEventListener {
func onMeetingRoomJoinCompleted(meeting: RealtimeKitClient) {
// Successfully joined the meeting (equivalent to 'joined' state)
}
func onMeetingRoomLeft() {
// Successfully left the meeting
}
func onMeetingEnded() {
// The meeting has ended for all participants (equivalent to 'ended' state)
}
func onActiveTabUpdate(activeTab: ActiveTab) {
// Active tab changed (e.g., chat, polls, participants)
// Use this to sync your custom UI with the active sidebar section
}
}
// Listen for local participant state changes
extension MeetingViewModel: RtkSelfEventListener {
func onAudioUpdate(isEnabled: Bool) {
// Audio toggled on/off
}
func onVideoUpdate(isEnabled: Bool) {
// Video toggled on/off
}
func onRemovedFromMeeting() {
// Local user was removed from the meeting by host
}
}
// Register the listeners
meeting.addMeetingRoomEventListener(meetingRoomEventListener: self)
meeting.addSelfEventListener(selfEventListener: self)对于 React Native,使用 useRealtimeKitSelector Hook 来观察 meeting 对象上的特定属性。这种模式与 Web 核心 SDK (Core SDK) 类似。
import { useEffect } from "react";
import { View, Text } from "react-native";
import {
RealtimeKitProvider,
useRealtimeKitClient,
useRealtimeKitMeeting,
useRealtimeKitSelector,
} from "@cloudflare/realtimekit-react-native";
import {
RtkUIProvider,
RtkMeeting,
} from "@cloudflare/realtimekit-react-native-ui";
function App() {
const [meeting, initMeeting] = useRealtimeKitClient();
useEffect(() => {
initMeeting({
authToken: "<participant_auth_token>",
defaults: { audio: true, video: true },
});
}, []);
return (
<RealtimeKitProvider value={meeting}>
<RtkUIProvider>
<MeetingWithState />
</RtkUIProvider>
</RealtimeKitProvider>
);
}
function MeetingWithState() {
const { meeting } = useRealtimeKitMeeting();
// Use selectors to observe meeting state
const roomState = useRealtimeKitSelector((m) => m.self.roomState);
const audioEnabled = useRealtimeKitSelector((m) => m.self.audioEnabled);
const videoEnabled = useRealtimeKitSelector((m) => m.self.videoEnabled);
useEffect(() => {
console.log("Room state:", roomState);
console.log("Audio:", audioEnabled);
console.log("Video:", videoEnabled);
}, [roomState, audioEnabled, videoEnabled]);
return (
<View>
{meeting && <RtkMeeting meeting={meeting} showSetupScreen={true} />}
{/* Use state to build custom UI */}
<View>
<Text>Room State: {roomState}</Text>
<Text>Audio: {audioEnabled ? "On" : "Off"}</Text>
<Text>Video: {videoEnabled ? "On" : "Off"}</Text>
</View>
</View>
);
}替代方案:使用事件监听器
您还可以使用基于事件的监听器来进行更细粒度的控制,类似于 Web 核心 SDK (Core SDK):
import { useEffect } from "react";
function MeetingEvents() {
const { meeting } = useRealtimeKitMeeting();
useEffect(() => {
if (!meeting) return;
const handleRoomJoined = () => {
console.log("Successfully joined the meeting");
};
const handleRoomLeft = ({ state }) => {
if (state === "ended") {
console.log("Meeting ended");
}
};
meeting.self.on("roomJoined", handleRoomJoined);
meeting.self.on("roomLeft", handleRoomLeft);
return () => {
meeting.self.removeListener("roomJoined", handleRoomJoined);
meeting.self.removeListener("roomLeft", handleRoomLeft);
};
}, [meeting]);
return null;
}rtkStatesUpdate 事件提供了关于 UI Kit 内部状态的详细信息。关键属性包括:
meeting:当前会议状态 -'idle'、'setup'、'joined'、'ended'或'waiting'activeSidebar:侧边栏当前是否打开(布尔值)sidebar:当前侧边栏区域 -'chat'、'participants'、'polls'、'plugins'等。activeScreenShare:屏幕共享 UI 是否处于激活状态(布尔值)activeMoreMenu:更多菜单是否打开(布尔值)activeSettings:设置面板是否打开(布尔值)viewType:当前视频网格视图类型(字符串)prefs:用户偏好设置对象(例如mirrorVideo、muteNotificationSounds)roomLeftState:离开房间时的状态activeOverlayModal:活动覆盖模态框配置对象activeConfirmationModal:活动确认模态框配置对象- 以及更多 UI 状态属性
在移动平台上,状态是通过核心 SDK (Core SDK) 事件监听器而不是单个状态对象来观察的。关键的事件监听器及其回调包括:
RtkMeetingRoomEventListener - 会议生命周期:
onMeetingRoomJoinStarted:会议加入过程已开始onMeetingRoomJoinCompleted:成功加入会议onMeetingRoomJoinFailed:会议加入失败(提供异常详细信息)onMeetingRoomLeaveStarted:离开过程已开始onMeetingRoomLeft:成功离开会议onMeetingEnded:所有参与者的会议已结束onActiveTabUpdate:活动侧边栏标签页已更改(聊天、投票、参与者)
RtkSelfEventListener - 本地参与者:
onAudioUpdate:音频已开启或关闭onVideoUpdate:视频已开启或关闭onRemovedFromMeeting:本地用户被主持人移出会议
RtkParticipantsEventListener - 远程参与者:
onParticipantJoin:有参与者加入会议onParticipantLeave:有参与者离开会议onActiveParticipantsChanged:活动参与者列表已更改onAudioUpdate:远程参与者的音频状态已更改onVideoUpdate:远程参与者的视频状态已更改
在 React Native 上,使用 useRealtimeKitSelector Hook 来观察 meeting 对象上的特定属性。关键属性包括:
m.self.roomState:当前房间状态('init'、'joined'、'left'等)m.self.audioEnabled:本地音频是否启用(布尔值)m.self.videoEnabled:本地视频是否启用(布尔值)m.self.screenShareEnabled:屏幕共享是否处于激活状态(布尔值)m.self.name:本地参与者显示名称m.self.id:本地参与者 Peer IDm.participants.joined:已加入的参与者列表m.participants.active:活动参与者列表
- 妥善存储状态:对于 React 应用,使用 React 的
useStateHook 或状态管理库(如 Zustand 或 Redux)。对于原生 JavaScript,使用响应式状态管理解决方案或简单的对象存储。 - 避免过度重新渲染:仅在必要时更新 UI。在 React 中,考虑使用
useMemo或useCallback来优化性能。 - 安全地访问嵌套属性:在访问嵌套属性之前,始终检查它们是否存在(例如
states.sidebar、states.prefs?.mirrorVideo)。 - 使用状态进行条件渲染:利用 UI 状态来显示/隐藏 UI elements 或响应界面更改(例如,在
states.activeScreenShare为 true 时显示自定义指示器)。 - 理解差异:
rtkStatesUpdate提供用于界面管理的 UI Kit 内部状态。对于会议数据(参与者、活动发言人、录制状态),请直接使用核心 SDK (Core SDK) 的meeting对象及其事件。
- 在清理时移除监听器:始终在
onDestroy()中移除事件监听器以防止内存泄漏。存储监听器引用,以便您稍后注销它们。 - 使用合适的线程:事件监听器回调可能会在后台线程上触发。在更新 UI 元素时,使用
runOnUiThread或发送到主处理程序。 - 使用可观察模式存储状态:使用
LiveData、StateFlow或MutableState(Compose) 响应式地将状态更改传播到您的 UI。 - 理解差异:事件监听器提供会议生命周期和参与者状态更改。UI Kit 分别管理其自身的内部 UI 状态。
- 在清理时移除监听器:当您的视图控制器 (view controller) 或视图模型 (view model) 被销毁时,请始终移除事件监听器,以防止循环引用和内存泄漏。
- 使用
@Published实现响应式 UI:在 SwiftUI 中,在您的ObservableObject中将状态属性标记为@Published,以便在会议状态发生变化时自动重新渲染视图。 - 处理线程:事件监听器回调可能会在后台线程上触发。从回调更新 UI 元素时,使用
DispatchQueue.main.async。 - 理解差异:事件监听器提供会议生命周期和参与者状态更改。UI Kit 分别管理其自身的内部 UI 状态。
- 为了效率使用选择器:
useRealtimeKitSelectorHook 仅在选定值更改时重新渲染组件。仅选择您需要的特定属性,而不是整个 meeting 对象。 - 清理事件监听器:使用
meeting.self.on()事件监听器时,始终从useEffect返回一个调用removeListener的清理函数。 - 结合使用
useMemo和useCallback:当会议状态频繁发生变化时,使用 React 记忆化 (memoization) Hook 来防止不必要的重新渲染。 - 理解差异:
useRealtimeKitSelector提供对核心 SDK (Core SDK) 会议状态(参与者、媒体、房间状态)的访问。UI Kit 通过RtkMeeting组件处理其自身的内部 UI 状态。