AdminTable Component
Overview
AdminTable is the core universal data table component in the system, extended from BootstrapBlazor's Table<TItem> component. It encapsulates a full set of features including CRUD operations, pagination and sorting, search and filtering, import/export, data permissions, and tree display. Almost all admin management pages in the system use this component.
Features
- Supports CRUD operations with automatic pagination and sorting
- Supports Excel import/export with template download
- Supports tree table display (
IsTree) with automatic parent-child hierarchy handling - Built-in data permission control (
UseDataPermission) for automatic filtering by user's department - Supports simple search and advanced search (multi-condition combined queries)
- Provides lifecycle events such as before query, before/after save, before/after delete, and before/after import
- Automatically controls button visibility based on button permissions (
[AdminButton]) - Supports custom edit dialog templates (
EditTemplate) - Light query (
e.Select.LightQuery()) lets a list load only the fields it needs, with large columns opt-in by name
Parameters
Type Parameters
| Parameter | Description |
|---|---|
| TItem | Entity type, must implement IEntity<TKey> interface |
| TKey | Primary key type |
Property Parameters
| Parameter | Type | Description |
|---|---|---|
| IsTree | bool | Whether it is a tree table |
| IsMultipleSelect | bool | Whether to enable multi-select |
| ShowSearch | bool | Whether to show the search box |
| ShowAdvancedSearch | bool | Whether to show the advanced search button |
| ShowExtendButtons | bool | Whether to show extension buttons |
| ShowImportButton | bool | Whether to show the import button |
| ShowExportButton | bool | Whether to show the export button |
| UseDataPermission | bool | Whether to enable data permission filtering |
| EnableDraft | bool | Whether to enable draft auto-save to prevent data loss from accidental page closure |
| EnableSaveWithoutClose | bool | Whether to enable save without closing |
| DraftAutoSaveInterval | int | Draft auto-save interval (seconds), default 30 seconds |
| EditDialogSize | Size | Edit dialog size |
| IgnoreSearchColumns | Expression | Specify columns to ignore in search |
| GetParentId | Func | Parent ID delegate for tree table |
| OnBeforeQuery | EventCallback | Before query event, for appending Includes, Where, etc. |
| OnBeforeSaveAsync | EventCallback | Before save event, for data validation or preprocessing |
| OnFinishSaveAsync | EventCallback | After save event, for follow-up processing (e.g., creating tenant admin) |
| OnBeforeDeleteAsync | EventCallback | Before delete event, for cascade loading or cancellation |
| OnBeforeImportAsync | EventCallback | Before import event, for custom import logic |
Usage Examples
Basic Usage
<AdminTable TItem="SysUser" TKey="long"
ShowSearch ShowAdvancedSearch ShowExtendButtons
OnBeforeQuery="OnBeforeQuery"
OnBeforeSaveAsync="OnBeforeSaveAsync"
OnBeforeDeleteAsync="OnBeforeDeleteAsync">
<TableColumns>
<TableColumn @bind-Field="context.Username" Text="Username" />
<TableColumn @bind-Field="context.Nickname" Text="Nickname" />
<TableColumn @bind-Field="context.IsEnabled" Text="Status" />
</TableColumns>
</AdminTable>
Tree Table
<AdminTable TItem="SysMenu" TKey="long" IsTree IsMultipleSelect
OnBeforeQuery="OnBeforeQuery" ... />
Appending Include Before Query
private void OnBeforeQuery(AdminQueryEventArgs<SysUser> e)
{
e.Select.IncludeMany(a => a.Roles).Include(a => a.Org);
}
Light Query: Load Only the Fields You Need
On a remote database (cloud database, cross-datacenter link), the default SELECT * pulls every large column of the entity (longtext / blob) plus the large columns of every included navigation entity back to the server. A single page of a few dozen rows can transfer several megabytes and take more than ten seconds, while the list usually needs only a few dozen ordinary columns. With light query enabled, the list only loads the columns it really needs.
private void OnBeforeQuery(AdminQueryEventArgs<SysUser> e)
{
e.Select.LightQuery() // Enable light query: only non-large columns
.IncludeLargeColumns(x => x.Remark) // Opt a large column in (path relative to the root entity)
.Include(a => a.Org) // Existing Include / Where calls stay exactly as they are
.Where(a => a.Org.IsEnabled == true);
}
| Method | Description |
|---|---|
LightQuery() |
Enables light query: the main table selects only non-large columns, and navigation objects are batched and loaded by foreign key (also without large columns). Not calling it keeps the original behavior, so other projects are unaffected |
IncludeLargeColumns(x => x.字段) |
Opts a large column in; the path is relative to the root entity (x => x.Remark, x => x.Org.Remark). Calling it enables light query on its own, so LightQuery() is not required |
Behavior details:
- How a large column is detected: the database type is in the TEXT / BLOB family (including LONGTEXT),
ColumnAttribute.StringLength < 0, or the property type isbyte[]/Stream - Navigation loading: many-to-one and one-to-one navigations are queried in one batch per navigation (
WHERE Id IN (...)) and attached back to the list rows; up to two levels are filled automatically (root entity → first level → second level) - Collection navigations (
IncludeMany) are not trimmed and are still loaded with all columns, exactly as before - Filtering, sorting, searching and data permissions keep working: the JOINs survive the column trimming, so conditions that reference navigations (e.g.
Where(a => a.Org.IsEnabled == true)) are unaffected - Sorting:
SortString/SortList/ clicking a column header are all translated into table-qualified column sorting (ORDER BY a.\CreatedTime` DESC`). After the column trimming the sorted column is no longer part of the SELECT list, so a bare column name would raise "column is ambiguous" as soon as the query joins a table with the same column name; qualifying it avoids that - The edit dialog re-fetches the complete row by primary key before it opens, so large fields inside the form are still complete and saving never writes null into a field that was not loaded
Large Column Flags: Know Whether It Has a Value Without Loading It
A list page often only needs to know whether a row has a remark or an image, not the content itself. With light query enabled the content is not loaded, so you can add a flag property to the entity and let the framework compute it:
public class SysUser : Entity<long>
{
/// <summary>Remark body</summary>
[Column(StringLength = -2)]
public string? Remark { get; set; }
/// <summary>Whether a remark exists (existence only, the body is not loaded)</summary>
[Column(IsIgnore = true)]
public bool? IsRemark { get; set; }
}
| Flag property | Meaning |
|---|---|
Is{Column} (bool / bool?) |
Whether the large column has content |
{Column}Length (int / int? / long / long?) |
The length of the large column |
[LargeColumnFlag("Column")] |
Explicit source column when the name does not follow the convention |
[LargeColumnFlag("Column", Mode = LargeColumnFlagMode.Length)] |
Explicit source column, length mode |
Behavior details:
- The flag property must be marked
[Column(IsIgnore = true)]: a property without that marker is treated as a real business column and the framework overwrites its value with the computed one (the list shows a wrong value, and saving writes the wrong value back to the database). Conversely, a real business column (for examplestring Contentplus a realint ContentLengthmeaning "maximum length") is never mistaken for a flag by the naming convention. - The source column must be a string property on the same entity
- Light query: the flag is computed by SQL (
case when a.Remark IS NOT NULL AND a.Remark <> '' then 1 else 0 end); the body itself is never transferred - Normal query: the body is already loaded, so the flag is computed in memory. Both modes produce exactly the same result
- Flags declared on navigation entities work as well (same result in list rows and in the edit dialog)
- When the same entity type appears on several navigation paths (for example a self-referencing navigation), each path computes its flags independently
Validation Before Save
private async Task OnBeforeSaveAsync(AdminSaveEventArgs<SysUser> e)
{
if (await _repo.Select.Where(a => a.Username == e.Item.Username).AnyAsync())
{
await SwalService.Error("Username already exists");
e.Cancel = true;
}
}
Notes
- When using data permissions, the entity must implement the
IDataPermissioninterface - The default import file size limit is 5MB
- Tree tables require setting the
GetParentIdparameter - Once the entity is under approval (it implements
IApprovalBill, or its base class isApprovalEntity/ApprovalEntityFull), a successful save is submitted for approval automatically — both the default save path and the customOnSaveAsyncsave path behave the same way. SetApprovalOptions.AutoSubmitOnSave = falseto turn that off and callIApprovalGateway.SubmitAsyncfrom the page instead - A bill that is pending approval cannot be edited or deleted (the user is told "单据正在审批中,不能修改或删除"). Approved bills are locked by default as well (
ApprovalOptions.AllowEditAfterApprovedor the flow'sallowEditAfterApprovedcan unlock them). See Approval - After light query is enabled (
e.Select.LightQuery()), list rows no longer carry large columns. Whenever a list template or a filter condition reads a large column, opt it in withIncludeLargeColumns, otherwise that column is always empty - The light query allow-list path supports up to "root entity.first level.second level" (e.g.
x => x.Org.Remark); deeper navigation levels are not loaded automatically - Each navigation adds one extra batched
INquery (indexed by primary key, typically a few hundred milliseconds), in exchange for a dramatic drop in transferred data - Large column flag properties (
Is{Column}/{Column}Length/[LargeColumnFlag]) must be marked[Column(IsIgnore = true)], otherwise they are treated as real columns and written to the database - Filter actions supported by the column filter and the advanced search: equal / not equal / contains / not contains / greater / greater or equal / less / less or equal / is null / is not null. "Is null" and "is not null" are translated into SQL
IS NULL/IS NOT NULL, so nullable columns and reference-typed columns filter correctly. Regex matching (Match / NotMatch) and custom predicates (CustomPredicate) can only be evaluated in memory and cannot be expressed by a paginated database query; using them throwsNotSupportedException(both actions only appear when a page explicitly supplies<RegexFilter />, never by default) - When "is null / is not null" is applied to a non-nullable value type column (such as
bool/int/DateTime): the column is never null, so "is not null" is treated as always true (matches every row) and "is null" as no matching row (empty result) — consistent with the official BootstrapBlazor semantics - The before-save hook may replace the entity as a whole: in
OnBeforeSaveAsyncyou can either mutate the entity in place (e.Item.Name = "...") or replace it (e.Item = new TItem { ... }) — the replaced entity is what actually reaches the database (both the default save flow and a page's ownOnSaveAsyncsupport this) - The before-import hook may replace the set of rows to import:
e.Items = e.Items.Where(...).ToList()insideOnBeforeImportAsyncis honoured (the removed rows are not imported), and the replaced set is re-checked against the row-level data permissions - Import updates existing records, so it needs the "edit" permission: Excel import is a hybrid "insert + update by primary key / unique key" path, so a role that may only add can insert but must not overwrite existing records — rows that hit an existing primary key / unique key require the
editbutton permission, and rows without it are dropped with a message - Exported columns = visible columns: the export contains every currently visible column, including navigation collection columns and computed columns (the value of that property). These columns used to be dropped silently, which made the exported Excel miss columns the table showed