TabbedWorkspace 标签工作区

通用布局能力：RenderTabbedWorkspace 及其 RenderBox 内容实例统一支持 width、height、min/max、margin 和槽位对齐；文档管理器只负责生命周期和切换。详见组件通用布局属性。

RenderTabbedWorkspace 是多文档 tab 工作区视图，TabbedDocumentManager 是对应的文档状态和生命周期管理器。它们适合复杂业务系统中“多个页面/文档同时打开、可切换、可关闭、可重排、各自有局部上下文”的场景。

核心分工：

• TabbedDocumentManager：文档记录、active 状态、打开、激活、更新、关闭、关闭保护、生命周期通知、局部 app context。
• RenderTabbedWorkspace：订阅 manager，把 documents 投影到 RenderTabs，布局当前 active document content，提供 tab 右键菜单和常用快捷键。

API 总览

import {  RenderTabbedWorkspace,  TabbedDocumentManager,  RenderText,  type TabbedDocumentContext,  type TabbedDocumentContextAware,  type TabbedDocumentDefinition,  type TabbedDocumentLifecycle,  type TabbedDocumentPatch,  type TabbedDocumentRecord,} from 'ds-ui'

最小装配顺序是：创建 TabbedDocumentManager，用 openDocument() 注册内容，再把 manager 传给 RenderTabbedWorkspace。文档内容由 manager 持有，关闭文档时才释放对应 context 和 content host。

何时使用

使用 TabbedWorkspace：

• 工作台支持多个业务页面同时打开。
• 每个 tab 需要自己的页面实例和页面上下文。
• 关闭 tab 需要执行 beforeClose 或页面生命周期保护。
• 页面需要知道自己所属 tab，并能更新标题、dirty、tooltip、icon 或请求关闭。
• 需要右键菜单：关闭、关闭其他、关闭右侧、关闭全部。
• 需要 Ctrl/Meta + Tab 切换，Ctrl/Meta + W 关闭 active tab。

不要使用：

• 只需要标签头，使用 Tabs。
• 页面内轻量“标签 + 当前内容”，使用 TabView。
• 需要停靠、拆分、浮动窗口，使用 DockWorkspace。
• 需要浏览器级路由和缓存策略完全由业务掌控时，可以自己组合 Tabs 和页面容器。

最小示例

const manager = new TabbedDocumentManager() manager.openDocument({  tabId: 'patient-list',  title: '患者列表',  content: new RenderText('患者列表'),}) const workspace = new RenderTabbedWorkspace({  manager,})

openDocument() 会打开新文档并激活它；如果 tabId 已存在，则更新标题、closable、dirty、tooltip、icon 并激活已有 tab，不替换原 content。

页面上下文示例

const encounterIdKey = createAppContextKey<string>('encounter-id')const manager = new TabbedDocumentManager() manager.openDocument({  tabId: 'orders',  title: '医嘱录入',  content: new RenderText('医嘱内容'),  contextValues: [[encounterIdKey, 'enc-001']],}) const workspace = new RenderTabbedWorkspace({  manager,  disposeManagerOnDispose: true,})

如果打开文档时没有传 context，manager 会为该文档创建独立 AppContextRegistry，并在文档关闭时随 content host 一起释放。

更新文档状态示例

const manager = new TabbedDocumentManager()manager.openDocument({  tabId: 'record',  title: '病历',  content: new RenderText('病历内容'),}) manager.updateDocument('record', {  title: '病历 *',  dirty: true,  tooltip: '有未保存修改',  icon: 'document',})

updateDocument() 只更新 tab 元数据，不替换 content。

关闭保护示例

const manager = new TabbedDocumentManager() manager.openDocument({  tabId: 'editor',  title: '编辑器',  content: new RenderText('编辑内容'),  dirty: true,  beforeClose: () => {    return canSave()  },})

beforeClose 返回 false 或抛出异常时，关闭会被取消。异步返回 Promise<boolean> 也支持。

TabbedDocumentDefinition

同一 tabId 重复打开时：

• 不替换已有 content。
• 更新 title、closable、dirty、tooltip、icon。
• 激活已有 tab。
• 调用方传入的 replacement content 不会被 manager 自动 dispose，所有权仍属于调用方。

TabbedDocumentRecord

manager 内部保存的记录：

业务通常读取 documents、activeDocument、getDocument()，不要直接修改 record 字段；修改状态应使用 updateDocument() 或 document context。

TabbedDocumentManager API

TabbedDocumentPatch

updateDocument() 和 TabbedDocumentContext.update() 支持的字段：

TabbedDocumentContext

如果 content 实现 TabbedDocumentContextAware，manager 打开文档时会调用 attachDocumentContext(context)，关闭或重置时会调用 detachDocumentContext()。

RenderPage 已支持 document context，可直接使用 setDirty()、setTitle()、requestClose() 等页面级方法。

生命周期接口

内容可以实现 TabbedDocumentLifecycle：

关闭保护优先级：

1. TabbedDocumentDefinition.beforeClose
2. content 的 beforeDocumentClose()
3. 默认允许关闭

如果关闭保护抛异常，manager 会按拒绝关闭处理。

RenderTabbedWorkspace Options

const manager = new TabbedDocumentManager()const workspace = new RenderTabbedWorkspace({  manager,  emptyTitle: '暂无页面',  emptyDescription: '从左侧导航打开一个模块。',  disposeManagerOnDispose: false,})

RenderTabbedWorkspace 属性和能力

Workspace 会订阅 manager。manager 变化时：

• 更新 tabs.tabs。
• 更新 tabs.activeKey。
• 切换 active contentHost。
• 关闭已不存在 tab 的右键菜单。
• 请求布局。

标签右键菜单

右键 tab 会打开内置菜单：

批量关闭会按顺序执行 closeDocument()。如果某个文档关闭保护拒绝，后续批量关闭会停止。

快捷键

RenderTabbedWorkspace.handleUnhandledKeyDownFromDescendant() 支持：

它只处理从后代冒泡来的未处理快捷键。全局快捷键或命令快捷键仍应通过命令系统管理。

App Context 策略

每个文档都会有一个 contentHost：

• contentHost 是 RenderAppContextScope。
• 如果 definition 提供 context，使用该外部 context。
• 如果只提供 contextValues，创建新的子 context 并注入 values。
• 如果没有提供 context，创建文档私有 context。
• 默认情况下，manager 创建的 context 会随文档关闭释放。
• 外部传入的 context 默认不释放，除非 disposeContextOnClose: true。

这让某个 tab 页内部的组件、弹窗和子页面可以通过上下文查到页面私有数据；tab 关闭后上下文随页面释放。

布局和绘制

• Workspace 顶部布局内部 RenderTabs。
• active contentHost 布局在标签条下方。
• 有限高度下，body 高度为 constraints.maxHeight - tabs.height。
• 无限高度下，body 高度至少 260。
• 没有 active content 时，绘制空状态标题和说明。
• 切换 active content 时，会清理旧 active content 内部焦点，避免焦点留在已 detach 子树。

Dispose 策略

默认 disposeManagerOnDispose: false：

• workspace dispose 时取消订阅 manager。
• detach 当前 active contentHost。
• 不 dispose manager，也不 dispose manager 中的 documents。
• 适合 manager 生命周期由外层 app/workspace controller 管理。

设置 disposeManagerOnDispose: true：

• workspace dispose 时同步 dispose manager。
• manager 会释放所有 documents、context、contentHost 和订阅。
• 适合 workspace 独占 manager 的简单页面。

与 Tabs / TabView / DockWorkspace 的区别

性能边界

• manager 会持有所有已打开文档的 content 实例和上下文。
• inactive documents 不挂载到 workspace active content，但对象仍在内存中。
• 大量复杂页面同时打开会占用内存；业务应限制打开数量或提供关闭/释放策略。
• dirty、title、tooltip 等元数据更新只会刷新 tab strip，不应重建 content。
• 批量关闭可能执行多个异步 close guard，应避免在 close guard 中做长时间阻塞工作。

常见问题

重复 openDocument 会替换内容吗？

不会。重复 tabId 只更新元数据并激活已有文档。新传入的 replacement content 不由 manager 接管，也不会自动 dispose。

closeDocument 为什么返回 false？

可能是文档不存在、正在关闭中、beforeClose 返回 false、content lifecycle 拒绝关闭，或 close guard 抛异常。

inactive document 会被销毁吗？

不会。它只是没有挂载为 workspace 的 active content。关闭文档或 dispose manager 时才释放。

dispose workspace 后文档为什么还在？

默认 workspace 不拥有 manager。要让 workspace 销毁时连带释放所有文档，构造时设置 disposeManagerOnDispose: true。

页面怎么更新自己的 tab 标题或 dirty 状态？

实现 TabbedDocumentContextAware 获取 context，或使用 RenderPage 内置的 document context 方法，然后调用 setTitle()、setDirty() 等。

相关文档

• Tabs 标签
• TabView 标签视图
• DockWorkspace 停靠工作区
• App Context 与页面生命周期
• Tab Workspace 指南
• 焦点与输入