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 组合，不要绕过控制器直接操作内部对象。

值编辑与表单接入

内置表单编辑器通过结构化 ValueEditor<TValue> 契约提供静默值写入、用户值变化、整体失焦和焦点请求。页面用显式绑定连接编辑器和 FormSession，框架不会扫描组件树或根据嵌套层级猜测字段。

API 类型 用途
ValueEditor interface 值编辑器最小结构契约。
FormBindingBag class 批量持有字段绑定并统一释放。
bindFormField() function 绑定一个字段、编辑器和可选字段 presenter。
ValueEditorEventEmitter class 为自定义编辑器实现多订阅值变化和失焦事件。
createValueEditorAdapter() function 不修改原组件继承关系，把已有控件适配为 ValueEditor。

commitEdit()、cancelEdit()、clear()、readonly、status 和 helperText 是按组件实际能力提供的可选契约。提交前暂存输入、关联字段回填、自定义适配和生命周期见编辑器契约与表单字段绑定。

基础显示

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 单行文本输入。
RenderButtonEdit class ButtonEdit 带一个或多个尾部动作按钮的文本输入。
RenderMaskedTextEdit class MaskedTextEdit 按固定 mask 录入并显示格式化文本。
MaskEngine class MaskedTextEdit 可独立使用的 mask 解析、格式化和编辑引擎。
RenderPasswordField class TextField 密码输入。
RenderSearchBox class TextField 搜索输入，支持搜索事件和清除。
RenderTextArea class TextArea 多行文本输入、批注内容等。
RenderNumberInput class NumberInput 数字输入。
RenderDatePicker class DatePicker 日期、日期时间输入。
DatePickerPopup class DatePicker 日期悬浮选择面板。通常由 RenderDatePicker 内部使用。
RenderTimeEdit class TimeEdit 不附带日期和时区的时刻输入。
RenderDateRangeEdit class DateRangeEdit 起止日历日期范围输入。
DateRangePickerPopup class DateRangeEdit 日期范围悬浮选择面板。通常由 RenderDateRangeEdit 内部使用。
RenderTimeSpanEdit class TimeSpanEdit 可超过 24 小时并可选支持负值的持续时长输入。
RenderUpload class Upload 文件选择、校验、上传进度、取消和重试。
BrowserFilePickerBridge class Upload 浏览器原生文件选择器适配器。
browserFilePicker instance Upload 默认浏览器文件选择桥实例。
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 内部使用。

常用关联类型和 helper：

  • FormFieldStatus
  • TextBoxAction、TextBoxEditContext、TextBoxEditResult、TextBoxEditSource、TextBoxInputAdapter、TextBoxValueChangeReason、TextAreaValueChangeReason
  • ButtonEditButton、RenderButtonEditOptions
  • RenderMaskedTextEditOptions、MaskEditResult、MaskTokenDefinition、MaskTokenDefinitions、MaskValue
  • RadioOption
  • CalendarTime、CalendarTimePrecision、ISODate
  • NumberInputValueChangeReason、NumberInputValueChangeDetail
  • DatePickerValueChangeReason、DatePickerValueChangeDetail
  • TimeEditOptions、TimePrecision、TimeParts、TimeSegment、TimeEditValueChangeReason、TimeEditValueChangeDetail
  • DateRangeEditOptions、DateRangeValue、DateRangeEditValueChangeReason、DateRangeEditValueChangeDetail
  • TimeSpanEditOptions、TimeSpanPrecision、TimeSpanParts、TimeSpanSegment、TimeSpanValueOptions、TimeSpanEditValueChangeReason、TimeSpanEditValueChangeDetail
  • CheckboxValueChangeReason、SwitchValueChangeReason、RadioGroupValueChangeReason
  • SliderValueChangeReason、SegmentedControlValueChangeReason、ColorPickerValueChangeReason
  • RenderUploadOptions、UploadFileItem、UploadFileRejection、UploadFileStatus、UploadHandler、UploadProgressContext
  • FilePickerBridge、FilePickerOptions、fileMatchesAccept、formatFileSize
  • parseTimeValue、formatTimeValue、normalizeTimeValue、normalizeTimeParts、stepTimePart、timeValueToSeconds
  • composeTimeSpanValue、decomposeTimeSpanValue、formatTimeSpanValue、normalizeTimeSpanValue、stepTimeSpanValue
  • normalizeDateRangeValue
  • SegmentedControlOption

输入组件只负责编辑值和基础交互。业务校验建议通过 FormSession 和显式字段绑定投影到 status、helperText 或 RenderFieldPresenter，不要把保存逻辑写入底层控件。

选择器

API 类型 详细文档 用途
RenderComboBox class Dropdown 单选枚举下拉。
DropdownPopup class Dropdown 单选下拉 popup。通常内部使用。
RenderMultiSelectDropdown class MultiSelectDropdown 多选下拉。
MultiSelectDropdownPopup class MultiSelectDropdown 多选 popup。通常内部使用。
RenderCheckedComboBox class CheckedComboBox 使用摘要触发字段的高密度多选组合框。
RenderTokenEdit class TokenEdit 支持候选项和自由文本的标签输入。
RenderLookupEdit class LookupEdit 扁平表格查询选择。
RenderDropTreeEdit class DropTreeEdit 树形单选下拉。
RenderDropCheckTreeEdit class DropCheckTreeEdit 树形多选下拉。
RenderDropTreeGridEdit class DropTreeGridEdit 树表单选下拉。

常用关联类型和 helper：

  • DropdownOption、ComboBoxValueChangeReason、RenderMultiSelectDropdownOptions、MultiSelectDropdownDisplayMode、MultiSelectDropdownValueChangeReason
  • RenderCheckedComboBoxOptions
  • RenderTokenEditOptions、TokenEditOption、TokenEditToken、TokenEditValueChangeReason
  • LookupEditColumn、LookupEditQueryProcessor、LookupEditDebugState、LookupEditValueChangeReason
  • TreeNode、TreeSelectionMode
  • DropTreeEditQueryProcessor、defaultDropTreeEditQueryProcessor、DropTreeEditValueChangeReason
  • DropCheckTreeEditQueryProcessor、DropCheckTreeEditSummaryBuilder、DropCheckTreeEditValueChangeReason
  • DropTreeGridEditQueryProcessor、defaultDropTreeGridEditQueryProcessor、DropTreeGridEditValueChangeReason

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

数据组件

API 类型 详细文档 用途
RenderDataGrid class GridView 高性能数据表格、编辑、选择、排序、筛选。
DataGridEditSession class 编辑会话 跟踪 DataGrid 的新增、修改、删除、dirty 和恢复。
bindDataGridToForm() function 表单校验与提交 把 DataGrid 的编辑和校验接入一个 FormSession。
RenderTreeView class TreeView 树形列表、勾选、单选和虚拟滚动。
RenderTreeGrid class TreeGrid 树形表格、多列树节点。
RenderTable class Table 静态表格展示。
RenderReportView class ReportView 通用虚拟报表 Canvas，负责冻结、选择、滚动、复制和尺寸调整。
RenderReportV3Workspace class ReportView Cell-first 报表设计工作台，包含设计、预览、资源、属性和校验区域。
RenderReportV3RuntimeSurface class ReportView 展示 v3 materializer 运行文档，并支持模板行列尺寸回写。
RenderScheduler class Scheduler 默认只读的 Day、Week、Month 和 Agenda 资源日程，以及 opt-in 本地 CRUD、Event Editor、Day/Week 空白创建与 timed Event 移动/资源重分配。
RenderListView class ListView 列表展示和选择。
RenderItemsControl class ItemsControl 通用 items 渲染、虚拟化列表和面板。
RenderEntryGrid class EntryGrid 表单式标签-字段-单位网格。
RenderFormPanel class EntryGrid 表单布局面板。
RenderFieldPresenter class EntryGrid 单个字段 label、内容、meta、校验展示。
RenderPagination class Pagination 分页条。

常用关联类型和 helper：

  • DataGridOptions、GridEditorValidationMessages、GridColumnDef、GridColumnDate、GridColumnTime、GridColumnEditorDate、GridColumnEditorTime
  • DEFAULT_GRID_EDITOR_VALIDATION_MESSAGES
  • DataGridEditSessionOptions、DataGridChangeSet、DataGridRowEditState、DataGridFormBindingOptions
  • GridDataChangeEvent、GridDataChangeOrigin、GridDataMutationOptions
  • GridSelectionState、GridSortState、GridFilterRule
  • TreeNode、TreeCheckChange、TreeLabelToken
  • TreeGridNode、TreeGridOptions、TreeGridSelectionState
  • TableColumn、TableSortState
  • ReportTemplateV3、ReportValueFormatV3、ReportDatasetMap、ReportViewSharedOptions、ReportViewDebugState、ReportDrillthroughHandler
  • prepareReportTemplateV3ForPersistence()：模板压缩、JSON round-trip 与 compiler 保存门禁
  • RenderSchedulerConfigurationError、RenderSchedulerOptions、RenderSchedulerDebugState、SchedulerKey、SchedulerVersion、SchedulerInstantRange、SchedulerAllDayRange、SchedulerEventTime、SchedulerWallDateTime、SchedulerTimeDisambiguation、SchedulerOccurrenceIdentity、SchedulerRecurrenceDefinition
  • SchedulerDataSnapshot、SchedulerEvent、SchedulerResource、SchedulerAssignment、SchedulerTimeRangeKind、SchedulerTimeRange、SchedulerTimelineView、SchedulerView、SchedulerZoomPreset、SchedulerScrollAlignment、SchedulerStatus、SchedulerHeaderFormatter、SchedulerReadonlyItem、SchedulerSetDataOptions
  • SchedulerEventDraft、SchedulerUpdateEventCommand、SchedulerMutationResult、SchedulerDataChange、SchedulerProposedDataChange、SchedulerBeforeDataChangeEvent、SchedulerDataChangeDescriptor、SchedulerDataAction、SchedulerDataChangeKind、SchedulerDataGesture、SchedulerDataChangeSource、SchedulerDataChangeRejection、SchedulerChangedEvent、SchedulerChangedAssignment、SchedulerCreateEventContext
  • SchedulerInteractionSource、SchedulerInteractionRejection、SchedulerCancelableInteractionEvent、SchedulerSelectionChangeReason、SchedulerSelectionChangeDescriptor、SchedulerBeforeSelectionChangeEvent、SchedulerSelectionChangeEvent
  • SchedulerEventActivationSurface、SchedulerEventActivateDescriptor、SchedulerBeforeEventActivateEvent、SchedulerEventActivateEvent、SchedulerViewChangeDescriptor、SchedulerBeforeViewChangeEvent、SchedulerViewChangeEvent、SchedulerZoomChangeDescriptor、SchedulerBeforeZoomChangeEvent、SchedulerZoomChangeEvent
  • SchedulerNavigationRequest、SchedulerNavigateDescriptor、SchedulerBeforeNavigateEvent、SchedulerNavigateEvent、SchedulerViewport、SchedulerViewportChangeEvent
  • 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。