DockWorkspace 停靠工作区

通用布局能力：RenderDockWorkspace 实例统一支持 width、height、min/max、margin 和槽位对齐；文档内容自身也按其 RenderBox 属性参与工作区布局。详见组件通用布局属性。

RenderDockWorkspace 是可停靠、可拆分、可浮动的多窗口工作区视图，DockWindowManager 是对应的窗口记录、布局树和生命周期管理器。它适合 IDE、CIS 工作台、调试工具台、病历工作区这类“多个业务窗口长期并存，并且允许用户把窗口拖出、拖回、左右/上下分屏”的界面。

当前 RenderDockWorkspace 管理的是一棵单一 dock tree。left、right、top、bottom 停靠会在这棵 tree 内创建 split；它还不是完整的 workbench-level dock manager，不提供左侧/右侧/底部工具区与中心文档区的同级 region、auto-hide tool strip 或多 tab floating group。

核心分工：

• DockWindowManager：打开文档、打开已有窗口、激活、关闭、关闭保护、浮动、停靠、拆分、拖拽状态、布局树和局部 App Context。
• RenderDockWorkspace：订阅 manager，把 DockLayoutNode 渲染为 tab group 与 splitter，绘制 dock guide、drop preview、空状态，并处理工作区级快捷键。
• RenderWindow：实际文档窗口外壳。停靠时用 tabbed presentation，浮动时作为 host window 的 owned window。

API 总览

import {  DockWindowManager,  RenderDockWorkspace,  RenderText,  RenderWindow,  type DockDropScope,  type DockDropTarget,  type DockDropZone,  type DockLayoutNode,  type DockOpenWindowOptions,  type DockSplitNode,  type DockTabGroupNode,  type DockWindowRecord,} from 'ds-ui'

最小装配顺序是：创建 DockWindowManager，用 openDocument() 或 openWindow() 注册窗口，再把 manager 传给 RenderDockWorkspace。需要浮动窗口时，还要通过 setWindowHost() 绑定顶层 RenderWindow。

何时使用

使用 DockWorkspace：

• 页面需要像 IDE 一样支持左右/上下拆分。
• tab 可以拖出成为 floating window，也可以拖回工作区。
• 检查器、病历、医嘱、时间轴等窗口可以在同一棵 dock tree 内并排工作。
• 浮动窗口仍要保留原文档上下文、命令状态和关闭保护。
• 需要右键菜单：浮动窗口、新建垂直标签组、新建水平标签组、关闭、关闭其他、关闭右侧、关闭全部。

不要使用：

• 只需要标签头，使用 Tabs。
• 只需要“标签 + 当前内容页”，使用 TabView。
• 需要普通多文档 tab，但不允许浮动和拆分，使用 TabbedWorkspace。
• 只是一个普通左右布局，使用 DockPanel。
• 需要 Visual Studio 风格的左/右工具区、中心文档区、底部输出区、pin/auto-hide 和多工具 floating group，应使用后续 workbench-level dock 组件。

最小示例

const manager = new DockWindowManager() manager.openDocument({  tabId: 'patient-chart',  title: '患者总览',  content: new RenderText('患者总览内容'),}) const workspace = new RenderDockWorkspace({  manager,})

openDocument() 会把业务内容包入文档上下文 host，再创建一个内部 RenderWindow。该窗口默认以 tabbed presentation 停靠到当前 active group。

使用宿主窗口承载浮窗

如果工作区允许浮动窗口，应把应用当前顶层窗口传给 manager。浮动窗口会作为 host window 的 owned window 管理，这样才能保持层级、置顶和统一释放。

const hostWindow = new RenderWindow({ title: '工作台' })const manager = new DockWindowManager()manager.setWindowHost(hostWindow) const workspace = new RenderDockWorkspace({  manager,  disposeManagerOnDispose: true,})

如果没有调用 setWindowHost()，manager 仍会维护 floatingWindows，但浮窗不会自动加入某个顶层窗口的 owned window 集合。业务工作台通常应在页面或 shell 初始化时设置 host。

打开已有 RenderWindow

openWindow() 用于把已经创建好的 RenderWindow 纳入 dock 管理。它适合工具窗口、运行时诊断窗口、对象检查器窗口等场景。

const manager = new DockWindowManager()const inspector = new RenderWindow({  title: '对象查看器',  width: 420,  height: 320,}) inspector.setChildren([  new RenderText('检查器内容'),]) manager.openWindow(inspector, {  tabId: 'inspector',  title: '对象查看器',  icon: 'search',})

注意：openWindow() 的生命周期和上下文 hook 从 RenderWindow 本身读取，不会把 window 的子节点当作文档 content。业务页面通常用 openDocument()；工具窗口可以用 openWindow()。

程序化拆分

const manager = new DockWindowManager() manager.openDocument({  tabId: 'chart',  title: '患者总览',  content: new RenderText('患者总览'),}) manager.openDocument({  tabId: 'orders',  title: '医嘱录入',  content: new RenderText('医嘱录入'),}) const orders = manager.getDocument('orders')if (orders && manager.root.type === 'tabs') {  manager.dockWindow(orders.window, manager.root, 'right')}

dockWindow(window, group, 'right') 会创建 horizontal split。left/top 的新 group 放在 first，right/bottom 的新 group 放在 second。

浮动和拖回

const manager = new DockWindowManager()manager.openDocument({  tabId: 'timeline',  title: '病程时间轴',  content: new RenderText('病程时间轴'),}) const record = manager.getDocument('timeline')if (record) {  manager.floatWindow(record.window, {    x: 80,    y: 60,    width: 420,    height: 260,  })   manager.dockWindow(record.window)}

浮动不会释放 content，也不会重建上下文。拖回中心区域等价于 dockWindow(window, targetGroup, 'center')；拖到工作区边缘等价于 dockWindowToWorkspace(window, zone)。

文档上下文

DockWorkspace 复用 TabbedWorkspace 的文档上下文模型：

const encounterIdKey = createAppContextKey<string>('encounter-id')const manager = new DockWindowManager() manager.openDocument({  tabId: 'orders',  title: '医嘱录入',  content: new RenderText('医嘱内容'),  contextValues: [[encounterIdKey, 'enc-001']],}) const record = manager.getDocument('orders')const encounterId = record?.context.appContext.get(encounterIdKey)

上下文规则：

• openDocument() 会创建 RenderAppContextScope 包裹业务 content。
• 未传 context 时，manager 创建私有 AppContextRegistry，关闭文档时默认释放。
• 传入外部 context 时，默认不释放外部 context。
• 传入 contextValues 时，会注入到文档 context。
• floatWindow() 和 dockWindow() 只迁移窗口，不替换文档 context。
• content 实现 TabbedDocumentContextAware 时，打开时调用 attachDocumentContext(context)，关闭或 dispose 时调用 detachDocumentContext()。

关闭保护

let saved = falseconst manager = new DockWindowManager() manager.openDocument({  tabId: 'editor',  title: '编辑器',  dirty: true,  content: new RenderText('编辑内容'),  beforeClose: () => saved,})

关闭保护优先级：

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

beforeClose 和 beforeDocumentClose() 支持同步或异步返回 boolean。返回 false 或抛出异常时关闭会被取消。closable: false 的文档不会被 closeDocument()、右键关闭和 Ctrl/Meta + W 关闭。

Tab Tooltip

tooltip 会投影到 docked tab 和 floating window 的 tab 元信息。它当前是字符串字段，适合展示页面来源、业务对象摘要或未保存说明；字符串中可以使用 \n 显示多行短文本。

manager.openDocument({  tabId: 'system-role-permission',  title: '角色权限管理',  content: new RenderText('角色权限内容'),  tooltip: [    '菜单路径：系统设置 / 平台管理 / 角色权限管理',    '页面路径：/platform/roles',  ].join('\n'),})

如果需要可交互说明或复杂排版，不要塞进 tab tooltip；使用 Popover、侧栏或页面内详情区承载。

DockWindowManager 属性

DockWindowManager 方法

TabbedDocumentDefinition

openDocument() 使用 TabbedDocumentDefinition。这和 TabbedWorkspace 是同一套定义。

DockOpenWindowOptions

openWindow(window, options) 使用 DockOpenWindowOptions。

DockWindowRecord

manager 内部保存的文档记录：

布局节点

DockLayoutNode 是 manager 的布局树：

type DockLayoutNode = DockTabGroupNode | DockSplitNode

拆分方向：

• zone: 'left' | 'right' 创建 direction: 'horizontal'。
• zone: 'top' | 'bottom' 创建 direction: 'vertical'。
• 新 pane 默认占比为 0.32 或 0.68，取决于停靠方向。

Drop Target

拖拽时 RenderDockWorkspace.hitTestDrop(position) 返回 DockDropTarget | null。

通常不需要业务手动设置 drop resolver。RenderDockWorkspace 构造时会调用 manager.setDropResolver(position => this.hitTestDrop(position))。

RenderDockWorkspace Options

const manager = new DockWindowManager()const workspace = new RenderDockWorkspace({  manager,  disposeManagerOnDispose: false,})

RenderDockWorkspace 属性和方法

右键菜单

tab 右键菜单包含：

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

快捷键

RenderDockWorkspace.handleUnhandledKeyDownFromDescendant() 支持：

它只处理从后代冒泡来的未处理快捷键。全局命令、菜单快捷键和业务按钮权限仍应通过命令系统管理。

拖拽和停靠行为

• 在 tab strip 内拖动，只执行 tab 重排。
• tab 指针离开 header strip 后，才进入 dock drag。
• 拖到另一个 group 的 tab header，会合并到该 group center。
• 拖到 pane 的中心/边缘 guide，会在 pane 内合并或拆分。
• 拖到 workspace 边缘 guide，会把窗口停靠到整个工作区边缘。
• 拖出工作区且没有 drop target，会变成 floating window。
• 浮窗拖拽取消时恢复开始拖拽前的 rect。

布局和绘制

• workspace 背景使用 theme.surfaceWindow。
• root 为 tab group 时，绘制 tab header 和 active RenderWindow。
• root 为 split 时，递归渲染 RenderSplitter。
• 没有 docked documents 时，绘制空状态文本：暂无 Dock 文档。
• 拖拽中绘制 drop preview 和 dock guide button。
• 无限约束下 workspace 默认尺寸为 720 x 420。
• 停靠状态下 RenderWindow 使用 tabbed presentation，不绘制独立窗口 chrome。
• 浮动状态下 RenderWindow 使用 floating presentation，由 host window owned windows 绘制。

生命周期和释放

默认 disposeManagerOnDispose: false：

• workspace 释放时取消订阅 manager。
• 清理 drop resolver。
• 释放内部 tab group view 和 splitter view。
• 不关闭 manager 中的 documents。
• 适合 manager 生命周期由外层工作台 controller 管理。

设置 disposeManagerOnDispose: true：

• workspace dispose 时调用 manager.dispose()。
• manager 会释放所有 records、windows、content、context、订阅和拖拽状态。
• 适合简单页面或 demo 中 workspace 独占 manager 的场景。

关闭单个文档时：

1. 检查 closable。
2. 防止同一个 tabId 重入关闭。
3. 执行关闭保护。
4. 从 floating set、layout tree、recordOrder 中移除。
5. detach 文档上下文。
6. 触发 active 文档 deactivated/activated。
7. dispose RenderWindow。

与 Tabs / TabView / TabbedWorkspace 的区别

性能边界

• DockWorkspace 只布局当前布局树中的 group、splitter 和 active windows。
• 每个 group 只挂载 active window；同组非 active window 不参与内容布局绘制。
• floating windows 由 host window owned windows 管理，仍会参与顶层窗口布局/绘制。
• 大型业务页面失活后应暂停数据轮询、动画和高频刷新。
• 不要把业务状态绑定到当前停靠位置；位置只是用户工作台布局状态。
• 大型系统如需持久化布局，应在业务层序列化 DockLayoutNode 所需信息，不要直接持久化 render object。

常见问题

重复打开同一个 tabId 会替换内容吗？

不会。openDocument() 遇到重复 tabId 时只更新标题、closable、dirty、tooltip、icon 并激活已有文档，不替换原 content。新传入的 replacement content 不会被 manager 接管。

浮动窗口还能读取原页面上下文吗？

可以。floatWindow() 只改变 presentation 和宿主关系，不改变文档 appContext。前提是文档创建时通过 context 或 contextValues 正确注入上下文。

closeDocument 为什么返回 false？

常见原因：

• tabId 不存在。
• 文档 closable 是 false。
• 同一个文档正在关闭中。
• beforeClose 返回 false 或抛异常。
• content 的 beforeDocumentClose() 返回 false 或抛异常。

为什么浮窗没有显示？

检查是否给 manager 设置了顶层 host：

const manager = new DockWindowManager()const hostWindow = new RenderWindow({ title: '工作台' })manager.setWindowHost(hostWindow)

没有 host 时，manager 仍知道哪些窗口是 floating，但不会自动把它们加入某个顶层窗口的 owned windows。

可以直接操作 root 布局树吗？

只读分析可以。业务代码不要直接改 manager.root 内部节点，应通过 dockWindow()、dockWindowToWorkspace()、floatWindow()、closeDocument() 等方法修改，保证 record、parent、owner、active 状态和生命周期同步。

相关文档

• TabbedWorkspace
• Tabs
• TabView
• DockPanel
• Floating Window 指南
• App Context
• 命令与权限