SxDataGrid UI 设计规范

自动生成时间: 2026-02-04 组件路径: src/NextUI.Blazor/Components/DataGrid/SxDataGrid.razor

1. 组件概述

  • 组件包含 5 个参数，0 个回调，5 个公开方法。
  • 内部组合组件：SxButton, SxIcon, SxMenu。
  • 依赖注入: INextUILocalizer L。
  • 实现接口: IAsyncDisposable。

2. 组件模式

模式 条件 说明
条件渲染 GenerateHeader != GenerateHeaderOption.None && _context.Columns.Count > 0 影响局部渲染块
条件渲染 ShowColumnOptions 影响局部渲染块
条件渲染 column.IsSortable && !column.IsSorted 影响局部渲染块
条件渲染 column.IsSorted 影响局部渲染块
条件渲染 HasColumnFilter(column 影响局部渲染块
条件渲染 ResizableColumns 影响局部渲染块
条件渲染 column.IsSortable && !column.IsSorted 影响局部渲染块
条件渲染 column.IsSorted 影响局部渲染块
条件渲染 column.IsSortable || ResizableColumns || column.FilterPropertyName != null 影响局部渲染块
条件渲染 HasColumnFilter(column 影响局部渲染块
条件渲染 ResizableColumns 影响局部渲染块
条件渲染 _context.Columns.Count == 0 影响局部渲染块
条件渲染 LoadingContent != null 影响局部渲染块
条件渲染 ErrorContent != null 影响局部渲染块
条件渲染 EmptyContent != null 影响局部渲染块

3. 表单字段

字段组件 绑定
- -

4. 操作按钮

外观 动作/链接 禁用条件
@(IsColumnFilterEnabled(column) ? ButtonAppearance.Accent : ButtonAppearance.Stealth) - -
@(IsColumnFilterEnabled(column) ? ButtonAppearance.Accent : ButtonAppearance.Stealth) - -
ButtonAppearance.Stealth - -
ButtonAppearance.Stealth - -
ButtonAppearance.Accent - -
ButtonAppearance.Stealth - @(!IsColumnFiltered(column))
ButtonAppearance.Stealth - -
ButtonAppearance.Stealth - -
ButtonAppearance.Stealth ClearSortAsync @(!column.IsSorted)
ButtonAppearance.Accent - -
ButtonAppearance.Stealth CancelExactWidth -
ButtonAppearance.Stealth - -
ButtonAppearance.Stealth - -
ButtonAppearance.Stealth - -

5. 验证规则

未检测到显式验证标记。

6. 状态与流程

内部状态字段：

  • _context: SxGridContext<TGridItem>
  • _gridRef: ElementReference
  • _virtualizeComponent: Virtualize<TGridItem>?
  • _pendingDataLoadCts: CancellationTokenSource?
  • _loading: bool
  • _error: Exception?
  • _jsModule: IJSObjectReference?
  • _resizeCleanup: IJSObjectReference?
  • _disposed: bool
  • _resizeInitialized: bool
  • _isResizing: bool
  • _internalFilterState: SxFilterState
  • _subscribedFilterState: SxFilterState?
  • _previousItems: IQueryable<TGridItem>?
  • _previousItemsProvider: SxGridItemsProvider<TGridItem>?
  • _isFirstRender: bool
  • _suppressLoadingIndicator: bool
  • _isInitialDataLoad: bool
  • EffectiveFilterState: SxFilterState
  • _exactWidthInput: int?

7. 公共 API

7.1 Parameters

参数 类型 默认值 说明
OverscanCount int 3 Number of extra items to render for smooth scrolling.
RowSize DataGridRowSize DataGridRowSize.Small Row height preset.
ShowHover bool true Whether to show hover effect on rows.
GenerateHeader GenerateHeaderOption GenerateHeaderOption.Sticky Header generation option.
ResizeType DataGridResizeType DataGridResizeType.Discrete Column resize behavior.

7.2 Public Methods

  • RefreshDataAsync: Task
  • SortByColumnAsync: Task
  • ClearSortAsync: Task
  • ClearAllFilters: void
  • DisposeAsync: ValueTask

7.3 Events/Callbacks

无回调事件。

8. 典型使用场景 (Use Cases)

8.1 UC-1: 基础渲染

  1. 组件渲染默认状态
  2. 关键区域可见
  3. 无异常

9. 状态不变性测试 (State Invariants)

  • 同一参数重复设置不应触发非必要 UI 改变
  • 与表单字段无关的操作不应影响字段值

10. 测试检查点

  • 条件 GenerateHeader != GenerateHeaderOption.None && _context.Columns.Count > 0 下渲染正确
  • 条件 ShowColumnOptions 下渲染正确
  • 条件 column.IsSortable && !column.IsSorted 下渲染正确
  • 条件 column.IsSorted 下渲染正确
  • 条件 HasColumnFilter(column 下渲染正确
  • 条件 ResizableColumns 下渲染正确
  • 条件 column.IsSortable && !column.IsSorted 下渲染正确
  • 条件 column.IsSorted 下渲染正确

11. Fluent UI 对齐

对应 Fluent UI Blazor 组件：FluentDataGrid 源码：src/Core/Components/DataGrid/* 对齐要点：

  • 数据源：Items/ItemsProvider 二选一，可配合 RefreshItems。
  • 虚拟化：Virtualize + ItemSize + OverscanCount。
  • 列调整：ResizableColumns、ResizeColumnOnAllRows、ResizeType。
  • RowStyle 不建议动态更新（会干扰脚本），应使用 RowClass。
  • MultiLine 不能与 Virtualize 同时使用。 关键参数/事件：
  • DisplayMode（Grid/Table）、RowSize、AutoFit、AutoItemsPerPage。
  • OnRowClick/OnRowDoubleClick/OnCellClick、OnItemsLoading。
  • ColumnOptionsLabels/ColumnResizeLabels/ColumnSortLabels。 差异与扩展：
  • SxDataGrid 需对齐列宽/选中/虚拟化与 RowStyle 限制。

12. 参考文档摘要

  • docs/ComponentInventory.md: NextUI 组件全量版图审计 (Fluent UI v4.13.2 对齐) 本文档作为 NextUI 设计系统的“全量施工蓝图”，实时对齐 Microsoft Fluent UI Blazor v4.13.2 官方组件库。所有组件分为已实现 [x]、开发中 [-] 和待开发 [ ] 状态。
  • docs/plans/2026-01-25-sxdatagrid-workbench-pages.md: SxDataGrid Workbench 子页面实现计划 > For Claude: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
  • docs/plans/2026-01-25-sxdatagrid-design.md: SxDataGrid Component Design Date: 2026-01-25

13. 规范合规检查

  • 可能存在硬编码样式: 存在十六进制颜色；存在 px 硬编码

14. 变更历史

  • 2026-02-04: 深度分析填充规范。