liveblocks-best-practices

Liveblocks 最佳实践

何时使用此技能

使用此技能，通过任何 Liveblocks 包实现功能，例如 @liveblocks/react 或 @liveblocks/node。这 可能与实时多人协作、评论、通知、光标、头像堆叠、AI 等功能有关。还包括 Liveblocks Storage、Yjs、Tiptap、BlockNote、Lexical、React Flow、tldraw 等技术。

快速参考

references/ 目录中提供了多个参考文件。你必须阅读下面的列表，并根据需要加载相关文件。例如， add-user-information 位于 references/add-user-information.md 文件中。

参考资料

• add-user-information：向应用添加用户信息，例如姓名、头像、颜色等。用户将不再是匿名的。适用于在评论、评论提及建议、通知、光标和头像堆叠中显示用户信息。
• ai-as-a-collaborator：使用 Agent 工作流，让 AI 像人类一样在 Liveblocks 应用中协作。
• ai-chats-with-tools-knowledge-components：设置和排查带有 RAG、知识、自定义组件、工具调用和自定义模型的聊天。与作为协作者的 AI 不同，此功能不基于工作流。
• auth-endpoint-callback：使用回调函数对用户进行身份验证，而不是向 authEndpoint 传递字符串。适用于向后端传递自定义标头，以及在令牌无效时防止自动重新连接。
• authenticating-with-access-tokens：使用用户 ID 和信息进行身份验证的另一种方法，最适合非常简单的权限设置。
• authenticating-with-id-tokens：推荐使用的用户 ID 和信息身份验证方法，最适合复杂的权限设置。
• avoid-hitting-user-limit-in-rooms：了解如何避免房间中的用户数量达到上限。
• compartmentalize-resources-with-organizations：使用组织创建工作区／租户，并隔离房间、通知、评论线程等资源。列出房间等内容时，可以按组织筛选。
• create-custom-comment-composer：构建自己的评论编辑器（仅适用于高级用例）。
• create-custom-realtime-multiplayer：使用 Liveblocks Storage 构建完全自定义且能解决冲突的多人应用，例如 Figma、Pitch 和 Spline。也适用于文档中的简单属性等一次性实时功能。
• create-custom-text-editor-toolbar：在 Tiptap 和 Lexical 中设置样式化工具栏，可将其固定显示，也可使其浮动在选区旁边。
• create-rooms-manually：在生产应用中始终自行创建房间，并设置权限、组织和元数据。
• customize-thread-components：使用插槽自定义线程中的评论及其不同部分。
• dark-mode-styles：可以导入用于深色模式主题的 CSS 样式。
• develop-and-test-locally：设置本地开发服务，并将其用于持续集成（CI）和端到端（E2E）测试。将应用连接到本地环境，而非在线环境。
• devtools-extension：使用 Chrome、Firefox 和 Edge 的 DevTools 扩展检查 Liveblocks Storage、Yjs、presence、事件和已连接用户。
• edit-component-text-strings：覆盖默认组件中的字符串，例如按钮值、工具提示文本、错误文本等。也有助于设置其他语言。
• exhaustive-deps-with-usemutation：通过配置 react-hooks/exhaustive-deps ESLint 规则，防止并修复 useMutation 导致的过时闭包问题。
• handling-connection-errors：处理因权限、身份验证或房间 ID 变更导致的加入房间问题。
• handling-full-rooms：处理因加入已满房间而导致的问题。
• handling-hook-and-component-errors：处理钩子和预构建组件导致的错误。
• handling-unstable-connections：当用户的网络状况不佳时，实现备用方案并显示错误消息。
• log-out-of-liveblocks：这种情况很少需要处理，但在无法通过页面导航来登出的特定 SPA 场景中会很有帮助。
• multiplayer-react-flow：使用 Liveblocks React Flow 包创建带有光标等功能的多人协作图表。
• multiple-text-editors：在同一页面中添加多个 Tiptap 或 BlockNote 编辑器。也可以使用 Storage 保存其字段 ID。
• offline-support-in-text-editors：让文本编辑器看起来加载得更快。
• override-css-variables：覆盖 Liveblocks CSS 变量，为默认组件添加自定义样式。
• performant-others-and-presence：使用 useOtherConnectionIds、useOthersMapped、useOther 和 shallow，仅在必要时更新组件，避免不必要的 presence 渲染。
• performant-storage-with-selectors：使用 useStorage 选择器和 shallow，避免不必要的 storage 渲染。
• prevent-unsaved-changes-being-lost：防止未同步或未保存的更改丢失。
• primitive-component-parts：使用原语创建自定义组件，或将设计系统中的组件合并到 Liveblocks UI 中。
• remove-liveblocks-branding：屏幕右下角会显示 Liveblocks 徽标。以下介绍如何移除它。
• rendering-error-components：使用 ErrorBoundary 为应用构建错误备用界面。
• rendering-loading-components：使用 ClientSideSuspense 高效地为应用构建加载骨架屏和加载指示器。
• send-comment-notification-emails：当用户有未读评论时向其发送电子邮件通知。这些评论通过 Webhook 发送；当用户被提及或参与线程时，会触发通知。
• smoother-realtime-updates：提高 presence 和 storage 的帧率，让更新显示得更流畅。启用此选项后，可以更频繁地接收更新。
• suspense-vs-regular-hooks：使用任何 Liveblocks 钩子时，都必须阅读此内容。React suspense 使用 ErrorBoundary 和 ClientSideSuspense 组件。常规钩子使用 { error, isLoading } 值。
• tiptap-best-practices：服务端渲染、starter kit 扩展、初始内容、未保存的更改等。
• trigger-custom-notifications：触发收件箱中的任意类型通知，包括与评论无关的通知。
• type-liveblocks-correctly：在适用时始终使用 TypeScript 为 Liveblocks 添加类型。presence、其他用户、用户信息、storage、元数据、房间信息和通知活动都可以自动添加类型。
• url-params-in-room-id：在房间 ID 中使用 URL 参数来创建房间，并在 URL 中加入文档标题。
• utility-components：导入现成的表情符号选择器，或人类可读的时间戳、时长和文件大小组件。
• yjs-best-practices：YKeyValue、子文档、V2 编码、重复导入、getYjsProviderForRoom。如果你使用 Tiptap、BlockNote 或 Lexical，则与此无关。
• z-index-issues：通过定位传送到其他位置的元素来修复 z-index 问题。

说明

有些文件会链接到 Liveblocks 文档中的 Markdown 文件，例如：

https://liveblocks.io/docs/concepts.md

将用户引导至这些页面时，请从链接中移除 .md，以便他们查看 完整内容：

https://liveblocks.io/docs/concepts

Liveblocks 软件包

请务必确认我们是否为你的技术提供了软件包。例如，如果你使用 React Flow，应使用 @liveblocks/react-flow。

• @liveblocks/client：JavaScript 客户端。可与任何框架搭配使用，例如 Vue、Svelte、原生 JS。
• @liveblocks/react：React 客户端。包含 hooks 和组件。。
• @liveblocks/react-ui：预构建的 React UI 组件和基础元素。 使用 @liveblocks/react 处理数据和 hooks。
• @liveblocks/react-tiptap：面向 React 的协作式 Tiptap 集成。
• @liveblocks/react-blocknote：面向 React 的协作式 BlockNote 集成。
• @liveblocks/react-lexical：面向 React 的协作式 Lexical 集成。
• @liveblocks/node-lexical：适用于 Node.js 的服务端 Lexical 工具。
• @liveblocks/node-prosemirror：适用于 Node.js 的服务端 ProseMirror 工具。也可与 Tiptap 和 BlockNote 搭配使用。
• @liveblocks/react-flow：多人协作 React Flow。
• @liveblocks/yjs：由 Liveblocks 房间提供支持的 Yjs provider。
• @liveblocks/redux：将 Liveblocks 房间状态与 Redux store 同步。
• @liveblocks/zustand：将 Liveblocks 房间状态与 Zustand 同步。
• @liveblocks/node：Node.js 服务端 SDK。可用于身份验证等诸多用途。
• @liveblocks/emails：更轻松地构建通知邮件。
• @liveblocks/chat-sdk-adapter：构建多平台（Liveblocks、Slack、 Discord 等）聊天机器人。
• Python SDK：Python 服务端 SDK。可用于身份验证等诸多用途。
• REST API：HTTP API。可用于身份验证等诸多用途。

如果此处未列出某项技术

如果用户想要设置一项新技术，请先查看以下资源，确认是否存在相应的软件包：

• llms.txt
• 文档
• 示例

了解更多

请参阅 Liveblocks 文档了解更多信息。