SuperAPI AI 工具集

liveblocks

编程与开发

查看项目

更新于 10-16 07:08

技能介绍

Liveblocks 是一个用于为应用添加实时协作功能的完整工具包,包含在线状态(presence)、存储(storage)、评论、通知,以及 Yjs/Redux 集成。以下内容依据提供的资料整理。

安装与配置

安装命令:

npm install @liveblocks/client @liveblocks/react

配置文件 liveblocks.config.ts 中,使用 createClient 创建客户端,使用 createRoomContext 创建房间上下文,并定义 Presence、Storage、UserMeta 类型。示例中 publicApiKey 使用 "pk_xxx",并注明生产环境可使用 authEndpoint 替代。随后导出 RoomProvider、useMyPresence、useUpdateMyPresence、useOthers、useSelf、useStorage、useMutation、useRoom 等。

基础用法通过 RoomProvider 包裹协作组件,并传入 id、initialPresence 等属性。

在线状态(Presence)

Presence 用于跟踪临时性的用户状态,例如光标、选区、输入指示。

使用 useMyPresence / useUpdateMyPresence 更新自己的在线状态(如光标坐标);使用 useOthers 获取其他用户的光标与信息并渲染;使用 useSelf 获取自己的连接信息与用户元数据。

性能方面可使用选择器模式(selector pattern),例如 useOthers((others) => others.length) 仅在数量变化时重新渲染,或仅取出其他用户的光标位置。

存储(Storage)

Storage 使用无冲突数据类型在多个客户端之间持久化并同步数据。

可在 RoomProvider 中通过 initialStorage 初始化,例如 todos: new LiveList([])、canvas: new LiveMap()、settings: new LiveObject({ theme: "dark" })。

使用 useStorage 读取数据(示例中若为 null 则显示 Loading);使用 useMutation 修改存储,示例包含 addTodo、toggleTodo、deleteTodo 等操作。

实时数据类型:

  • LiveList:支持 push(追加)、insert(指定索引插入)、move(移动)、delete(按索引删除)、clear(清空)。
  • LiveMap:支持 set、get、delete、has。
  • LiveObject:支持 set、get、update(批量更新多个属性)。

Suspense 支持

从 @liveblocks/react 引入 ClientSideSuspense,配合 @liveblocks/react/suspense 的 useStorage 使用。示例中用 ClientSideSuspense 包裹编辑器,fallback 显示 Loading;使用 suspense hooks 后无需再做 null 检查。

鉴权(Authentication)

提供 Auth Endpoint 示例(app/api/liveblocks-auth/route.ts):使用 @liveblocks/node 的 Liveblocks,传入 secret(环境变量 LIVEBLOCKS_SECRET_KEY),在 POST 中获取会话、读取 room、prepareSession 并传入 userInfo(name、avatar),再通过 session.allow(room, session.FULL_ACCESS) 授权,最后 session.authorize() 返回 body 与 status。客户端配置改用 authEndpoint: "/api/liveblocks-auth"。

广播(Broadcast)

使用 useRoom 获取房间,通过 room.broadcastEvent 发送不存储的临时消息(如 { type: "MESSAGE", text }),并通过 room.subscribe("event", ...) 订阅接收。

历史记录 / 撤销重做

从 @liveblocks/react 引入 useHistory、useCanUndo、useCanRedo。示例通过 history.undo、history.redo 按钮操作,并用 canUndo/canRedo 控制禁用状态。可通过一次 useMutation 批量修改以便合并为单个撤销步骤;也可使用 history.pause() 与 history.resume() 暂停/恢复历史记录。

Yjs 集成

安装命令:npm install @liveblocks/yjs yjs

使用 useRoom 获取房间,创建 Y.Doc 与 LiveblocksYjsProvider(room, yDoc),可与 TipTap、Quill、Lexical 等编辑器配合(示例中使用 Collaboration.configure 与 CollaborationCursor.configure),并在清理时调用 yProvider.destroy() 与 yDoc.destroy()。

评论(Comments)

安装命令:npm install @liveblocks/react-comments

从 @liveblocks/react-comments 引入 Thread、Composer,从 @liveblocks/react/suspense 引入 useThreads。示例中遍历 threads 渲染 Thread,并放置 Composer。

常见模式

  • 多人光标:结合 useUpdateMyPresence 与 useOthers(过滤 cursor 非 null),在指针移动时更新相对于容器的坐标,并在指针离开时置为 null;渲染 Cursor 组件。
  • 谁在这里(Who's Here):使用 useOthers 与 useSelf 渲染头像堆叠。
  • 实时选区:在 Presence 中定义 selectedId,点击时更新自己的选区,并通过 useOthers 取得他人的选区以标记样式。

最佳实践

资料中列出的最佳实践包括:使用选择器避免不必要的重新渲染;为 presence/storage 添加类型以获得自动补全与安全性;使用 Suspense hooks 获得更简洁的加载状态;批量 mutation 以分组撤销/重做;生产环境使用 authEndpoint(而非公开 API key);对光标更新进行防抖以提升性能。

限制

资料未提供关于收费、价格、平台支持范围或具体效果指标的说明,这些内容暂未提供。