DirectSurface UIDirectSurface UI
开始使用
文档/API 参考

Widgets API 参考

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

import {  RenderButton,  RenderStackPanel,  RenderText,} from 'ds-ui' const row = new RenderStackPanel({  orientation: 'horizontal',  spacing: 8,})row.addChild(new RenderText('操作'))row.addChild(new RenderButton({  label: '保存',  onClick: () => save(),}))

不要从 src/widgets/...、demo/src/... 或内部文件路径导入。只有 ds-ui 包入口导出的类、函数和类型才是正式公共 API。

选型规则

  • 基础展示、按钮、图标、卡片等通用 UI 使用基础组件。
  • 用户录入值使用输入组件；校验、保存、权限和审计由页面或命令系统处理。
  • 枚举、树、树表、查询选择使用选择器。
  • 大数据列表、树、表格优先使用内置虚拟化数据组件。
  • 页面级操作优先通过命令组件绑定 CommandManager。
  • 弹窗、右键菜单、tooltip、通知等使用 overlay/feedback 组件和 manager。
  • 文档、代码、大文本、图表、条码二维码使用可视化组件。
  • 病历编辑器是专业组件，应通过控制器和 options 组合，不要绕过控制器直接操作内部对象。

基础显示

API 类型 详细文档 用途
RenderText class Text 单行文本、标题、说明、状态文本。
RenderParagraph class Text 段落文本和多行文本展示。
RenderBorder class Border 单子节点背景、边框、圆角和 accent 视觉容器。
RenderButton class Button 普通文字按钮。
RenderIconButton class IconButton icon-only 按钮、工具型按钮。
RenderIcon class IconButton 单独绘制内置 icon。
RenderBadge class Badge / Chip / Divider 状态徽标、数量提示。
RenderChip class Badge / Chip / Divider 标签、筛选条件、可关闭 chip。
RenderDivider class Badge / Chip / Divider 水平或垂直分割线。
RenderProgressBar class ProgressBar 进度条、加载进度和任务进度展示。
RenderCard class Card / Section / PageHeader 重复项卡片、内容块容器。
RenderSection class Card / Section / PageHeader 页面分区标题和内容组合。
RenderPage class Card / Section / PageHeader 页面根容器。
RenderPageHeader class Card / Section / PageHeader 页面标题、说明和操作区。
RenderEmpty class Card / Section / PageHeader 空状态。
RenderGroupBox class Card / Section / PageHeader 有标题的分组框。
RenderItemContainer class ItemsControl 列表项外壳，统一 hover、selected、active 状态。
RenderCollapsiblePanelGroup class CollapsiblePanelGroup VS Code 风格纵向折叠分区和可调高度面板。
RenderReviewSidebar class ReviewSidebar 批注、修订、审阅块等右侧信息列表。

常用关联类型和 helper：

  • RenderTextOptions、RenderTextOverflow、RenderTextRole、RenderTextSize、RenderTextWeight
  • ButtonVariant
  • IconName
  • BadgeAppearance、BadgeStatus、BadgeLayoutMetrics
  • ItemContainerState、ItemContainerAppearance、ItemContainerStyleOverrides、ItemTemplate
  • CollapsiblePanelSection、RenderCollapsiblePanelGroupOptions
  • ReviewSidebarItem、ReviewSidebarAction、ReviewSidebarItemType

输入组件

API 类型 详细文档 用途
RenderTextBox class TextField 单行文本输入。
RenderPasswordField class TextField 密码输入。
RenderSearchBox class TextField 搜索输入，支持搜索事件和清除。
RenderTextArea class TextArea 多行文本输入、批注内容等。
RenderNumberInput class NumberInput 数字输入。
RenderDatePicker class DatePicker 日期、日期时间输入。
DatePickerPopup class DatePicker 日期悬浮选择面板。通常由 RenderDatePicker 内部使用。
RenderCheckbox class Checkbox / Switch / Radio 布尔勾选。
RenderSwitch class Checkbox / Switch / Radio 开关状态。
RenderRadioGroup class Checkbox / Switch / Radio 单选组。
RenderSlider class Slider 范围值选择。
RenderSegmentedControl class SegmentedControl 分段选择。
RenderColorPicker class ColorPicker 颜色输入。
ColorPickerPopup class ColorPicker 颜色悬浮面板。通常由 RenderColorPicker 内部使用。

常用关联类型：

  • FormFieldStatus
  • RadioOption
  • CalendarTime、CalendarTimePrecision、ISODate
  • SegmentedControlOption

输入组件只负责编辑值和基础交互。业务校验建议通过 status、helperText、命令状态和页面状态组合，不要把保存逻辑写入底层控件。

选择器

API 类型 详细文档 用途
RenderComboBox class Dropdown 单选枚举下拉。
DropdownPopup class Dropdown 单选下拉 popup。通常内部使用。
RenderMultiSelectDropdown class MultiSelectDropdown 多选下拉。
MultiSelectDropdownPopup class MultiSelectDropdown 多选 popup。通常内部使用。
RenderLookupEdit class LookupEdit 扁平表格查询选择。
RenderDropTreeEdit class DropTreeEdit 树形单选下拉。
RenderDropCheckTreeEdit class DropCheckTreeEdit 树形多选下拉。
RenderDropTreeGridEdit class DropTreeGridEdit 树表单选下拉。

常用关联类型和 helper：

  • DropdownOption
  • LookupEditColumn、LookupEditQueryProcessor、LookupEditDebugState
  • TreeNode、TreeSelectionMode
  • DropTreeEditQueryProcessor、defaultDropTreeEditQueryProcessor
  • DropCheckTreeEditQueryProcessor、DropCheckTreeEditSummaryBuilder
  • DropTreeGridEditQueryProcessor、defaultDropTreeGridEditQueryProcessor

选择器 popup 要跟随锚点、滚动和缩放。长文本选项优先通过 popup 宽度、tooltip、分行展示或表格列展示解决，不要把候选项裁到不可读。

数据组件

API 类型 详细文档 用途
RenderDataGrid class GridView 高性能数据表格、编辑、选择、排序、筛选。
RenderTreeView class TreeView 树形列表、勾选、单选和虚拟滚动。
RenderTreeGrid class TreeGrid 树形表格、多列树节点。
RenderTable class Table 静态表格展示。
RenderReportView class ReportView 通用虚拟报表 Canvas，负责冻结、选择、滚动、复制和尺寸调整。
RenderReportV3Workspace class ReportView Cell-first 报表设计工作台，包含设计、预览、资源、属性和校验区域。
RenderReportV3RuntimeSurface class ReportView 展示 v3 materializer 运行文档，并支持模板行列尺寸回写。
RenderListView class ListView 列表展示和选择。
RenderItemsControl class ItemsControl 通用 items 渲染、虚拟化列表和面板。
RenderEntryGrid class EntryGrid 表单式标签-字段-单位网格。
RenderFormPanel class EntryGrid 表单布局面板。
RenderFieldPresenter class EntryGrid 单个字段 label、内容、meta、校验展示。
RenderPagination class Pagination 分页条。

常用关联类型和 helper：

  • DataGridOptions、GridColumnDef、GridSelectionState、GridSortState、GridFilterRule
  • TreeNode、TreeCheckChange、TreeLabelToken
  • TreeGridNode、TreeGridOptions、TreeGridSelectionState
  • TableColumn、TableSortState
  • ReportTemplateV3、ReportValueFormatV3、ReportDatasetMap、ReportViewSharedOptions、ReportViewDebugState、ReportDrillthroughHandler
  • prepareReportTemplateV3ForPersistence()：模板压缩、JSON round-trip 与 compiler 保存门禁
  • ListViewItem
  • ItemsControlVirtualizationOptions、ItemsControlSelectionChange、ItemContainerStyleOverrides
  • EntryGridTrack、EntryGridChildData、fieldTrack()、labelTrack()、px()、fr()

大数据场景优先使用内置虚拟化能力。开发调试场景中，表格、树、对象查看器应支持复制当前选中值。

命令组件

API 类型 详细文档 用途
RenderCommandButton class CommandButton 单个命令按钮。
RenderCommandToolbar class CommandToolbar 从命令配置生成工具栏。
RenderToolbar class Toolbar 手工组合普通工具栏项、分组和溢出。
createCommandContextMenu() function Commands API 将命令菜单配置转换成右键菜单 entries。
createCommandMenuBarItems() function Commands API 将命令菜单配置转换成菜单栏 items。
executeCommandMenuSelection() function Commands API 执行命令菜单选中项。
resolveCommandMenuEntries() function Commands API 只解析命令菜单 entries，不打开菜单。

常用关联类型：

  • RenderCommandButtonOptions
  • RenderCommandToolbarOptions、CommandToolbarGroup、CommandToolbarItem
  • ToolbarGroup、ToolbarItem、ToolbarSlot
  • CommandMenuItem、CommandMenuCommandItem、CommandMenuSubmenuItem

页面按钮权限和 enabled 状态优先走命令系统，不要把同一套权限判断散落在按钮、菜单和快捷键里。

导航和工作区

API 类型 详细文档 用途
RenderMenuBar class MenuBar 顶部菜单栏。
RenderNavigationMenu class NavigationMenu 左侧导航、分组导航。
RenderBreadcrumb class Breadcrumb 面包屑导航。
RenderTabs class Tabs 标签页标题栏。
RenderTabControl class TabView 标签头加当前内容页的轻量组合控件。
RenderTabItem class TabView TabView 的单个内容页。
RenderTabbedWorkspace class TabbedWorkspace 多文档 tab 工作区。
TabbedDocumentManager class TabbedWorkspace tab 文档生命周期管理器。
RenderDockWorkspace class DockWorkspace 可停靠、拆分、浮动窗口工作区。
DockWindowManager class DockWorkspace dock 窗口记录和生命周期管理。
RenderWindow class DockWorkspace 窗口外壳。
RenderSplitter class Splitter 分割条。
RenderStatusBar class StatusBar 状态栏。

常用关联类型：

  • MenuBarItem
  • NavigationMenuEntry、NavigationMenuGroup、NavigationMenuItem
  • BreadcrumbItem
  • TabItem、TabContextMenuHandler、TabDragHandler
  • RenderTabControlOptions、RenderTabItemOptions
  • TabbedDocumentContext、TabbedDocumentContextAware
  • TabbedDocumentDefinition、TabbedDocumentPatch、TabbedDocumentRecord、TabbedDocumentLifecycle
  • DockDropZone、DockDropScope、DockDropTarget
  • DockLayoutNode、DockTabGroupNode、DockSplitNode
  • DockOpenWindowOptions、DockWindowRecord
  • StatusBarGroup、StatusBarItem

工作区对象通常是应用级能力。页面对象、页面上下文、页面命令和页面私有 app context 应随 tab 或窗口生命周期释放。

弹层和反馈

API 类型 详细文档 用途
ContextMenuManager class ContextMenu 右键菜单管理。
NotificationManager class Notification 通知消息。
TooltipManager class Popup tooltip 管理器。
TooltipService class Popup 全局 tooltip 服务入口。
TooltipTarget class Popup tooltip 目标封装。
RenderModal class Modal 模态弹窗。
RenderDrawer class Drawer 抽屉。
RenderPopover class Popover 锚点浮层。
PopoverPopup class Popover Popover popup 实现。
RenderLoadingHost class Loading 页面 loading 容器。
RenderLoadingModal class Loading loading 模态框。
RenderPromptModal class Prompt 输入确认弹窗。

常用关联类型：

  • ContextMenuEntry、ContextMenuItem、ContextMenuSeparator
  • NotificationType
  • TooltipContent、TooltipPresenter
  • ModalButton
  • DrawerSide
  • PopoverPlacement
  • RenderLoadingHostOptions、RenderLoadingModalOptions

弹层要明确调用者、锚点和释放边界。由页面打开的弹层应优先继承页面上下文；页面关闭时应关闭或释放页面拥有的弹层。

可视化、文档和开发工具

API 类型 详细文档 用途
RenderLineChart class LineChart 折线图。
RenderBarChart class BarChart 柱状图。
RenderDonutChart class DonutChart 环形图。
RenderSparkline class Sparkline 小型趋势图。
RenderChartRangeSlider class ChartRangeSlider 图表范围选择。
paintFramePerformanceTimelineChart() function PerformanceTimeline 运行时性能浮层时间线绘制。
RenderBarcode class Barcode / QRCode 条码、二维码绘制。
RenderImagePreview class ImagePreview 图片预览、占位和适配。
RenderMarkdownViewer class MarkdownViewer Markdown 文档阅读、目录、搜索、复制。
parseMarkdown() function MarkdownViewer Markdown 字符串解析为内部 AST。
parseInlines() function MarkdownViewer 解析一段行内 Markdown。
markdownDocumentToPlainText() function MarkdownViewer Markdown AST 转纯文本。
markdownBlocksToPlainText() function MarkdownViewer Markdown block 数组转纯文本。
markdownBlockToPlainText() function MarkdownViewer 单个 Markdown block 转纯文本。
markdownInlinesToPlainText() function MarkdownViewer Markdown inline 数组转纯文本。
collectMarkdownDocumentHeadings() function MarkdownViewer 从 Markdown 文档收集标题。
createMarkdownHeadingSlug() function MarkdownViewer 生成标题锚点 slug。
RenderPlainTextEditor class PlainTextEditor 高性能纯文本/代码编辑器。
RenderCodeEditor class CodeEditor 通用语言服务驱动的代码编辑器。
PlainTextEditorController class PlainTextEditor 纯文本编辑器控制器。
LineArrayTextDocument class PlainTextEditor 行数组文本模型。
FoldingModel class PlainTextEditor 折叠模型。
findJsonFoldRange() function PlainTextEditor JSON 风格折叠范围查找。
plainTextTokenizer object PlainTextEditor 纯文本 tokenizer。
jsonTextTokenizer object PlainTextEditor JSON tokenizer。
javascriptTextTokenizer object PlainTextEditor JavaScript / TypeScript tokenizer。
shellTextTokenizer object PlainTextEditor Shell tokenizer。
tokenizerForLanguage() function PlainTextEditor 根据语言 id 获取 tokenizer。
RenderObjectInspector class ObjectInspector 开发调试对象查看器。
RenderRuntimeDiagnosticsPanel class Runtime API 运行时诊断面板。
RenderRuntimeDiagnosticsSnapshotViewer class Runtime API 诊断快照查看器。
parseRuntimeDiagnosticsSnapshotJson() function Runtime API 解析诊断快照 JSON。
validateRuntimeDiagnosticsSnapshot() function Runtime API 校验诊断快照结构。

常用关联类型和 helper：

  • ChartSeries、BarChartSeries、DonutChartSegment、ChartAxisOptions、ChartDataState、ChartDomain、ChartAnnotation、RenderLineChartOptions、RenderChartRangeSliderOptions
  • resolveFramePerformanceTimelineChartState、FramePerformanceTimelineChartOptions、FramePerformanceTimelineChartDebugState
  • BarcodeOptions、BarcodeType、BarcodeMetrics
  • ImagePreviewSource、ImagePreviewFit、ImagePreviewShape、ImagePreviewLoadState、ImagePreviewDebugState
  • MarkdownDocument、MarkdownBlock、MarkdownInline、MarkdownParseOptions、MarkdownViewerDebugState、MarkdownSearchResult
  • TextDocumentModel、TextEditResult、TextPosition、TextRange、TextTokenizer、TextToken、PlainTextSearchMatch
  • ObjectInspectorOptions、ObjectInspectorDebugNode

图表用于业务数据展示；MarkdownViewer 用于文档中心；PlainTextEditor 用于大文本和代码类文本；ObjectInspector 和运行时诊断面板用于开发调试。

专业编辑器

API 类型 详细文档 用途
RenderMedicalRecordEditor class 病历编辑器集成 电子病历编辑、绘制、选区、数据元、留痕和批注。
MedicalRecordEditorController class 病历编辑器集成 病历编辑器外部控制器。

常用关联类型：

  • MedicalRecordDocument
  • MedicalRecordEditorControllerOptions
  • RenderMedicalRecordEditorOptions
  • MedicalRecordEditorDebugState
  • MedicalRecordToolbarState

病历编辑器是复杂专业组件。业务应通过 controller、document、view options 和命令入口控制功能，不建议依赖内部 render tree 或私有医学编辑器实现对象。

使用边界

  • 组件文档说明控件用法；公共 API 的完整导出边界见 公共 API 索引。
  • 复杂业务状态和权限应通过 App Context 和 命令与权限 注入，不要让组件持有全局业务单例。
  • 大数据控件应优先关注虚拟化、滚动边界、复制和调试可见性。
  • 页面只组合组件，不复制组件内部 hover、focus、scroll、tooltip、selection 逻辑。
  • 未导出的内部 helper、demo 页面类和测试工具不是公共 API。