Files
Store.Management/.agents/skills/reference-fast-wpf-grid/SKILL.md
T
2026-10-27 19:01:56 +08:00

117 lines
4.0 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
name: reference-fast-wpf-grid
description: >-
MAX.FastWpfGrid 高性能表格完整使用指南(FastGridModelBase 模式、XAML 绑定、Excel 导出)。
当用户处理百万行级别大数据表格、使用 MAX.FastWpfGrid、FastWpfGrid、FastGridControl、
FastGridModelBase 或需要表格导出时自动加载。
disable-model-invocation: false
---
# MAX.FastWpfGrid 完整参考
## 概述
MAX.FastWpfGrid 是基于 **WriteableBitmap** 渲染的高性能 WPF 表格控件,不依赖 WPF 视觉树,所有内容绘制到位图上,实现百万行数据的流畅滚动。
- **NuGet 包**:`MAX.FastWpfGrid`(**禁止**旧包名 `FastWpfGrid`)
- **命名空间 / 程序集**:`MAX.FastWpfGrid`(旧命名空间 `FastWpfGrid` 已废弃)
- **本地源码**:`{LIBS_ROOT}MAX.FastWpfGrid\MAX.FastWpfGrid\`(路径变量见 `max-libraries-reference.md`)
- **核心类型**:
- `FastGridControl`:WPF 控件,通过 `Model` 属性绑定数据模型
- `FastGridModelBase`:数据模型基类,继承后覆写 `GetRowHeaderText`、`GetColumnHeaderText`、`GetCellText` 方法提供数据
- `FastGridCellImpl`:富文本单元格(图文混排、背景色),在 `GetCell()` 中使用
- **建模模式**:通常封装一个 `TableModelBase` 抽象基类(继承 `FastGridModelBase`),统一处理行列头渲染和右键菜单分发
## 模型模式
继承 `FastGridModelBase`,覆写三个核心方法:
```csharp
using MAX.FastWpfGrid;
public class XxxTableModel : FastGridModelBase
{
private readonly IReadOnlyList<XxxData> _data;
public XxxTableModel(IReadOnlyList<XxxData> data)
: base(columnCount, data.Count)
{
_data = data;
}
public override string GetRowHeaderText(int row)
=> (row + 1).ToString();
public override string GetColumnHeaderText(int column)
=> column switch
{
0 => "时间戳",
1 => "通道A",
2 => "通道B",
_ => $"列{column}",
};
public override string GetCellText(int row, int column)
=> column switch
{
0 => _data[row].Timestamp.ToString(),
1 => _data[row].ChannelA.ToString("0.####"),
2 => _data[row].ChannelB.ToString("0.####"),
_ => string.Empty,
};
}
```
需要颜色、图文混排的单元格,覆写 `GetCell()` 返回 `FastGridCellImpl` 实例。
## XAML 绑定
```xml
xmlns:fwg="clr-namespace:MAX.FastWpfGrid;assembly=MAX.FastWpfGrid"
<fwg:FastGridControl
Model="{Binding TableModel}"
IsReadOnly="True"
HeaderHeight="18"
BackgroundColor="#fafafa"
CellFontSize="12"/>
```
## 导出 Excel(MiniExcel)
将 `FastGridModelBase` 子类包装为 `DbDataReader`,配合 **MiniExcel** 实现 XLSX 导出:
```csharp
// 将 TableModel 适配为 DbDataReader 供 MiniExcel 流式写入
private sealed class TableModelDataReader(TableModelBase model) : DbDataReader
{
private int _currentRow = -1;
public override int FieldCount => model.ColumnCount;
public override bool HasRows => model.RowCount > 0;
public override bool Read()
{
_currentRow++;
return _currentRow < model.RowCount;
}
public override string GetName(int ordinal) => model.GetColumnHeaderText(ordinal) ?? string.Empty;
public override object GetValue(int ordinal) => model.GetCellText(_currentRow, ordinal) ?? string.Empty;
public override string GetString(int ordinal) => model.GetCellText(_currentRow, ordinal) ?? string.Empty;
// 其余 DbDataReader 抽象成员使用默认实现
public override int RecordsAffected => -1;
public override bool IsClosed => false;
public override int Depth => 0;
// ...
}
// 导出 Excel
using FileStream fileStream = new(filePath, FileMode.Create, FileAccess.Write, FileShare.None);
using TableModelDataReader reader = new(tableModel);
MiniExcel.SaveAs(fileStream, reader, excelType: ExcelType.XLSX);
```
纯文本导出则直接循环调用 `GetCellText()` 写入 CSV/TSV 即可。