DirectSurface UIDirectSurface UI
开始使用
文档/开始使用

创建第一个页面

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

选择页面基类

框架公共 API 提供 RenderPage 作为页面容器。页面内部继续组合布局和组件。

import { RenderPage, RenderStackPanel } from 'ds-ui' export class OrderPage extends RenderPage {  constructor() {    const content = new RenderStackPanel({      orientation: 'vertical',      spacing: 8,      crossAxisAlignment: 'stretch',    })     super({ child: content })  }}

业务项目可以按自己的工程需要封装 BusinessDocumentPage，例如统一页面 padding、滚动、日志、命令作用域和局部上下文。这样的业务基类属于应用自身，不属于 ds-ui 公共 API：

import { RenderPage, RenderStackPanel } from 'ds-ui' export class BusinessDocumentPage extends RenderPage {  protected readonly content: RenderStackPanel   constructor() {    const content = new RenderStackPanel({      orientation: 'vertical',      spacing: 8,      crossAxisAlignment: 'stretch',    })    super({ child: content })    this.content = content  }}

使用布局组件

常见页面结构：

const root = new RenderStackPanel({  orientation: 'vertical',  spacing: 8,  crossAxisAlignment: 'stretch',}) root.addChild(header)root.addChild(toolbar)root.addChild(content, 1)

如果需要左右结构：

const body = new RenderDockPanel()leftPanel.width = 260body.addChild(leftPanel, { dock: 'left' })body.setFill(rightPanel)

布局组件只表达结构，不处理业务动作。查询区、工具栏、主内容、详情区应先分清滚动所有者，再决定是否使用 ScrollViewer、GridView、TreeView 或其他自带滚动的复杂组件。

添加组件

const query = new RenderTextBox({  placeholder: '输入关键字',  onChange: value => {    // 更新查询条件  },}) const button = new RenderButton({  label: '查询',  onClick: () => {    // 执行业务查询  },})

常见页面控件选择：

场景 推荐组件 文档
单行输入 RenderTextBox TextField
多行输入 RenderTextArea TextArea
数字输入 RenderNumberInput NumberInput
日期时间 RenderDatePicker DatePicker
单选枚举 RenderComboBox Dropdown
表格数据 RenderDataGrid GridView
树形数据 RenderTreeView TreeView

注册页面

在模块注册表中增加页面入口，让菜单可以打开该页面。

const orderModule = {  key: 'order',  title: '订单',  load: async () => OrderPage,}

注册方式由业务应用决定。框架只提供 render tree、工作区、窗口、命令和上下文能力；路由表、菜单权限、模块懒加载和页面缓存策略属于业务应用层。

页面上下文和命令

复杂页面通常需要页面级上下文和页面级命令：

  • 页面级上下文保存当前业务对象、页面参数、controller 和页面级缓存。
  • 页面级命令统一保存、刷新、删除、提交等动作。
  • 页面关闭时，页面 scope 应自动释放命令、上下文、订阅和弹窗。

这部分不要写成全局单例。详见 应用上下文、命令与权限 和 页面上下文与生命周期。

写测试

页面测试重点验证组合、事件和状态，而不是重复测试基础组件。

it('opens order page', () => {  const page = new OrderPage()  page.layout({ minWidth: 0, maxWidth: 980, minHeight: 0, maxHeight: 720 })})

页面开发检查表

  • 页面是否只组合已有组件。
  • 可复用页面片段是否由公共组件组合，并收敛在业务项目自己的共享模块中。
  • 关键交互是否有测试。
  • 弹窗、上下文、命令是否随页面生命周期释放。
  • 大数据场景是否使用虚拟化。

下一步