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;
    }
}

注意事项

  1. 用数据权限的话,实体必须实现 IDataPermission 接口
  2. 导入文件默认限制 5MB
  3. 树形表格要设 GetParentId 参数
  4. 实体接入审批(实现 IApprovalBill,或基类换成 ApprovalEntity / ApprovalEntityFull)后,保存成功会自动提交审批——默认保存路径和自定义 OnSaveAsync 保存路径都会提交(两者行为一致);ApprovalOptions.AutoSubmitOnSave = false 可关闭自动提交,改由页面调用 IApprovalGateway.SubmitAsync
  5. 单据处于审批中时禁止修改与删除(提示「单据正在审批中,不能修改或删除」);已通过的单据默认也锁定(ApprovalOptions.AllowEditAfterApproved 或流程里的 allowEditAfterApproved 可放开)。详见审批
  6. 开启轻量查询(e.Select.LightQuery())后,列表行里不再带大字段。列表模板或筛选条件如果用到了大字段,务必用 IncludeLargeColumns 点名,否则该字段恒为空
  7. 轻量查询的白名单路径最深支持到「根实体.一级导航.二级导航」(如 x => x.Org.Remark),更深的层级导航不会自动加载
  8. 轻量查询下每多一种导航就多一条批量 IN 查询(走主键索引,单条耗时通常在百毫秒级),换来的是传输量的大幅下降
  9. 大字段标记属性(Is{列名} / {列名}Length / [LargeColumnFlag])必须标 [Column(IsIgnore = true)]:没有该标记的属性会被当成真实列,框架会用正文的计算结果覆盖它的值(列表显示错值,保存还会把错值写回库);反之,真实业务列不会被命名约定误认成标记
  10. 列过滤器和高级搜索支持的过滤动作:等于 / 不等于 / 包含 / 不包含 / 大于 / 大于等于 / 小于 / 小于等于 / 为空 / 不为空。「为空」「不为空」会翻译成 SQL 的 IS NULL / IS NOT NULL,可空列与引用类型列都能正常过滤;正则匹配(Match / NotMatch)和自定义谓词(CustomPredicate)只能做内存过滤,数据库分页查询无法表达,用了会抛出 NotSupportedException(这两个动作需要页面显式指定 <RegexFilter /> 才会出现,默认不会出现)
  11. 「为空 / 不为空」作用在不可空值类型列(如 bool / int / DateTime)上时:该列永远不为 null,「不为空」视为条件成立(匹配全部),「为空」视为没有匹配行(结果为空)——与 BootstrapBlazor 官方语义一致
  12. 保存前钩子可以整体替换待保存对象:OnBeforeSaveAsync 里既可以原地改属性(e.Item.Name = "..."),也可以整体替换(e.Item = new TItem { ... })——替换后的对象才是真正落库的内容(默认保存流与页面自定义 OnSaveAsync 两条路径都支持)
  13. 导入前钩子可以整体替换待导入行集合:OnBeforeImportAsync 里 e.Items = e.Items.Where(...).ToList() 会被采纳(被剔除的行不会落库),替换后会重新走一遍行级数据权限过滤
  14. 导入会更新既有记录,因此需要「编辑」权限:Excel 导入是"新增 + 按主键/唯一键更新"的混合写入路径,只有 add 权限的角色可以新增,但不能改写既有记录 —— 会命中既有主键/唯一键的行要求 edit 按钮权限,不满足的行会被剔除并提示
  15. 导出列 = 表格可见列:导出包含当前可见的全部列,导航集合列与计算列也会被导出(值为该属性的取值);此前这些列会被静默丢弃,导致导出的 Excel 比表格少列