AdminTable 组件
概述
AdminTable 是系统里最核心的表格组件,在 BootstrapBlazor 的 Table<TItem> 基础上扩展而来,把增删改查、分页排序、搜索筛选、导入导出、数据权限、树形展示这些功能都打包好了。后台管理页面基本上都用它。
功能特性
- CRUD 全支持,分页排序自动搞定
- Excel 导入导出,还能下载模板
- 树形表格(
IsTree),父子层级自动处理 - 内置数据权限(
UseDataPermission),自动按部门过滤 - 简单搜索 + 高级搜索(多条件组合)
- 查询前、保存前后、删除前后、导入前后都有生命周期事件
- 按钮权限(
[AdminButton])控制显示隐藏 - 自定义编辑弹窗模板(
EditTemplate) - 轻量查询(
e.Select.LightQuery()),列表只查非大字段,大字段可按需点名查询
参数说明
类型参数
| 参数 | 说明 |
|---|---|
| TItem | 实体类型,必须实现 IEntity<TKey> 接口 |
| TKey | 主键类型 |
属性参数
| 参数 | 类型 | 说明 |
|---|---|---|
| IsTree | bool | 是否为树形表格 |
| IsMultipleSelect | bool | 是否启用多选 |
| ShowSearch | bool | 是否显示搜索框 |
| ShowAdvancedSearch | bool | 是否显示高级搜索按钮 |
| ShowExtendButtons | bool | 是否显示扩展按钮 |
| ShowImportButton | bool | 是否显示导入按钮 |
| ShowExportButton | bool | 是否显示导出按钮 |
| UseDataPermission | bool | 是否启用数据权限过滤 |
| EnableDraft | bool | 是否启用草稿自动保存功能,防止因意外关闭页面而丢失数据 |
| EnableSaveWithoutClose | bool | 是否启用保存不关闭功能 |
| DraftAutoSaveInterval | int | 草稿自动保存间隔(秒),默认 30 秒 |
| EditDialogSize | Size | 编辑弹窗尺寸 |
| IgnoreSearchColumns | Expression | 指定忽略搜索的列 |
| GetParentId | Func | 树形表格的父级 ID 委托 |
| OnBeforeQuery | EventCallback | 查询前事件,用于追加 Include、Where 等 |
| OnBeforeSaveAsync | EventCallback | 保存前事件,用于数据验证或预处理 |
| OnFinishSaveAsync | EventCallback | 保存后事件,用于后续处理(如创建租户管理员) |
| OnBeforeDeleteAsync | EventCallback | 删除前事件,用于级联加载或拦截 |
| OnBeforeImportAsync | EventCallback | 导入前事件,用于自定义导入逻辑 |
使用示例
基本用法
<AdminTable TItem="SysUser" TKey="long"
ShowSearch ShowAdvancedSearch ShowExtendButtons
OnBeforeQuery="OnBeforeQuery"
OnBeforeSaveAsync="OnBeforeSaveAsync"
OnBeforeDeleteAsync="OnBeforeDeleteAsync">
<TableColumns>
<TableColumn @bind-Field="context.Username" Text="用户名" />
<TableColumn @bind-Field="context.Nickname" Text="昵称" />
<TableColumn @bind-Field="context.IsEnabled" Text="状态" />
</TableColumns>
</AdminTable>
树形表格
<AdminTable TItem="SysMenu" TKey="long" IsTree IsMultipleSelect
OnBeforeQuery="OnBeforeQuery" ... />
查询前追加 Include
private void OnBeforeQuery(AdminQueryEventArgs<SysUser> e)
{
e.Select.IncludeMany(a => a.Roles).Include(a => a.Org);
}
轻量查询:只查用得上的字段
远端数据库(云库、跨机房)上,列表默认 SELECT * 会把实体的大字段(longtext / blob)连同 Include 进来的导航实体大字段一起拉回,单页几十行就可能传输几 MB、耗时十几秒,而列表真正用得上的往往只有几十个普通字段。开启轻量查询后,列表只查询真正需要的字段。
private void OnBeforeQuery(AdminQueryEventArgs<SysUser> e)
{
e.Select.LightQuery() // 开启轻量查询:只查非大字段
.IncludeLargeColumns(x => x.Remark) // 点名要查的大字段(路径相对根实体)
.Include(a => a.Org) // 原有 Include / Where 写法一行不用改
.Where(a => a.Org.IsEnabled == true);
}
| 方法 | 说明 |
|---|---|
LightQuery() |
开启轻量查询:主表只查非大字段列;导航对象按外键批量补齐(补齐时同样只取非大字段)。不调用则保持原有行为,不影响其它项目 |
IncludeLargeColumns(x => x.字段) |
点名要查询的大字段,路径相对根实体(x => x.Remark、x => x.Org.Remark)。调用它即视为开启轻量查询,无需再写 LightQuery() |
行为说明:
- 大字段判定:数据库类型为 TEXT / BLOB 家族(含 LONGTEXT)、
ColumnAttribute.StringLength < 0、或属性类型是byte[]/Stream - 导航补齐:多对一 / 一对一导航按外键批量单独查询(
WHERE Id IN (...))后挂回列表行,最多自动补齐两级(根实体 → 一级导航 → 二级导航) - 集合导航(
IncludeMany)不参与裁剪,仍按原样全字段加载 - 筛选、排序、搜索、数据权限照常生效:投影裁列后 JOIN 仍然保留,
Where(a => a.Org.IsEnabled == true)这类引用导航的条件不受影响 - 排序:
SortString/SortList/ 点击列头排序,都会转成带表别名的列排序(ORDER BY a.\CreatedTime` DESC`)。投影裁列后排序列不在 SELECT 列表里,若用裸列名会在 JOIN 了同名列的表时报"列名歧义",转成带表别名后不存在该问题 - 编辑弹窗会自动按主键回查完整行再打开,因此表单里的大字段仍是完整内容,保存不会把未加载的字段写成 null
大字段标记:只判断有没有值,不查正文
列表页常常只需要知道「这条记录有没有备注 / 有没有配图」,并不需要正文本身。开启轻量查询后正文不会被查回来,这时可以给实体加一个标记属性,由框架负责算出结果:
public class SysUser : Entity<long>
{
/// <summary>备注正文</summary>
[Column(StringLength = -2)]
public string? Remark { get; set; }
/// <summary>是否有备注(只判断有没有,不查正文)</summary>
[Column(IsIgnore = true)]
public bool? IsRemark { get; set; }
}
| 标记属性写法 | 含义 |
|---|---|
Is{列名}(bool / bool?) |
该大字段是否有内容 |
{列名}Length(int / int? / long / long?) |
该大字段的长度 |
[LargeColumnFlag("列名")] |
名字不符合约定时,显式指定源列 |
[LargeColumnFlag("列名", Mode = LargeColumnFlagMode.Length)] |
显式指定源列并取长度 |
行为说明:
- 标记属性必须标
[Column(IsIgnore = true)]:没有该标记的属性会被当成真实业务列, 框架会用正文的计算结果覆盖它的值(列表显示错值,保存还会把错值写回库)。 反过来,真实业务列(例如string Content+ 真实列int ContentLength表示"最大长度") 也不会被命名约定误认成标记。 - 源列必须是同一个实体上的 string 属性
- 轻量查询:标记由 SQL 计算(
case when a.Remark IS NOT NULL AND a.Remark <> '' then 1 else 0 end),正文一个字节都不传 - 普通查询:正文已加载,标记在内存里算。两种模式的结果完全一致
- 导航实体上的标记同样生效(列表行、编辑弹窗都一致)
- 同一实体类型出现在多条导航路径上时(如自引用导航),各路径的标记独立计算,互不影响
保存前验证
private async Task OnBeforeSaveAsync(AdminSaveEventArgs<SysUser> e)
{
if (await _repo.Select.Where(a => a.Username == e.Item.Username).AnyAsync())
{
await SwalService.Error("用户名已存在");
e.Cancel = true;
}
}
注意事项
- 用数据权限的话,实体必须实现
IDataPermission接口 - 导入文件默认限制 5MB
- 树形表格要设
GetParentId参数 - 实体接入审批(实现
IApprovalBill,或基类换成ApprovalEntity/ApprovalEntityFull)后,保存成功会自动提交审批——默认保存路径和自定义OnSaveAsync保存路径都会提交(两者行为一致);ApprovalOptions.AutoSubmitOnSave = false可关闭自动提交,改由页面调用IApprovalGateway.SubmitAsync - 单据处于审批中时禁止修改与删除(提示「单据正在审批中,不能修改或删除」);已通过的单据默认也锁定(
ApprovalOptions.AllowEditAfterApproved或流程里的allowEditAfterApproved可放开)。详见审批 - 开启轻量查询(
e.Select.LightQuery())后,列表行里不再带大字段。列表模板或筛选条件如果用到了大字段,务必用IncludeLargeColumns点名,否则该字段恒为空 - 轻量查询的白名单路径最深支持到「根实体.一级导航.二级导航」(如
x => x.Org.Remark),更深的层级导航不会自动加载 - 轻量查询下每多一种导航就多一条批量
IN查询(走主键索引,单条耗时通常在百毫秒级),换来的是传输量的大幅下降 - 大字段标记属性(
Is{列名}/{列名}Length/[LargeColumnFlag])必须标[Column(IsIgnore = true)]:没有该标记的属性会被当成真实列,框架会用正文的计算结果覆盖它的值(列表显示错值,保存还会把错值写回库);反之,真实业务列不会被命名约定误认成标记 - 列过滤器和高级搜索支持的过滤动作:等于 / 不等于 / 包含 / 不包含 / 大于 / 大于等于 / 小于 / 小于等于 / 为空 / 不为空。「为空」「不为空」会翻译成 SQL 的
IS NULL/IS NOT NULL,可空列与引用类型列都能正常过滤;正则匹配(Match / NotMatch)和自定义谓词(CustomPredicate)只能做内存过滤,数据库分页查询无法表达,用了会抛出NotSupportedException(这两个动作需要页面显式指定<RegexFilter />才会出现,默认不会出现) - 「为空 / 不为空」作用在不可空值类型列(如
bool/int/DateTime)上时:该列永远不为 null,「不为空」视为条件成立(匹配全部),「为空」视为没有匹配行(结果为空)——与 BootstrapBlazor 官方语义一致 - 保存前钩子可以整体替换待保存对象:
OnBeforeSaveAsync里既可以原地改属性(e.Item.Name = "..."),也可以整体替换(e.Item = new TItem { ... })——替换后的对象才是真正落库的内容(默认保存流与页面自定义OnSaveAsync两条路径都支持) - 导入前钩子可以整体替换待导入行集合:
OnBeforeImportAsync里e.Items = e.Items.Where(...).ToList()会被采纳(被剔除的行不会落库),替换后会重新走一遍行级数据权限过滤 - 导入会更新既有记录,因此需要「编辑」权限:Excel 导入是"新增 + 按主键/唯一键更新"的混合写入路径,只有
add权限的角色可以新增,但不能改写既有记录 —— 会命中既有主键/唯一键的行要求edit按钮权限,不满足的行会被剔除并提示 - 导出列 = 表格可见列:导出包含当前可见的全部列,导航集合列与计算列也会被导出(值为该属性的取值);此前这些列会被静默丢弃,导致导出的 Excel 比表格少列