增加DataGridEx

This commit is contained in:
chfei committed 2026-10-28 16:48:02 +08:00
1 parent 497e9f1c34
commit 499379e20b
23 files changed
+2682 -6

No files matched your search

+62
View File
@@ -0,0 +1,62 @@
---
name: datagridex
description: DataGridEx WPF 表格控件的能力与用法,涵盖分页、行选择、序号、列显隐、自定义操作栏与分页栏、加载动画、排序和图片列。需要了解或配置 DataGridEx 时使用。
---
# DataGridEx
DataGridEx 继承 WPF DataGrid,提供以下能力。属性默认值和配置示例见 [references/usage.md](references/usage.md)。
## 行选择与序号
- 行头复选框与独立序号列,可分别显示或隐藏。
- 表头支持全选、未选和部分选中的三态显示;全选范围是当前 ItemsSource/视图。
- 点击行尾空白可选中对应行;支持行头点击切换选择、可选的右键选中和行菜单。
- SelectedItems 支持绑定可增删集合,集合内增删与表格选择双向同步。使用 OneWay 绑定集合引用,无需属性 setter;不支持只读或固定大小集合。
- 序号自动创建,按当前显示顺序和分页偏移计算,排序与行回收后更新。
- 选中行背景与前景可配置。
## 分页
- 首页、上一页、下一页、末页、页大小选择、当前页和总记录数。
- PageIndex、PageSize 支持绑定;翻页通过 PageChangedCommand 发出 DataGridPageRequest(PageIndex, PageSize)。
- 换页或改变页大小清空选择;改变页大小回到第一页,总数减少时自动调整到有效页码。
- 调用方提供当前页数据和总数;控件不请求数据,也不再次切分 ItemsSource。
- ShowPagination 控制分页栏显隐。隐藏时仍保留分页状态;不分页时保持 PageIndex=1。
## 列与排序
- 支持原生 DataGrid 列类型和自定义模板列,列放在 DataGridEx.Columns 中。
- 内置列设置面板,勾选后立即显示或隐藏列。
- CanHideColumn=False 可将业务列设为固定显示;复选框与序号使用各自开关。
- 列显示设置不持久化,没有额外的右侧冻结实现。
- 支持表头排序,排序图标位于列右侧;默认仅对当前数据源排序。
- 服务端全量排序由调用方处理 Sorting 事件并重新查询。
## 自定义内容
- ShowToolbar 控制操作栏显隐,ShowColumnSettings 控制列设置按钮。
- ToolbarContent 自定义操作栏中间区域,保留选择提示和列设置按钮。
- PaginationContent 替换整个分页栏;未设置或为 null 时使用默认分页栏。
- 两个内容槽均继承调用方 DataContext,可放置按钮、统计文字和业务布局。
## 加载与空数据
- IsLoading 控制加载遮罩及不确定进度动画,LoadingText 配置提示文字。
- 加载期间禁用表格、操作栏和分页栏,结束后恢复;不控制表格外部控件。
- NoDataTips 配置空数据提示,IsActive 可抑制空数据提示,与 IsLoading 分开控制。
- 加载状态由调用方设置,控件不推断请求开始、完成或失败。
## 图片列与虚拟化
- DataGridExImageColumn 支持图片地址绑定、占位图绑定及 ElementStyle。
- 默认图片尺寸 58×58,Stretch=Uniform。
- 可见单元格按需加载图片,行回收时取消旧请求,避免旧图片覆盖新行。
- 支持图片缓存,以及拖动滚动条期间暂停图片加载、停止后恢复。
- 启用行/列虚拟化和容器回收。
## 集合视图支持
ItemsSource 可绑定 ICollectionView。调用方可使用独立 ListCollectionView,通过 Filter 和 Refresh 实现当前页实时筛选并保留视图排序。
搜索输入框、匹配规则、后台查询、异步取消和跨页全部选择不属于控件内置能力。
@@ -0,0 +1,97 @@
# DataGridEx 调用与属性
## 常用接入
以下绑定属性由调用方 ViewModel 提供,controls 表示 DataGridEx 所在命名空间。
~~~xml
<controls:DataGridEx x:Name="StoreGrid"
IsReadOnly="True"
ShowCheckBox="True" ShowRowNumber="True"
ShowToolbar="True" ShowColumnSettings="True" ShowPagination="True"
ItemsSource="{Binding CurrentItems, Mode=OneWay}"
SelectedItems="{Binding SelectedStores, Mode=OneWay}"
TotalItemCount="{Binding TotalCount, Mode=OneWay}"
PageSize="50"
PageChangedCommand="{Binding LoadPageCommand, Mode=OneWay}"
IsLoading="{Binding LoadingStatus.IsLoading, Mode=OneWay}"
LoadingText="{Binding LoadingStatus.Message, Mode=OneWay}">
<controls:DataGridEx.ToolbarContent>
<Button Content="批量操作" Command="{Binding BatchCommand, Mode=OneWay}"/>
</controls:DataGridEx.ToolbarContent>
<controls:DataGridEx.Columns>
<DataGridTextColumn Header="店铺名称"
Binding="{Binding Name, Mode=OneWay}"
controls:DataGridEx.CanHideColumn="False"/>
<DataGridTextColumn Header="店铺 ID"
Binding="{Binding StoreId, Mode=OneWay}"/>
</controls:DataGridEx.Columns>
</controls:DataGridEx>
~~~
首次数据由调用方装入,不依赖 PageChangedCommand 自动启动。默认不自动生成列;数据要使用正确的类型,日期/金额等通过绑定格式化展示。
## 常用属性
| 属性 | 当前默认值 / 约束 |
| --- | --- |
| ShowCheckBox / ShowRowNumber | false / false,分别显示选择行头与序号 |
| ShowSelectAll | true;同时启用 ShowCheckBox 才显示表头全选 |
| ShowToolbar / ShowColumnSettings / ShowPagination | true;列设置按钮位于操作栏 |
| ToolbarContent | null;页面 DataContext 下的自定义批量操作内容 |
| PaginationContent | null;自定义整个分页栏,null 恢复默认栏 |
| PageIndex / PageSize | 1 / 50;均须大于 0,支持双向绑定 |
| PageSizes | 20、50、100;自定义集合应包含当前 PageSize |
| TotalItemCount | 0,不能为负数;应为后台查询总数而非当前页条数 |
| PageChangedCommand | ICommand,参数 DataGridPageRequest |
| IsLoading / LoadingText | false / 正在加载数据… |
| SelectedItems | 原生选中集合;绑定时要求可增删集合 |
| SelectedRowBackground / SelectedRowForeground | 浅梅紫 / 黑色 |
| ToggleSelectionOnRowHeaderClick | true;点击行头切换选中 |
| SelectRowOnRightClick | false;开启后右击未选中行会单选该行 |
| RowContextMenu | null;行级菜单,行 Tag 可访问页面 DataContext |
| NoDataTips / IsActive | 复用 DataGridHelper;IsActive=true 抑制空数据提示,不等同于 IsLoading |
| PauseImageLoadingWhileDragging | true;拖动时暂停图片,停止滚动后延迟恢复 |
| EnableImageCache | true |
| CanHideColumn(附加属性) | true;对业务列设 false 可固定显示 |
只读状态:PageCount、PageSummary、TotalSummary、SelectionSummary、AreAllRowsSelected(三态)、IsSelectionModeActive、IsImageLoadingSuspended。不要尝试双向写入只读属性。
## 自定义分页栏
将下面属性元素放在命名为 StoreGrid 的 DataGridEx 内。内置路由命令包含 FirstPageCommand、PreviousPageCommand、NextPageCommand、LastPageCommand,边界由控件判定。
~~~xml
<controls:DataGridEx.PaginationContent>
<DockPanel>
<StackPanel DockPanel.Dock="Right" Orientation="Horizontal">
<Button Content="上一页"
Command="{x:Static controls:DataGridEx.PreviousPageCommand}"
CommandTarget="{Binding ElementName=StoreGrid, Mode=OneWay}"/>
<TextBlock Margin="12,0" VerticalAlignment="Center"
Text="{Binding PageSummary, ElementName=StoreGrid, Mode=OneWay}"/>
<Button Content="下一页"
Command="{x:Static controls:DataGridEx.NextPageCommand}"
CommandTarget="{Binding ElementName=StoreGrid, Mode=OneWay}"/>
</StackPanel>
<TextBlock VerticalAlignment="Center"
Text="{Binding TotalSummary, ElementName=StoreGrid, Mode=OneWay}"/>
</DockPanel>
</controls:DataGridEx.PaginationContent>
~~~
PageIndex/PageSize 如需双向绑定,明确 Mode=TwoWay 和 UpdateSourceTrigger=PropertyChanged。隐藏分页栏不会停用分页状态或改变当前数据。
## 图片列
~~~xml
<controls:DataGridExImageColumn Header="图片" Binding="{Binding ImageUrl, Mode=OneWay}"/>
~~~
图片列使用 NetworkThumbnail,默认 58×58、Stretch=Uniform;可配置 ElementStyle 和 PlaceholderBinding。可见单元格按需加载,回收时取消旧请求,避免旧图片覆盖新行。拖动暂停和缓存由所属表格配置;它们不是表格整体加载动画的开关。
## 能力边界
列显示设置不持久化;没有额外的右侧冻结实现。控件支持 ICollectionView 数据源,但搜索输入与查询逻辑由调用方实现,不承担 HTTP 请求、数据库访问或跨页全部选择。