@netless/forge-room

forge-room 是 Netless Forge 平台的核心房间管理模块，提供实时的协作房间基础设施。它为房间内的用户提供包括白板、文档、幻灯片等在内的各种实时协作应用。

特性

- 🏠 房间管理: 提供完整的房间生命周期管理
- 🔄 实时同步: 基于 Yjs 的协作数据同步
- 📱 应用生态: 支持多种协作应用的插件化架构
- 👥 用户管理: 完整的用户状态和权限管理
- 🌐 多通信支持: 支持 RTM 和 Socket.IO 两种通信方式
- 💾 数据持久化: 自动保存和恢复房间状态

安装

``bash
npm install @netless/forge-room


或


pnpm add @netless/forge-room
`

快速开始

$3

构建房间实例之前，需要调用服务端 API 创建房间获取房间 token，参考 创建房间 API。

`typescript
import { Room } from "@netless/forge-room";
import { RTMProvider_2_2 } from "@netless/forge-rtm";
import { WhiteboardApplication } from "@netless/forge-whiteboard";
import RTM from "agora-rtm";

// 创建 RTM 客户端
const rtmClient = new RTM('your-agora-app-id', 'user-id', {
token: 'your-rtm-token',
presenceTimeout: 4,
});

// 登录 RTM
await rtmClient.login();

// 创建 RTM 提供者
const rtmProvider = new RTMProvider_2_2(rtmClient);

// 创建房间实例
const room = new Room("room-id", rtmProvider);

// 注册应用（必须在加入房间前完成）
room.applicationManager.registerApplication(WhiteboardApplication);

// 加入房间
await room.joinRoom({
userId: "user-id",
nickName: "用户昵称",
roomToken: "room-token", // 白板房间 token
sdkConfig: {
region: "cn-hz",
appIdentifier: "appIdentifier"
},
windowManager: {
ratio: 1920 / 1080,
windowPosition: { x: 0.05, y: 0.05 },
windowSize: { width: 0.6, height: 0.6 },
},
writable: true,
verboseLog: false
});
`

$3

`typescript
// 启动白板应用
const whiteboard = await room.applicationManager.launchApplication(
WhiteboardApplication,
{
width: 1920,
height: 1080,
defaultToolbarStyle: {
tool: "curve"
}
},
"MainWhiteboard" // 固定 appId，确保所有用户共享同一个白板
);

// 配置视图样式并挂载到 DOM
whiteboard.view.style.height = "100vh";
whiteboard.view.style.width = "100vw";
whiteboard.view.style.background = "#f9f9fc";

document.body.appendChild(whiteboard.view);
`

API 文档

$3

#### 构造函数

`typescript
new Room(roomId: string, communicationProvider: CommunicationProvider)
`

#### 主要方法

##### joinRoom(options: JoinRoomOptions): Promise

加入房间

参数:
- userId: 用户 ID
- nickName: 用户昵称
- roomToken: 房间 token
- sdkConfig: SDK 配置
- region: 区域配置（如 "cn-hz", "dev"）
- appIdentifier: 应用标识符
- windowManager: 窗口管理器配置
- writable: 是否可写（默认: true）
- verboseLog: 是否启用详细日志（默认: false）

##### leaveRoom(): Promise

离开房间并清理资源

#### 属性

- applicationManager: 应用管理器
- windowManager: 窗口管理器（如果配置了）
- state: 房间当前状态
- isWritable: 当前用户是否可写

$3

#### registerApplication(ApplicationClass: ApplicationClass): void

注册应用类到房间。必须在 joinRoom 之前调用。

#### launchApplication(ApplicationClass, config?, appId?): Promise

启动应用实例

参数:
- ApplicationClass: 应用类
- config: 应用配置对象（可选）
- appId: 应用 ID（可选，默认使用随机 UUID）

#### on(event: 'launch' | 'terminal', listener: Function): void

监听应用生命周期事件

- 'launch': 应用启动时触发
- 'terminal': 应用终止时触发

$3

#### view: HTMLElement

窗口管理器的 DOM 视图

#### permissions: PermissionManager

窗口权限管理器

核心概念

$3

房间内每个应用都有唯一的 appId，通过 launchApplication 的第三个参数指定。appId 划分了一块房间数据，房间里的所有用户都可以无冲突地访问和修改这块数据。

何时应该手动指定 appId？
- 当希望房间内所有用户共享同一个应用实例时（如主白板）
- 使用固定的 appId 确保数据一致性

何时应该用默认的 uuid？
- 当需要为每个用户创建独立的应用实例时
- 响应用户操作创建新的应用实例

$3

每个应用实例都有一个 view 属性，在 JavaScript 中对应一个 DOM 对象。forge-room 只负责管理应用的创建、数据同步和销毁，不包含任何 UI 组件，因此你需要：

1. 对 view 进行样式配置
2. 将 view 挂载到你的应用容器中
3. 在 applicationManager 的 terminal 事件中移除 view 以避免内存泄漏

`typescript
// 正确的 view 清理方式
room.applicationManager.on('terminal', (appId, app) => {
console.log(应用 ${appId} 已终止);
app.view.remove(); // 在应用终止时自动移除 DOM 元素
});
`

$3

房间层面提供了只读与可写的权限划分：

只读: 用户只能观看房间内容，无法进行任何修改操作。
可写: 用户可以进行内容创建、修改和删除等操作。

在可写的基础上, 每个 App 都有进一步详细的权限控制.

$3

`typescript
// 监听应用事件
room.applicationManager.on('launch', (appId, app) => {
console.log(应用 ${appId} 已启动);
});

room.applicationManager.on('terminal', (appId, app) => {
console.log(应用 ${appId} 已终止);
app.view.remove(); // 清理 DOM
});

``