分组讨论室

代码示例

如果您更喜欢通过查看示例来学习，请查看相应的示例存储库。

Web 示例

分组讨论室允许会议参与者分成较小的组，进行有针对性的讨论和协作。随着远程办公和在线学习的兴起，分组讨论室已成为在虚拟环境中增强参与度和建设社区的重要工具。它们是研讨会、在线课堂或当您需要在主会议之外与选定参与者进行私密交流时的理想选择。

在 RealtimeKit 中，分组讨论室是作为单独的会议创建的。每个分组讨论室都是一个独立的会议，可以像任何其他 RealtimeKit 会议一样进行管理。RealtimeKit 提供了一组 SDK API，用于创建、管理和在分组讨论室之间切换。

主要特性

以下是 RealtimeKit 分组讨论室的一些主要特性：

使用预设管理主持人与参与者的权限和特权
主持人可以创建分组讨论室、分配参与者、开始和关闭分组讨论室以及在不同的讨论室之间切换
参与者可以开始和停止视频，使用聊天和投票功能与其他参与者互动，以及静音/取消静音音频
像任何其他 RealtimeKit 会议一样单独录制所有分组会话

分组讨论室中的角色

分组讨论室中的角色由预设进行管理。

主持人

主持人可以创建分组讨论室、分配参与者、开始和关闭分组讨论室以及在讨论室之间切换。

参与者

作为分组讨论室中的参与者，您可以：

Switch to Parent Meeting（切换到主会议） - 返回主会议（如果您拥有所需的权限）
Switch Connected Meetings（切换关联会议） - 从主会议移动到更小的、有针对性的讨论组（分组讨论室）进行协作
协作 - 在分组会话期间使用聊天和投票等工具

音频和视频

每个分组讨论室都作为一个独立的会议运行。当您从主会议切换到分组讨论室时，它会自动切换到分组会话的音频和视频。在分组会话期间，您可以随时静音或取消静音音频，以及开始或停止视频，就像在主会议中一样。

当分组会话结束时，您的音频和视频会自动切换回主会议。

如果您的视频在分组会话期间是开启状态，则在返回主会话时它将保持开启状态
如果您的麦克风在分组会话期间是开启状态，则在返回主会话时它将保持开启状态

录制分组会话

每个分组会话都是一个独立的会话。每个分组会话的录制均单独存储和管理，就像任何其他 RealtimeKit 会议一样。有关更多信息，请参阅录制。

分组讨论室管理

分组讨论室允许参与者分成独立的会话。主持人可以创建分组讨论室、分配参与者、开始和关闭分组讨论室。

创建预设

预设是应用于主持人和参与者的一组权限和 UI 配置。它们决定了分组讨论室的外观、感觉和行为。

对于分组讨论室，您必须在 Connected Meetings 中为主持人和参与者提供以下权限：

主持人

主持人预设应在 Connected Meetings 中具有 Full Access（完全访问） 权限。这允许主持人：

创建分组讨论室
分配参与者到讨论室
开始和关闭分组讨论室
在讨论室之间切换

参与者

您可以选择向参与者提供以下权限：

Switch Connected Meetings（切换关联会议） - 允许参与者在分组讨论室之间移动
Switch to Parent Meeting（切换到主会议） - 允许参与者返回主会议

保存预设

对预设进行所有更改后，单击 Save（保存）
输入您的预设名称，然后单击 Save（保存）
您的预设将被列出 - 单击 **Edit（编辑）**以进行任何更改

创建会议

使用 Create meeting API 创建 RealtimeKit 会议。此 API 会返回您会议的唯一标识符。

添加参与者

创建会议后，使用 Add participant API 添加每个参与者。之前创建的 presetName 必须在 Add Participant API 请求的请求体中传递。

启动分组讨论室

集成分组讨论室

通过 API 设置好分组讨论室后，你需要使用 RealtimeKit SDK 将其集成到你的应用程序中。

This page is not available for the Flutterplatform.

初始化支持分组讨论室的 SDK

初始化 SDK 并为分组讨论室添加事件处理函数：

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>");

	useEffect(() => {
		if (authToken) {
			initMeeting({
				authToken: authToken,
			});
		}
	}, [authToken]);

	// Add event handler for breakout rooms
	useEffect(() => {
		if (meeting) {
			meeting.connectedMeetings.on("meetingChanged", (newMeeting) => {
				// Meeting object is automatically updated in React
				console.log("Switched to breakout room or main meeting");
			});
		}
	}, [meeting]);

	return (
		<RealtimeKitProvider value={meeting}>
			<RtkMeeting showSetupScreen={true} meeting={meeting} />
		</RealtimeKitProvider>
	);
}

当参与者在主会议和分组讨论室之间切换时，会触发 meetingChanged 事件。在 React 中，meeting 对象由 provider 自动管理。

<script type="module">
	import RealtimeKitClient from "https://cdn.jsdelivr.net/npm/@cloudflare/realtimekit@latest/dist/index.es.js";

	let meeting = await RealtimeKitClient.init({
		authToken: "<participant_auth_token>",
	});

	// Add event handler for breakout rooms
	meeting.connectedMeetings.on("meetingChanged", (newMeeting) => {
		meeting = newMeeting;
		document.querySelector("rtk-meeting").meeting = meeting;
	});
</script>

当参与者在主会议和分组讨论室之间切换时，会触发 meetingChanged 事件。当该事件触发时，更新 meeting 对象引用。

import { Component, ViewChild, AfterViewInit } from '@angular/core';
import RealtimeKitClient from '@cloudflare/realtimekit';
import { RtkMeeting } from '@cloudflare/realtimekit-angular';

@Component({
	selector: 'app-root',
	template: `<rtk-meeting #myid [showSetupScreen]="true"></rtk-meeting>`
})
export class AppComponent implements AfterViewInit {
	@ViewChild('myid') meetingComponent: RtkMeeting;
	rtkMeeting: RealtimeKitClient;

	async ngAfterViewInit() {
		let meeting = await RealtimeKitClient.init({
			authToken: '<participant_auth_token>',
		});

		// Add event handler for breakout rooms
		meeting.connectedMeetings.on('meetingChanged', (newMeeting) => {
			meeting = newMeeting;
			if (this.meetingComponent) {
				this.meetingComponent.meeting = meeting;
			}
		});

		this.rtkMeeting = meeting;
		if (this.meetingComponent) {
			this.meetingComponent.meeting = meeting;
		}
	}
}

当参与者在主会议和分组讨论室之间切换时，会触发 meetingChanged 事件。当该事件触发时，更新 meeting 对象引用。

使用 RealtimeKitUI.startMeeting() 时，SDK 会自动管理 RtkConnectedMeetingsListener — 无需为分组讨论室切换进行额外设置。

如果你正在构建 自定义会议 UI（绕过 MeetingViewController），请自行注册监听器：

import RealtimeKit
import RealtimeKitUI

let listener = RtkConnectedMeetingsListener(rtkClient: rtkClient)

listener.onChangingMeeting = { meetingId in
    // Show a loading overlay; the SDK is switching rooms
    let isReturningToMain = meetingId == rtkClient.connectedMeetings.parentMeeting?.id
    showLoadingOverlay(message: isReturningToMain ? "Returning to Main Room\u{2026}" : "Joining breakout room\u{2026}")
}

listener.onMeetingChanged = { error in
    hideLoadingOverlay()
    if let error {
        showErrorAlert(message: error.message)
    } else {
        // Re-register all feature event listeners — the SDK clears them during the room switch
        // Re-register your listener instances, for example:
        // rtkClient.addSelfEventListener(selfEventListener: mySelfListener)
        // rtkClient.addParticipantsEventListener(participantsEventListener: myParticipantsListener)
    }
}

listener.onStateUpdate = { meetings, parentMeeting in
    // Refresh your breakout-rooms UI list
}

使用 RealtimeKitUIBuilder + startMeeting() 时，SDK 会自动注册并管理 RtkConnectedMeetingsEventListener — 无需为分组讨论室切换进行额外设置。

如果你正在构建 自定义会议 UI，请自行注册监听器：

import com.cloudflare.realtimekit.ui.RtkConnectedMeetingsEventListener
import com.cloudflare.realtimekit.models.MeetingError

val connectedMeetingsListener = object : RtkConnectedMeetingsEventListener {
    override fun onChangingMeeting(meetingId: String) {
        // Show a transition screen; the SDK is switching rooms
        val isReturningToMain = meetingId == meeting.connectedMeetings.parentMeeting?.id
        showLoadingOverlay(isReturningToMain)
    }

    override fun onMeetingChanged(error: MeetingError?) {
        hideLoadingOverlay()
        if (error != null) {
            showErrorMessage(error.message)
        }
        // No need to re-register listeners — the SDK handles this automatically
    }
}

meeting.addConnectedMeetingsEventListener(connectedMeetingsListener)

当 SDK 开始离开当前讨论室时，会触发 onChangingMeeting 回调。当切换完成（或失败）时，会触发 onMeetingChanged 回调。

当参与者在分组讨论室之间移动时，useRealtimeKitClient 挂钩会自动处理 meetingChanged 事件并替换活动客户端引用。无需手动处理事件。

import { useEffect } from "react";
import { useRealtimeKitClient } from "@cloudflare/realtimekit-react-native";
import { RtkMeeting } from "@cloudflare/realtimekit-react-native-ui";

function App() {
  const [meeting, initMeeting] = useRealtimeKitClient();

  useEffect(() => {
    initMeeting({ authToken: "<participant_auth_token>" });
  }, []);

  if (!meeting) return null;

  return <RtkMeeting meeting={meeting} showSetupScreen={true} />;
}

在分组讨论室之间切换时，RtkMeeting 会自动显示“正在加入…”（Joining…）过渡屏幕。无需额外设置。

渲染会议 UI

使用包含内置分组讨论室支持的默认会议 UI 组件：

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>");

	useEffect(() => {
		if (authToken) {
			initMeeting({
				authToken: authToken,
			});
		}
	}, [authToken]);

	useEffect(() => {
		if (meeting) {
			meeting.connectedMeetings.on("meetingChanged", (newMeeting) => {
				console.log("Switched to breakout room or main meeting");
			});
		}
	}, [meeting]);

	return (
		<RealtimeKitProvider value={meeting}>
			<RtkMeeting showSetupScreen={true} meeting={meeting} />
		</RealtimeKitProvider>
	);
}

showSetupScreen 属性控制是否显示设置屏幕，允许参与者在加入会话之前预览其音频和视频。

<body>
	<rtk-meeting id="my-meeting"></rtk-meeting>

	<script type="module">
		import RealtimeKitClient from "https://cdn.jsdelivr.net/npm/@cloudflare/realtimekit@latest/dist/index.es.js";

		let meeting = await RealtimeKitClient.init({
			authToken: "<participant_auth_token>",
		});

		// Add event handler for breakout rooms
		meeting.connectedMeetings.on("meetingChanged", (newMeeting) => {
			meeting = newMeeting;
			document.querySelector("rtk-meeting").meeting = meeting;
		});

		document.querySelector("rtk-meeting").showSetupScreen = true;
		document.querySelector("rtk-meeting").meeting = meeting;
	</script>
</body>

showSetupScreen 属性控制是否显示设置屏幕，允许参与者在加入会话之前预览其音频和视频。

<rtk-meeting #myid [showSetupScreen]="true"></rtk-meeting>

import { Component, ViewChild, AfterViewInit } from '@angular/core';
import RealtimeKitClient from '@cloudflare/realtimekit';
import { RtkMeeting } from '@cloudflare/realtimekit-angular';

@Component({
	selector: 'app-root',
	templateUrl: './app.component.html'
})
export class AppComponent implements AfterViewInit {
	@ViewChild('myid') meetingComponent: RtkMeeting;
	rtkMeeting: RealtimeKitClient;

	async ngAfterViewInit() {
		let meeting = await RealtimeKitClient.init({
			authToken: '<participant_auth_token>',
		});

		// Add event handler for breakout rooms
		meeting.connectedMeetings.on('meetingChanged', (newMeeting) => {
			meeting = newMeeting;
			if (this.meetingComponent) {
				this.meetingComponent.meeting = meeting;
			}
		});

		this.rtkMeeting = meeting;
		if (this.meetingComponent) {
			this.meetingComponent.meeting = meeting;
		}
	}
}

showSetupScreen 属性控制是否显示设置屏幕，允许参与者在加入会话之前预览其音频和视频。

import RealtimeKit
import RealtimeKitUI

let meetingInfo = RtkMeetingInfo(authToken: "<participant_auth_token>")
let rtkUI = RealtimeKitUI(meetingInfo: meetingInfo)

let setupVC = rtkUI.startMeeting { [weak self] in
    // Called when the participant leaves or ends the meeting
    self?.dismiss(animated: true)
}
present(setupVC, animated: true)

设置屏幕（音频/视频预览）默认显示。内置的分组讨论室支持（包括讨论室切换遮罩和讨论室标题更新）由 MeetingViewController 自动处理。

import com.cloudflare.realtimekit.models.RtkMeetingInfo
import com.cloudflare.realtimekit.ui.RealtimeKitUIBuilder
import com.cloudflare.realtimekit.ui.RealtimeKitUIInfo

val meetingInfo = RtkMeetingInfo(authToken = "<participant_auth_token>")
val uiKitInfo = RealtimeKitUIInfo(
    activity = this,
    rtkMeetingInfo = meetingInfo,
)
val rtkUIKit = RealtimeKitUIBuilder.build(uiKitInfo)
rtkUIKit.startMeeting()

内置的分组讨论室支持由 RtkMeetingActivity 自动处理。当 SDK 在不同讨论室之间移动参与者时，它会显示带有本地化消息的过渡遮罩。主持人可以通过 RtkBreakoutRoomsBottomSheet 管理分组讨论室，当轻点控制栏的 Breakout Rooms 按钮时，该面板会自动显示。

import { useEffect } from "react";
import { useRealtimeKitClient } from "@cloudflare/realtimekit-react-native";
import { RtkMeeting } from "@cloudflare/realtimekit-react-native-ui";

function App() {
  const [meeting, initMeeting] = useRealtimeKitClient();

  useEffect(() => {
    initMeeting({ authToken: "<participant_auth_token>" });
  }, []);

  if (!meeting) return null;

  return <RtkMeeting meeting={meeting} showSetupScreen={true} />;
}

内置的分组讨论室支持由 RtkMeeting 自动处理。当参与者在不同讨论室之间移动时，会自动显示“正在加入…”（Joining…）过渡屏幕。主持人可以使用 RtkBreakoutRoomsManager 管理分组讨论室，该管理器可通过控制栏中的 RtkBreakoutRoomsToggle 进行访问。

后续步骤

你已成功将分组讨论室集成到你的 RealtimeKit 应用程序中。参与者现在可以：

加入主会议
由主持人分配到分组讨论室
在主会议和分组讨论室之间切换
在更小、更专注的小组中进行协作

如需更高级的自定义，请探索以下内容：

UI Kit 组件库 - 浏览可用组件
UI Kit 状态 - 了解组件如何同步
构建自定义 UI - 创建自定义会议界面

分组讨论室

代码示例

Web 示例

主要特性

分组讨论室中的角色

主持人

参与者

音频和视频

录制分组会话

分组讨论室管理

创建预设

主持人

参与者

保存预设

创建会议

添加参与者

启动分组讨论室

自动分配参与者

手动分配参与者

自动分配参与者

手动分配参与者

自动分配参与者

手动分配参与者

自动分配参与者

手动分配参与者

集成分组讨论室

初始化支持分组讨论室的 SDK

渲染会议 UI

后续步骤