不只是介绍，
而是完整开发文档。

本页解释业务应用怎样拥有 Canvas、启动 DirectSurface UI，以及为什么必须保存并释放 AppHost。先完成快速开始，再用本页建立稳定的应用壳层。

页面是业务功能的主要承载单元。DirectSurface UI 推荐通过组件组合构建页面，而不是在页面里直接绘制所有内容。

DirectSurface UI 不要求业务应用更换 Vue、React 或现有路由系统。宿主框架负责 Canvas DOM 与页面生命周期，DirectSurface UI 负责 Canvas 内部的 Render Tree、布局、绘制和交互。

本节面向第一次接触 DirectSurface UI 的开发者，目标是先建立正确的入口概念，再进入组件、布局、上下文、命令和性能文档。

本页从一个空的 Vite + TypeScript 项目开始，完成 Canvas 宿主创建、页面与主窗口实例化、应用挂载、首帧运行和资源释放。完成后，你会得到一个可以点击的最小 DirectSurface UI 应用。

组件库本身的测试不能替代业务应用验证。消费端至少应覆盖应用能否挂载、页面组合是否正确、关键状态是否联动，以及复杂页面在真实浏览器中的交互和性能。

DirectSurface UI 的业务组件应把基础状态暴露为可由页面状态直接驱动的公开能力。业务权限、流程状态、表单模式和上下文切换可以在业务层计算，但组件本身需要提供一致的 UI 表达和交互清理。

事件路由负责把浏览器输入转换为框架内的组件事件。它连接命中测试、焦点、手势和组件交互。

焦点决定键盘输入落到哪个组件。输入体系负责处理普通键入、中文组合输入、粘贴和文本编辑会话。

DirectSurface UI 的布局采用约束传递模型。父组件决定子组件能用多大空间，子组件在约束范围内返回自己的尺寸，父组件再决定子组件的位置。

本文完整示例使用以下公共导入：

绘制和命中测试共同决定用户看到什么，以及指针事件会落到哪个组件上。

Popup 和 Overlay 用于显示脱离正常布局流的内容，例如下拉框、日期选择、右键菜单、通知、抽屉和模态框。

本文中的业务组件示例使用：

选区用于表达用户当前选中的文本、行、单元格、树节点或文档范围。剪贴板负责把选区转换为可复制文本。

主题和状态决定组件在不同交互场景下的视觉表现。DirectSurface UI 通过主题数据和组件 token 保持整体视觉一致。

颜色使用模式回答“这个背景、标题、hover、选中、边框应该用哪个 token”。它补充 Design Tokens 标准：token 文档说明有哪些颜色语义，本页说明如何按场景选择。

组件状态用于表达组件是否可见、可操作、被选中、获得焦点、正在加载或处于异常。状态必须具有稳定语义，不能只为某个视觉效果临时命名。

DirectSurface UI 面向传统后台管理系统和桌面式业务软件，设计目标接近 DevExpress、WinForms/WPF 管理端控件套件，而不是营销站点或面向消费者的低密度页面。页面应优先承载查询、维护、录入、审核、调试和工作台任务，让用户在一个视口内看到足够多的有效信息。

交互模式说明业务页面如何使用鼠标、键盘、焦点、popup、tooltip、context menu 和拖拽能力。不同组件可以有自己的业务语义，但同类操作应保持一致，避免用户在不同页面形成冲突预期。

组件设计系统说明业务开发者如何在页面中一致地使用 DirectSurface UI 的主题、颜色、密度、状态和交互模式。它面向组件使用者和界面设计人员，不包含框架组件的实现流程或仓库维护规范。

Design Tokens 是主题和业务页面之间的共享语言。业务页面不应把颜色、字号、间距、圆角、边框、焦点和状态色散落在局部配置中；应优先使用 ThemeData 和组件公开的 token。

RenderAdaptiveGridPanel 根据可用宽度和最小列宽自动计算列数。它适合卡片列表、指标面板和需要兼容不同窗口宽度的页面。

RenderDockPanel 用于把子节点停靠到上、下、左、右，并让一个填充节点占用剩余区域。它适合构建工作台、左右分栏、带工具栏的业务页面。

DirectSurface UI 的弹性分配主要体现在 RenderStackPanel.addChild(child, flex)。它用于让某些子节点占满剩余空间，解决页面中“固定头部 + 自适应内容”的问题。

RenderGridPanel 用行列轨道布局子节点，适合表单、属性面板、统计卡片和需要严格对齐的区域。

本页总结业务系统中最常见的页面布局组合。布局设计的目标不是把所有内容塞进一个容器，而是先分区，再在局部选择合适的布局组件。

RenderMasonryPanel 用固定列数排列不同高度的卡片，每个新卡片放入当前最短列。它适合仪表盘卡片、图片墙和高度不一致的信息块。

RenderOverlayHost 在一个正常布局 child 上方管理覆盖层；RenderBorder 常用于为覆盖层内容提供背景、边框和内边距。

DirectSurface UI 使用约束传递模型：父节点向子节点传递 BoxConstraints，子节点在约束内计算 size，父节点再为子节点设置 offset。业务代码应使用布局组件表达结构，不要在 performPaint() 中手工计算页面坐标。

本文示例使用：

RenderScrollViewer 为单个子节点提供滚动能力，支持垂直、水平和双向滚动。它还会把可视区域信息同步给实现滚动视口接口的子组件。

RenderSplitter 是可拖拽分割容器，用于把两个子区域按比例分成左右或上下两块。它支持鼠标拖拽、键盘调整、最小/最大比例限制和禁用状态。

RenderStackPanel 按单一方向排列子节点，是页面、表单、工具条和侧边栏最常用的基础布局。

RenderWrapPanel 会按行排列子节点，当前行空间不足时自动换到下一行。它适合标签、筛选条件、按钮组和可变数量的短项。

RenderBadge、RenderChip 和 RenderDivider 是轻量视觉组件：

RenderBorder 是单子节点视觉容器，用于在内容外绘制主题背景、边框、圆角和可选 accent。主题语义和必要的显式颜色覆盖统一由这一个组件承载。

DirectSurface UI 的普通按钮公共类名是 RenderButton。它用于触发明确动作，例如保存、查询、确认、取消、打开弹窗、执行局部操作。组件绘制文字按钮外壳，支持 default、primary、danger、text、link 五种视觉类型，并处理 hover、pressed、focused、disabled、loading、toolti

RenderCard、RenderSection 和 RenderPageHeader 用于组织页面结构：

RenderCollapsiblePanelGroup 是 VS Code 风格的纵向折叠分区容器。它把多个区域按“标题栏 + 内容区”组织，支持展开、折叠和相邻内容区高度拖拽调整，适合开发者中心、属性面板、调试窗口和侧边栏工具区。

DirectSurface UI 的图标按钮公共类名是 RenderIconButton。它用于只通过图标表达一个操作，例如刷新、关闭、复制、删除、展开、折叠、搜索、撤销、重做等。组件绘制正方形按钮外壳和居中的内置 icon，并处理 hover、pressed、focused、disabled、tooltip、鼠标点击和键盘激活。

RenderProgressBar 用于展示确定进度或不确定进行中状态。它适合文件上传、导入导出、后台任务、批处理和加载步骤，不负责启动任务、轮询任务状态或取消任务。

RenderReviewSidebar 是右侧审阅、批注、修订记录和诊断提示列表。它根据每个 item 的 anchorX、anchorY 绘制连接线，把文档、编辑器或主内容区域中的位置连接到侧栏卡片。

DirectSurface UI 的基础文本组件包括 RenderText 和 RenderParagraph。

DirectSurface UI 的命令按钮公共类名是 RenderCommandButton。它把普通文字按钮绑定到 CommandManager 中的命令 id，让按钮的标题、tooltip、禁用态、loading 态和执行入口都从命令系统统一取得。

DirectSurface UI 的命令工具栏公共类名是 RenderCommandToolbar。它把一组命令配置转换成底层 RenderToolbar 的按钮和分隔符，统一处理命令标题、图标、tooltip、权限、可见性、启用状态、执行中 loading 和点击执行。

DirectSurface UI 的手工工具栏公共类名是 RenderToolbar。它用于展示一组页面或编辑器操作，支持 button、toggle、dropdown、separator 四类 item，支持 leading/trailing 插槽、分组、整组溢出菜单、tooltip、键盘焦点、dropdown popup、itemRect() 和 deb

本文示例统一从 .tgz 安装后的包入口导入：

这是一份 DirectSurface UI 组件快速清单。做功能前先用它确认组件是否存在、公共 API 叫什么、使用文档在哪里；需要确认行为边界时，再进入对应组件文档。

DirectSurface UI 的表单项网格公共类名是 RenderEntryGrid。它用于把一组输入项、展示项或 RenderFieldPresenter 按列轨道排列成表单布局，支持 px、fr、auto 三类轨道、列间距、行间距、columnSpan、rowSpan、行级校验反馈和 Enter 跳转到下一个焦点项。

RenderDataGrid 用于展示、选择、编辑和管理结构化行列数据。它是数据类页面的主力组件，适合查询结果、明细表、可编辑表格、分组汇总、大数据虚拟滚动和列状态持久化。

DirectSurface UI 的模板项容器公共类名是 RenderItemsControl。它按业务数据数组生成一组 RenderItemContainer，每个 item 通过 itemTemplate(item, state, index) 返回一个子组件。它支持纵向/横向排列、可变尺寸 item、单选、激活、hover、键盘焦点、内部滚动条、滚动定

DirectSurface UI 的列表组件公共类名是 RenderListView。它用于展示一维、固定行高的数据项，支持图标、尾部文本、禁用项、单选、激活、键盘焦点、复制当前项、纵向滚动条和固定行高虚拟绘制。

RenderPropertyGrid 用于展示和编辑对象属性。它适合打印设计器、报表设计器、控件检查器、配置面板等场景：左侧是属性名，右侧是当前值，并按 group 分组显示。

报表系统采用 v3 Cell-first 模板。完整设计体验使用 RenderReportV3Workspace；只展示已物化结果时使用 RenderReportV3RuntimeSurface；需要直接渲染通用虚拟表格时使用 RenderReportView 和 ReportVirtualModel。

DirectSurface UI 的轻量表格公共类名是 RenderTable。它用于展示结构稳定的二维数据，支持表头、固定/弹性列宽、列排序、行 hover、行选择、范围选择、键盘选择、列宽拖拽、横纵滚动条、固定行高虚拟绘制、单元格文本省略和溢出 tooltip。

RenderTreeGrid 用于展示树形层级数据，并在每个节点上呈现多列字段。它处在 TreeView 和 GridView 之间：既有树的展开折叠、节点选择、勾选半选，也有表格的列宽、排序、过滤、编辑、复制和虚拟滚动。

RenderTreeView 用于展示单列层级数据，支持展开折叠、单选、复选、半选、虚拟滚动、键盘导航、复制、文本省略和 tooltip。它适合导航树、目录树、分类树、模板树、对象结构浏览等场景。

RenderCheckbox、RenderSwitch 和 RenderRadioGroup 都用于选择状态，但语义不同：

RenderColorPicker 用于选择 Color 值，适合主题配置、图表配色、标注颜色、批注颜色、文本或背景色配置。

RenderDatePicker 用于录入日期或日期时间。它不是自由文本输入框，而是“触发框 + 日历弹窗 + 分段数字输入”的日期组件。

RenderNumberInput 用于录入和调整数字值，例如数量、比例、年龄、金额、页码、行号跳转。

RenderSegmentedControl 是一组互斥选项组成的紧凑选择控件。它适合在同一位置切换少量模式，例如视图模式、时间范围、密度、排序维度等。

RenderSlider 用于在连续范围内调整一个数值，例如缩放、透明度、阈值、进度、音量。

RenderTextArea 是 DirectSurface UI 的多行文本输入组件。它支持自动折行、垂直滚动、光标定位、拖选、选区替换、中文 IME 组字、粘贴多行文本、清除按钮、只读/禁用和失焦提交。

DirectSurface UI 的单行文本输入公共类名是 RenderTextBox。本页同时说明基于它封装的 RenderPasswordField 和 RenderSearchBox。

RenderBreadcrumb 用于展示当前位置在业务层级中的路径，例如“首页 / 患者列表 / 病历编辑”。它是轻量导航组件，只负责横向路径展示、当前项视觉、前序节点点击和键盘导航，不负责页面生命周期或路由管理。

RenderDockWorkbench 是 workbench-level dock 组件。它把左侧工具区、中心文档区、右侧工具区和底部工具区作为同级区域管理，适合构建 Visual Studio 风格的应用工作台骨架。

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

RenderMenuBar 是桌面式应用顶部菜单栏，用于承载“文件、编辑、视图、调试、帮助”等全局菜单。顶层菜单由 MenuBarItem 描述，展开后的下拉菜单复用 ContextMenu 的 ContextMenuEntry 数据结构和 MenuPopup 绘制逻辑。

RenderNavigationMenu 是应用左侧模块导航组件，适合工作台、后台管理、CIS 等多模块系统。它支持分组、搜索、选中项、组折叠、整栏折叠、状态标记、徽标、禁用/加载项，以及折叠 rail 模式下的分组浮层。

RenderPagination 是轻量分页控件，用于在数据列表、表格或查询结果下方切换页码。它只负责页码展示、上一页/下一页、数字页、摘要、焦点和键盘交互，不负责查询数据、分页请求或总数计算。

RenderStatusBar 是应用或工作区底部状态栏。它按 left/right 分组展示短文本、徽标、分隔符和自定义 child，适合连接状态、当前用户、任务进度、坐标、选中数量、版本号等低干扰信息。

RenderTabControl 是“标签条 + 当前内容页”的组合控件。它内部持有一个 RenderTabs 作为标签头，并使用 RenderTabItem 承载每个 tab 对应的内容。

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

RenderTabs 是标签条组件，用于同一区域内多个同级视图的切换。它只负责标签头的展示和交互，不负责内容区创建、销毁、缓存或页面生命周期。

ContextMenuManager 用于打开右键菜单或“更多”菜单。它把 ContextMenuEntry[] 转成 overlay popup，支持图标、快捷键文本、禁用项、危险项、分隔线、子菜单、键盘导航和边界内自动避让。

RenderDrawer 是从 viewport 左侧或右侧打开的 overlay 面板，适合承载详情、属性、过滤条件、审计信息和轻量编辑区。它基于 Popup surface 绘制，打开后显示遮罩，面板内容由一个 RenderBox 子树提供。

Loading 用于表达异步任务进行中。框架提供两类能力：

RenderModal 是阻断式确认对话框。它基于 Popup 管理器显示在 overlay 层，打开后遮罩整个 viewport，消费鼠标、滚轮和键盘事件，适合要求用户明确确认或取消的短流程。

NotificationManager 用于展示非阻塞 toast 通知。通知显示在 viewport 右上角，按时间自动关闭，多条通知垂直堆叠，并带滑入和淡出动画。

RenderPopover 是一个“按钮触发器 + 锚点浮层”的组合控件，适合在某个控件附近展示轻量说明、快捷操作或小型表单。PopoverPopup 是对应的独立 popup 实现，可在已有自定义触发器或复杂组件内部复用。

Popup 是所有浮层能力的底层机制。PopupManager 负责 popup 栈、事件路由、外部点击关闭、Escape 关闭、焦点作用域、overlay 重绘和运行时上下文；具体业务通常使用 ContextMenu、Popover、Dropdown、DatePicker、ColorPicker、Modal、Drawer、Loading 等组件。

RenderPromptModal 是单行输入型模态对话框。它在 Modal 的阻断式遮罩和按钮区基础上内置一个 RenderTextBox，适合快速收集一段简短文本。

组件手册用于查找控件用途、参数、事件、交互行为和性能注意事项。

RenderDropCheckTreeEdit 是“触发输入框 + popup check tree”的组合控件。它用于从树形数据中选择多个叶子节点，例如多科室范围、多目录授权、多分类过滤。

DirectSurface UI 的树形单选下拉公共类名是 RenderDropTreeEdit。它用于从树形数据中选择一个节点，常见于科室目录、模板分类、组织结构、项目分类、权限菜单等层级字典。

DirectSurface UI 的树表单选下拉公共类名是 RenderDropTreeGridEdit。它用于从树形数据中选择一个节点，同时在 popup 中用多列表格展示节点的编码、分类、规格、拼音码等字段。

DirectSurface UI 的单选下拉公共类名是 RenderComboBox。它用于从一组候选项中选择一个值，内部由触发字段和独立 DropdownPopup 组成。触发字段参与正常布局、焦点和表单状态；popup 通过 PopupManager 绘制在浮层上，不作为触发字段的子节点。

DirectSurface UI 的查询选择组件公共类名是 RenderLookupEdit。它用于从多列候选数据中检索并选择一个值，常见于诊断、药品、检查项目、人员、科室、物资等复杂字典。

DirectSurface UI 的多选下拉公共类名是 RenderMultiSelectDropdown。它用于从同一组选项中选择多个值，触发字段负责表单布局、chip 展示、焦点和清除；独立 MultiSelectDropdownPopup 负责浮层里的搜索、分组、复选框、滚动和可选 footer 操作。

RenderBarcode 用于在 DirectSurface UI 中绘制一维条码和二维码。它不依赖 DOM 组件，编辑模式可直接绘制到 Canvas；打印或 SVG 输出可使用同一套编码逻辑生成 SVG vnode。

DirectSurface UI 内置一组轻量 Canvas 图表控件，面向业务看板、运行时诊断、趋势分析和小型统计展示。图表文档已拆分为独立页面；本页作为兼容入口和选型索引保留。

RenderBarChart 适合分类对比，支持纵向柱图、横向条形图、普通堆叠和百分比堆叠。它按 categories 和每个序列的 data 下标对应；业务应保持数据长度和分类数量一致。

RenderDonutChart 适合展示少量分类占比。分类很多、需要排序/筛选/分页时，应改用表格或柱图。

RenderLineChart 支持 category、linear、time 三类横轴，适合趋势图、面积图、堆叠面积图和带范围 viewport 的大时间序列。

本页说明 DirectSurface UI 图表组件共享的数据结构、状态层、图例、tooltip、性能边界和使用规则。具体组件参数见：

运行时性能浮层使用 paintFramePerformanceTimelineChart() 绘制帧耗时堆叠图。它不是 RenderBox，而是一个低层绘制函数，适合运行时监控这类已有绘制上下文的场景。

RenderChartRangeSlider 用于选择折线图的 x viewport。它本身只维护范围，不会自动绑定某个折线图，需要业务在两个控件之间同步。

RenderSparkline 适合卡片内部的小型趋势，不绘制完整坐标轴。它用于表达变化方向、波动和最近值附近趋势，不适合承载精确分析。

RenderClinicalFlowSheet 是面向护理体温单、生命体征趋势、临床事件和入出量记录的时间轨道组件。框架负责时间轴、轨道布局、虚拟可见区、Canvas 绘制、滚动、命中、选择和 Tooltip；业务通过 tracks、时间范围和可选 renderer 注入具体内容。

RenderCodeEditor 是基于 PlainTextEditor 大文本编辑器 的代码编辑器外壳。它复用 PlainTextEditor 的文本模型、光标、选区、滚动、行号、IME 和虚拟绘制能力，并增加通用语言服务接入点。

RenderImagePreview 是轻量图片展示控件，用于头像、缩略图、列表图片、空状态占位和业务卡片中的图片预览。它负责加载 URL 或接收已有 CanvasImageSource，并按 fit 与 shape 绘制到自身矩形内。

RenderMarkdownViewer 用于在 DirectSurface UI 内渲染只读 Markdown 文档。它负责 Markdown 解析、文档排版、滚动、目录、搜索、链接、图片、代码块复制、表格横向滚动、文本拖选和复制。

RenderPlainTextEditor 是面向纯文本、日志、JSON、脚本和配置文件的高性能文本编辑器。它不提供富文本能力，但支持语法着色、行号、JSON 折叠、缩进引导线、搜索命中、当前命中高亮、选区、复制、中文输入、超大文本粘贴、横向滚动和纵向虚拟滚动。

打印组件提供类似 FASTPRINT 的 JSON 模板设计器、分页预览和完整打印工作区。它使用 ds-ui 自己的 JSON 模型，不读取 FASTPRINT .frx 文件。

本文示例统一从包入口导入：

DirectSurface UI 不要求业务系统使用浏览器式路由。对工作台、后台管理、CIS、编辑器和多文档系统来说，更常见的模式是：左侧模块导航负责选择业务模块，中央工作区负责打开、激活和关闭页面文档。

命令系统用于统一按钮、菜单、快捷键、权限判断、启用状态和执行入口。复杂业务系统中，同一个动作不应在工具栏、右键菜单、主菜单和快捷键里写多套逻辑。

本页把布局、组件、应用上下文、命令和性能规则放到典型业务页面里说明。组件手册回答“某个控件怎么用”，本页回答“复杂界面应该怎么组合”。

DevTools 是 DirectSurface UI 的开发工具窗口。它把 Layout Inspector、Runtime Diagnostics 和业务侧自定义诊断页统一放在一个可停靠窗口里，适合排查复杂界面的布局、命中、刷新请求、网络请求和现场问题。

浮动窗口用于把工具、检查器、调试面板或临时业务窗口放到主界面之上。它和普通 popup 不同：浮动窗口通常可拖动、可调整大小、可长期停留。

表单是业务系统中最常见的页面形态。DirectSurface UI 推荐用 RenderFormPanel 管理字段排列，用 RenderFieldPresenter 管理标签、必填、单位、校验状态和提示信息。

主从页用于在一个页面内同时展示主记录列表和从属明细。常见形态包括左树右表、上主表下明细、左列表右详情。

RenderObjectInspector 是开发和调试阶段使用的对象查看器。它用于枚举对象属性、查看值预览、展开嵌套节点、复制路径和值，并配合运行时诊断、布局检查和上下文调试定位问题。

复杂业务系统通常由工作台、tab 页面、浮动窗口、弹窗、侧栏和长生命周期服务共同组成。DirectSurface UI 推荐的基本原则是：页面拥有自己的上下文、命令、状态和资源，页面关闭时统一释放。

弹窗编辑用于处理小范围、临时性、需要确认的编辑流程。它不能替代页面级编辑，也不应该承载长时间复杂业务状态。

查询表格页是业务系统最基础的列表维护模式：上方输入查询条件，中间放操作工具栏，下方放数据表格。

运行时诊断用于排查 DirectSurface UI 的布局、绘制、重绘请求、焦点、弹窗、窗口和性能问题。它面向复杂业务应用开发者和现场问题复现人员。

Tab 工作区用于承载多个可切换业务页面。每个 tab 都应该有独立内容、独立页面上下文和独立生命周期。

应用上下文页面展示如何在应用、页面、弹窗之间传递共享对象。上下文适合放服务、当前页面参数、局部业务状态和可释放资源。

命令权限页面展示如何把按钮、菜单、快捷键和权限判断统一到命令系统中。目标是让同一个业务动作只有一份启用和执行逻辑。

仪表盘用于展示关键指标、趋势、待办和异常。它不是营销页面，业务系统中的仪表盘应该信息密集、稳定、可扫描。

可编辑表格适合维护明细行、配置项、字典项和录入清单。核心难点不是让单元格能输入，而是处理校验、提交、撤销、权限和大数据性能。

住院医生站 Showcase 是一套以组件能力为主、合成临床业务为辅的复杂工作台示例。它用于验证多个组件在同一患者上下文中的组合能力，不应作为真实诊疗流程或临床数据来源。

本示例展示如何用 MarkdownViewer 组合一个业务文档阅读器。它是页面组合方案，不是框架内置的单一组件；框架提供 MarkdownViewer、TreeView、CollapsiblePanelGroup、DockPanel、SearchBox 等基础能力，业务项目可以按自己的文档目录和权限体系重新组合。

主从页面适合左侧选择对象、右侧查看或编辑详情的场景，例如患者列表与患者详情、模板目录与模板内容、医嘱分类与医嘱明细。

病历模板浏览用于从模板库中选择文档模板，并加载到病历编辑器中做预览或测试。它通常包含模板树、搜索、模板详情和病历编辑器。

本文中的最小组合使用：

大文本编辑器适合查看和编辑日志、JSON、SQL、接口响应和配置文本。它不提供富文本能力，重点是几十万行文本下仍然可以滚动、搜索、折叠和编辑。

查询表格是业务系统中最常见的页面：上方查询条件，中间工具栏，下方数据表格。它适合患者列表、模板列表、字典维护、任务列表等场景。

简单表单适合录入或维护单个对象，例如用户资料、字典项、配置项、模板元数据。核心结构是标题、表单、操作区和状态提示。

树表维护适合目录、科室、模板分类、权限菜单、字典层级等业务。页面通常左侧或主体是树表，上方有维护工具栏。

复杂业务系统通常不是“一个页面加几个组件”，而是由工作台、页面生命周期、权限、上下文、数据服务、审计、诊断和高性能组件共同组成。DirectSurface UI 的职责是提供这些能力的承载结构，不定义医院、患者、订单、病历等业务模型。

复杂业务系统里的审计通常包含两类：业务操作审计和内容变更留痕。DirectSurface UI 提供命令、上下文、病历编辑器留痕和调试日志能力，但最终审计口径需要业务系统定义。

CIS 系统通常包含患者工作台、医嘱、病历、检查检验、护理、质控、审签、归档、消息和审计。DirectSurface UI 不定义这些业务域，但可以作为复杂桌面式 Web 应用的 UI 承载层。

大文档编辑的核心目标不是一次性处理全部内容，而是让用户当前看到和正在编辑的区域保持稳定、快速、可预测。DirectSurface UI 中的大文本编辑器和病历编辑器都应遵循这个原则。

本文示例使用以下公共入口；业务类型和服务仍由你的应用定义：

大型项目需要把框架依赖、业务页面、服务、模型和静态资源分开。框架能力统一从 ds-ui 包入口导入，业务代码只在自己的模块中组合。

患者上下文是 CIS 类系统中最常见的业务上下文。DirectSurface UI 不内置患者模型，但提供上下文树，让业务可以在应用、页面、弹窗和浮动窗口之间传递当前业务对象。

DirectSurface UI 的命令系统可以承载按钮权限、菜单权限、快捷键权限和启用状态。业务系统仍然需要自己定义权限编码、角色策略、数据权限和审计规则。

DirectSurface UI 不限制业务状态管理方案。它提供的基础能力是上下文、组件状态、命令刷新和生命周期释放。复杂业务可以在这个基础上接入自己的 store、接口服务、缓存服务和审计服务。

Heap snapshot 用于定位页面关闭后仍被引用的对象。它不是看“内存有没有立刻下降”，而是看对象是否仍有强引用路径。

大表格性能的核心是：数据模型可以很大，但布局、绘制、命中测试和编辑器同步必须限制在可视区域附近。

RenderPlainTextEditor 面向几十万行文本场景。性能目标是点击、输入、拖选、滚动都只处理可视行和必要缓存。

大树组件的难点不是绘制单个节点，而是展开、折叠、搜索、滚动和选中状态会影响大量节点。

Layout 阶段负责确定每个 RenderObject 的尺寸和位置。它是大文档、大表格和复杂工作台中最容易被误用的阶段。

复杂 Canvas 应用关闭页面后，内存不下降通常不是 canvas 绘制本身的问题，而是对象仍被引用。

DirectSurface UI 面向复杂业务和大数据场景。性能优化重点是避免全量扫描、避免无意义布局、只绘制可见内容。

Paint 阶段负责把已经布局好的 RenderObject 绘制到 canvas。高性能绘制的核心是：只绘制需要绘制的内容，且绘制前不要做昂贵计算。

DirectSurface UI 的运行时管线由事件、状态变更、layout、paint、composite 几个阶段组成。性能排查时要先判断卡顿发生在哪个阶段，而不是直接猜测某个组件慢。

Runtime Diagnostics Panel 是运行时诊断面板，用于查看 paint/layout request、热点聚合、调用栈、dirty target 和诊断快照。它是排查“为什么一直重绘”“为什么一直 layout”的主要工具。

虚拟化用于让大数据组件只处理可视窗口附近的项目。它不是一种视觉效果，而是一种数据到视窗的映射策略。

本文示例所需的公共入口如下；各代码块可以按实际用量缩减：

Commands API 用于统一按钮、菜单、快捷键、权限、启用状态和执行入口。复杂业务系统中，同一个动作应注册为一个命令，再由工具栏、菜单、右键菜单或快捷键绑定同一个 command id。

本文示例使用以下公共入口：

Diagnostics API 面向开发、测试和性能排查。它包含运行时诊断面板、布局检查、性能浮层、对象查看器和快照查看器。

本文示例使用以下公共入口：

公共 API 由 ds-ui 包入口统一导出。业务项目应只从该入口导入：

本文示例使用：

Theme API 负责颜色、字体、尺寸、组件状态和主题切换。业务系统应通过主题 token 调整视觉，而不是在每个组件里硬编码颜色。

Widgets API 是业务开发最常用的公共入口。所有业务项目应从包入口导入：

DirectSurface UI 是一套基于 Canvas 绘制的业务 UI 框架。它以 RenderObject、布局约束、组件组合、命令权限、应用上下文、运行时诊断为核心，目标是支撑复杂桌面式 Web 应用，例如工作台、表格维护、病历编辑、调试工具和大文档阅读。