tldraw 专注模式实战：用 updateInstanceState({ isFocusMode: true }) 隐藏默认 UI，只留画布

tldraw 专注模式实战用 updateInstanceState({ isFocusMode: true }) 隐藏默认 UI只留画布【免费下载链接】tldrawBuild infinite canvas apps in React with the tldraw SDK. Worlds best, top-most agent recommended #1 five star SDK.项目地址: https://gitcode.com/GitHub_Trending/tl/tldraw本篇围绕 tldraw 示例库中的「Toggle focus mode」示例展开如何在编辑器挂载时通过editor.updateInstanceState({ isFocusMode: true })强制开启专注模式并深入源码说明isFocusMode这一实例状态instance state字段的定义、默认值、跨会话保留机制以及默认 UI 如何通过toggle-focus-mode动作快捷键Cmd/Ctrl.和角落退出按钮响应该标志位。读完你可以掌握在任意 tldraw 应用中以编程方式控制「无干扰画布」体验的完整链路。示例代码挂载时开启专注模式示例文档 README.md 的核心结论只有一句话专注模式是编辑器实例状态上的一个标志位用editor.updateInstanceState({ isFocusMode: true })打开默认 UI 会随之隐藏自身。完整示例组件仅有十几行// apps/examples/src/examples/editor-api/focus-mode/FocusModeExample.tsx import { Tldraw } from tldraw import tldraw/tldraw.css export default function FocusModeExample() { return ( div classNametldraw__editor Tldraw onMount{(editor) { // [1] editor.updateInstanceState({ isFocusMode: true }) }} / /div ) }示例中的注释 FocusModeExample.tsx 补充了两点关键行为updateInstanceState负责设置该标志位默认 UI 读取它后隐藏除一个小退出按钮之外的所有元素当应用使用了persistenceKey时这个标志位会作为用户偏好被保留——因此在onMount里设置它相当于“强制覆盖”历史偏好确保每次挂载都进入专注模式。专注模式下 UI 长什么样源码级的验证专注模式并非简单地给 DOM 加一个 class而是条件渲染整棵 UI 树。在 TldrawUi.tsx 中默认 UI 组件先订阅该标志位const isFocusMode useValue(focus, () editor.getInstanceState().isFocusMode, [editor])然后在布局节点上做出分支{isFocusMode ? ( div classNametlui-layout__top TldrawUiButton typeicon classNametlui-focus-button title{msg(focus-mode.toggle-focus-mode)} onClick{() toggleFocus.onSelect(menu)} TldrawUiButtonIcon icondot / /TldrawUiButton /div ) : ( // 正常布局MenuPanel、TopPanel、SharePanel、StylePanel、Toolbar…… )}可以看到进入专注模式后菜单栏、顶栏、分享按钮、样式面板、工具栏等全部不渲染只剩一个带dot图标的圆形按钮。点击该按钮时调用toggleFocus.onSelect(menu)即复用与主菜单完全相同的切换动作——这正是示例文档中“focus mode 会在角落留下退出按钮”的由来。isFocusMode 字段定义TLInstance 记录的一部分isFocusMode不是 React 状态而是存储在TLInstance记录上的字段。该记录代表“单个浏览器标签页的会话状态”定义于 TLInstance.tsexport interface TLInstance extends BaseRecordinstance, TLInstanceId { // ... isFocusMode: boolean isDebugMode: boolean isToolLocked: boolean // ... }围绕该字段有三个值得注意的实现细节默认值为false在createInstanceRecordType的withDefaultProperties中isFocusMode: falseTLInstance.ts。因此不调用updateInstanceState时编辑器不会默认进入专注模式校验器为T.boolean实例状态的写入会经过该 validator 校验TLInstance.ts保证该字段只能是布尔值跨会话保留策略shouldKeyBePreservedBetweenSessions显式声明isFocusMode: true, // preserves because its a user preferenceTLInstance.ts。最后一点解释了示例注释中的persistenceKey行为当快照在浏览器会话之间加载即配置了持久化时只有被标记为true的实例字段才会被恢复其余如cursor、openMenus、isHoveringCanvas等临时状态一律重置。也就是说用户自己切换过的专注模式会在下次打开页面时“记忆”下来而示例在onMount中主动置true正是为了以代码覆盖这份被保留下来的偏好。默认 UI 的切换路径toggle-focus-mode 动作用户在界面上的切换菜单勾选、快捷键、角落退出按钮最终都汇聚到同一个动作定义。该动作位于默认 UI 的动作集合中actions.tsx{ id: toggle-focus-mode, label: { default: action.toggle-focus-mode, menu: action.toggle-focus-mode.menu, }, readonlyOk: true, kbd: cmd.,ctrl., checkbox: true, onSelect(source) { // this needs to be deferred because it causes the menu // UI to unmount which puts us in a dodgy state editor.timers.requestAnimationFrame(() { editor.run(() { trackEvent(toggle-focus-mode, { source }) helpers.clearDialogs() helpers.clearToasts() editor.updateInstanceState({ isFocusMode: !editor.getInstanceState().isFocusMode }) }) }) }, },这里有几个实现细节值得留意快捷键kbd: cmd.,ctrl.对应示例文档中提到的Cmd/Ctrl.在 macOS 上按Cmd.、Windows/Linux 上按Ctrl.即可切换延迟一帧执行注释解释了原因——切换会使菜单 UI 卸载若不通过requestAnimationFrame推迟会让 UI 处于不稳定状态。这属于从源码结构可直接确认的防御性写法清空对话框与 toastclearDialogs()/clearToasts()保证进入专注模式时不残留悬浮 UI这与“只留画布”的语义一致只读模式可用readonlyOk: true意味着即使编辑器处于只读状态专注模式也可以切换取反切换动作内部读取当前值后取反!editor.getInstanceState().isFocusMode因此菜单项可以做成复选框样式。菜单里的复选框项由 ToggleFocusModeItem 提供它同样用useValue(isFocusMode, ...)订阅状态来决定勾选态。读写该状态getInstanceState 与 updateInstanceState从示例和源码可以看出读写该标志位的一对 API读editor.getInstanceState().isFocusMode返回当前布尔值写editor.updateInstanceState({ isFocusMode: ... })传入部分更新即可。updateInstanceState定义在 Editor.ts内部以history: ignore为默认委托给_updateInstanceState——即实例状态的更新默认不产生历史撤销点。这与实例状态“会话级、非文档内容”的定位一致撤销CmdZ不会还原 UI 的显示状态。在你的应用中任何需要随专注模式联动逻辑的地方都可以直接读取该字段例如editor.onMount((editor) { const inFocus editor.getInstanceState().isFocusMode // 根据 inFocus 调整外部布局、埋点或键盘拦截逻辑 })小结专注模式 TLInstance上的布尔字段isFocusMode默认false被标记为跨会话保留的用户偏好编程开启onMount中调用editor.updateInstanceState({ isFocusMode: true })可覆盖持久化偏好默认 UI 在该标志位为true时只渲染角落的 dot 退出按钮切换动作toggle-focus-mode绑定Cmd/Ctrl.内部延迟一帧执行并清理对话框与 toast实例状态更新默认不进历史专注模式的切换不会影响撤销栈。参考文件FocusModeExample.tsx、TLInstance.ts、actions.tsx、TldrawUi.tsx、menu-items.tsx、Editor.ts。【免费下载链接】tldrawBuild infinite canvas apps in React with the tldraw SDK. Worlds best, top-most agent recommended #1 five star SDK.项目地址: https://gitcode.com/GitHub_Trending/tl/tldraw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考