GridView 数据表格

通用布局能力：DataGridOptions 继承 RenderBoxOptions，表格可直接配置 width、height、min/max、margin 和槽位对齐，也可在创建后赋值；这些属性不再由 GridView 维护第二套状态。详见组件通用布局属性。

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

何时使用

• 需要展示二维表格数据，并支持行选择、单元格选择或范围选择。
• 需要可编辑单元格、下拉编辑、日期编辑、树形下拉、树表下拉或校验。
• 需要排序、过滤、快速过滤、分组、汇总和列菜单。
• 需要固定列、拖拽调整列宽、列顺序调整、列显示状态持久化。
• 需要在大量数据下保持可视行绘制和滚动性能。

何时不要使用

• 只展示少量静态表格，优先使用 Table。
• 数据有父子层级并且要在表格中展开折叠，优先使用 TreeGrid。
• 只需要键值型表单布局，优先使用 EntryGrid 或 FormPanel。
• 单列列表、菜单或卡片列表，优先使用 ListView 或 ItemsControl。

API 总览

主类：

• RenderDataGrid<T extends Record<string, any>>

核心配置类型：

• DataGridOptions<T>
• GridColumnDef<T>
• GridColumnEditorDef<T>
• GridSelectionState<T>
• GridSelectionChangeEvent<T>
• GridSelectionOptions
• GridViewPreset

常用辅助类型：

• GridColumnBase
• GridColumnText
• GridColumnNumber
• GridColumnCheckbox
• GridColumnSelect
• GridColumnSelectGrid
• GridColumnDate
• GridColumnCustom
• GridSortDescriptor
• GridFilterRule
• GridGroupDef
• GridSummaryDef
• GridColumnState
• GridColumnFilterState
• GridCellValidationArgs
• GridCellValidationResult
• GridRowValidationArgs
• GridRowValidationResult
• GridValidationResult
• GridRowStyleArgs
• GridCellStyleArgs
• GridCellDisplayTextArgs
• GridCellContext<T>
• GridCellEditPolicy
• GridCellEditState

这些类型都从 ds-ui 包入口导出。

最小示例

import { RenderDataGrid, type GridColumnDef } from 'ds-ui' interface PatientRow {  id: string  name: string  gender: string  age: number} const columns: GridColumnDef<PatientRow>[] = [  { key: 'name', title: '姓名', type: 'text', width: 120, sortable: true, filterable: true },  { key: 'gender', title: '性别', type: 'select', width: 80, sortable: true, filterable: true, options: [    { value: 'M', label: '男' },    { value: 'F', label: '女' },  ] },  { key: 'age', title: '年龄', type: 'number', width: 80, align: 'right', sortable: true, filterable: true },] const grid = new RenderDataGrid<PatientRow>({  rowKey: 'id',  columns,  rows: [    { id: 'p1', name: '李安然', gender: 'F', age: 36 },  ],  selectionMode: 'row',  sortable: true,  editable: true,  onCellChange: (row, key, value) => {    ;(row as any)[key] = value  },})

构造参数

new RenderDataGrid<T>(options: DataGridOptions<T>)

列配置

所有列共享 GridColumnBase 字段：

列类型：

左、右固定列与普通滚动列之间会持续绘制强分隔线和轻阴影。横向滚动使内容进入固定区域下方时，对应方向的阴影会自动增强；滚动到边缘后恢复为轻阴影。该视觉覆盖表头、过滤行、数据区和汇总区，不需要额外配置。

编辑器配置

GridColumnEditorDef 用于覆盖列的默认编辑器。

编辑流程：

1. 鼠标双击、键盘编辑或 API 调用 beginEdit() 进入编辑。
2. 输入控件修改临时文本或临时值。
3. commitEdit() 或编辑器确认时触发校验。
4. 校验通过后触发 onCellChange(row, key, value)。
5. 业务代码在 onCellChange 中更新源对象或外部状态。

数字步进

number 编辑器在当前单元格进入编辑状态后显示上下步进按钮。步进只更新当前编辑草稿，仍然在 Enter、Tab、失焦或显式 commitEdit() 时统一校验和提交，不会在每次点击按钮时直接触发 onCellChange。

interface OrderRow {  dose: number} const columns: GridColumnDef<OrderRow>[] = [  {    key: 'dose',    title: '剂量',    type: 'number',    min: 0,    max: 100,    step: 0.5,    decimals: 1,  },]

• 点击上、下按钮分别增加或减少一个 step；step 只有在有限且大于 0 时生效，否则统一按 1 处理。配置 decimals 后，step 会先对齐到相同的小数精度；如果结果为 0，则使用一个最小显示单位（10^-decimals），保证每次点击都能产生可见且可逆的变化。
• decimals 会先截断为整数，再限制在 0 到 100；非有限值按未配置处理。min、max 也只接受有限值，非有限边界会被忽略；当同时配置且 min > max 时，这组冲突边界不会参与归一化。
• 按钮步进和最终提交共用同一套数值归一化。命中或越过有效的 min、max 时，边界值本身是稳定结果；其余数值先按 decimals 取小数位，再限制到有效边界内。即使边界无法用指定小数位精确表示，按钮显示的草稿在提交时也不会再次变成另一个值。
• 一次按压只属于发起它的指针和当时的编辑会话。只有同一指针在同一会话、同一按钮内完成释放才会步进；在原按钮外释放、滚动表格、取消指针或切换编辑会话都不会修改草稿。
• 连续快速点击步进按钮只按点击次数步进，不会触发单元格双击编辑，也不会因单元格双击逻辑重新全选输入文本；步进后光标位于新文本末尾。
• 数字编辑状态下，ArrowUp、ArrowDown 与按钮行为一致；非编辑状态下仍用于表格行导航。
• 空草稿从 0 开始步进，再应用小数位和边界；当前文本不是完整有效数字时不会执行步进，也不会覆盖用户正在修正的内容。
• 有效小数步进使用十进制定点加减，避免 0.2 + 0.1 一类常见浮点残差。
• 数字步进不响应鼠标滚轮，避免滚动表格时意外修改业务数据。

输入校验

Grid 校验只负责输入值是否合法，不负责业务提交、后台保存或服务端状态。

• number 编辑器会拒绝 12abc、NaN、Infinity 等非完整有限数字，不会截取数字前缀或静默写回旧值。
• date 编辑器会拒绝无法解析或不存在的 ISO 日期。
• validateCell 负责单字段规则，在单元格提交、程序化 setCellValue() 和全表 validate() 时执行。
• validateRow 负责同一行字段之间的关联规则，只在显式调用 validate() 时执行。返回对象的 key 必须对应列 key，错误会显示在对应单元格。
• GridRowValidationArgs.sourceRowIndex 是该行在原始 rows 数组中的索引，不是排序、过滤或分组后的可视索引；业务身份优先使用 row 或 rowId。
• validate() 会先尝试提交活动编辑器，然后验证全部源数据行和全部列，包括被筛选掉的行与隐藏列；不会修改合法数据。
• 校验错误沿用单元格错误边框，hover 显示错误文本。focusFirstError() 只定位当前可见且列未隐藏的第一个错误。

import { RenderDataGrid, type GridColumnDef } from 'ds-ui' interface OrderRow {  itemCode: string  amount: number  unitCode: string} const columns: GridColumnDef<OrderRow>[] = [  { key: 'itemCode', title: '项目', type: 'text', editable: true },  { key: 'amount', title: '数量', type: 'number', editable: true },  { key: 'unitCode', title: '单位', type: 'text', editable: true },]const rows: OrderRow[] = [] const grid = new RenderDataGrid<OrderRow>({  columns,  rows,  validateCell: ({ key, value }) => {    if (key === 'itemCode' && !value) return '请选择项目'    return true  },  validateRow: ({ row }) => {    if (row.amount > 0 && !row.unitCode) {      return { unitCode: '请输入单位' }    }    return undefined  },}) const result = grid.validate()if (!result.valid) grid.focusFirstError()

GridValidationResult<T> 返回 { valid, errors }；errors 与 getCellErrors() 使用同一个 GridCellErrorState<T>[] 数据源。

逐单元格编辑策略

列的 editor 和 key 仍然固定；需要让同一列在不同行具有不同权限时，使用 resolveCellEditPolicy，不要动态切换编辑器或字段绑定。

import { RenderDataGrid, type GridColumnDef } from 'ds-ui' interface OrderRow {  itemCode: string  dose: number  approved: boolean  orderType: 'drug' | 'service'} const columns: GridColumnDef<OrderRow>[] = [  { key: 'itemCode', title: '医嘱项目', type: 'text' },  { key: 'dose', title: '剂量', type: 'number' },]const rows: OrderRow[] = [] const grid = new RenderDataGrid<OrderRow>({  columns,  rows,  editable: true,  resolveCellEditPolicy: ({ row, column }) => {    if (row.approved) {      return {        state: 'readonly',        reason: '医嘱已审核，不能再修改',      }    }    if (column.key === 'dose' && row.orderType !== 'drug') {      return {        state: 'disabled',        reason: '非药品医嘱不使用剂量',      }    }    return { state: 'inherit' }  },})

GridCellContext<T> 包含 row、可视 rowIndex、column、可视 columnIndex 和当前 value。GridCellEditPolicy 字段：

• readonly 保持正常阅读、焦点、选择和复制能力，但不会启动编辑器。
• disabled 使用弱化视觉，默认从 Tab 路径跳过；显式设置 tabStop:true 可让它参与导航。
• 未配置 resolver 时，editable:false 和没有有效 editor 的列继续从默认 Tab 编辑路径跳过；需要让这类列参与导航时，显式返回 state:'readonly', tabStop:true。
• 策略覆盖鼠标、Enter/F2/Space、checkbox、弹出编辑器、粘贴和编辑中的提交；策略运行时变化为不可编辑时，当前编辑会取消而不写回。
• Grid 的 disabled、readonly、editable:false 和列的 editable:false 是最终边界，回调不能把这些边界重新提升为 editable。
• setCellValue() 是程序化数据 API，不受逐单元格用户编辑策略阻断，仍会执行标准化和校验。

Lookup 感知当前单元格

Grid 列的 lookup.queryProcessor 除了查询选项，还会收到 context.cell。可用它根据当前医嘱行过滤候选项，而不需要为每一行创建不同编辑器：

import type { GridLookupQueryProcessor } from 'ds-ui' interface OrderRow {  orderType: 'drug' | 'service'  itemCode: string} interface OrderOption {  code: string  name: string  orderType: OrderRow['orderType']} const queryProcessor: GridLookupQueryProcessor<OrderOption, OrderRow> = context => ({  rows: context.rows.filter(option =>    option.orderType === context.cell.row.orderType &&    String(option.name).includes(context.query)  ),})

cell 在 popup 打开和每次搜索时均指向外层 Grid 单元格；它不是下拉候选行。列声明为 GridColumnDef<Row> 时，内联 queryProcessor 的 context.cell.row 会沿用该 Row 类型；单独复用处理器时可显式声明 GridLookupQueryProcessor<Option, Row>。

排序、过滤、分组和汇总

排序

GridSortDescriptor：

sortState 是兼容单列排序状态，sort 是当前多列排序描述。业务优先使用 sort。

过滤

GridFilterRule：

GridFilterOperator 支持：

• contains
• equals
• startsWith
• endsWith
• gt
• gte
• lt
• lte
• between
• empty
• notEmpty
• in
• notIn

默认交互采用表头下拉筛选：将列设置为 filterable:true 后，表头右侧显示下拉图标。点击图标或在当前列按 Alt+ArrowDown 打开弹窗。

• “值筛选”列出当前列的唯一值、搜索和全选状态；选项保留原始数据值，显示文本沿用列编辑器的 label 解析。候选项计数不一致时显示计数，全部一致时自动隐藏低信息量的计数列。
• 数组和普通对象等复杂候选值按稳定的结构语义去重和匹配，不受对象属性声明顺序影响；循环引用等不可序列化值退回同一对象实例语义。
• “条件筛选”提供文本、数值、日期等列适用的操作符。
• 弹窗中的修改是草稿，只有“确定”或在输入区按 Enter 才提交；“取消”、Escape 和点击外部均放弃草稿。
• Tab / Shift+Tab 在清除动作、筛选页签、输入区、值列表、条件操作符和底部按钮之间循环；页签和操作符支持方向键，Enter / Space 激活当前动作。
• 唯一值默认最多收集 10,000 项；超过限制时搜索仅覆盖已加载项。此时从默认全选状态取消值会生成 notIn 规则，未展示的值仍保持包含。
• 已生效的列显示筛选图标，弹窗打开时表头入口保持选中反馈。
• 筛选弹窗的间距、控件高度、列表行高、按钮尺寸和视口边距跟随主题密度，并复用 popup、输入框、复选框与滚动条的明暗主题状态样式。
• 筛选弹窗使用独立于列宽的首选宽度和最大宽度；宽列不会把弹窗横向拉伸，弹窗右侧与表头筛选入口保持对齐。
• 值筛选会按初始候选数量收缩高度，超过 6 个可见行后再启用滚动；搜索过程中高度保持稳定。条件筛选使用独立的紧凑高度，切换操作符时不会上下抖动。
• 弹窗优先在表头下方打开；下方能容纳基本操作区时会在下方压缩列表高度，否则紧贴表头上方打开，并按该方向的可用空间限制高度。
• readonly:true 只禁止数据修改，仍允许排序和筛选等数据视图操作；disabled:true 会关闭并阻止筛选弹窗交互。

过滤仍保留两套数据入口：

• filters：表头弹窗使用的结构化规则，也适合业务持久化。
• columnFilters：可选过滤行的文本值，适合需要始终可见的简单输入式过滤。通过 filterRowVisible:true 显式启用；不建议作为默认视觉方案。

快速过滤

quickFilter 会在数据模型中执行全局文本匹配。大数据场景中，不要在每次输入时同步构造新 rows，应通过防抖后设置 grid.quickFilter 或 grid.setQuickFilter()。

分组

GridGroupDef<T>：

分组列头使用 G1、G2 等徽标明确标识分组层级；该徽标不是排序优先级或筛选数量。分组行不是源数据行，事件和选择只会把数据行转换为业务行。

汇总

GridSummaryDef<T>：

可读写属性

disabled、readonly、editable、resizableColumns、autoFitColumns、rangeSelectionAutoScroll、sortable 可以在运行时直接修改。setter 会同步清理不再合法的临时状态：例如关闭编辑会取消当前编辑，关闭列宽调整会取消 resize，关闭排序会清空当前排序，禁用组件会关闭自身 popup 并释放焦点。

运行时设置 rowHeight 或 headerHeight 会转为显式尺寸，并触发布局、滚动范围和编辑器几何同步；后续主题切换不会覆盖显式值。

替换 grid.rows 表示重新绑定数据源。GridView 会结束当前编辑并关闭自身 popup；未配置 rowKey 时会清空选择、焦点、悬停和校验错误。配置 rowKey 时，选择和校验错误会按行 id 尝试恢复，但编辑状态仍会结束。

方法

编辑

beginEdit() 只定位当前排序、过滤和分组投影中的可视数据行。目标行被过滤排除、目标列被隐藏或当前编辑策略不允许编辑时返回 false，不会自动清除筛选条件。自动定位只保证纵向行可见，不改变横向滚动位置。

过滤和搜索

分组

选择和定位

GridSelectionOptions：

数据行

列状态

焦点、复制和调试

事件与回调

GridRowEvent<T> 字段：

选择模型

selectionMode 支持：

• row：行选择。适合查询列表和主从页面。
• cell：单元格选择。适合轻量编辑表。
• range：范围选择。适合复制、批量编辑和表格型录入。

GridSelectionState<T> 字段：

键盘、鼠标和复制行为

• 鼠标点击数据行会更新焦点、当前行和选择状态。
• 鼠标双击数据行会触发 onRowActivate；单击只触发 onRowClick。表格不可编辑时，按 Enter 也会激活当前行。
• 拖拽列边界可调整列宽，前提是 resizableColumns=true。指针进入可调整边界时显示 col-resize 光标和弱预览线；按下拖动后使用更强的贯穿式指示线，离开、取消、禁用或释放能力时会清理反馈。
• 双击列边界可自动适配列宽，前提是 autoFitColumns=true。
• 表头右键或列菜单入口可打开列菜单。
• 鼠标滚轮滚动可视行，不会重建所有行对象。
• 选择文本溢出的单元格时，hover 会显示完整文本 tooltip。
• getCopyText() 返回当前选择对应的文本，供框架剪贴板逻辑使用。
• 编辑状态下键盘优先交给内置编辑器；非编辑状态下键盘用于选择和导航。
• 数字编辑状态下，上下方向键执行 step 步进；结束编辑后恢复为上下行导航。
• Popup 打开时，键盘优先交给 PopupManager 处理。

状态表现

dataState 为 ready 时显示数据。其他状态：

• loading：显示加载提示。
• empty：显示空数据提示。即使 dataState='ready'，可视行数为 0 时也会表现为空。
• error：显示错误提示。

状态文本由 stateMessage 控制。非 ready 且鼠标在主体区域时，主体交互会被忽略，避免在无数据状态下选中旧行。

整体状态：

• disabled=true：使用弱化遮罩表达不可操作状态，不显示 hover/focus，且不响应滚动、选择、复制、菜单或编辑。
• readonly=true：保持正常可读视觉和选择反馈；允许复制、滚动、排序、过滤和分组展开，但不允许修改业务数据。
• editable=false：只关闭单元格与结构编辑，不等价于整体禁用。
• 逐单元格 disabled 会弱化该单元格，readonly 保持普通可读外观；两者都允许鼠标选择，原因可通过 tooltip 查看。

样式和显示文本

GridRowStyleArgs<T> 包含 row、rowId、theme、backgroundColor、selected、hovered、focused 和 editing。其中 backgroundColor 是进入业务回调前已经解析出的当前状态背景；GridCellStyleArgs<T> 会把它更新为当前单元格实际使用的基础背景，并额外提供 value、column 和 error。

自定义列的 renderColor(value, row, context) 使用同一个 GridCellStyleArgs<T> 上下文。旧的两参数回调仍兼容；需要跨明暗主题和选中态保持可读时，应根据 context.theme 与 context.backgroundColor 解析颜色。

resolveRowStyle(args) 可返回：

resolveCellStyle(args) 额外支持：

getCellDisplayText(args) 用于控制显示文本，不改变源数据值。典型场景：

• 枚举值显示成中文。
• 金额格式化。
• 日期格式化。
• 根据错误状态显示特殊文本。

持久化视图状态

使用 getViewPreset() 和 applyViewPreset() 可以保存和恢复：

• 列宽。
• 列顺序。
• 列隐藏。
• 固定列位置。
• 列宽模式。
• 排序。
• 结构化过滤。
• 过滤行文本。
• 快速过滤。

示例：

import type { RenderDataGrid } from 'ds-ui' declare const grid: RenderDataGrid<any> const preset = grid.getViewPreset()localStorage.setItem('patient-grid', JSON.stringify(preset)) const saved = localStorage.getItem('patient-grid')if (saved) {  grid.applyViewPreset(JSON.parse(saved))}

性能原则

• rows 应尽量保持业务对象稳定。只变更某一行时优先修改对象后调用 refreshRow(row)。
• 每个 GridView 实例会按 Lookup 列维护独立的 valueKey → row 索引。绘制、悬停、复制、筛选和分组只查询索引，不会在交互热路径反复扫描完整候选数组。
• 替换 Lookup 的 rows 引用、改变候选数量或替换列配置时索引会自动重建。同一数组保持相同长度但原地修改候选键时，调用 refreshLookup(columnKey) 明确刷新索引。
• Lookup 索引只负责已选值的显示解析；queryProcessor 仍决定 popup 中本次查询的候选结果、顺序和数量。
• 大数据下不要每次 hover、输入或滚动都重建 columns 和 rows 数组。
• autoFitColumns 和 widthMode:'autoContent' 会测量文本。组件内部有采样限制，但仍不应在高频路径反复触发。
• getCellDisplayText、resolveRowStyle、resolveCellStyle、resolveCellEditPolicy 会在绘制可视单元格时调用，逻辑必须轻量，不要访问网络或做大对象遍历。
• 过滤和排序在数据模型层执行。几十万行场景应在业务层考虑分页、服务端查询或防抖。
• 固定列会增加绘制分区，但仍只绘制可视行。

当前限制

• 排序、过滤、分组和汇总均在客户端数据模型中执行。几十万行或远程数据源应由业务层提供分页、服务端查询和防抖，不应一次传入全部数据。
• 虚拟化使用统一 rowHeight，当前不支持按行动态高度、合并单元格或跨行布局。
• GridColumnCustom 主要用于自定义显示；需要完整自定义交互或层级行时，应分别使用显式 editor 或 TreeGrid。
• 只读状态面向交互约束；业务代码仍可通过 setCellValue()、替换 rows 等公开 API 主动更新数据。

常见组合

• 查询表单 + GridView：查询条件放在 TextField、Dropdown、DatePicker 等组件中，查询后替换 rows。
• GridView + 命令按钮：使用 CommandButton 或 CommandToolbar 控制新增、删除、导出、刷新。
• GridView + 弹窗编辑：行点击后打开 Modal、Drawer 或 Popup 编辑详细信息。
• GridView + TreeGrid：普通列表用 GridView，有层级关系时用 TreeGrid。

相关组件

• TreeGrid 树表：层级数据表格。
• Table 静态表格：少量静态数据展示。
• EntryGrid 键值表格：表单型键值布局。
• ListView 列表：单列列表和选择。
• LookupEdit 查询选择：独立查询选择组件。
• DropTreeGridEdit 树表下拉：树表弹出选择。
• CommandToolbar 命令工具栏：表格上方操作区。
• Runtime Diagnostics：调试绘制、布局和事件。