Files
Store.Management/.agents/skills/add-list-page/SKILL.md
T
2026-10-27 19:01:56 +08:00

86 lines
3.9 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: add-list-page
description: >-
在 PipeReviewReport 客户端中新建同构列表页(KPI + FilterBar + DataGrid + Pagination +
列配置 + LoadingCover)。Round 5 项目管理页是标准样板;视频/缺陷列表复用同一骨架。
disable-model-invocation: false
---
# 新建列表页(KPI + 筛选 + 表格)
本项目多个业务列表页结构同构。以 `PipeReviewReport.Projects` 的
`ProjectsMainView` / `ProjectsMainViewModel` 为样板,**组装**而非重写。
## 骨架结构
```
page-head(标题 + 刷新 / 导出 / 新建)
KPI × N(f:KpiCard)
f:FilterBar(左筛选 + 右列配置)
卡片:DataGrid + hc:Pagination + f:LoadingCover
```
## Framework 可复用件(禁止模块内再写一份)
| 组件 | 命名空间 / 路径 |
|---|---|
| `KpiCard` | `Framework/Controls/KpiCard` |
| `FilterBar` | `Framework/Controls/FilterBar`(`Filters` / `Actions` 槽) |
| `LoadingCover` | `Framework/Controls/LoadingCover` |
| `ColumnConfigDialog` | `Framework/Views/Dialogs/ColumnConfigDialog` |
| `IColumnConfigService` | `GetVisibleColumnsAsync` / `SaveVisibleColumnsAsync` |
| `IExcelExportService` | 动态列头导出 xlsx |
| `ColumnDefinition` / `ExcelColumn` | `Framework/Models` |
| `hc:Pagination` / `hc:SearchBar` / `hc:Tag` / `hc:Empty` | HandyControl |
## ViewModel 约定
1. Primary Constructor 注入数据服务;`OnInitializeInRuntime` 填筛选项默认值;`LoadedOnce` 拉数。
2. `LoadingStatus` + `f:LoadingCover`;禁止自建 `IsBusy`。
3. 分页:`PageIndex` / `MaxPageCount` + `PagedQueryHelper`;写回页码时用 `suppressPageReload` 防递归。
4. 筛选变更 → 页码归 1 → 重查;搜索用 `hc:SearchBar.Command`。
5. 列可见性:模块内静态 `XxxListColumns.All` / `DefaultVisible` / `ResolveVisible`;VM 暴露 `ColXxxVisibility`;页面资源放 `f:BindingProxy Data="{Binding}"`,DataGrid 列用 `Visibility="{Binding Data.ColXxxVisibility, Source={StaticResource VmProxy}}"`(**禁止** `x:Reference` 绑到 Root,会循环依赖)。
6. 行内命令:`RelativeSource AncestorType=DataGrid` 取页面 DataContext,不要用 `x:Reference Root`。
7. 弹窗:`DialogViewModelOkCancel` + `f:DialogService` + `ShowOKCancel`(见 `add-dialog` skill)。
8. 导出:`SaveFileDialogService` → 按当前筛选拉全量(设上限)→ 仅导出可见列。
## XAML 注册示例
```xml
<UserControl x:Name="Root" Style="{DynamicResource UserControlStyle}" ...>
<dxmvvm:Interaction.Behaviors>
<f:DialogService x:Name="XxxEditDialog" ContentType="{x:Type dialogs:XxxEditDialog}"/>
<f:DialogService x:Name="ColumnConfigDialog" ContentType="{x:Type f:ColumnConfigDialog}"/>
<dxmvvm:SaveFileDialogService x:Name="SaveFileDialog"/>
</dxmvvm:Interaction.Behaviors>
...
<f:FilterBar>
<f:FilterBar.Filters><!-- SearchBar + ComboBox --></f:FilterBar.Filters>
<f:FilterBar.Actions>
<Button Command="{Binding ColumnConfigCommand}" Content="列配置"/>
</f:FilterBar.Actions>
</f:FilterBar>
</UserControl>
```
## 列配置调用
```csharp
ColumnConfigDialogParameter parameter = new(DataScope.Xxx, XxxListColumns.All, visibleKeys.ToList());
if (ColumnConfigDialog.ShowOKCancel(this, parameter) && parameter.Result is not null)
{
List<string> resolved = XxxListColumns.ResolveVisible(parameter.Result);
await columnConfigService.SaveVisibleColumnsAsync(DataScope.Xxx, resolved);
ApplyVisibleColumns(resolved);
}
```
## 检查清单
- [ ] 用了 `KpiCard` / `FilterBar` / `LoadingCover` / Framework `ColumnConfigDialog`
- [ ] 列 Key 与导出 `ExcelColumn.Key` 一致
- [ ] 空列表有 `hc:Empty`
- [ ] 删除走 `IMessageBoxServiceEx.ShowOkCancelWarning`(确认框优先 OK/Cancel,见 `handycontrol-usage.md`)
- [ ] 无 `var`;MVVM 属性用 `GetProperty`/`SetProperty`;Command 用 `field ??=`
- [ ] 输入框已显式 `MaxLength="{x:Static shared:InputLimits.Path/Text}"`(搜索框用 Text)