三个全新 sgcHTML 管理组件：Presence、RolesPermissions 和 UserManagement

2026年7月21日 · 组件

这是介绍 sgcHTML 25 个全新组件系列文章的最后一篇。压轴登场的是每个管理后台迟早都需要的三个组件：谁正在线、谁被允许做什么，以及真正用来管理账号的那张表格。这三个组件都通过和你的聊天、任务进度界面已经在用的同一条 WebSocket 通道推送实时更新，因此这一批组件可以和前几篇文章里的组件直接搭配使用。

Presence — 实时的在线用户名单

TsgcHTMLComponent_Presence 可以渲染成层叠头像堆叠，也可以渲染成姓名加状态的列表，超出 MaxVisible 的部分会折叠成一个 "+N" 溢出标记。AddUser 用于新增或更新一条名单记录，SetUserStatus 只更新状态圆点，而 GetUserFragmentHTML 会把这单条改动推送给每一个已连接的客户端。

uses
  sgcHTML_Component_Presence;

var
  oPresence: TsgcHTMLComponent_Presence;
begin
  oPresence := TsgcHTMLComponent_Presence.Create(nil);
  try
    oPresence.PresenceID := 'roster';
    oPresence.Layout := plAvatars;
    oPresence.MaxVisible := 5;
    oPresence.Title := 'Online';

    oPresence.AddUser('u1', 'Ana Torres', psOnline);
    oPresence.AddUser('u2', 'Marc Bell', psAway, '', 'Back at 3pm');
    oPresence.AddUser('u3', 'Kenji Ito', psBusy);

    WebModule.Response := oPresence.HTML;   // avatar stack + scoped CSS
  finally
    oPresence.Free;
  end;
end;

// Push a status change to every connected client, no full re-render:
oPresence.SetUserStatus('u2', psOnline);
TsgcHTMX_Engine_Server.BroadcastFragment(oPresence.GetUserFragmentHTML('u2'));

RolesPermissions — 一张授权矩阵，而不是塞满复选框的表单

TsgcHTMLComponent_RolesPermissions 把角色排列成列，把权限排列成行（按分类分组），每个交叉点上都有一个复选框。AddRole 和 AddPermission 分别构建这两个轴，SetGrant 用于勾选初始单元格，而客户端每一次切换都会以 JSON 数据的形式发送到服务器端，你的处理程序必须先完成授权检查，然后再通过 ProcessGrantChanged 应用这次改动。

uses
  sgcHTML_Enums, sgcHTML_Component_RolesPermissions;

var
  oMatrix: TsgcHTMLComponent_RolesPermissions;
begin
  oMatrix := TsgcHTMLComponent_RolesPermissions.Create(nil);
  try
    oMatrix.MatrixID := 'acl';
    oMatrix.StickyHeader := True;

    oMatrix.AddRole('admin', 'Administrator').Color := hcDanger;
    oMatrix.AddRole('editor', 'Editor');
    oMatrix.AddRole('viewer', 'Viewer');

    oMatrix.AddPermission('users.edit', 'Edit users', 'Users');
    oMatrix.AddPermission('users.delete', 'Delete users', 'Users');
    oMatrix.AddPermission('billing.view', 'View invoices', 'Billing');

    oMatrix.SetGrant('admin', 'users.edit', True);
    oMatrix.SetGrant('admin', 'users.delete', True);
    oMatrix.SetGrant('editor', 'users.edit', True);

    WebModule.Response := oMatrix.HTML;   // matrix table + inline script
  finally
    oMatrix.Free;
  end;
end;

// Server-side handler for a checkbox toggle received over WebSockets.
// ALWAYS verify the acting user is authorized before applying the change:
oMatrix.ProcessGrantChanged('editor', 'users.delete', True);

UserManagement — 账号表格本身

TsgcHTMLComponent_UserManagement 就是那些角色最终被分配到的表格：头像、状态徽章、角色徽章、最近登录时间、搜索框，以及每一行的操作下拉菜单（编辑、禁用/启用、重置密码，如果你选择启用，还可以模拟登录和删除）。AddUser 追加一行并返回一个供你填写的 TsgcHTMLUser；ProcessUserAction 负责处理某一行下拉菜单发回的任意操作，同样只有在你自己完成授权检查之后才能执行。

uses
  sgcHTML_Component_UserManagement;

var
  oUsers: TsgcHTMLComponent_UserManagement;
  oUser: TsgcHTMLUser;
begin
  oUsers := TsgcHTMLComponent_UserManagement.Create(nil);
  try
    oUsers.TableID := 'users';
    oUsers.AllowImpersonate := True;
    oUsers.AllowDelete := True;

    oUser := oUsers.AddUser('u1', 'ana.torres', 'ana@example.com');
    oUser.DisplayName := 'Ana Torres';
    oUser.Roles := 'admin,editor';
    oUser.Status := usActive;
    oUser.LastLogin := '2026-07-15 09:12';

    oUsers.AddUser('u2', 'marc.bell', 'marc@example.com').Status := usInvited;

    WebModule.Response := oUsers.HTML;   // toolbar + table + inline script
  finally
    oUsers.Free;
  end;
end;

// Server-side handler for an action received over WebSockets.
// ALWAYS verify the acting user is authorized before applying it:
oUsers.ProcessUserAction('userDisable', 'u2');

请注意 RolesPermissions 和 UserManagement 中重复出现的这个模式：组件本身只负责渲染界面和发出事件，绝不会自行改变状态。只有当你自己的服务器端代码判断操作用户确实有权做出这个改动，并显式调用 ProcessGrantChanged 或 ProcessUserAction 之后，状态才会改变。这是有意为之的设计：组件永远不会替你做任何授权判断。

系列完结

五篇文章，二十五个组件：structured data（TreeGrid、PivotTable、ActivityFeed、Splitter）、charts and codes（Heatmap、Sparkline、CandlestickChart、TreeMap、QRCode、Barcode）、form inputs（MultiSelect、ColorPicker、Slider、TimePicker、SignaturePad、Transfer）、feedback and layout（Badge、PDFViewer、ContextMenu、ProgressBar、JobProgress、LogViewer），以及今天介绍的这三个管理组件。完整功能矩阵目前列出了九大类共 83 个组件，并且每一个组件都在各自的页面上提供了 Delphi、C++Builder 和 .NET 的快速入门文档，其中当然包括 Presence、RolesPermissions 和 UserManagement。

有疑问、反馈，或需要迁移帮助？联系我们 — 回复你的将是编写这些代码的人。