From 97fe2ff306d6c3f3e31fc34a869f8bdc6e3683f8 Mon Sep 17 00:00:00 2001
From: ZhangAo <hi_itao@163.com>
Date: Mon, 12 Oct 2026 17:32:50 +0800
Subject: [PATCH] u

---
 code/g3soft-erp/docs/后端架构设计.md          |  117 +
 code/g3soft-erp/docs/核心表结构设计.md        |  195 ++
 .../web/src/layouts/DefaultLayout.vue         |   11 +-
 .../web/src/layouts/LayoutTabbar.vue          |    2 +-
 .../components/PreferencesDrawer.vue          |   49 +-
 code/g3soft-erp/web/src/preferences/config.ts |    5 +-
 code/g3soft-erp/web/src/preferences/index.ts  |    1 +
 .../web/src/preferences/style-presets.ts      |   53 +
 code/g3soft-erp/web/src/preferences/types.ts  |   19 +-
 .../src/preferences/update-css-variables.ts   |   25 +-
 code/g3soft-erp/web/src/stores/app.ts         |   35 +-
 code/g3soft-erp/web/src/styles/index.scss     |    2 +
 .../web/src/styles/skin-shadcn.scss           |  174 ++
 code/g3soft-libs/.changeset/attachment.md     |   18 -
 code/g3soft-libs/docs/.vitepress/config.mts   |    2 +-
 .../docs/content/ui/data/attachment.md        |  234 --
 .../g3soft-libs/docs/content/ui/data/table.md |  183 ++
 .../g3soft-libs/docs/content/ui/form/input.md |    6 +-
 .../docs/content/ui/form/rich-text.md         |  252 ++-
 .../docs/content/ui/overlay/dropdown.md       |   17 +
 .../docs/examples/attachment/basic.vue        |   80 -
 .../docs/examples/attachment/modal.vue        |   58 -
 .../docs/examples/attachment/readonly.vue     |   20 -
 .../docs/examples/attachment/select.vue       |   61 -
 .../docs/examples/rich-text/tools.vue         |   39 +
 .../docs/examples/table/actions.vue           |   47 +
 .../g3soft-libs/docs/examples/table/basic.vue |   25 +
 .../docs/examples/table/editable.vue          |   50 +
 .../docs/examples/table/resizable.vue         |   65 +
 .../docs/examples/table/selection.vue         |   45 +
 .../docs/examples/table/sorting.vue           |   25 +
 .../docs/examples/table/virtual.vue           |   33 +
 code/g3soft-libs/docs/table-design.md         |  285 +++
 .../packages/ui/e2e/attachment.spec.ts        |   56 -
 .../packages/ui/e2e/rich-text-table.spec.ts   |  143 +-
 .../packages/ui/e2e/rich-text-toolbar.spec.ts |  484 +++-
 .../packages/ui/e2e/rich-text-tools.spec.ts   |  441 ++++
 .../g3soft-libs/packages/ui/e2e/table.spec.ts |  162 ++
 code/g3soft-libs/packages/ui/package.json     |    4 +-
 .../packages/ui/playground/main.ts            |  113 +-
 .../ui/src/attachment/Attachment.test.ts      |  273 ---
 .../packages/ui/src/attachment/Attachment.vue |  393 ----
 .../ui/src/attachment/AttachmentCard.vue      |  376 ----
 .../ui/src/attachment/AttachmentList.vue      |  848 -------
 .../ui/src/attachment/AttachmentPreview.vue   |  241 --
 .../packages/ui/src/attachment/file.test.ts   |   90 -
 .../packages/ui/src/attachment/file.ts        |  116 -
 .../packages/ui/src/attachment/icons.ts       |   26 -
 .../packages/ui/src/attachment/index.ts       |   29 -
 .../packages/ui/src/attachment/types.ts       |  204 --
 code/g3soft-libs/packages/ui/src/index.ts     |    6 +-
 .../packages/ui/src/input/Input.test.ts       |  107 +
 .../packages/ui/src/input/Input.vue           |   68 +-
 .../packages/ui/src/locale/index.ts           |   84 -
 .../packages/ui/src/popover/Popover.vue       |    2 +-
 .../packages/ui/src/rich-text/LinkMenu.vue    |  308 +++
 .../ui/src/rich-text/ListTypeIcon.vue         |  124 ++
 .../ui/src/rich-text/PreviewDialog.vue        |  250 +++
 .../packages/ui/src/rich-text/RichText.vue    |  244 ++-
 .../ui/src/rich-text/SourceCodeDialog.vue     |  263 +++
 .../packages/ui/src/rich-text/TableMenu.vue   |   28 +-
 .../packages/ui/src/rich-text/Toolbar.vue     | 1948 +++++++++++++++--
 .../ui/src/rich-text/extensions.test.ts       |   87 +
 .../packages/ui/src/rich-text/extensions.ts   |  201 +-
 .../packages/ui/src/rich-text/format.ts       |  237 ++
 .../packages/ui/src/rich-text/index.ts        |   11 +
 .../packages/ui/src/rich-text/print.ts        |  177 ++
 .../packages/ui/src/rich-text/types.ts        |   45 +
 .../packages/ui/src/table/G3Table.test.ts     |  368 ++++
 .../packages/ui/src/table/G3Table.vue         |  868 ++++++++
 .../packages/ui/src/table/index.ts            |   19 +
 .../ui/src/table/style/_overrides.scss        |  123 ++
 .../packages/ui/src/table/style/index.scss    |   22 +
 .../packages/ui/src/table/types.ts            |  200 ++
 .../packages/ui/src/table/utils/actions.ts    |  248 +++
 .../ui/src/table/utils/column.test.ts         |  184 ++
 .../packages/ui/src/table/utils/column.ts     |  144 ++
 .../ui/src/table/utils/editable.test.ts       |  406 ++++
 .../packages/ui/src/table/utils/editable.ts   |  312 +++
 .../ui/src/table/utils/selection.test.ts      |  237 ++
 .../packages/ui/src/table/utils/selection.ts  |  174 ++
 code/g3soft-libs/packages/ui/vite.config.ts   |    7 +
 code/g3soft-libs/pnpm-lock.yaml               |   11 +
 83 files changed, 10083 insertions(+), 3662 deletions(-)
 create mode 100644 code/g3soft-erp/docs/后端架构设计.md
 create mode 100644 code/g3soft-erp/docs/核心表结构设计.md
 create mode 100644 code/g3soft-erp/web/src/preferences/style-presets.ts
 create mode 100644 code/g3soft-erp/web/src/styles/skin-shadcn.scss
 delete mode 100644 code/g3soft-libs/.changeset/attachment.md
 delete mode 100644 code/g3soft-libs/docs/content/ui/data/attachment.md
 create mode 100644 code/g3soft-libs/docs/content/ui/data/table.md
 delete mode 100644 code/g3soft-libs/docs/examples/attachment/basic.vue
 delete mode 100644 code/g3soft-libs/docs/examples/attachment/modal.vue
 delete mode 100644 code/g3soft-libs/docs/examples/attachment/readonly.vue
 delete mode 100644 code/g3soft-libs/docs/examples/attachment/select.vue
 create mode 100644 code/g3soft-libs/docs/examples/rich-text/tools.vue
 create mode 100644 code/g3soft-libs/docs/examples/table/actions.vue
 create mode 100644 code/g3soft-libs/docs/examples/table/basic.vue
 create mode 100644 code/g3soft-libs/docs/examples/table/editable.vue
 create mode 100644 code/g3soft-libs/docs/examples/table/resizable.vue
 create mode 100644 code/g3soft-libs/docs/examples/table/selection.vue
 create mode 100644 code/g3soft-libs/docs/examples/table/sorting.vue
 create mode 100644 code/g3soft-libs/docs/examples/table/virtual.vue
 create mode 100644 code/g3soft-libs/docs/table-design.md
 delete mode 100644 code/g3soft-libs/packages/ui/e2e/attachment.spec.ts
 create mode 100644 code/g3soft-libs/packages/ui/e2e/rich-text-tools.spec.ts
 create mode 100644 code/g3soft-libs/packages/ui/e2e/table.spec.ts
 delete mode 100644 code/g3soft-libs/packages/ui/src/attachment/Attachment.test.ts
 delete mode 100644 code/g3soft-libs/packages/ui/src/attachment/Attachment.vue
 delete mode 100644 code/g3soft-libs/packages/ui/src/attachment/AttachmentCard.vue
 delete mode 100644 code/g3soft-libs/packages/ui/src/attachment/AttachmentList.vue
 delete mode 100644 code/g3soft-libs/packages/ui/src/attachment/AttachmentPreview.vue
 delete mode 100644 code/g3soft-libs/packages/ui/src/attachment/file.test.ts
 delete mode 100644 code/g3soft-libs/packages/ui/src/attachment/file.ts
 delete mode 100644 code/g3soft-libs/packages/ui/src/attachment/icons.ts
 delete mode 100644 code/g3soft-libs/packages/ui/src/attachment/index.ts
 delete mode 100644 code/g3soft-libs/packages/ui/src/attachment/types.ts
 create mode 100644 code/g3soft-libs/packages/ui/src/rich-text/LinkMenu.vue
 create mode 100644 code/g3soft-libs/packages/ui/src/rich-text/ListTypeIcon.vue
 create mode 100644 code/g3soft-libs/packages/ui/src/rich-text/PreviewDialog.vue
 create mode 100644 code/g3soft-libs/packages/ui/src/rich-text/SourceCodeDialog.vue
 create mode 100644 code/g3soft-libs/packages/ui/src/rich-text/extensions.test.ts
 create mode 100644 code/g3soft-libs/packages/ui/src/rich-text/format.ts
 create mode 100644 code/g3soft-libs/packages/ui/src/rich-text/print.ts
 create mode 100644 code/g3soft-libs/packages/ui/src/table/G3Table.test.ts
 create mode 100644 code/g3soft-libs/packages/ui/src/table/G3Table.vue
 create mode 100644 code/g3soft-libs/packages/ui/src/table/index.ts
 create mode 100644 code/g3soft-libs/packages/ui/src/table/style/_overrides.scss
 create mode 100644 code/g3soft-libs/packages/ui/src/table/style/index.scss
 create mode 100644 code/g3soft-libs/packages/ui/src/table/types.ts
 create mode 100644 code/g3soft-libs/packages/ui/src/table/utils/actions.ts
 create mode 100644 code/g3soft-libs/packages/ui/src/table/utils/column.test.ts
 create mode 100644 code/g3soft-libs/packages/ui/src/table/utils/column.ts
 create mode 100644 code/g3soft-libs/packages/ui/src/table/utils/editable.test.ts
 create mode 100644 code/g3soft-libs/packages/ui/src/table/utils/editable.ts
 create mode 100644 code/g3soft-libs/packages/ui/src/table/utils/selection.test.ts
 create mode 100644 code/g3soft-libs/packages/ui/src/table/utils/selection.ts

diff --git a/code/g3soft-erp/docs/后端架构设计.md b/code/g3soft-erp/docs/后端架构设计.md
new file mode 100644
index 00000000..be9201fd
--- /dev/null
+++ b/code/g3soft-erp/docs/后端架构设计.md
@@ -0,0 +1,117 @@
+# FMS 后端架构设计
+
+> 文档版本：V1.1（精简方案）
+> 编制日期：2026-10-12
+> 状态：待评审
+> 适用范围：沿用现有 FMS API 与 SQL Server 模块配置方式
+> 配套文档：[核心表结构设计.md](./核心表结构设计.md)
+
+## 1. 设计目标
+
+本文以已经使用的 FMS 数据库和 `fms-api` 接口为基础，只补充模块配置的版本历史能力。目标是让新 ERP 后端和其他 IT 团队能够沿用熟悉的表结构、SQL 和通用数据接口，而不是重新建设一套元数据运行时。
+
+- 保留 `s_module`、`s_field`、`s_module_schema`、`s_relation` 的现有职责和字段约定。
+- 元数据描述常用模块、字段和页面配置；SQL 是可选的正式扩展方式，遇到配置不便表达的查询时使用。
+- 沿用通用数据 API、机构上下文和 SQL Server 数据源路由；不为每个业务模块新增专用 CRUD API。
+- 只新增轻量模块版本历史；不引入模板引擎、编译发布管线、运行时快照目录或复杂审批流程。
+
+## 2. 总体结构
+
+```text
+模块管理界面
+  ├─ s_module：模块树、表/视图、SQL、保存目标
+  ├─ s_field：模块字段及业务类型
+  ├─ s_module_schema：列表 / 表单 / 查询 JSON
+  └─ s_relation：模块数据关系
+          │
+          ├─ 普通数据请求 → 现有 /data 通用接口 → SQL Server
+          ├─ 自定义查询 SQL → 只读 SQL 校验 → SQL Server
+          └─ 显式版本保存/恢复 → s_module_version
+```
+
+运行时继续读取现有模块配置表。`s_module_version` 只做历史记录与恢复，不成为普通业务请求的读取入口。
+
+## 3. 模块配置如何驱动请求
+
+### 3.1 模块与页面配置
+
+- 模块编码 `s_module.b_id` 是稳定业务编码，由配置方提供，不使用运行时雪花 ID。
+- `b_module_type` 使用现有 `module`、`data`、`virtual` 约定：分组、标准数据对象和虚拟业务对象。
+- `b_view_table`、`b_save_table`、`b_key_field` 描述普通查询和保存目标；数据库对象默认使用 `dbo`。
+- `s_field` 声明模块字段编码、名称和业务类型；具体 SQL 类型通过数据库结构探测获得。
+- `s_module_schema` 的 `view`、`edit`、`query` JSON 控制列表、表单和查询界面；字段语义不在多个 JSON 中重复定义。
+- `s_relation` 声明模块间字段关系；`b_parent_id` 只用于模块树，不表示业务数据关系。
+
+### 3.2 SQL 兜底
+
+- 常规简单查询使用配置的 `b_view_table` 和通用查询接口。
+- 关联、聚合或其他配置表达起来不合适的查询，可在模块配置中使用 `b_query_sql`；它是模块配置数据，不要求在后端代码中为每家公司登记 SQL 编码。
+- 对于按机构隔离的数据库，机构数据源路由继续使用现有 `OrgContext` / `OrgDataSourceManager`。各机构可在自己的配置库维护不同模块 SQL，不新增租户配置层。
+- 运行查询 SQL 必须经过现有只读校验路径；只允许查询语句，不允许用查询 SQL 执行新增、修改、删除或 DDL。写入走现有保存/删除接口或明确的业务服务。
+- `b_order_sql` 是模块默认排序；排序标识符按现有 `DbUtils` 校验规则处理。查询参数和值不得通过未校验的字符串拼接进入 SQL。
+
+## 4. 沿用的通用数据 API
+
+已有的 `/data/*` 契约继续作为数据访问入口，不因模块配置版本化而更换：
+
+| 接口 | 用途 |
+|---|---|
+| `POST /data/loaddata` | 按表/视图、条件、排序和字段列表查询 |
+| `POST /data/page` | 分页查询 |
+| `POST /data/loaddatabysql` | 执行只读 `SELECT` / `WITH` 查询 |
+| `POST /data/saveobjt` | 在一个事务中保存多表新增、修改 |
+| `POST /data/delete` | 按模块或受控目标删除 |
+| `POST /data/describe` | 探测表或视图列结构 |
+| `POST /data/nextid`、`/data/nextcode` | 取雪花 ID 或模块业务编码 |
+
+`loaddata` / `page` 使用表或视图名、结构化筛选和排序参数；`loaddatabysql` 用于复杂只读查询。已有 `DbUtils` 负责标识符验证、SQL 只读检查和 SQL 执行。通用保存服务依据真实表结构生成参数化写入，不通过 `b_query_sql` 写业务数据。
+
+新接入系统应沿用这些请求/响应格式和既有身份、机构、权限上下文；模块管理页面负责读取模块配置并组织请求，不需要另造一套模块专属 CRUD API。
+
+## 5. 模块配置版本历史
+
+### 5.1 行为边界
+
+- 版本功能只增加 `s_module_version` 一张表；快照 JSON 包含模块及其字段、界面、关系和相关模块级扩展配置。
+- 显式创建版本时，后端从现有配置表读取当前状态，分配递增版本号并保存不可变快照。
+- 查看历史只读取版本表；恢复历史版本时，后端校验后在一个事务中恢复现有模块配置表。
+- 恢复成功后业务运行仍读取原有 `s_module` 等表；不切换运行时版本指针，也不改变 `/data/*` 接口。
+- 恢复内容可另存为新的版本记录；禁止覆盖历史快照。
+
+因此这项能力是**配置备份、版本查看与恢复**，不是草稿/发布隔离。配置当前仍按现有保存机制生效；若之后出现明确的灰度发布需求，再单独扩展。
+
+### 5.2 最小后端改动
+
+增加一个模块版本服务，负责：
+
+1. 创建版本：在数据库事务中读取模块及子配置，验证并序列化快照。
+2. 查询版本：按模块编码列出版本号、说明、创建人和时间。
+3. 恢复版本：校验快照结构和关联目标，在同一事务内更新模块配置，并记录恢复结果。
+
+版本操作可通过模块管理 API 暴露；业务数据 API、模块表主键、普通保存流程和 SQL 查询流程不变。版本号由后端分配，不依赖客户端提供。
+
+## 6. SQL 与数据安全约定
+
+- 客户端不能以任意表名或列名绕过后端标识符验证。
+- 普通查询的筛选值以参数传递；字段、排序方向等 SQL 标识由校验后的配置控制。
+- `b_query_sql` 和 `/data/loaddatabysql` 仅用于只读查询，并使用现有 `DbUtils.validateReadOnlySql()` 校验。
+- SQL 配置及执行需经过现有机构、用户和数据范围权限上下文；不能因为使用 SQL 扩展绕过权限校验。
+- 写操作使用 `/data/saveobjt`、`/data/delete` 或已有业务服务，并纳入现有事务和审计规则。
+- 版本恢复同样执行配置权限校验、引用校验和事务处理。
+
+## 7. 不在本次范围内
+
+- 不重构现有 FMS `DataController` 接口，也不改变 SQL Server、JDBC 或机构数据源路由方式。
+- 不增加 `s_template` / `s_template_version`、`s_module_snapshot`、用户偏好新表或权限/工作流新表。
+- 不强制运行时从 JSON 快照读取模块定义，不引入 `ModuleDefinition` 编译缓存层。
+- 不把 SQL 移到后端固定代码目录；保留模块配置中的可选 SQL 兜底。
+- 不重新定义业务表、菜单、用户、权限、工作流、文件和审计子系统。
+- 不把模块版本管理等同于数据库 migration；业务表结构仍通过已有 SQL migration 管理。
+
+## 8. 接入检查清单
+
+1. 确认机构/数据库连接按现有路由建立，业务对象位于 `dbo`。
+2. 普通表格和表单配置 `s_module`、`s_field`、`s_module_schema`；复杂查询按需配置 `b_query_sql`。
+3. 用 `/data/describe` 检查实际表/视图字段，用 `s_field` 和视图 JSON 保持编码一致。
+4. 查询、保存、删除分别调用现有通用接口；不从客户端接收未经验证的 DML SQL。
+5. 重要配置变更后显式保存模块版本；恢复时通过版本服务执行，不手工覆盖版本历史表。
diff --git a/code/g3soft-erp/docs/核心表结构设计.md b/code/g3soft-erp/docs/核心表结构设计.md
new file mode 100644
index 00000000..b0ea9f95
--- /dev/null
+++ b/code/g3soft-erp/docs/核心表结构设计.md
@@ -0,0 +1,195 @@
+# FMS 后端核心表结构设计
+
+> 文档版本：V1.1（精简方案）
+> 编制日期：2026-10-12
+> 状态：待评审
+> 数据库：SQL Server
+> 配套文档：[后端架构设计.md](./后端架构设计.md)
+
+## 1. 范围与原则
+
+本文沿用现有 FMS 的模块表结构和 SQL 驱动方式，只说明模块运行需要的核心元数据表，并增加一张轻量的模块版本历史表。业务表、用户/权限、菜单、多语言、工作流等既有表和接口不在本文重定义。
+
+- 业务数据仍保存在 SQL Server 的真实表和视图中。
+- `s_module`、`s_field`、`s_module_schema`、`s_relation` 描述模块及其界面、字段和关联；不采用 EAV 存业务记录。
+- 常规功能用模块配置；配置不够或 SQL 更直接时，可通过模块的 `b_query_sql` 使用 SQL 查询。
+- 运行时继续读取现有模块配置表；版本表仅保存可查看、可恢复的历史配置，不引入新的运行时快照目录。
+- 保持现有命名和数据类型；不增加模板体系、草稿/发布状态机、额外快照表或元数据编译器。
+- 与现有 FMS 数据库约定一致：模块关联完整性、JSON 和类型校验由应用层负责，不依赖外键、`CHECK` 约束或触发器。
+
+## 2. 核心表清单
+
+| 表 | 职责 | 是否新增 |
+|---|---|---|
+| `s_module` | 模块树、查询来源、保存目标和默认行为 | 否，沿用现有设计 |
+| `s_field` | 模块字段编码、名称和业务类型 | 否，沿用现有设计 |
+| `s_module_schema` | 列表、表单、查询等界面 JSON 配置 | 否，沿用现有设计 |
+| `s_relation` | 模块之间的字段关系 | 否，沿用现有设计 |
+| `s_module_version` | 手动保存的模块配置历史及恢复来源 | 是，唯一新增表 |
+
+现有 `s_user_module_pref`、`s_autocode`、`s_delete_rule` 等辅助配置表继续按原设计使用；权限、菜单和工作流表也保持原状。它们不因本方案改名或迁移。
+
+## 3. 模块 `s_module`
+
+```sql
+create table dbo.s_module (
+    b_id          varchar(50)    not null primary key, -- 模块编码，稳定业务键
+    b_parent_id   varchar(50)    null,                -- 父模块编码，根节点为空
+    b_depth       int            not null default 0,  -- 模块树层级，根节点为 0
+    b_path        varchar(1000)  not null,            -- 模块树路径，由应用层维护
+    b_name        nvarchar(200)  not null,            -- 模块名称
+    b_i18n        varchar(150)   null,                -- 多语言资源编码
+    b_module_type varchar(20)    not null,            -- module / data / virtual
+    b_view_table  varchar(128)   null,                -- 默认查询表或视图名
+    b_save_table  varchar(128)   null,                -- 默认保存目标表名
+    b_key_field   varchar(50)    null,                -- 数据主键字段
+    b_scope_field varchar(50)    null,                -- 数据范围字段，如记录归属人字段
+    b_order_sql   varchar(500)   null,                -- 默认排序规则
+    b_query_sql   nvarchar(max)  null,                -- 可选查询 SQL 或 SQL 模板
+    b_config_json nvarchar(max)  null,                -- 低频模块扩展配置
+    b_canuse      tinyint        not null default 1,  -- 是否启用：1 启用，0 停用
+    b_xh          int            not null default 0,  -- 同级模块显示顺序
+    b_bz          nvarchar(2000) null,                -- 备注
+    b_updated_at  datetime2      null                 -- 模块配置最后保存时间
+);
+
+create index ix_s_module_parent
+    on dbo.s_module (b_parent_id, b_canuse, b_depth, b_xh, b_id);
+
+create index ix_s_module_path
+    on dbo.s_module (b_path, b_canuse, b_id);
+
+create index ix_s_module_type
+    on dbo.s_module (b_module_type, b_canuse, b_xh, b_id);
+
+create index ix_s_module_view_table
+    on dbo.s_module (b_view_table, b_canuse, b_id);
+
+create index ix_s_module_save_table
+    on dbo.s_module (b_save_table, b_canuse, b_id);
+```
+
+### 3.1 字段约定
+
+- `module` 是模块分组；`data` 是标准数据模块；`virtual` 是由查询 SQL 或业务实现提供数据的虚拟模块。
+- `b_view_table` 是普通查询的数据源；配置 `b_query_sql` 时，模块查询使用该 SQL；两者都没有时，由虚拟模块的业务实现提供数据。
+- `b_save_table` 和 `b_key_field` 描述标准保存目标；业务写入仍走现有保存接口或业务服务。
+- `b_query_sql` 是可选的 SQL 兜底配置，不是后端代码中的固定 SQL 编码。可按现有机构/数据库配置维护不同 SQL。它用于查询，不替代标准保存流程。
+- `b_order_sql` 保存该模块的默认排序；值按现有 SQL 标识符和排序校验规则处理。
+- `b_parent_id` 是模块树的权威关系；`b_depth`、`b_path` 是派生字段，新增或移动节点时由应用层在事务内维护。
+
+## 4. 字段 `s_field`
+
+```sql
+create table dbo.s_field (
+    b_module_id varchar(50)   not null,             -- 所属 data / virtual 模块编码
+    b_field     varchar(50)   not null,             -- 模块字段编码或查询结果别名
+    b_name      nvarchar(200) not null,             -- 字段名称
+    b_i18n      varchar(150)  null,                 -- 多语言资源编码
+    b_type      varchar(30)   not null,             -- 字段业务类型
+    b_canuse    tinyint       not null default 1,   -- 是否启用：1 启用，0 停用
+    b_xh        int           not null default 0,   -- 字段默认顺序
+    primary key (b_module_id, b_field)
+);
+
+create index ix_s_field_module_order
+    on dbo.s_field (b_module_id, b_canuse, b_xh, b_field);
+```
+
+`b_type` 表示业务层字段类型；SQL Server 实际类型通过表/视图结构探测获得，不在 `s_field` 重复保存。字段分组、控件、必填、只读、显示顺序等界面行为放在 `s_module_schema` 的 JSON 中。
+
+## 5. 界面配置 `s_module_schema`
+
+```sql
+create table dbo.s_module_schema (
+    b_module_id   varchar(50)   not null,          -- 所属 data / virtual 模块编码
+    b_schema_type varchar(20)   not null,          -- view / edit / query
+    b_schema_json nvarchar(max) not null,          -- 对应界面的完整 JSON 配置
+    b_canuse      tinyint       not null default 1, -- 是否启用：1 启用，0 停用
+    b_updated_by  varchar(50)  null,              -- 最后修改人编码
+    b_updated_at  datetime2    null,              -- 最后修改时间
+    primary key (b_module_id, b_schema_type)
+);
+
+create index ix_s_module_schema_type
+    on dbo.s_module_schema (b_module_id, b_schema_type, b_canuse);
+```
+
+每个模块按需配置 `view`（列表）、`edit`（表单）、`query`（查询条件）。每种类型当前一份 JSON；JSON 结构版本由 JSON 顶层的 `schemaVersion` 管理。字段编码引用 `s_field.b_field`。个人偏好仍使用现有 `s_user_module_pref`，不混入系统默认配置。
+
+## 6. 模块关系 `s_relation`
+
+```sql
+create table dbo.s_relation (
+    b_source_module_id varchar(50) not null, -- 源模块编码
+    b_source_field     varchar(50) not null, -- 源字段编码
+    b_target_module_id varchar(50) not null, -- 目标模块编码
+    b_target_field     varchar(50) not null, -- 目标字段编码
+    b_relation_type    varchar(20) not null, -- one_to_one / one_to_many / many_to_one
+    b_on_delete        varchar(20) not null default 'restrict', -- restrict / cascade / none
+    b_canuse           tinyint not null default 1, -- 是否启用：1 启用，0 停用
+    b_xh               int not null default 0, -- 关系显示顺序
+    primary key (
+        b_source_module_id,
+        b_source_field,
+        b_target_module_id,
+        b_target_field
+    )
+);
+
+create index ix_s_relation_source
+    on dbo.s_relation (b_source_module_id, b_canuse, b_xh, b_source_field, b_target_module_id);
+
+create index ix_s_relation_target
+    on dbo.s_relation (b_target_module_id, b_canuse, b_source_module_id);
+```
+
+模块树只表达业务分组；主子表、引用和多对多关系通过 `s_relation` 或中间表模块表达。关系目标及删除策略由应用层校验，不建立通用业务外键。
+
+## 7. 模块版本历史 `s_module_version`
+
+该表是本方案唯一新增表。它保存模块配置的历史副本，用于查看和恢复；不引入模板版本、独立快照表、发布状态机或运行时版本目录。
+
+```sql
+create table dbo.s_module_version (
+    b_module_id      varchar(50)    not null, -- 所属模块编码
+    b_version_no     int            not null, -- 模块内递增版本号
+    b_snapshot_json  nvarchar(max)  not null, -- 该版本的完整模块配置快照
+    b_change_note    nvarchar(1000) null,     -- 版本说明
+    b_created_by     varchar(50)    null,     -- 创建版本的用户编码
+    b_created_at     datetime2      not null default sysdatetime(), -- 创建版本时间
+    primary key (b_module_id, b_version_no)
+);
+```
+
+快照 JSON 使用独立的 `snapshotVersion` 描述快照格式。它至少包含模块行、字段行、界面配置和相关关系；如需完整恢复模块行为，也包含该模块对应的自动编码、删除规则等配置。示意：
+
+```json
+{
+  "snapshotVersion": 1,
+  "module": {},
+  "fields": [],
+  "schemas": [],
+  "relations": [],
+  "autocodes": [],
+  "deleteRules": []
+}
+```
+
+### 7.1 保存与恢复规则
+
+1. 管理员显式创建版本时，后端在同一事务中读取当前模块配置并写入 `s_module_version`；版本记录创建后不修改。
+2. `b_version_no` 按模块递增；并发创建时由后端事务锁定模块并分配下一个号码。
+3. 恢复版本时先校验快照格式和模块引用，再在一个事务内将快照恢复到现有配置表。
+4. 恢复操作成功后，当前运行行为仍由 `s_module` 等现有配置表决定；为保留操作历史，可将恢复结果另存为一个新版本，不覆盖旧版本。
+5. 版本快照只保存模块配置，不保存业务数据、用户个人偏好、权限授权、菜单、翻译内容或数据库建表脚本。
+
+这套版本历史不提供独立草稿或“线上发布版本”隔离：模块配置仍按现有方式生效。若未来确实需要草稿/发布隔离，再单独评估，不作为本次改造前提。
+
+## 8. 既有表与校验边界
+
+- `s_user_module_pref`：沿用个人视图偏好；它是用户级显示覆盖，不属于模块版本快照。
+- `s_autocode`、`s_delete_rule`：继续按现有规则工作；模块版本需要完整回滚时，其模块配置一并纳入快照。
+- `s_menu`、权限、多语言、日志、工作流及业务表：沿用各自现有设计，不在本文件重建。
+- 模块/字段/关系存在性、`b_module_type`、`b_schema_type` 和 JSON 内容由后端校验；不新增外键、`CHECK` 或触发器。
+- 业务数据库结构变更仍通过 SQL migration 管理；模块版本不替代数据库 migration。
diff --git a/code/g3soft-erp/web/src/layouts/DefaultLayout.vue b/code/g3soft-erp/web/src/layouts/DefaultLayout.vue
index 9e4665cf..f38130f5 100644
--- a/code/g3soft-erp/web/src/layouts/DefaultLayout.vue
+++ b/code/g3soft-erp/web/src/layouts/DefaultLayout.vue
@@ -54,6 +54,15 @@ const showHeader = computed(() => pref.value.header.enable && !isContentFullscre
 /** 页签栏（局部全屏时保留） */
 const showTabbar = computed(() => pref.value.tabbar.enable)
 
+/**
+ * 页面缓存（KeepAlive）的 include 名单，受 tabbar.keepAlive 偏好控制。
+ *
+ * 关闭时传空数组而不是 undefined：KeepAlive 的 include 语义是「白名单」——
+ * 空数组没有任何 name 能匹配上 → 一律不缓存（已缓存的实例会被其内部的
+ * include watch 清掉）；而 undefined 表示「不过滤」→ 反而会缓存所有页面。
+ */
+const keepAliveInclude = computed(() => (pref.value.tabbar.keepAlive ? appStore.cachedKeys : []))
+
 /** 内容区样式：内边距走偏好 */
 const contentStyle = computed(() => ({
   padding: `${pref.value.app.contentPadding}px`,
@@ -180,7 +189,7 @@ watch(
             :name="pref.transition.enable ? pref.transition.name : undefined"
             mode="out-in"
           >
-            <KeepAlive :include="appStore.cachedKeys" :max="8">
+            <KeepAlive :include="keepAliveInclude">
               <component :is="formatComponentInstance(Component, r.fullPath)" :key="r.fullPath" />
             </KeepAlive>
           </Transition>
diff --git a/code/g3soft-erp/web/src/layouts/LayoutTabbar.vue b/code/g3soft-erp/web/src/layouts/LayoutTabbar.vue
index 1bd1b312..374ef462 100644
--- a/code/g3soft-erp/web/src/layouts/LayoutTabbar.vue
+++ b/code/g3soft-erp/web/src/layouts/LayoutTabbar.vue
@@ -214,7 +214,7 @@ onMounted(async () => {
   /* 首次挂载也要定位激活页签 —— 修复「刷新后页签不居中」。
    *
    * 为什么不能只靠下面的 watch：
-   *   页签是持久化的（g3erp:app:v2），刷新时 pinia 在组件挂载【之前】就把 tabs 还原好了，
+   *   页签是持久化的（g3erp:app），刷新时 pinia 在组件挂载【之前】就把 tabs 还原好了，
    *   而 route.fullPath 在路由解析完成时也已确定。
    *   于是 watch 的两个依赖在挂载这一刻【already 是初始值】，
    *   没有 immediate 的 watch 根本不会触发 → revealActiveTab 一次都没跑
diff --git a/code/g3soft-erp/web/src/preferences/components/PreferencesDrawer.vue b/code/g3soft-erp/web/src/preferences/components/PreferencesDrawer.vue
index 78388768..b012d798 100644
--- a/code/g3soft-erp/web/src/preferences/components/PreferencesDrawer.vue
+++ b/code/g3soft-erp/web/src/preferences/components/PreferencesDrawer.vue
@@ -10,6 +10,7 @@ import PrefBlock from './PrefBlock.vue'
 import SelectItem from './SelectItem.vue'
 import SwitchItem from './SwitchItem.vue'
 import ToggleItem from './ToggleItem.vue'
+import { resolvePrimaryColor } from '../style-presets'
 import type { Preferences } from '../types'
 
 /**
@@ -43,6 +44,12 @@ const tabs = [
 // 外观页签
 // ---------------------------------------------------------------------------
 
+/** 界面风格（换皮预设）：default 保持现状，shadcn 现代极简 */
+const styleOptions = [
+  { label: '默认', value: 'default' },
+  { label: '现代极简', value: 'shadcn' },
+]
+
 /** 主题模式卡片（对照 vben theme.vue 的 THEME_PRESET） */
 const themePreset = [
   { icon: Sun, name: 'light' as const, label: '浅色' },
@@ -159,9 +166,9 @@ function setThemeMode(name: 'light' | 'dark' | 'auto'): void {
   store.update({ theme: { mode: name } })
 }
 
-/** 主题色切换（直接写三段式色值） */
+/** 主题色切换（直接写三段式色值）；标记为用户显式选择，风格切换不再覆盖它 */
 function setColorPrimary(value: string): void {
-  store.update({ theme: { colorPrimary: value } })
+  store.update({ theme: { colorPrimary: value, colorPrimaryCustom: true } })
 }
 
 /**
@@ -235,9 +242,13 @@ function hexToHslTriplet(hex: string): string {
   return `${Math.round(h)} ${Math.round(s * 100)}% ${Math.round(l * 100)}%`
 }
 
-/** 当前主题色对应的 hex，喂给取色器。已是 hex/rgb/hsl() 的直接用。 */
+/**
+ * 当前主题色对应的 hex，喂给取色器。
+ * 未显式选过色时（colorPrimaryCustom=false）解析为「当前风格的内置默认色」，
+ * 这样 shadcn 风格下取色器显示的是中性黑，而不是被忽略的 colorPrimary。
+ */
 const customColorHex = computed(() => {
-  const value = pref.value.theme.colorPrimary
+  const value = resolvePrimaryColor(pref.value.theme, pref.value.app.style, store.isDark)
   if (value.startsWith('#') || value.startsWith('rgb') || value.startsWith('hsl')) return value
   return hslTripletToHex(value) ?? '#165dff'
 })
@@ -276,6 +287,19 @@ const hasDiff = computed(() => true)
     <div class="pref-drawer__body">
       <!-- ===================== 外观 ===================== -->
       <template v-if="activeTab === 'appearance'">
+        <!-- 界面风格（换皮预设） -->
+        <PrefBlock title="风格">
+          <ToggleItem
+            :model-value="pref.app.style"
+            :items="styleOptions"
+            @update:model-value="
+              (v) => store.update({ app: { style: v as Preferences['app']['style'] } })
+            "
+          >
+            界面风格
+          </ToggleItem>
+        </PrefBlock>
+
         <!-- 主题模式（图标卡片） -->
         <PrefBlock title="主题模式">
           <div class="pref-card-row">
@@ -320,7 +344,10 @@ const hasDiff = computed(() => true)
             >
               <div
                 class="pref-card__box"
-                :class="{ 'is-active': pref.theme.colorPrimary === theme.value }"
+                :class="{
+                  'is-active':
+                    pref.theme.colorPrimaryCustom && pref.theme.colorPrimary === theme.value,
+                }"
               >
                 <div
                   class="pref-card__swatch"
@@ -336,7 +363,9 @@ const hasDiff = computed(() => true)
               <div
                 class="pref-card__box"
                 :class="{
-                  'is-active': !builtinThemes.some((t) => t.value === pref.theme.colorPrimary),
+                  'is-active':
+                    pref.theme.colorPrimaryCustom &&
+                    !builtinThemes.some((t) => t.value === pref.theme.colorPrimary),
                 }"
               >
                 <!-- 不传 presets：用组件默认值 true，面板自带常用色板便于快捷选色 -->
@@ -607,6 +636,14 @@ const hasDiff = computed(() => true)
           >
             刷新后保留
           </SwitchItem>
+          <SwitchItem
+            :model-value="pref.tabbar.keepAlive"
+            :disabled="!pref.tabbar.enable"
+            tip="切换页签后再回来，保留页面状态（表单输入、滚动位置等）"
+            @update:model-value="(v) => store.update({ tabbar: { keepAlive: v } })"
+          >
+            缓存页签
+          </SwitchItem>
           <SwitchItem
             :model-value="pref.tabbar.wheelable"
             :disabled="!pref.tabbar.enable"
diff --git a/code/g3soft-erp/web/src/preferences/config.ts b/code/g3soft-erp/web/src/preferences/config.ts
index c50ce1e5..4b5173a0 100644
--- a/code/g3soft-erp/web/src/preferences/config.ts
+++ b/code/g3soft-erp/web/src/preferences/config.ts
@@ -14,6 +14,7 @@ export const defaultPreferences: Preferences = {
   app: {
     name: 'G3Soft ERP',
     layout: 'sidebar-nav',
+    style: 'default',
     contentPadding: 16,
     dynamicTitle: true,
     enablePreferences: true,
@@ -22,6 +23,7 @@ export const defaultPreferences: Preferences = {
 
   theme: {
     colorPrimary: '212 100% 45%',
+    colorPrimaryCustom: false,
     colorSuccess: '144 57% 58%',
     colorWarning: '42 84% 61%',
     colorDestructive: '348 100% 61%',
@@ -94,8 +96,7 @@ export const defaultPreferences: Preferences = {
     middleClickToClose: false,
     wheelable: true,
     persist: true,
-    maxCount: 0,
-    keepAlive: false,
+    keepAlive: true,
   },
 
   transition: {
diff --git a/code/g3soft-erp/web/src/preferences/index.ts b/code/g3soft-erp/web/src/preferences/index.ts
index 803d9ac9..ee3b2369 100644
--- a/code/g3soft-erp/web/src/preferences/index.ts
+++ b/code/g3soft-erp/web/src/preferences/index.ts
@@ -15,6 +15,7 @@ export type {
   PageTransitionType,
   Preferences,
   SidebarPreferences,
+  StyleType,
   TabbarPreferences,
   TabsStyleType,
   ThemeModeType,
diff --git a/code/g3soft-erp/web/src/preferences/style-presets.ts b/code/g3soft-erp/web/src/preferences/style-presets.ts
new file mode 100644
index 00000000..cf4277f3
--- /dev/null
+++ b/code/g3soft-erp/web/src/preferences/style-presets.ts
@@ -0,0 +1,53 @@
+import type { StyleType } from './types'
+
+/**
+ * 应用风格预设表（换皮）。
+ *
+ * 只承载「必须由 JS 产出」的那部分 —— 也就是被 `applyPreferencesToCss`
+ * 内联写进 `<html>` 的变量（内联样式压过一切样式表，皮肤样式块覆盖不了它们）。
+ * 其余配色/几何一律由样式层的 `html[data-g3-style=...]` 覆盖，见 styles/skin-shadcn.scss。
+ */
+export interface StylePreset {
+  /**
+   * 风格的内置默认主色（HSL 三段式，按明暗）。
+   * 仅在「用户没显式选过主色」时取用 —— 必须写成三段式：
+   * toColor() 对 #hex 会早退、丢掉 alpha，导致 hover/active 退化。
+   */
+  defaultPrimary: { light: string; dark: string }
+  /**
+   * 主色淡底（选中/激活底）。给定则固定使用（shadcn 用 accent 灰）；
+   * 缺省则按「主色 + 15%/20%」派生（default 沿用旧行为）。
+   */
+  primarySoft?: { light: string; dark: string }
+}
+
+export const stylePresets: Record<StyleType, StylePreset> = {
+  default: {
+    // 与 config.ts 的默认主题色一致
+    defaultPrimary: { light: '212 100% 45%', dark: '212 100% 45%' },
+  },
+  shadcn: {
+    // #0f172b / #e2e8f0
+    defaultPrimary: { light: '223 48% 11%', dark: '214 32% 91%' },
+    // shadcn 的 accent：选中/激活底一律是中性的浅灰/深灰，而非主色淡底
+    primarySoft: { light: '#f1f5f9', dark: '#1d293d' },
+  },
+}
+
+/**
+ * 解析当前实际生效的主色。
+ *
+ *   - 用户显式选过色（colorPrimaryCustom）→ colorPrimary；
+ *   - 否则：shadcn 风格用该风格的内置中性主色（按明暗），default 风格仍用 colorPrimary
+ *     （保持旧行为，避免"用户此前存下的自定义色因缺少 colorPrimaryCustom 标记被重置"）。
+ *
+ * 规则集中在这里，供 update-css-variables 与偏好面板取色器共用，避免两处漂移。
+ */
+export function resolvePrimaryColor(
+  theme: { colorPrimary: string; colorPrimaryCustom: boolean },
+  style: StyleType,
+  dark: boolean,
+): string {
+  if (theme.colorPrimaryCustom || style === 'default') return theme.colorPrimary
+  return stylePresets[style].defaultPrimary[dark ? 'dark' : 'light']
+}
diff --git a/code/g3soft-erp/web/src/preferences/types.ts b/code/g3soft-erp/web/src/preferences/types.ts
index 1959ed97..b588e039 100644
--- a/code/g3soft-erp/web/src/preferences/types.ts
+++ b/code/g3soft-erp/web/src/preferences/types.ts
@@ -40,6 +40,15 @@ export type BreadcrumbStyleType = 'background' | 'normal'
 /** 页签风格。 */
 export type TabsStyleType = 'card' | 'chrome' | 'plain'
 
+/**
+ * 应用风格（换皮预设）。
+ *   - default：保持现状（vben 风）
+ *   - shadcn：现代极简（shadcn admin 风）
+ *
+ * 只影响配色/几何等「皮」，不影响布局形态（页签/导航/面包屑的 styleType 各自独立）。
+ */
+export type StyleType = 'default' | 'shadcn'
+
 /** 页面切换动画。 */
 export type PageTransitionType =
   | 'fade'
@@ -53,6 +62,12 @@ export type PageTransitionType =
 export interface ThemePreferences {
   /** 主题色（HSL 三段式，如 '212 100% 45%' 或直接色值） */
   colorPrimary: string
+  /**
+   * 主题色是否由用户显式选择过。
+   * false（默认）→ shadcn 风格下使用该风格的内置中性主色；default 风格沿用 colorPrimary。
+   * true → 两种风格都使用 colorPrimary 里存的具体色值。
+   */
+  colorPrimaryCustom: boolean
   /** 成功色 */
   colorSuccess: string
   /** 警告色 */
@@ -81,6 +96,8 @@ export interface AppPreferences {
   name: string
   /** 布局方式 */
   layout: LayoutType
+  /** 应用风格（换皮预设） */
+  style: StyleType
   /** 内容区左右内边距 */
   contentPadding: number
   /** 动态标题（切换路由时改 document.title） */
@@ -205,8 +222,6 @@ export interface TabbarPreferences {
   wheelable: boolean
   /** 持久化页签（刷新后保留） */
   persist: boolean
-  /** 最大页签数，0 表示不限 */
-  maxCount: number
   /** 开启 keepAlive 缓存 */
   keepAlive: boolean
 }
diff --git a/code/g3soft-erp/web/src/preferences/update-css-variables.ts b/code/g3soft-erp/web/src/preferences/update-css-variables.ts
index b4a194f6..e875cf9e 100644
--- a/code/g3soft-erp/web/src/preferences/update-css-variables.ts
+++ b/code/g3soft-erp/web/src/preferences/update-css-variables.ts
@@ -1,4 +1,5 @@
 import type { Preferences } from './types'
+import { resolvePrimaryColor, stylePresets } from './style-presets'
 
 /**
  * 偏好设置 → CSS 变量。
@@ -37,6 +38,7 @@ export function applyPreferencesToCss(preferences: Preferences): void {
   if (!root) return
 
   const { theme, app, sidebar, header } = preferences
+  const preset = stylePresets[app.style]
 
   // ---- 深色模式：给 html 加 .dark 类，样式里用 .dark { ... } 覆盖变量 ----
   const dark = isDarkTheme(theme.mode)
@@ -49,9 +51,16 @@ export function applyPreferencesToCss(preferences: Preferences): void {
   // 输入框文字发黑看不见，下拉/弹窗底色依旧雪白。
   root.dataset.g3Theme = dark ? 'dark' : 'light'
 
+  // ---- 风格钩子：皮肤样式层按 html[data-g3-style='shadcn'] 覆盖变量 ----
+  // （只能在这里写内联/属性；皮肤样式块负责「非内联」变量，见 styles/skin-shadcn.scss）
+  root.dataset.g3Style = app.style
+
   // ---- 主题色 ----
+  // 主色来源见 resolvePrimaryColor：用户显式选过就用它，否则 shadcn 用内置中性主色。
+  const primary = resolvePrimaryColor(theme, app.style, dark)
+
   const colors: Array<[string, string]> = [
-    ['--g3-color-primary', theme.colorPrimary],
+    ['--g3-color-primary', primary],
     ['--g3-color-success', theme.colorSuccess],
     ['--g3-color-warning', theme.colorWarning],
     ['--g3-color-danger', theme.colorDestructive],
@@ -61,18 +70,20 @@ export function applyPreferencesToCss(preferences: Preferences): void {
   }
 
   // ---- 主色半透明底（选中态背景 / 页签激活态）----
-  // 跟随主题色动态派生：选中背景 = 当前主色 + 15%/20% 透明度，
-  // 这样在偏好里换主题色时，选中背景会一起变，而不是停在写死的蓝色。
-  // 透明度对齐 vben：浅色 15%，深色 20%。
-  root.style.setProperty('--g3-color-primary-soft', toColor(theme.colorPrimary, dark ? 0.2 : 0.15))
+  // default：跟随主题色动态派生（当前主色 + 15%/20% 透明度），换主题色时选中背景一起变。
+  // shadcn：固定用中性 accent 灰 —— shadcn 的选中态是灰底而非主色淡底。
+  const soft = preset.primarySoft?.[dark ? 'dark' : 'light'] ?? toColor(primary, dark ? 0.2 : 0.15)
+  root.style.setProperty('--g3-color-primary-soft', toColor(soft))
 
   // ---- 主色的悬停 / 按下态（@g3soft/ui 的按钮、链接 hover/active 读这两个变量）----
   // 组件库在 @g3soft/tokens 里给的是「种子色 + 90% / 80% 透明度」，而种子色是 #18181b（近黑）：
   // 只覆盖 --g3-color-primary 的话，蓝色按钮 hover 会直接变成黑色。这里按同一套算法跟随主题色。
-  root.style.setProperty('--g3-color-primary-hover', toColor(theme.colorPrimary, 0.9))
-  root.style.setProperty('--g3-color-primary-active', toColor(theme.colorPrimary, 0.8))
+  root.style.setProperty('--g3-color-primary-hover', toColor(primary, 0.9))
+  root.style.setProperty('--g3-color-primary-active', toColor(primary, 0.8))
 
   // ---- 圆角与字号 ----
+  // 注意：--g3-radius-base 目前无消费方（G3 组件读 --g3-radius/-sm/-lg，见
+  // @g3soft/tokens）；shadcn 风格的圆角由 styles/skin-shadcn.scss 覆盖 --g3-radius* 实现。
   root.style.setProperty('--g3-radius-base', `${theme.radius}rem`)
   root.style.setProperty('--g3-font-size-base', `${theme.fontSize}px`)
 
diff --git a/code/g3soft-erp/web/src/stores/app.ts b/code/g3soft-erp/web/src/stores/app.ts
index 1ca8c786..1ceb58e7 100644
--- a/code/g3soft-erp/web/src/stores/app.ts
+++ b/code/g3soft-erp/web/src/stores/app.ts
@@ -19,11 +19,8 @@ export interface TabItem {
   affix?: boolean
 }
 
-/**
- * 存储键带版本号：页签结构变更（如 v1 的 name/path → v2 的 key/fullPath）时递增，
- * 旧键直接废弃 —— 仓库约定不兼容历史持久化数据，不做迁移。
- */
-const STORAGE_KEY = 'g3erp:app:v2'
+/** 页签持久化存储键 */
+const STORAGE_KEY = 'g3erp:app'
 
 export const useAppStore = defineStore(
   'app',
@@ -35,9 +32,15 @@ export const useAppStore = defineStore(
      * keep-alive 的 include 列表：已打开页签的 fullPath。
      * 与 g3hd2026 的 tab.cachedKeys 同源 —— KeepAlive 按组件 name（= fullPath 字符串）
      * 匹配缓存，绕开「异步组件 vnode.type 引用不稳定」导致缓存失效的问题。
-     * 开页签 push、关页签 splice，保证缓存槽与页签严格同步（关闭即销毁实例，不泄漏）。
+     *
+     * 【从 tabs 派生，而不是单独维护一份 ref】：
+     * 曾用「ref + 开页签 push / 关页签 prune」的写法，会与 tabs 漂移 ——
+     * hydrateTabs 恢复 tabs 时不会恢复 cachedKeys，且 addTab 对"已存在的页签"直接 return，
+     * 于是刷新后恢复的页签永远进不了 include，KeepAlive 匹配不到 → 缓存失效。
+     * 改为 computed 后二者天然一致：关闭页签会随之移出，KeepAlive 的 include watch
+     * 也会照常销毁对应缓存实例，不会泄漏。
      */
-    const cachedKeys = ref<string[]>([])
+    const cachedKeys = computed(() => tabs.value.map((item) => item.key))
 
     /**
      * 路由刷新计数表：key = fullPath，值变化即强制该页签重建组件。
@@ -62,13 +65,10 @@ export const useAppStore = defineStore(
       contentFullscreen.value = !contentFullscreen.value
     }
 
-    /** 打开（或激活）一个页签；已存在则不重复添加，新开则加入缓存列表 */
+    /** 打开（或激活）一个页签；已存在则不重复添加（include 的 cachedKeys 由 tabs 派生） */
     function addTab(tab: TabItem): void {
       if (!tabs.value.some((item) => item.key === tab.key)) {
         tabs.value.push(tab)
-        if (!cachedKeys.value.includes(tab.key)) {
-          cachedKeys.value.push(tab.key)
-        }
       }
     }
 
@@ -77,9 +77,8 @@ export const useAppStore = defineStore(
       const index = tabs.value.findIndex((item) => item.key === key)
       if (index === -1) return undefined
 
+      // 关闭即销毁缓存实例：cachedKeys 由 tabs 派生，移出 tabs 后 include 自动收敛
       tabs.value.splice(index, 1)
-      // 同步移出缓存列表（关闭即销毁缓存实例，避免泄漏）
-      pruneCachedKeys()
       // 优先激活右侧页签，没有则激活左侧
       return tabs.value[index] ?? tabs.value[index - 1]
     }
@@ -87,13 +86,11 @@ export const useAppStore = defineStore(
     /** 关闭除指定页签外的全部（保留 affix） */
     function removeOtherTabs(key: string): void {
       tabs.value = tabs.value.filter((item) => item.affix || item.key === key)
-      pruneCachedKeys()
     }
 
     /** 关闭全部（保留 affix） */
     function removeAllTabs(): void {
       tabs.value = tabs.value.filter((item) => item.affix)
-      pruneCachedKeys()
     }
 
     /** 关闭左侧：指定页签之前的、非 affix 的页签全部移除 */
@@ -101,7 +98,6 @@ export const useAppStore = defineStore(
       const index = tabs.value.findIndex((item) => item.key === key)
       if (index === -1) return
       tabs.value = tabs.value.filter((item, i) => item.affix || i >= index)
-      pruneCachedKeys()
     }
 
     /** 关闭右侧：指定页签之后的、非 affix 的页签全部移除 */
@@ -109,13 +105,6 @@ export const useAppStore = defineStore(
       const index = tabs.value.findIndex((item) => item.key === key)
       if (index === -1) return
       tabs.value = tabs.value.filter((item, i) => item.affix || i <= index)
-      pruneCachedKeys()
-    }
-
-    /** 把缓存列表收敛到当前打开的页签集合（关闭页签后调用，防缓存实例泄漏） */
-    function pruneCachedKeys(): void {
-      const keep = new Set(tabs.value.map((item) => item.key))
-      cachedKeys.value = cachedKeys.value.filter((key) => keep.has(key))
     }
 
     /** 取某页签的刷新计数（未刷新过为 0） */
diff --git a/code/g3soft-erp/web/src/styles/index.scss b/code/g3soft-erp/web/src/styles/index.scss
index 2a996bf1..2278ba55 100644
--- a/code/g3soft-erp/web/src/styles/index.scss
+++ b/code/g3soft-erp/web/src/styles/index.scss
@@ -3,8 +3,10 @@
 // 1) tokens 的 CSS 产物（:root 变量），必须在最前
 // 2) @g3soft/ui 的组件样式
 // 3) 本应用全局样式与 reset
+// 4) 风格层（换皮）：必须最后，才能压过上面几层的同名变量
 
 @use '@g3soft/tokens';
 @use '@g3soft/ui/style.css';
 
 @use './global';
+@use './skin-shadcn';
diff --git a/code/g3soft-erp/web/src/styles/skin-shadcn.scss b/code/g3soft-erp/web/src/styles/skin-shadcn.scss
new file mode 100644
index 00000000..be210bee
--- /dev/null
+++ b/code/g3soft-erp/web/src/styles/skin-shadcn.scss
@@ -0,0 +1,174 @@
+// 风格层：现代极简（shadcn admin）。由偏好 app.style 决定是否命中。
+//
+// 触发钩子：applyPreferencesToCss 写 `html[data-g3-style='shadcn']`。
+//
+// 为什么是样式表 + JS 双管齐下：
+//   - applyPreferencesToCss 用 root.style.setProperty 内联写了 13 个变量（主色系列、
+//     primary-soft、radius-base、字号、布局尺寸），**内联样式压过一切样式表**，
+//     所以那几个必须在 JS 里按风格产出（见 preferences/update-css-variables.ts）。
+//   - 其余变量（tokens 组件令牌族 + 业务外壳族）没有被内联，可以用本文件覆盖。
+//
+// 分层：
+//   1) 变量层（浅色 / 深色）
+//   2) 组件里写死颜色的局部块 —— 必须显式提权（非 scoped <style> 注入顺序不可靠）
+
+// ---------------------------------------------------------------------------
+// 1) 变量层（浅色）
+//    html[data-g3-style='shadcn'] 特异性 (0,2,0) > global.scss 的 .dark (0,1,0)
+// ---------------------------------------------------------------------------
+html[data-g3-style='shadcn'] {
+  // ---- tokens 组件令牌族（@g3soft/ui 组件读这组）----
+  --g3-text-1: #020618;
+  --g3-text-2: #45556c;
+  --g3-text-3: #62748e;
+  --g3-text-disabled: #90a1b9;
+  --g3-text-inverse: #ffffff;
+
+  --g3-bg-container: #ffffff;
+  --g3-bg-disabled: #f1f5f9;
+  --g3-border-color: #e2e8f0;
+
+  // 真正决定 G3 组件圆角的是这三个（--g3-radius-base 无消费方）
+  --g3-radius-sm: 6px;
+  --g3-radius: 8px;
+  --g3-radius-lg: 10px;
+
+  --g3-shadow: 0 1px 2px 0 rgb(0 0 0 / 5%);
+  --g3-shadow-popup: 0 4px 12px -2px rgb(0 0 0 / 12%);
+  --g3-fill: #f1f5f9;
+  --g3-fill-hover: #e2e8f0;
+  --g3-mask-bg: rgb(2 6 24 / 45%);
+
+  // ---- 业务 / 外壳族 ----
+  --g3-color-text: #020618;
+  --g3-color-text-secondary: #45556c;
+  --g3-color-text-tertiary: #62748e;
+  --g3-color-bg: #ffffff;
+  --g3-color-bg-container: #ffffff;
+  --g3-color-border: #e2e8f0;
+  --g3-color-fill-hover: #f1f5f9;
+  --g3-color-primary-bg: #f1f5f9;
+  --g3-color-accent: #f1f5f9;
+  --g3-color-accent-hover: #e2e8f0;
+  --g3-color-foreground: #020618;
+  --g3-color-sidebar: #ffffff;
+  --g3-color-header: #ffffff;
+}
+
+// ---------------------------------------------------------------------------
+// 2) 变量层（深色）
+//    必须逐变量齐全：浅色块 (0,2,0) 高于 global.scss 的 .dark (0,1,0)，
+//    漏项会让深色下漏回浅色值（半 shadcn 半浅色）。
+// ---------------------------------------------------------------------------
+html[data-g3-style='shadcn'].dark {
+  --g3-text-1: #f8fafc;
+  --g3-text-2: #cad5e2;
+  --g3-text-3: #90a1b9;
+  --g3-text-disabled: #62748e;
+  --g3-text-inverse: #020618;
+
+  --g3-bg-container: #0f172b;
+  --g3-bg-disabled: #1d293d;
+  --g3-border-color: rgb(255 255 255 / 10%);
+
+  --g3-shadow: 0 1px 2px 0 rgb(0 0 0 / 40%);
+  --g3-shadow-popup: 0 4px 12px -2px rgb(0 0 0 / 50%);
+  --g3-fill: #1d293d;
+  --g3-fill-hover: #253047;
+  --g3-mask-bg: rgb(0 0 0 / 60%);
+
+  --g3-color-text: #f8fafc;
+  --g3-color-text-secondary: #cad5e2;
+  --g3-color-text-tertiary: #90a1b9;
+  --g3-color-bg: #020618;
+  --g3-color-bg-container: #0f172b;
+  --g3-color-border: rgb(255 255 255 / 10%);
+  --g3-color-fill-hover: #1d293d;
+  --g3-color-primary-bg: #1d293d;
+  --g3-color-accent: #1d293d;
+  --g3-color-accent-hover: #253047;
+  --g3-color-foreground: #f8fafc;
+  --g3-color-sidebar: #020618;
+  --g3-color-header: #020618;
+}
+
+// ---------------------------------------------------------------------------
+// 3) 组件里写死的侧栏深色色板
+//    DefaultLayout / LayoutSidebar / LayoutMixedRail / LayoutMixedColumn 的
+//    `.dark &` 与 `.is-dark` 用字面量（#1d2129 / #2e3238 / #313438），
+//    只改 --g3-color-* 覆盖不到，必须显式提权覆盖 --sidebar-*。
+// ---------------------------------------------------------------------------
+$sidebar-dark: (
+  '--sidebar-bg': #020618,
+  '--sidebar-border': rgb(255 255 255 / 10%),
+  '--sidebar-item-color': #cad5e2,
+  '--sidebar-item-hover-bg': #1d293d,
+  '--sidebar-item-hover-color': #f8fafc,
+  '--sidebar-item-active-bg': #1d293d,
+  '--sidebar-item-active-color': #f8fafc,
+  '--sidebar-muted-color': #90a1b9,
+  '--sidebar-title-color': #f8fafc,
+);
+
+// .layout 是变量宿主（本身无背景），只覆盖变量即可 —— 双列菜单两列从它继承。
+html.dark[data-g3-style='shadcn'] .layout {
+  @each $name, $value in $sidebar-dark {
+    #{$name}: $value;
+  }
+}
+
+// 三个真实的侧栏列：除变量外还直写了 background / border-right-color。
+html[data-g3-style='shadcn'] .layout-sidebar.is-dark,
+html[data-g3-style='shadcn'] .layout-mixed-rail.is-dark,
+html[data-g3-style='shadcn'] .layout-mixed-column.is-dark,
+html.dark[data-g3-style='shadcn'] .layout-sidebar,
+html.dark[data-g3-style='shadcn'] .layout-mixed-rail,
+html.dark[data-g3-style='shadcn'] .layout-mixed-column {
+  @each $name, $value in $sidebar-dark {
+    #{$name}: $value;
+  }
+
+  background: var(--sidebar-bg);
+  border-right-color: var(--sidebar-border);
+}
+
+// ---------------------------------------------------------------------------
+// 4) 半深色顶栏（global.scss 里写死 #1d2129/#2e3238/#f7f8fa）
+// ---------------------------------------------------------------------------
+html[data-g3-style='shadcn'] .semi-dark-header .layout-header {
+  color: #f8fafc;
+  background: #0f172b;
+  border-bottom-color: rgb(255 255 255 / 10%);
+}
+
+// ---------------------------------------------------------------------------
+// 5) 「主色底 + 写死白字」的两处
+//    shadcn 深色下主色是近白（#e2e8f0），白字会压白底看不见。
+//    改用 --g3-color-primary-on（浅色模式=#fafafa / 深色=#18181b），自动取对比色。
+// ---------------------------------------------------------------------------
+html[data-g3-style='shadcn'] .layout-mixed-rail__item.is-active {
+  color: var(--g3-color-primary-on, #fafafa);
+}
+
+html[data-g3-style='shadcn']
+  :is(
+    .login__logo-mark,
+    .layout-sidebar__logo-mark,
+    .layout-header__logo-mark,
+    .layout-mixed-rail__logo-mark
+  ) {
+  color: var(--g3-color-primary-on, #fafafa);
+}
+
+// ---------------------------------------------------------------------------
+// 6) 登录页装饰光晕：默认跟随主色（shadcn 主色近黑时本已中性，
+//    但用户自定义主色后会变彩色）—— 这里固定成中性，保持极简观感。
+// ---------------------------------------------------------------------------
+html[data-g3-style='shadcn'] .login__glow {
+  background: linear-gradient(
+    154deg,
+    rgb(2 6 24 / 6%) 30%,
+    rgb(15 23 43 / 18%) 48%,
+    rgb(2 6 24 / 6%) 64%
+  );
+}
diff --git a/code/g3soft-libs/.changeset/attachment.md b/code/g3soft-libs/.changeset/attachment.md
deleted file mode 100644
index 72759847..00000000
--- a/code/g3soft-libs/.changeset/attachment.md
+++ /dev/null
@@ -1,18 +0,0 @@
----
-'@g3soft/ui': minor
----
-
-新增 `G3Attachment` 附件管理器（分类 / 列表 / 预览三栏）。
-
-**与业务解耦**：组件不发任何请求，只消费 `files` + `categories` 两份数据，用户意图全部以事件抛出；需要组件代跑请求时传 `uploadRequest` / `removeRequest`。
-
-- 布局走 `G3Splitter`：默认「分类 200 + 列表自适应」两栏；`showPreview`（默认 `false`）打开后追加 360 的预览栏。`showCategory` / `showPreview` 为假时对应面板不渲染；预览栏关掉时 `preview` 事件照常抛出，业务可自行开弹窗。
-- 分类用 `G3Tree`，在传入的 `categories` 之上合成「全部」根节点（对外用 `categoryKey === ''` 表示），`categoryChange` 会把原始分类对象一并带出。
-- 上传三条入口：底栏选择、拖拽、`pasteUpload`（opt-in，默认关，避免多实例抢 `document`）。入队前按 `accept` / `maxSize` / `maxCount` 校验，被拒文件走 `invalid` 事件（`info.message` 已按语言包生成）。
-- 待上传队列在列表最前面渲染（带「待上传」标记）；未传 `uploadRequest` 时点上传即抛 `upload` 并清空队列（所有权移交业务），传了则托管请求、失败保留队列可重试。blob 预览地址由组件统一释放。
-- 多选批量下载 / 删除；删除内建确认 `Modal`（`confirmRemove` 可关，不使用命令式 `Modal.confirm`，避免依赖全局挂载容器）；下载默认按 `item.url` 内建触发（`builtinDownload` 可关）。
-- 分页：未传 `total` 视为客户端分页（组件切片），传了则为服务端分页（`files` 即当前页）；`page` / `pageSize` 非受控，不传时组件内部维护。
-- 字段名中性（`id` / `name` / `size` / `ext` / `url` / `categoryId`），业务字段走 `item.raw` 原样回传；文件族配色映射到 `--g3-color-danger` / `success` / `warning` / `primary`，并留 `--g3-attachment-type-*` 供主题覆盖。
-- 视觉与交互按当前设计语言落地：尺寸 / 间距 / 圆角 / 过渡全部走令牌；工具栏整行统一 12px 字 / 24px 控件、高度写死并用 1px 竖线分组，窄面板（容器查询）下文字收成图标，勾选前后高度恒定；操作默认藏在 hover / `:focus-within` 里（`@media (hover: none)` 常显）；空态就是虚线投放区并顺带写明 `accept` / `maxSize` / `maxCount` 限制；待上传队列非空时底栏整块染主色淡底（脏状态）；上传与分页合成一块，不再出现两条并排分隔线；卡片封面用 `aspect-ratio` + `object-fit: cover`，封面底边是 2px 上传进度条；面板之间的分割线常显且收成 1px。
-- 语言包新增 `attachment` 分组（zh-CN / en-US）：**自定义 `Locale` 对象的项目需要补上这一组**，否则类型不完整。
-- 附单测（`src/attachment/Attachment.test.ts` 组件契约 + `file.test.ts` 纯函数）与文档 / 4 个示例，文档见 `docs/content/ui/data/attachment.md`。
diff --git a/code/g3soft-libs/docs/.vitepress/config.mts b/code/g3soft-libs/docs/.vitepress/config.mts
index 145a7443..d4b3c2e9 100644
--- a/code/g3soft-libs/docs/.vitepress/config.mts
+++ b/code/g3soft-libs/docs/.vitepress/config.mts
@@ -170,10 +170,10 @@ export default defineConfig({
           icon: 'table-properties',
           collapsed: false,
           items: [
-            { text: 'Attachment 附件管理器', link: '/ui/data/attachment' },
             { text: 'DatePicker 日期选择', link: '/ui/data/date' },
             { text: 'Pagination 分页器', link: '/ui/data/pagination' },
             { text: 'Splitter 分割面板', link: '/ui/data/splitter' },
+            { text: 'Table 表格', link: '/ui/data/table' },
             { text: 'Tabs 标签页', link: '/ui/data/tabs' },
             { text: 'Tree 树形控件', link: '/ui/data/tree' },
           ],
diff --git a/code/g3soft-libs/docs/content/ui/data/attachment.md b/code/g3soft-libs/docs/content/ui/data/attachment.md
deleted file mode 100644
index 11d2f19d..00000000
--- a/code/g3soft-libs/docs/content/ui/data/attachment.md
+++ /dev/null
@@ -1,234 +0,0 @@
----
-title: Attachment 附件管理器
-description: 分类 / 列表（可选预览）的附件管理面板，上传（选择、拖拽、粘贴）、批量下载删除与分页
----
-
-# Attachment 附件管理器
-
-`Attachment` 是「一个业务对象的附件集合」管理器：左栏分类、中栏文件（卡片 / 列表双视图），支持选择、拖拽、粘贴上传，多选批量下载 / 删除与分页。右栏预览默认关闭，需要时 `show-preview` 打开。
-
-它**不请求任何接口**，也不认识「模块 / 业务主键」这类概念：数据从 `files` / `categories` 进来，用户意图以事件出去；需要组件代跑请求时，传 `uploadRequest` / `removeRequest` 即可。
-
-## 何时使用
-
-- 需要管理某个业务单据 / 项目的附件集合（上传、分类、下载、删除）；
-- 文件可能有很多，需要分类过滤、分页、批量操作；
-- 只需要一个简单的「选择文件」入口时，用 [Input](/ui/form/input) 或原生 `<input type="file">` 更轻。
-
-## 基础用法
-
-给 `files`（附件）和 `categories`（分类，可选）两份数据，上传与删除交给业务：
-
-<demo vue="attachment/basic.vue" />
-
-## 多选与批量操作
-
-没勾选时工具栏只有「全选」；一旦勾选，工具栏浮出「已选 N 项 + 下载 + 删除」。示例关掉了 `builtin-download`，下载只上报事件：
-
-<demo vue="attachment/select.vue" />
-
-## 只读
-
-`readonly` 会隐藏上传 / 删除入口，并让拖拽、粘贴失效，适合审批查看场景：
-
-<demo vue="attachment/readonly.vue" />
-
-## 弹窗用法
-
-附件组件本身不是弹窗，需要弹窗时用 [Modal](/ui/overlay/modal) 包一层即可（高度用 `height` 给）：
-
-<demo vue="attachment/modal.vue" />
-
-## 上传与校验
-
-三种入队方式：点底栏「选择」、把文件拖进列表区、`paste-upload` 打开后在页面任意处 `Ctrl/Cmd + V`。
-
-入队前按 `accept` / `maxSize` / `maxCount` 校验，被拒的文件通过 `invalid` 事件抛出（`info.message` 是组件按当前语言包生成的提示原文，可直接 toast）：
-
-```ts
-function onInvalid(info: AttachmentInvalidInfo) {
-  // reason: 'accept' | 'max-size' | 'max-count'
-  message.warning(info.message)
-}
-```
-
-队列里的文件先渲染在列表最前面（带「待上传」标记），点「上传」后组件把它们交出去：
-
-- **没传 `upload-request`**：emit `upload(files, ctx)`，并**立即清空队列**（文件所有权移交业务）；
-- **传了 `upload-request`**：组件托管请求，期间「上传」按钮 loading；成功后 emit `upload-success(files, result)`，`result` 是数组时自动追加进 `files`；失败 emit `upload-error(err, files)` 且**保留队列**（可重试）。
-
-## 数据契约
-
-列表项的字段是中性的，不含任何业务字段名：
-
-```ts
-const files = ref<AttachmentItem[]>([
-  { id: 12, name: '合同.pdf', size: 512_000, categoryId: 'contract', url: '/files/12.pdf' },
-])
-```
-
-业务侧字段名不同也没关系 —— 组件的所有事件都把原始数据放在 `item.raw` 里原样回传，字段映射写在业务侧的一个 adapter 就够：
-
-```ts
-// 后端行 → 组件项
-const toItem = (row: BfFilesRow): AttachmentItem => ({
-  id: row.subid,
-  name: row.mx_filename,
-  size: Number(row.mx_filesize),
-  ext: row.mx_fileext,
-  url: row.mx_mapfilename,
-  categoryId: row.mx_cate_id,
-  raw: row,
-})
-```
-
-## 分页
-
-两种模式，由 `total` 区分：
-
-| 模式 | 传参 | 行为 |
-| --- | --- | --- |
-| 客户端分页 | 只给 `files` | `files` 是完整列表，组件按 `page` / `pageSize` 自行切片 |
-| 服务端分页 | 再给 `total` | `files` 已经是当前页数据，组件只画不切，翻页靠 `update:page` |
-
-`page` / `pageSize` 是**非受控**的：不传时组件内部维护（默认 1 / 20），传了就完全听你的（`v-model:page-size` 等）。
-
-## API
-
-### Props
-
-| 名称 | 类型 | 默认值 | 说明 |
-| --- | --- | --- | --- |
-| `files` | `AttachmentItem[]` | `[]` | 附件列表，配合 `v-model:files` |
-| `categories` | `AttachmentCategory[]` | `[]` | 分类数据；为空则不渲染左栏 |
-| `categoryKey` | `string \| number` | `''` | 选中分类，`''` 表示「全部」，配合 `v-model:categoryKey` |
-| `showCategory` | `boolean` | `true` | 是否显示左栏（无 `categories` 时自动隐藏） |
-| `showPreview` | `boolean` | `false` | 是否显示右栏预览；关掉时 `preview` 事件照常抛出，可自行开弹窗预览 |
-| `readonly` | `boolean` | `false` | 只读：隐藏上传 / 删除，拖拽与粘贴失效 |
-| `loading` | `boolean` | `false` | 列表加载中 |
-| `categoryLoading` | `boolean` | `false` | 分类加载中 |
-| `selectable` | `boolean` | `true` | 是否可勾选 |
-| `multiple` | `boolean` | `true` | 是否允许多选 |
-| `accept` | `string` | — | 接受的文件类型，同原生 `accept`（支持 `.pdf` / `image/*` / `application/pdf`） |
-| `maxSize` | `number` | `0` | 单文件大小上限（字节），`0` 表示不限制 |
-| `maxCount` | `number` | `0` | 待上传队列上限，`0` 表示不限制 |
-| `pasteUpload` | `boolean` | `false` | 监听 `document` 的粘贴上传（多实例场景请只开一个） |
-| `confirmRemove` | `boolean` | `true` | 删除前二次确认（内建 Modal） |
-| `builtinDownload` | `boolean` | `true` | 依据 `item.url` 内建触发下载；关掉后只上报 `download` |
-| `pagination` | `boolean` | `true` | 是否显示分页（数据不足一页时自动隐藏） |
-| `page` | `number` | — | 当前页，非受控（内部默认 `1`） |
-| `pageSize` | `number` | — | 每页条数，非受控（内部默认 `20`） |
-| `total` | `number` | — | 总条数；**传了即为服务端分页**，`files` 视为当前页 |
-| `pageSizeOptions` | `Array<number \| string>` | `[10, 20, 50, 100]` | 每页条数选项 |
-| `showSizeChanger` | `boolean` | `false` | 显示每页条数切换器 |
-| `height` | `number \| string` | — | 根容器高度，数字按 px；默认撑满父容器（父级无高度时保底 320px） |
-| `uploadRequest` | `(files: File[], ctx: AttachmentUploadContext) => Promise<AttachmentItem[] \| void> \| AttachmentItem[] \| void` | — | 托管上传 |
-| `removeRequest` | `(items: AttachmentItem[]) => Promise<void> \| void` | — | 托管删除 |
-
-### Events
-
-| 名称 | 参数 | 说明 |
-| --- | --- | --- |
-| `update:files` | `(files: AttachmentItem[])` | 删除成功 / 托管上传回填后更新列表 |
-| `update:categoryKey` | `(key: string \| number)` | 分类切换 |
-| `update:page` | `(page: number)` | 翻页 |
-| `update:pageSize` | `(size: number)` | 每页条数变化 |
-| `change` | `(files: AttachmentItem[])` | 列表增删（上传成功 / 删除成功） |
-| `select` | `(items: AttachmentItem[])` | 勾选变化 |
-| `categoryChange` | `(key: string \| number, category: AttachmentCategory \| null)` | 分类切换，带原始分类对象 |
-| `preview` | `(item: AttachmentItem \| null)` | 点击某项预览（翻页同样触发） |
-| `download` | `(items: AttachmentItem[])` | 下载 |
-| `remove` | `(items: AttachmentItem[])` | 用户确认删除且请求成功 |
-| `removeError` | `(error: unknown, items: AttachmentItem[])` | 删除失败 |
-| `upload` | `(files: File[], ctx: AttachmentUploadContext)` | 未传 `uploadRequest` 时把待上传文件交给业务 |
-| `uploadSuccess` | `(files: File[], result: AttachmentItem[] \| void)` | 托管上传成功 |
-| `uploadError` | `(error: unknown, files: File[])` | 托管上传失败（队列保留） |
-| `invalid` | `(info: AttachmentInvalidInfo)` | 文件被 `accept` / `maxSize` / `maxCount` 拒绝 |
-
-### Exposed（通过 ref 调用）
-
-| 名称 | 类型 | 说明 |
-| --- | --- | --- |
-| `selectedItems` | `AttachmentItem[]` | 当前勾选的附件 |
-| `pendingFiles` | `AttachmentPendingFile[]` | 待上传队列 |
-| `openFileDialog()` | — | 打开系统文件选择框 |
-| `clearSelection()` | — | 清空勾选 |
-| `selectAll()` | — | 全选当前页 |
-| `addFiles(files)` | `File[] \| FileList => File[]` | 入队（走 `accept` / `maxSize` / `maxCount` 校验），返回被接受的文件 |
-| `clearPending()` | — | 清空待上传队列（业务自行接管上传时调用） |
-
-### 类型定义
-
-```ts
-interface AttachmentItem {
-  id: string | number
-  name: string
-  size?: number
-  ext?: string
-  url?: string
-  thumbnailUrl?: string
-  categoryId?: string | number
-  status?: 'ready' | 'uploading' | 'error'
-  percent?: number
-  raw?: unknown
-  [key: string]: unknown
-}
-
-interface AttachmentCategory {
-  id: string | number
-  name: string
-  count?: number
-  disabled?: boolean
-  children?: AttachmentCategory[]
-}
-
-interface AttachmentPendingFile {
-  file: File
-  name: string
-  size: number
-  ext: string
-  url?: string
-}
-
-interface AttachmentInvalidInfo {
-  reason: 'accept' | 'max-size' | 'max-count'
-  files: File[]
-  message: string
-}
-
-interface AttachmentUploadContext {
-  categoryId?: string | number
-}
-```
-
-### 样式变量
-
-类型色（图标 + 扩展名那一小块）按文件族取色，全部可覆盖；`--g3-color-*` 未加载时组件自带兜底值：
-
-| 变量 | 说明 |
-| --- | --- |
-| `--g3-attachment-type-image` | 图片：默认 `--g3-color-primary` |
-| `--g3-attachment-type-doc` | 文档（pdf / doc / txt …）：默认 `--g3-color-danger` |
-| `--g3-attachment-type-sheet` | 表格：默认 `--g3-color-success` |
-| `--g3-attachment-type-slide` | 演示：默认 `--g3-color-warning` |
-| `--g3-attachment-type-archive` | 压缩包：默认 `#d98e04`（暗色 `#e0a63c`） |
-| `--g3-attachment-type-media` | 音视频：默认 `#1f9ea8`（暗色 `#38bcc6`） |
-| `--g3-attachment-type-other` | 未知类型：默认 `--g3-text-3` |
-
-其余尺寸 / 间距 / 圆角 / 过渡全部走令牌（`--g3-control-height`、`--g3-space-*`、`--g3-radius*`、`--g3-duration*`），换肤时不需要动组件。
-
-## 实现说明
-
-- **默认两栏，预览按需开**：布局用 [Splitter](/ui/data/splitter)——分类栏固定 200px（150–320 可拖），列表栏自适应（≥280）；`show-preview` 打开后追加 360px（≥280）的预览栏。`showCategory` / `showPreview` 为假时对应面板直接不渲染，只剩两栏或一栏。预览栏关闭时 `preview` 事件照常抛出，业务可以接自己的弹窗 / 抽屉。
-- **面板之间有常显的分割线**：关掉了 Splitter 的 `barOnHover`（默认只在 hover 时显示），并把线宽收成 1px——否则分类栏与卡片区之间看不出边界。拖拽命中区仍是 10px，只是视觉线更细。
-- **工具栏整行同一档规格**：全选（复选框文案）、已选计数、批量按钮统一到 **12px 字 / 24px 控件**（按钮 `size="small"`），高度**写死** `24px + 上下各 8px`——必须用 `height` 而不是 `min-height`：默认 `content-box` 下 `min-height` 只管内容盒，实际高度 = 内容盒 + 上下 padding，勾选前后仍会变。行内元素一律 `flex: none`（不收缩）+ `flex-wrap: nowrap` + `overflow: hidden`。勾选后浮出「｜ 已选 N 项 · 下载 · 删除」，用 1px 竖线把「选择」与「操作」分组——字号一致、控件等高，才不会看着"歪"或空荡。删除与下载用 [Button](/ui/general/button) 的 `danger-outline` / `outline` 变体，在工具栏里有明确边界（`ghost` 的纯文字按钮会像裸文本飘着）。**窄面板**走容器查询（按面板宽度、不是视口宽度）：先收掉按钮文案只留图标，再窄一点连「全选」文案也收起，保证一行永远放得下。
-- **操作藏在 hover 里**：卡片右下角的「下载 / 删除」平时不显示，hover 或键盘聚焦（`:focus-within`）才浮现，`@media (hover: none)` 的触屏设备下常显。工具栏同理——没勾选任何文件时不渲染「下载 / 删除」，只留全选；勾选后浮出「已选 N 项 + 操作」。
-- **空态就是投放区**：虚线框铺满列表区，hover 转主色；文案两行（「暂无文件」+「拖拽文件到此处，或点击选择」），并把 `accept` / `maxSize` / `maxCount` 的限制拼成第三行提示，省得用户上传后才被拒。
-- **底栏是"脏"状态指示**：待上传队列非空时，底栏整块染主色淡底、计数变主色；上传与分页合成同一块（只有一条顶边），不会出现两条并排的分隔线。
-- **分类树用 [Tree](/ui/data/tree)**：`categories` 之上合成了一个「全部」根节点（对外用 `categoryKey === ''` 表示），因此可以给层级数据；`categoryChange` 会把原始分类对象一起带出来。
-- **删除确认是内建 Modal**：不走 `Modal.confirm()` 命令式（那会让组件依赖全局挂载容器）。`confirmRemove` 关掉后直接进请求。
-- **`update:files` 的语义**：受控组件不擅自改数据。删除成功、或托管上传返回数组时，组件会 emit 过滤 / 追加后的新数组，方便 `v-model:files` 一行接上；完全自管数据时忽略它即可。
-- **blob URL 的回收**：待上传图片的本地预览地址由组件创建，在出队、清空、切换分类、卸载时释放，业务无需关心。
-- **上传进度**：`files` 里某项 `status: 'uploading'` 时，卡片封面底边出现 2px 进度条、列表视图在大小列显示细轨 + 百分比（进度值读 `percent`）。
-- **粘贴上传默认关闭**：它监听 `document`，一个页面多个附件组件同时开会互相抢，所以做成显式 opt-in。
-- **RTL**：布局全部用逻辑属性（`inset-inline-start` / `inset-block-end` / `text-align: start` 等），宿主 `<html dir="rtl">` 下自动镜像，分隔条拖拽与键盘方向由 Splitter 的 `useDirection` 处理。
diff --git a/code/g3soft-libs/docs/content/ui/data/table.md b/code/g3soft-libs/docs/content/ui/data/table.md
new file mode 100644
index 00000000..e2ba1b5c
--- /dev/null
+++ b/code/g3soft-libs/docs/content/ui/data/table.md
@@ -0,0 +1,183 @@
+---
+title: Table 表格
+description: 高性能虚拟滚动表格，支持排序、固定列、多选、行内编辑、列宽 / 列序拖拽与行拖拽排序
+---
+
+# Table 表格
+
+`Table` 用于展示结构化数据，底层是 [`stk-table-vue`](https://ja-plus.github.io/stk-table-vue/)，虚拟滚动 / 列宽拖拽 / 列序拖拽 / 区域选择 / 行拖拽排序都由它提供；组件负责**性能门控**、**内部列管理**与**行内编辑态**。
+
+## 何时使用
+
+- 数据量大（成百上千行）且需要滚动流畅时；
+- 需要行内编辑、多选批量操作、列宽 / 列序可调时；
+- 数据量很小、只要一张静态表时，原生 `<table>` 或 [Grid](/ui/general/grid) 更轻。
+
+## 基础用法
+
+给 `columns` 与 `dataSource` 两份数据即可。序号列（`seq`）默认开启，外框与圆角默认有（`bordered`）。
+
+<demo vue="table/basic.vue" />
+
+## 虚拟滚动与性能
+
+组件内置两条门控，**自动**决定是否启用虚拟滚动，不需要业务手动切换：
+
+| 方向 | 阈值 | 低于阈值时 | 原因 |
+| --- | --- | --- | --- |
+| 纵向 | 行数 > 100 | 全量渲染 | 库的虚拟滚动在「行数略多于单屏行数」时会把最后几行算出视口外，必须滚动才可见；行数少时全量渲染没有性能代价，却换来确定性正确的渲染 |
+| 横向 | 列数 > 20 | 关掉横向虚拟 | 库在横向虚拟开启时会把每列宽度钉死为 `minWidth ?? width ?? 100`，未设 `width` 的列会失去「按比例铺满容器」的原生自适应 |
+
+可以用 `virtual` / `virtualX` 关掉，但**不能**把它们强制打开到阈值以下。
+
+<demo vue="table/virtual.vue" />
+
+除了门控，还有三处性能相关设计：
+
+- **无编辑行时不注入 `customCell`**：纯展示列与非编辑态的可编辑列走库的原生 `td` 渲染路径，滚动时每格少一个函数式组件实例；
+- **尺寸变化 150ms 防抖**：折叠动画 / 窗口缩放期间 ResizeObserver 每帧都会通知，逐帧重算会强制 reflow 并重渲染可见行列；组件合并到尺寸稳定后只刷新一次，并区分「仅宽度变化」只重算横向；
+- **选择列用原生 `<input type="checkbox">`**：视觉由 CSS 模拟成 [Checkbox](/ui/form/checkbox) 的外观，但每行不创建组件实例。
+
+## 多选与批量操作
+
+传 `rowSelection` 即在最前注入选择列；`getCheckboxProps` 可禁用个别行（禁用行不计入「全选」的分母）。
+
+<demo vue="table/selection.vue" />
+
+## 排序
+
+列上写 `sorter: true` 即可点表头排序（组件内排序，不请求接口）。`sortType` 决定按数字还是字符串比较，默认字符串；需要自定义规则时 `sorter` 也可以传函数。
+
+<demo vue="table/sorting.vue" />
+
+## 行内编辑
+
+列上加 `editor` 即可编辑：单击单元格进入，`Enter` 确认、`Esc` 取消。
+
+| 编辑器类型 | 说明 |
+| --- | --- |
+| `text` / `number` / `textarea` | 用 [Input](/ui/form/input) 渲染 |
+| `select` | 用 [Select](/ui/form/select) 渲染；`options` 可以是数组，也可以是接收当前行的函数 |
+| `checkbox` | 点击即切换，无需先激活整行；约定 `1` = 选中、`0` = 未选中（与后端 tinyint 对齐） |
+
+编辑器的输入值先写进内部草稿，**失焦才落库并抛出 `change`**。这样每敲一个字符不会触发父级重渲染（否则光标会丢、输入法会断）。用 `editable={false}` 可整体禁用编辑。
+
+<demo vue="table/editable.vue" />
+
+## 操作列
+
+列上加 `actions` 渲染成一排小按钮；`type: 'more'` 的项会收进「更多」下拉。带 `confirm` 的操作先弹确认框，确认后才执行 `onClick`。
+
+操作列建议显式写 `resizable: false`：它的宽度由内容决定，拖了不会落库，列一重建就丢。
+
+<demo vue="table/actions.vue" />
+
+## 列宽、列序与行拖拽
+
+列宽 / 列序拖拽要求用 `v-model:columns` 绑定列定义——否则组件拖完无处回写（松手回弹），会直接关掉这两个功能。行拖拽排序用 `row-draggable`，顺序变化通过 `row-order-change` 回传。
+
+<demo vue="table/resizable.vue" />
+
+## API
+
+### Props
+
+| 名称 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `columns` | `G3TableColumn<T>[]` | `[]` | 列定义，配合 `v-model:columns` 接收拖拽后的回写 |
+| `dataSource` | `T[]` | `[]` | 数据源 |
+| `rowKey` | `string \| (row) => string \| number` | `'id'` | 行唯一键 |
+| `virtual` | `boolean` | `true` | 纵向虚拟滚动总开关（实际是否开启受行数门控） |
+| `virtualX` | `boolean` | `true` | 横向虚拟滚动总开关（实际是否开启受列数门控） |
+| `rowHeight` | `number` | `30` | 行高，同时驱动虚拟滚动计算 |
+| `headerRowHeight` | `number` | `34` | 表头行高 |
+| `bordered` | `boolean \| string` | `true` | 外框圆角描边 + 行分隔线；`false` 时只留行分隔线 |
+| `colResizable` | `boolean \| object` | `true` | 列宽拖拽；未绑定 `v-model:columns` 时自动关闭。可用 `{ disabled: (col) => boolean }` 按列禁用 |
+| `columnDraggable` | `boolean \| object` | `true` | 列序拖拽；同上要求绑定 `v-model:columns` |
+| `rowDraggable` | `boolean` | `false` | 行拖拽排序 |
+| `rowSelection` | `TableRowSelection \| null` | `null` | 多选配置，见下 |
+| `seq` | `boolean \| { title?, width? }` | `true` | 序号列 |
+| `activeRowKey` | `string \| number \| null` | `null` | 当前高亮行 |
+| `editable` | `boolean` | `true` | 行内编辑总开关 |
+| `noDataFull` | `boolean` | `true` | 空态铺满容器高度 |
+| `showOverflow` | `boolean` | `true` | 内容溢出省略 |
+| `autoFitWidth` | `boolean` | `false` | 非横向虚拟时铺满容器宽度（开启后关闭列宽拖拽） |
+| `theme` | `'light' \| 'dark'` | — | 不传则跟随全局主题（`ConfigProvider` / `html[data-g3-theme]`） |
+| `footerData` | `T[]` | `[]` | 表尾数据 |
+| `footerConfig` | `object` | `` | 表尾配置 |
+
+### 列定义 `G3TableColumn<T>`
+
+在 `stk-table-vue` 的列类型基础上扩展；下面只列自有字段，其余（`width` / `minWidth` / `fixed` / `align` / `headerAlign` / `sorter` / `sortType` / `children` / `mergeCells` 等）原样透传。
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `dataIndex` | `keyof T & string` | 取值字段 |
+| `title` | `string` | 表头文字 |
+| `resizable` | `boolean` | 该列是否可拖宽；操作列 / 展开列建议设 `false` |
+| `editor` | `TableEditor<T>` | 行内编辑器，见下 |
+| `actions` | `TableAction<T>[]` | 操作列按钮 |
+| `customCell` | `(props) => VNode \| string` | 自定义单元格渲染（逃生舱），传了就不再自动包装 |
+
+### `editor`
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `type` | `'text' \| 'number' \| 'password' \| 'textarea' \| 'select' \| 'checkbox'` | 编辑器类型 |
+| `options` | `TableSelectOption[] \| ((row) => TableSelectOption[])` | select 选项，可依赖当前行其它字段 |
+| `disabled` | `boolean \| ((row) => boolean)` | 是否禁用该格编辑 |
+| `allowClear` | `boolean` | select 是否可清空，默认 `true` |
+| `emptyValue` | `unknown` | select 清空后落库的值，默认 `null` |
+| `onChange` | `(value, row, col) => void` | 本列值变化回调（早于组件的 `change`） |
+
+### `actions`
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `key` | `string \| number` | 唯一键；`type: 'more'` 的子项用它做下拉 key |
+| `label` | `string` | 文案 |
+| `type` | `'default' \| 'danger' \| 'delete' \| 'more'` | 语义类型 |
+| `icon` | `Component` | 图标组件 |
+| `visible` | `boolean \| ((row) => boolean)` | 是否显示 |
+| `disabled` | `boolean \| ((row) => boolean)` | 是否禁用 |
+| `confirm` | `string \| object` | 二次确认；字符串为标题，对象支持 `title` / `description` / `okText` / `cancelText` / `okType` / `width` / `maskClosable` |
+| `onClick` | `(row) => void` | 点击回调（带 `confirm` 时在确认后执行） |
+| `items` | `TableAction<T>[]` | `type: 'more'` 时的子项 |
+
+### Events
+
+| 名称 | 参数 | 说明 |
+| --- | --- | --- |
+| `update:columns` | `(columns)` | 列宽 / 列序拖拽后回写（内部列已剥离） |
+| `update:selectedRowKeys` | `(keys)` | 勾选变化 |
+| `change` | `(row, col, value)` | 行内编辑的值变化 |
+| `row-order-change` | `(rows, sourceIndex, targetIndex)` | 行拖拽排序完成 |
+| `area-selection-change` | `(ranges)` | 单元格选区变化（行内编辑依赖它） |
+
+### Exposed
+
+| 名称 | 类型 | 说明 |
+| --- | --- | --- |
+| `scrollToRow(rowKey)` | `Promise<void>` | 滚动到指定行 |
+| `editRow(rowKey, focusCol?)` | `Promise<void>` | 滚动到指定行并进入编辑 |
+| `initVirtualScroll()` / `refreshLayout()` | — | 手动重算虚拟滚动布局 |
+| `getSelectedArea()` / `clearSelectedArea()` | — | 读取 / 清空单元格选区 |
+| `setRowExpand(...)` | — | 展开 / 收起行（需配 `expand` 列） |
+
+### Slots
+
+| 名称 | 说明 |
+| --- | --- |
+| `empty` | 空态内容，默认显示「暂无数据」 |
+| `expand` | 展开行内容（需列配置 `type: 'expand'`） |
+
+## 实现说明
+
+- **底层是 `stk-table-vue`**：虚拟滚动、列宽 / 列序拖拽、区域选择、行拖拽、二级表头、固定列、合并单元格都由它实现。组件不重复造这些轮子，只做门控与适配。
+- **库样式已并入 `dist/style.css`**：库的 CSS 是独立文件（其 JS 里不含任何 `.css` import），组件 `@use` 了它，消费方不需要额外引一次第三方样式。
+  - 注意 SCSS 里**不能**写 `@use 'stk-table-vue/lib/style.css'`：带 `.css` 后缀时 Sass 不会内联，只原样输出一条 CSS `@import` 语句，产物里会留下一条浏览器解析不了的裸包路径。去掉后缀才会真正内联。
+- **主题通过覆盖库的 CSS 变量实现**：库把 41 个主题值都做成了 `.stk-table` 作用域内的变量，组件把它们映射到 `--g3-*` 令牌（覆盖层在 `src/table/style/_overrides.scss`）。改变量而不是逐个选择器改样式，库升级时不容易失效。
+- **区域选择按需自注册**：库的单元格区域选择是全局注册的（`registerFeature(useAreaSelection)`），不注册则 `area-selection-change` 永不触发、行内编辑失效。组件库不拥有 app 启动流程，因此**首次挂载时自动注册一次**；需要显式控制时可调用导出的 `registerTableFeatures()`。
+- **`data-testid` 透传到内层**：组件 `inheritAttrs: false`，`$attrs` 落在内层 `StkTable` 上。外框 / 圆角在我们自己的根节点 `.g3-table` 上，写 E2E 时按类名定位根节点。
+- **行编辑态存在 `WeakMap` 里**：按行对象存，不给业务数据打标记；行被回收时状态自动释放。行与行之间切换编辑**不翻转** `editingActive`，避免整表列重建。
+- **RTL**：布局用逻辑属性，带符号位移走 `--g3-dir-sign`；分隔条拖拽与键盘方向由库的 `useDirection` 处理。
diff --git a/code/g3soft-libs/docs/content/ui/form/input.md b/code/g3soft-libs/docs/content/ui/form/input.md
index d94673ee..718f54e1 100644
--- a/code/g3soft-libs/docs/content/ui/form/input.md
+++ b/code/g3soft-libs/docs/content/ui/form/input.md
@@ -157,5 +157,9 @@ export interface InputFocusOptions {
 - **数字模式的取舍**：输入过程保留字符串（否则用户打不出 `12.`），只在 `change` / 失焦时转为 `Number`，空串保持 `''`，避免 `Number('')` 变成 `0`；
 - 光标位置在数字过滤后会重新计算（`setSelectionRange`），因此在中间插入非法字符不会把光标弹到末尾；
 - 多行模式的高度拖拽用 Pointer Events + `requestAnimationFrame` 合并更新，拖拽期间改的是内联 `height`（从小高度往大拖不会跳变）；
-- `placeholder` 等原生属性声明为 prop 是刻意的：容器是 `<div>`，如果不声明，`placeholder` 会作为 fallthrough 属性挂到外层容器上，对真实输入框无效；
+- **`$attrs` 的落点**：根节点是包裹 `<div>`，真正的 `<input>` / `<textarea>` 在内部，所以组件设了 `inheritAttrs: false` 并手工分流 —— 归属输入行为的属性（`id` / `name` / `autocomplete` / 原生事件等）`v-bind` 到**内部控件**，表达布局的 `class` / `style` 留在**包裹层**。这样 `<label for="x">` 能正确聚焦、`@keydown` 的 `event.target` 是真正的输入框；
+- `placeholder` / `autocomplete` / `maxlength` 这类声明为 prop 是历史原因（早期未做 attrs 分流），保留是为了不打断既有调用方 —— 新代码可直接透传原生属性；
 - 聚焦样式用 `--g3-color-primary-ring` 画 2px 外环（而非 `outline`），这样在 `Space` / `Grid` 里不会因为 outline 被相邻元素裁掉。
+
+> 注意：`type` 仅支持 `default` / `password` / `number` / `textarea` 四个值（组件内部据此切换模式与净化逻辑）。传 `url` / `email` 这类原生类型不会生效，会按 `default` 处理 —— 需要在表单里做 URL/邮箱校验时，用 `G3FormItem` 的 `type` 规则。
+
diff --git a/code/g3soft-libs/docs/content/ui/form/rich-text.md b/code/g3soft-libs/docs/content/ui/form/rich-text.md
index 8abc1053..f27e0756 100644
--- a/code/g3soft-libs/docs/content/ui/form/rich-text.md
+++ b/code/g3soft-libs/docs/content/ui/form/rich-text.md
@@ -1,6 +1,6 @@
 ---
 title: RichText 富文本编辑器
-description: 基于 Tiptap 的富文本编辑，支持字体、字号、对齐、文字与背景色、上下标、图片视频上传与表格
+description: 基于 Tiptap 的富文本编辑，支持字体、字号、对齐、文字与背景色、上下标、列表样式、图片视频上传、表格、预览打印、整理格式与源代码
 ---
 
 # RichText 富文本编辑器
@@ -23,12 +23,32 @@ description: 基于 Tiptap 的富文本编辑，支持字体、字号、对齐
 
 ## 工具条
 
-工具条按「一天点几次」而不是「功能重不重要」排布，**始终一行、高度恒定 48px**：
+工具条按「一天点几次」而不是「功能重不重要」排布，并分成 7 组（组间靠**间距**区分，没有分割线）：
 
-- **常驻**（顺序：历史 → 正文格式 → 行内格式 → 对齐 → 颜色 → 列表与插入）：撤销、重做 ｜ 段落格式（正文 / 标题 1-3）｜ 加粗、斜体、下划线 ｜ 对齐（左 / 中 / 右）｜ 字体颜色、背景颜色 ｜ 无序列表、有序列表、链接、图片、插入表格；
-- **收进 `⋯ 更多`**：`字体` / `字号`（二级菜单，选中态跟随光标）、`格式` 组（删除线 / 上标 / 下标 / 引用）、`插入` 组（视频）。菜单项带分组标题与快捷键提示（对着 Tiptap 的真实键位写的，如删除线 `Ctrl+Shift+S`）。
+- **常驻**（顺序：历史 → 段落格式 → 行内格式 → 对齐 → 颜色 → 列表与插入 → 更多）：撤销、重做 ｜ 段落格式（正文 / 标题 1-6）｜ 加粗、斜体、下划线 ｜ 对齐（左 / 中 / 右）｜ 字体颜色、背景颜色 ｜ 无序列表、有序列表、图片、链接、插入表格 ｜ `⋯`；
+- **收进 `⋯ 更多`**：`字体` / `字号`（二级菜单）、`格式` 组（删除线 / 上标 / 下标 / 引用 / **整理格式**）、`插入` 组（视频）、`查看与导出` 组（**预览** / **打印** / **源代码**）。菜单项带分组标题与快捷键提示（对着 Tiptap 的真实键位写的，如删除线 `Ctrl+Shift+S`）。
 
-图标 16px、按钮 32px（等于 `--g3-control-height`）、组内间隙 4px、内边距 8px / 10px（左右 10px 让首列图标与正文的 12px 内边距对齐）；图标前景用 `text-1`（88% 黑）而不是 ghost 按钮默认的 `text-2`（65%），描边保持 lucide 原生粗细 —— 实测「发虚」的主因是浅灰前景而不是线宽，所以只加深颜色、不加重描边。整条工具条自然宽度约 **744px**：760px 以上的容器都是一行，再窄才折行，且折行以「组」为单位，不会把分隔线甩到行首/行尾。表格插入按钮留在工具条上而不是进 `⋯`：它要先选行列，收起后承载不了那个面板。
+> 无序列表 / 有序列表的**样式**不在「更多」里 —— 它们挂在两个列表按钮自己的下拉上（点按钮展开样式面板），见「列表」一节。
+
+图标 **18px**、按钮 32px（等于 `--g3-control-height`）、内边距 8px / 10px。图标前景用 `text-1`（88% 黑）而不是 ghost 按钮默认的 `text-2`（65%），描边保持 lucide 原生粗细 —— 实测「发虚」的主因是浅灰前景而不是线宽，所以只加深颜色、不加重描边。
+
+### 分组与折行
+
+分组用 `role="group"` + `aria-label` 表达语义，**视觉上不画分割线**（对齐 TinyMCE 的 `tox-toolbar__group`）：
+
+```html
+<div role="group" aria-label="行内格式" class="g3-rich-text__group">…</div>
+```
+
+分组容器用了 `display: contents` —— 组的盒子**不参与布局**，组内按钮被提升为工具条的直接 flex 项，因此**折行以按钮为单位**，每行都会填满、不会出现「整组被推到下一行、右边空一大片」。代价是间距不能再用组的 padding / `gap` 表达，改由按钮的 `margin-inline-end` 承担：组内 2px、组间 12px（6 倍对比构成分组感）。
+
+> 用 `flex-wrap: wrap` + `min-width: 0` 给组**做不到**按按钮折行：组对工具条来说始终是一个不可分割的 flex 项，`flex-wrap` 只影响组内部如何排列。
+
+### 键盘操作
+
+工具条是 `role="toolbar"` 的**单个 Tab 停靠点**（ARIA 作者实践）：`Tab` 进入工具条后，用 **`←` / `→`** 在按钮间移动（两端循环），**`Home` / `End`** 跳到首 / 尾，再 `Tab` 离开落到正文。RTL 下左右键按屏幕方向解释。这样避免「20 多个按钮各占一个 Tab 位、键盘用户要按二十几次才能穿过工具条」。
+
+内部用 roving tabindex 实现：焦点所在按钮 `tabindex=0`，其余 `-1`；按钮的禁用态（撤销 / 重做、图片上的对齐）变化后会重新归一化，不会出现「全部 -1 导致 Tab 进不来」。
 
 ## 对齐与颜色
 
@@ -38,7 +58,22 @@ description: 基于 Tiptap 的富文本编辑，支持字体、字号、对齐
 - **字体颜色**（`A` 图标 + 当前色条）：写 `color`；
 - **背景颜色**（荧光笔图标 + 当前色条）：写 `background-color`。
 
-两个取色按钮都是「图标 + 当前色条」的形式，色条显示选区当前的颜色（未设色时是空位）。点开后是预设色板面板：常用色一屏排满，`无颜色` 清除该属性，右侧彩虹色块打开系统取色器选任意颜色。选完色面板自动收起。
+两个取色按钮都是「图标 + 当前色条」的形式，色条显示选区当前的颜色（未设色时是空位）。点开后是预设色板面板：常用色一屏排满（24px 色块），`无颜色` 清除该属性，右侧彩虹色块打开系统取色器选任意颜色。选完色面板自动收起。
+
+### 换一套色板
+
+预设色板走 CSS 变量（`--g3-rich-text-swatch-text-1..10` / `--g3-rich-text-swatch-bg-1..10`），宿主可在任意祖先上覆盖，**不需要改组件代码、不需要发版**：
+
+```css
+/* 换成品牌色板 */
+.g3-rich-text__toolbar {
+  --g3-rich-text-swatch-text-5: #ff4d4f;
+}
+```
+
+变量化只解决「可覆盖」，默认色值不变（仍是 Ant Design 的 6 号色 / 1 号色）。**暗色主题下不会自动换一套色值** —— 正文颜色是文档内容的一部分，同一份 HTML 在不同主题下显示成不同颜色会让「所见即所得」失效；需要暗色调色板的宿主自行覆盖这些变量。
+
+色板显示走变量，但**写进文档的始终是解析后的具体颜色**（`rgb(...)`），不会把 `var(--g3-…)` 存进 HTML：邮件正文、复制出去的内容、别人家的页面都没有这个变量，存变量会渲染成透明或黑色。
 
 ## 图片 / 视频上传
 
@@ -57,6 +92,129 @@ type Upload = (file: File) => Promise<{
 }>
 ```
 
+## 链接
+
+工具条「链接」按钮弹出一个输入面板（不是 `window.prompt`），两个字段：**链接地址** 与 **显示文字**。填好后回车或点「确定」应用。两个输入框都**不设 placeholder** —— 字段名已经说明要填什么，示例文案属于噪音。
+
+**操作区**（一行，「取消 / 确定」始终靠右成组）：
+
+| 位置 | 按钮 | 说明 |
+| --- | --- | --- |
+| 左 | 移除链接 | 仅光标已在链接上时出现；危险语义与主操作分开，不让它和「确定」挨着 |
+| 右 | 取消 | Ghost 低强调，关闭面板且**不写入文档** |
+| 右 | 确定 | Primary 主操作；**只要地址非空就可用**（见下） |
+
+按钮用**默认尺寸**（32px，等于 `--g3-control-height`）而不是 `size="small"`（24px）：这是面板里唯一的决定动作，24px 在弹层里偏小，且无法与 `G3Input` 的 32px 等高、同一行里不齐平。用 `justify-content: space-between` 而非各组均分，是为了让**「确定」的位置在编辑态 / 非编辑态下始终不变**（编辑态左侧多出「移除链接」，靠右的主操作不该被挤动）。
+
+**「显示文字」不是必填**（只填地址就能提交）。链接文字按「填的显示文字 → 选中文字 → 地址本身」依次兜底，因此最后一种情况下链接文字就是 URL：
+
+| 场景 | 「显示文字」的行为 |
+| --- | --- |
+| 有选中文字 | 预填选中的文字；改成别的内容即**替换选中文字**；留空则**沿用原文字** |
+| 空选区（光标停在某处） | 作为**链接文字插入**（等价于「先打字再选中」）；留空则用**地址本身**当文字 |
+| 光标已在链接上 | 预填该链接的文字；改它就替换链接文字，留空则只改地址 |
+
+其他规则：
+
+- **地址不带协议时自动补 `https://`**：`example.com` → `https://example.com`；已是完整 URL、`#` 锚点、`/` 站内路径、`mailto:` 的一律不动；
+- **光标已在链接上**：面板预填当前地址与链接文字，并多出一个「移除链接」按钮；
+- 为防 XSS，只有 `http` / `https` / `mailto` / `tel` / `#` / `/` 开头的地址会被写入。
+
+### 右键菜单
+
+在正文的**链接**上右键，会在鼠标位置弹出操作菜单（在非链接处右键仍走浏览器原生菜单）：
+
+| 菜单项 | 行为 |
+| --- | --- |
+| 编辑链接 | 打开链接面板并预填该链接的地址与文字 |
+| 打开链接 | 新标签页打开（带 `noopener,noreferrer`） |
+| 删除链接 | **只去掉链接、保留文字**（想连文字一起删，用选中 + `Delete` 更直接） |
+
+菜单作用于**右键落点**那条链接，而不是当前光标所在处 —— 右键不一定移动光标，直接按选区操作会删错链接。
+
+## 列表
+
+工具条上的「无序列表 / 有序列表」是**分裂按钮**（对齐 TinyMCE 的 `bullist` / `numlist`）：**点图标 = 一键建 / 撤列表**，**点右侧箭头 = 打开样式面板**：
+
+| 面板 | 档位 |
+| --- | --- |
+| 无序列表 | 默认、实心圆点、空心圆圈、实心方块 |
+| 有序列表 | 默认、小写字母、小写罗马数字、小写希腊字母、大写罗马数字、大写字母 |
+
+样式面板里每一项画成**缩略图**（三条内容线 + 左侧真实的项目符号 / 编号，与 TinyMCE 图标同一画法），下方标注档位名，**一眼扫过就能分辨**，不需要记住 `disc` / `circle` / `square` 这些英文枚举。当前档位打勾并高亮。
+
+点某一档即把光标所在的列表设成该样式；**光标不在列表里时会先建列表再设样式** ——「想插一个方块列表」一次选择即可，不必先点无序列表再挑样式（内部是两个事务：建列表 + 设样式，按两次 `Ctrl+Z` 依次退回）。
+
+### 样式存成属性，不存成类名
+
+样式写进文档的是 **HTML 属性**（`<ul type="square">` / `<ol type="I">`），而不是 `class="g3-list-square"`。属性是自描述的：导出的 HTML 到邮件客户端、别人家的页面都保持原样；用类名的话离开本组件的样式表就退化成默认圆点，而富文本正文的第一要求是「导出即正确」。
+
+**小写希腊字母是唯一例外**：`<ol type="lower-greek">` 不是合法的 HTML 属性值（`<ol type>` 只认 `1 / a / A / i / I`），浏览器会当作未知值忽略、静默退回数字编号。这一档改用 `style="list-style-type: lower-greek"` 表达。组件的 `OrderedListWithGreek` 扩展补齐了官方 Tiptap 在这条路上的两个缺口（读回时不认 `lower-greek`、写出时会生成非法的 `type` 属性），因此这一档与其它档位一样能完整往返。
+
+### 自定义档位
+
+`bullet-list-types` / `ordered-list-types` 可传自己的选项（结构与 `{ label, value, glyph }` 一致），用于裁剪档位或本地化文案：
+
+```vue
+<G3RichText v-model="html" :bullet-list-types="[{ label: '默认', value: '', glyph: '•' }]" />
+```
+
+不传时用内置的 `DEFAULT_BULLET_LIST_TYPES` / `DEFAULT_ORDERED_LIST_TYPES`（已从包入口导出，便于在其基础上裁剪）。
+
+## 预览 / 打印
+
+「更多 → 查看与导出」里有两项：
+
+- **预览**：在模态框里按正文的真实排版**只读**渲染当前 HTML（标题层级、列表、表格、颜色、对齐都与编辑区一致），弹窗里还有一个「打印」按钮；
+- **打印**：**只打印正文**，不带宿主页面的导航、按钮与工具条。
+
+两者都用模态框 / 隐藏 iframe，而不是 `window.open`：嵌入式 WebView 与 iframe 里新窗口常被拦截，点了没反应；模态框复用库内 `G3Modal`，观感与全库一致，E2E 也能直接断言。
+
+### 预览为什么不是「再开一个编辑器」
+
+预览用 `v-html` 直接渲染，而不是把内容塞进第二个 Tiptap 实例：后者会把 ProseMirror 的**编辑态装饰**（空文档占位符、选中节点描边、列宽拖拽手柄）一起带进来，那正是「预览」不想要的。预览区复刻了一份与编辑器内一致的排版规则，保证「编辑时看到的」「预览看到的」「打印出来的」三者一致。
+
+预览打开时会**取一份内容快照**：预览的语义是「看一眼当前成果」，快照也保证了「从预览里打印」与「屏幕上看到的」是同一份内容。
+
+### 打印的实现
+
+用**隐藏 iframe** 装载正文 HTML 后调 `iframe.contentWindow.print()`，而不是直接 `window.print()` 打印整个页面（那会把宿主页面的界面一起打出来）。iframe 用「零尺寸 + 移出视口」隐藏，**不用** `display: none`（部分浏览器会跳过渲染、打印出空白页）也**不用** `visibility: hidden`（会被打印管线继承，同样打出白纸）。打印样式内置一份精简的文档排版（`@page` 页边距、标题层级、表格边框、图片不溢出），表格在纸上用 `table-layout: auto`（纸上没有「拖列宽」，按内容分配才不会把列压成一条缝）。
+
+## 整理格式
+
+「更多 → 格式 → 整理格式」清理**整篇文档**的结构垃圾 —— 它不同于工具条上的橡皮擦（那个只作用于选区的行内记号）：
+
+| 清理项 | 说明 |
+| --- | --- |
+| 空段落 | 粘贴后常见的 `<p></p>` 连排：视觉上是一块空白，但用户按退格删不掉 |
+| 空白文本 | `<p>   </p>` 里那三个空格 —— 让「看起来是空的」段落躲过空段落判断 |
+| 空行内记号 | `<strong> </strong>` 这类挂了个寂寞的 mark（Word 粘贴重灾区） |
+
+判据走**文档模型**（「这个段落节点的 `content.size` 是否为 0」）而不是对 HTML 跑正则：正则会误伤 `<p><span></span></p>` 这类非空段落，也会漏掉带属性的 `<p style="…"></p>`。只删**真正的空** —— 段落里只要还有一个可见字符就原样保留，只含图片 / 视频 / 表格 / 分割线的段落也不受影响（它们的内容不为空）。
+
+清理在**一个事务**里完成：撤销栈里只留一步，按一次 `Ctrl+Z` 即可整体退回。没有任何可清理项时**不会** dispatch（撤销栈不被无谓地污染），并通过 `cleanup` 事件把统计（删了几个空段落、几个空白文本、几个空记号）报给宿主。
+
+## 源代码
+
+「更多 → 查看与导出 → 源代码」打开一个模态框，直接编辑正文的 HTML，点**保存**写回编辑器（对齐 TinyMCE 的 `code` 插件）。
+
+- **保存是显式的**：只有「保存」才写回，改到一半可以直接「取消」关掉；「重置」把草稿恢复成打开时的内容；
+- **写回是一次可撤销的操作**：`Ctrl+Z` 能整体退回改源码之前；
+- **会产生 `source-save` 事件**（参数是写回后的 HTML），宿主可以据此做提示或埋点；
+- **不认识的标签会被过滤**：写回走的是 Tiptap 的 `setContent`，schema 之外的内容会被清洗掉 —— 界面里对此有明确说明。组件只拦「彻底解析失败」的情况（`DOMParser` 抛错时不允许保存），不规范但能解析的写法交给 schema 处理，不假装能完整往返。
+
+也可以不开工具条菜单、由宿主自己唤起（`ref` 调用）：
+
+```vue
+<G3RichText ref="editor" v-model="html" />
+<script setup>
+const editor = ref()
+editor.value?.openSourceCode()
+</script>
+```
+
+<demo vue="rich-text/tools.vue" />
+
 ## 只读 / 禁用
 
 `readonly` 可聚焦可复制但不可编辑；`disabled` 整体灰化不可交互。
@@ -65,19 +223,29 @@ type Upload = (file: File) => Promise<{
 
 ## 表格
 
-工具条「插入表格」按钮弹出行 / 列选择面板（支持关闭表头行）；光标进入表格后，表格下方会浮出就近操作栏：
+工具条「插入表格」按钮弹出**网格选择器**（对齐 TinyMCE / Word）：移入网格即高亮出 `行 × 列` 的矩形区域，下方实时显示尺寸（如 `3 × 4`），点击即插入；支持**单击**与**拖拽划选**两种用法。网格上限 **8 行 × 10 列**，可选范围由网格本身限定，因此不存在「填了非法值再夹回」的问题。面板里还有「包含表头行」勾选（默认勾选）。
+
+光标进入表格后，表格下方会浮出就近操作栏：
 
 - **行**：上方插入行、下方插入行、删除行；
 - **列**：左侧插入列、右侧插入列、删除列；
 - **单元格**：合并单元格、拆分单元格（两个独立按钮，不可用时各自置灰）；
-- **表头**：切换表头列、切换表头单元格；
 - **删除**：整表删除（与增删行列用分隔线隔开，防误点）。
 
 单元格内文字的对齐、颜色在顶部工具条里设置（单元格内容也是普通段落），操作栏不再重复提供。
 
-列宽拖拽：悬停列分隔线出现 `col-resize` 光标，左右拖动调整列宽。拖拽采用 `table-layout: fixed`，**只动被拖列、其余列纹丝不动**（Excel 语义）；列宽以 `colwidth` 属性持久化进 HTML，最小列宽 10px。拖宽后表格总宽超过容器时，在表格容器内横向滚动，不撑破编辑器内容区。`Tab` / `Shift+Tab` 在单元格间跳转，末格 `Tab` 自动追加行。
+列宽拖拽：悬停列分隔线出现 `col-resize` 光标，左右拖动调整列宽。拖拽采用 `table-layout: fixed`，**只动被拖列、其余列纹丝不动**（Excel 语义）；列宽以 `colwidth` 属性持久化进 HTML，最小列宽 10px。`Tab` / `Shift+Tab` 在单元格间跳转，末格 `Tab` 自动追加行。
 
-> 行列数限制为 1–20，超出会在插入时自动夹回，避免一次性生成超大表格卡死编辑器。
+### 为什么插入多列表格不会出滚动条
+
+插入与拖拽对「总宽超出容器」的处理**刻意相反**：
+
+| 时机 | 行为 | 原因 |
+| --- | --- | --- |
+| 插入表格 | 列宽**等比压缩**到容器宽以内 | 刚生成的表由浏览器按内容均分，列一多必然超出；用户要的是「铺满」而不是「横滚」 |
+| 拖拽列宽结束 | **保留**超宽，超出部分在表格容器内横向滚动 | 用户是故意把列拖宽的，压缩等于立刻撤销他的操作（Excel 语义：表格可变宽） |
+
+压缩时目标宽度取 `容器宽 - 1px` —— 这是 `border-collapse: collapse` 的舍入修正：折叠边框下浏览器会在表格外沿各补半像素，声明宽度 1060px 的表实际渲染为 1061px，而只要 `scrollWidth > clientWidth`（哪怕 1px）就会出现滚动条。
 
 ## 获取纯文本
 
@@ -102,6 +270,8 @@ type Upload = (file: File) => Promise<{
 | `uploadVideo` | `(file: File) => Promise<RichTextUploadResult>` | — | 视频上传函数，返回完整元数据 |
 | `fonts` | `RichTextFontOption[]` | 内置字体表 | 「更多」菜单里字体子菜单的选项 |
 | `fontSizes` | `RichTextFontSizeOption[]` | 内置字号表 | 「更多」菜单里字号子菜单的选项 |
+| `bulletListTypes` | `RichTextListTypeOption[]` | 内置 4 档 | 无序列表样式子菜单的选项 |
+| `orderedListTypes` | `RichTextListTypeOption[]` | 内置 6 档 | 有序列表样式子菜单的选项 |
 
 ### Events
 
@@ -112,6 +282,9 @@ type Upload = (file: File) => Promise<{
 | `blur` | `(event: FocusEvent)` | 失去焦点 |
 | `upload-inline` | `(result: RichTextUploadResult, kind: 'image' \| 'video')` | 内联资源上传完成，上报给外层收集 |
 | `upload-error` | `(error: Error, kind: 'image' \| 'video')` | 上传失败 |
+| `source-save` | `(html: string)` | 「源代码」对话框保存并写回后触发（参数为清洗后的 HTML） |
+| `cleanup` | `(result: RichTextCleanupResult)` | 整理格式执行完成（`changed: false` 表示本来就没有可清理的内容） |
+| `print` | `()` | 发起打印（工具条菜单或预览弹窗里的「打印」都会触发） |
 
 ### Exposed（通过 ref 调用）
 
@@ -122,6 +295,12 @@ type Upload = (file: File) => Promise<{
 | `getText` | `() => string` | 纯文本（邮件 text/plain） |
 | `focus` | `() => void` | 聚焦 |
 | `clear` | `() => void` | 清空内容 |
+| `openSourceCode` | `() => void` | 打开「源代码」对话框 |
+| `openPreview` | `() => void` | 打开「预览」对话框 |
+| `print` | `() => void` | 打印正文（只打印正文，不带宿主页面） |
+| `tidyFormat` | `() => RichTextCleanupResult` | 整理格式：清理空段落 / 空白文本 / 空行内记号 |
+
+> 后四个能力寄居在工具条里（按钮与对话框都在工具条组件内）。因此它们需要工具条被渲染 —— `toolbar: false` 时这些方法安全地什么都不做。
 
 ### 类型定义
 
@@ -144,6 +323,21 @@ export interface RichTextFontSizeOption {
   label: string
   value: string
 }
+
+export interface RichTextListTypeOption {
+  label: string
+  /** 写进文档的值：无序对应 <ul type>、有序对应 <ol type>；空串表示「默认」不写属性 */
+  value: string
+  /** 菜单里画出来的真实符号（• / ○ / ■ / a. / I. …） */
+  glyph: string
+}
+
+export interface RichTextCleanupResult {
+  removedEmptyParagraphs: number
+  trimmedBlankTexts: number
+  removedEmptyMarks: number
+  changed: boolean
+}
 ```
 
 ### 样式变量
@@ -157,6 +351,25 @@ export interface RichTextFontSizeOption {
 | `--g3-color-primary-soft` | 主色 12% | 按钮激活底、选中单元格底 |
 | `--g3-rich-text-toolbar-shadow-near` | `rgba(34,47,62,.1)` | 工具条投影近层（`0 2px 2px -2px`，`toolbar="bottom"` 时翻到上方） |
 | `--g3-rich-text-toolbar-shadow-far` | `rgba(34,47,62,.07)` | 工具条投影远层（`0 8px 8px -4px` 弥散） |
+| `--g3-rich-text-swatch-text-1..10` | 见下 | 字体颜色预设色板（10 个） |
+| `--g3-rich-text-swatch-bg-1..10` | 见下 | 背景颜色预设色板（10 个） |
+
+预设色板默认值（文字色取 Ant Design 6 号色、背景色取 1 号色）：
+
+| 序号 | 文字色 | 背景色 |
+| --- | --- | --- |
+| 1 | `#000000` | `#f5f5f5` |
+| 2 | `#434343` | `#fff1f0` |
+| 3 | `#8c8c8c` | `#fff7e6` |
+| 4 | `#bfbfbf` | `#feffe6` |
+| 5 | `#f5222d` | `#f6ffed` |
+| 6 | `#fa8c16` | `#e6fffb` |
+| 7 | `#52c41a` | `#e6f4ff` |
+| 8 | `#1677ff` | `#f0f5ff` |
+| 9 | `#722ed1` | `#f9f0ff` |
+| 10 | `#eb2f96` | `#fff0f6` |
+
+这些变量挂在 `.g3-rich-text__toolbar` 上（不是 `:root`），作用域收紧在组件内；覆盖时在任意祖先上声明即可（就近原则生效）。
 
 ## 实现说明
 
@@ -166,8 +379,21 @@ export interface RichTextFontSizeOption {
 - **对齐**：官方 `@tiptap/extension-text-align`，只挂到 `heading` / `paragraph`，`alignments` 限左中右；面板里是 `toggleTextAlign`，点当前档位即取消；
 - **内容区即编辑区**：`minHeight` / `maxHeight` 作用在内容区上，可编辑区（`.tiptap`）用 `flex: 1 0 auto` 撑满 —— 内容短时整块都能点（点空白即聚焦、光标落到正文末尾），内容长时按内容高度撑开、由内容区滚动且不裁切。注意 EditorContent 会在内容区与可编辑区之间再插一层包裹 DOM，所以 `.tiptap` 上的 `min-height: inherit` 取的是那一层的值（恒为 0），撑不高可编辑区；
 - **聚焦高亮只给正文区**：编辑器获得焦点时（根节点 `:focus-within`），正文区四周亮起 2px 主色内描边，工具条不参与 —— 谁可编辑谁亮。用 `inset box-shadow` 而不是 `border`（不参与布局，聚焦不挤动正文），也不用 TinyMCE 那种 `::after` 覆盖层（正文区就是滚动容器，覆盖层会跟着正文滚走，而滚动容器的阴影不随内容滚动，天然钉在内容盒上）；
-- **工具条密度与「更多」**：按钮 32px（等于 `--g3-control-height`）+ 组内 4px 间隙，字体 / 字号与低频功能收进 `⋯` 菜单，自然宽度从 928px 降到 744px；`⋯` 用 `G3Dropdown` 现成的 `type: 'label'`（分组标题）/ `children`（子菜单）/ `shortcut` / `selected` 能力拼出来，与工具条共用同一份 `ToolButton` 定义，激活态与禁用态一致。菜单内容约 295px，靠 Dropdown 默认的视口上限（`calc(100vh - 48px)`）保证面板内部不出滚动条，不需要额外传 `menuMaxHeight`；
-- **图标分量**：16px 图标 + lucide 原生描边（16px 下约 1.33px），只把前景从 ghost 默认的 `text-2`（65%）提到 `text-1`（88%）。试过描边 2.5 与放大到 24px，都偏重；实测「发虚」的主因是浅灰前景，动颜色这一项性价比最高；
+- **工具条密度与「更多」**：按钮 32px（等于 `--g3-control-height`），字体 / 字号与低频功能收进 `⋯` 菜单；`⋯` 用 `G3Dropdown` 现成的 `type: 'label'`（分组标题）/ `children`（子菜单）/ `shortcut` / `selected` 能力拼出来，与工具条共用同一份 `ToolButton` 定义，激活态与禁用态一致。菜单内容约 295px，靠 Dropdown 默认的视口上限（`calc(100vh - 48px)`）保证面板内部不出滚动条，不需要额外传 `menuMaxHeight`；
+- **工具条分组用 `display: contents`**：组盒子不参与布局，组内按钮被提升为工具条的直接 flex 项，折行才能**以按钮为单位**（否则整组被推到下一行、右边空一大片）。代价是间距改由按钮的 `margin-inline-end` 承担（组内 2px / 组间 12px）。`flex-wrap: wrap` + `min-width: 0` 给组**做不到**这件事 —— 组对工具条始终是一个不可分割的 flex 项；
+- **工具条是可键盘操作的整体**：`role="toolbar"` + roving tabindex，`←` / `→` 漫游、`Home` / `End` 跳首尾。按钮集合用 DOM 查询取得（按钮由多组数据拼出、还有 Dropdown / Popover 的触发器，声明式清单容易漏），DOM 顺序天然等于方向键该走的顺序。禁用态变化后用 `watch(..., { flush: 'post' })` 重新归一化 tabindex —— 否则可能出现「全部 -1」导致 Tab 进不来工具条；
+- **图标分量**：18px 图标 + lucide 原生描边（18px 下约 1.5px），只把前景从 ghost 默认的 `text-2`（65%）提到 `text-1`（88%）。试过描边 2.5、放大到 24px 都偏重；实测「发虚」的主因是浅灰前景，动颜色这一项性价比最高；
+- **段落格式下拉按真实排版渲染**：`headingLevels` 里带 `fontSize` / `fontWeight`，菜单项直接用它们画出「标题 1 是 2em 粗体」的样子，选择变成「看起来像我要的那级」而不是「记住它是几号」。这三个值必须与 `RichText.vue` 里 `.tiptap h1..h6` 的规则一致，否则预览会撒谎。用 `#menu` 插槽而非 `:items`：`DropdownItem` 的图标位只适合小图标，塞整块文字排版会被行高与省略号规则裁掉；
+- **色板可覆盖 / 色值必解析**：预设色板挂 CSS 变量（`--g3-rich-text-swatch-*`）以便宿主换肤，但写进文档的色值在点击时用 `getComputedStyle` 从色块解析成具体 `rgb(...)` —— 正文里存 `var(--g3-…)` 是错的（邮件 / 复制出去的内容没有这个变量）。选中环的判断同样走这套解析（`resolveSwatchColor`），保证「点了哪个色块」与「哪个色块显示为选中」一致；两侧色值的比较先统一归一化成 `rgb()`，否则文档里的 `#f5222d` 与变量渲染出的 `rgb(245,34,45)` 永远对不上；
+- **链接面板替代 `window.prompt`**：prompt 观感割裂（全库只有它用原生弹窗）、无法校验（`javascript: URL` 会被直接写进 href）、嵌入式环境常被拦截、E2E 无法对 UI 断言。改为 `G3Popover` + 「链接地址 / 显示文字」两个输入框，光标已在链接上时多出「移除链接」。地址只放行 `http` / `https` / `mailto` / `tel` / `#` / `/` 开头的值。**可提交性只看地址**（「显示文字」不是必填）：链接文字按「填的显示文字 → 选中文字 → 地址本身」兜底，所以只填地址也能插入，用地址当文字；
+- **改链接文字必须先落文字再选中再加链接**：`insertContent` 会把选区塌缩到插入内容之后，此时直接 `setLink` 挂的是空区间（等于没加），所以要显式 `TextSelection.create` 回选刚落下的文字。而「编辑已有链接」要**分两条路**：文字没变就只 `extendMarkRange` + `setLink` 原地改 href；文字变了要先 `extendMarkRange` 选中整条链接再替换 —— 若照搬「在光标处插入」，会把一个链接**劈成三段**（断点两边各留一段旧 href）；
+- **链接右键菜单**（`LinkMenu.vue`）：在正文的 `<a>` 上右键弹出「编辑链接 / 打开链接 / 删除链接」，带图标。没有复用 `G3Popover` 的 `trigger="contextmenu"` —— 那个模式要求浮层**包住**触发器元素，而 `<a>` 由 ProseMirror 渲染、随时重建，塞不进任何插槽；改用与 `TableMenu` 相同的手法（监听编辑器 DOM 的右键 + `position: fixed` 到鼠标位置 + `popup` 档 z-index）。删除只去链接、保留文字，且操作前把选区移到落点那个 `<a>` 上 —— 右键不一定移动光标，否则会删错链接；
 - **视频自写 node**：Tiptap 官方无视频扩展，`VideoNode.ts` 定义了轻量 `video` block node，输出 `<video controls>` 标签；邮件场景由业务层决定是否降级为「封面图 + 附件」（编辑器不绑定邮件语义）；
 - **内联资源上报**：图片 / 视频上传后 `emit('upload-inline', result, kind)`，外层把 `result` 收集进 `inlines` 数组，与邮件「inline 附件」模型对齐（参考 Email-Vue 的 `@upload-image`）；
-- **依赖策略**：Tiptap 核心走 `peerDependencies`，扩展走 `dependencies`，不把编辑器全家桶强塞给所有 `@g3soft/ui` 使用者。
+- **列表样式走节点属性**：无序写 `<ul type="disc|circle|square">`、有序写 `<ol type="a|i|I|A">`，不写类名 —— 属性自描述，导出的 HTML 离开组件样式表也正确。样式面板挂在两个列表按钮自己的下拉上（**分裂按钮**：点图标 `toggleList` 建/撤列表，点右侧箭头打开 `ListTypeIcon` 画出的 TinyMCE 同款缩略图面板）。点某一档时若光标不在列表里会**先建列表再设样式**。 ⚠️ 这两步**必须分两个事务执行、不能串在同一条 chain 里**：`updateAttributes` 是按 `state.doc`（本次事务开始前的文档）定位目标节点的，串在一起时它扫的还是「还没有列表」的旧文档，会静默什么都不做（表现为「选了方块列表，结果只是建了个默认圆点列表」）。代价是撤销栈里两步，但这正是「建列表」与「调样式」两件事的诚实反映。`updateAttributes` 清样式必须显式传 `null`（Tiptap 的 `type` 默认值是 `null`，传 `undefined` 会被跳过、旧样式留着）；
+- **小写希腊字母要自写扩展**：`<ol type="lower-greek">` 是非法 HTML 值（`<ol type>` 只认 `1 / a / A / i / I`），浏览器会静默退回数字。`OrderedListWithGreek`（`extensions.ts`）在官方 OrderedList 上补了两处：`renderHTML` 对 CSS-only 档位改写 `style="list-style-type: …"` 而不写非法 `type`，`addAttributes().type.parseHTML` 在官方逻辑（不认 `lower-greek`）返回空时补认它。注册时**必须在 StarterKit 里关掉内置的 `orderedList`**，否则同名扩展重复注册会直接报错；
+- **整理格式走文档模型而不是正则**：判据是「块节点的内容里有没有非空文本 / 非叶子节点」（`content.size === 0` 不足以覆盖 `<p><strong> </strong></p>`）。正则会误伤 `<p><span></span></p>`、也会漏掉带属性的空段落。多个待删区间先**归一化合并**再**从后往前**删 —— 嵌套区间（空段落 `[5,8]` 与段内空白文本 `[6,7]`）若只维护一个游标会把外层段落判为「已覆盖」而跳过（这正是初版写的反了的地方）；取消空 mark 的区间要用 `tr.mapping` 映射到删除后的坐标，否则会取消到错误位置。整篇清理合成**一个事务**，撤销栈里只留一步；
+- **预览用 `v-html` 而不是第二个编辑器实例**：后者会把编辑态装饰（占位符、选中节点描边、列宽手柄）一起带进来。预览区复刻一份与 `.tiptap` 一致的排版规则，保证「编辑时 / 预览 / 打印」三者观感一致。打开时取**内容快照**，使「从预览里打印」与「屏幕上看到的」是同一份内容；
+- **打印用隐藏 iframe**：直接 `window.print()` 会把宿主的导航与按钮一起打出来。iframe 用「零尺寸 + 移出视口」隐藏 —— **不能**用 `display: none`（部分浏览器跳过渲染、打印空白），也**不能**用 `visibility: hidden`（会被打印管线继承，同样打出白纸）。`srcdoc` 必须等 `load` 事件后再 `print()`，否则文档还没解析完、打出空白页；清理挂在 `afterprint` 上并用 `setTimeout` 兜底（WebKit 的 `print()` 不阻塞）；
+- **源代码对话框**：只有「保存」写回（改到一半可直接取消），写回走 `setContent` 并保持一次可撤销；校验只用 `DOMParser` 拦「彻底解析失败」，不规范但能解析的写法交给 Tiptap 的 schema 清洗，界面里如实告知「不认识的标签会被过滤」，不假装能完整往返；
+- **依赖策略**：Tiptap 扩展（`@tiptap/extension-*` / `starter-kit`）走 `dependencies`，随 `@g3soft/ui` 自动装上。`@tiptap/extension-list` 是**显式声明**的依赖（`OrderedListWithGreek` 直接 import 它）—— 它虽然也是 `starter-kit` 的传递依赖，但 pnpm 的严格隔离下传递依赖不可直接 import，不声明会在构建时解析失败；`@tiptap/core` / `@tiptap/pm` / `@tiptap/vue-3` 目前在 `devDependencies`，但构建产物会 `import '@tiptap/vue-3'` —— **发布前必须把它们移到 `peerDependencies`（或 `dependencies`）**，否则使用方装包后会报模块缺失。
diff --git a/code/g3soft-libs/docs/content/ui/overlay/dropdown.md b/code/g3soft-libs/docs/content/ui/overlay/dropdown.md
index 1454f9f6..53341fc3 100644
--- a/code/g3soft-libs/docs/content/ui/overlay/dropdown.md
+++ b/code/g3soft-libs/docs/content/ui/overlay/dropdown.md
@@ -52,6 +52,23 @@ description: 点击 / 悬停 / 右键触发的操作列表，支持子菜单与
 
 <demo vue="dropdown/header-slot.vue" />
 
+## 分裂按钮
+
+分裂按钮（对齐 Ant Design 的 `Dropdown.Button` / TinyMCE 的分裂下拉按钮）由 **`G3ButtonGroup` 组合**而成，`Dropdown` 本身不提供 `split` prop：图标按钮是独立的主操作（点它执行动作、不开菜单），箭头按钮是 `Dropdown` 自己的触发器（点它才展开菜单）。边框贴合、首尾圆角、hover 抬层全由 `G3ButtonGroup` 承担，无需自绘分隔线。
+
+```vue
+<G3ButtonGroup>
+  <G3Button @click="onToggleList">无序列表</G3Button>
+  <G3Dropdown>
+    <template #trigger>
+      <G3Button aria-label="无序列表样式"><ChevronDown /></G3Button>
+    </template>
+    <G3DropdownItem item-key="square">实心方块</G3DropdownItem>
+    <G3DropdownItem item-key="circle">空心圆圈</G3DropdownItem>
+  </G3Dropdown>
+</G3ButtonGroup>
+```
+
 ## 键盘操作
 
 菜单打开后焦点会进入菜单容器，因此可以直接用键盘：
diff --git a/code/g3soft-libs/docs/examples/attachment/basic.vue b/code/g3soft-libs/docs/examples/attachment/basic.vue
deleted file mode 100644
index 582b097b..00000000
--- a/code/g3soft-libs/docs/examples/attachment/basic.vue
+++ /dev/null
@@ -1,80 +0,0 @@
-<script setup lang="ts">
-// 最小用法：只喂 files + categories，上传 / 删除交给业务（组件不发请求）
-import { ref } from 'vue'
-import { G3Attachment } from '@g3soft/ui'
-import type { AttachmentCategory, AttachmentItem, AttachmentUploadContext } from '@g3soft/ui'
-
-// 分类（可选）：不给 categories 就只渲染「列表 + 预览」两栏
-const categories: AttachmentCategory[] = [
-  { id: 'contract', name: '合同文件' },
-  { id: 'invoice', name: '发票凭证' },
-  { id: 'photo', name: '现场照片' },
-]
-
-// 内联 SVG，保证文档站离线也能看到图片预览
-const PHOTO = `data:image/svg+xml;utf8,${encodeURIComponent(
-  '<svg xmlns="http://www.w3.org/2000/svg" width="320" height="200"><rect width="320" height="200" fill="#e5e7eb"/><text x="160" y="108" font-size="18" text-anchor="middle" fill="#6b7280">现场照片</text></svg>',
-)}`
-
-const files = ref<AttachmentItem[]>([
-  { id: 1, name: '2026年度框架合同.pdf', size: 512_000, categoryId: 'contract' },
-  { id: 2, name: '供应商报价明细.xlsx', size: 86_000, categoryId: 'invoice' },
-  { id: 3, name: '现场照片.jpg', size: 1_240_000, categoryId: 'photo', url: PHOTO },
-  { id: 4, name: '验收纪要.docx', size: 24_000, categoryId: 'contract' },
-])
-
-const lastEvent = ref('等待操作…')
-
-// 没传 upload-request 时，组件把待上传文件抛出来，落库由业务决定
-function onUpload(incoming: File[], context: AttachmentUploadContext) {
-  files.value = [
-    ...files.value,
-    ...incoming.map((file, index) => ({
-      id: `local-${Date.now()}-${index}`,
-      name: file.name,
-      size: file.size,
-      categoryId: context.categoryId,
-      // 真实项目换成接口返回的地址；示例用 blob 地址即时预览
-      url: URL.createObjectURL(file),
-    })),
-  ]
-  lastEvent.value = `upload：${incoming.map((file) => file.name).join('、')}`
-}
-
-function onRemove(items: AttachmentItem[]) {
-  const removed = new Set(items.map((item) => item.id))
-  files.value = files.value.filter((file) => !removed.has(file.id))
-  lastEvent.value = `remove：${items.map((item) => item.name).join('、')}`
-}
-
-function onDownload(items: AttachmentItem[]) {
-  lastEvent.value = `download：${items.map((item) => item.name).join('、')}`
-}
-
-function onInvalid(info: { message: string }) {
-  lastEvent.value = `invalid：${info.message}`
-}
-</script>
-
-<template>
-  <div>
-    <G3Attachment
-      v-model:files="files"
-      :categories="categories"
-      :height="560"
-      @upload="onUpload"
-      @remove="onRemove"
-      @download="onDownload"
-      @invalid="onInvalid"
-    />
-    <p class="hint">{{ lastEvent }}</p>
-  </div>
-</template>
-
-<style scoped>
-.hint {
-  margin: 8px 0 0;
-  color: #8c8c8c;
-  font-size: 12px;
-}
-</style>
diff --git a/code/g3soft-libs/docs/examples/attachment/modal.vue b/code/g3soft-libs/docs/examples/attachment/modal.vue
deleted file mode 100644
index 2b1c5279..00000000
--- a/code/g3soft-libs/docs/examples/attachment/modal.vue
+++ /dev/null
@@ -1,58 +0,0 @@
-<script setup lang="ts">
-// 弹窗用法：业务自己用 G3Modal 包一层，附件组件并不知道「弹窗」的存在
-import { ref } from 'vue'
-import { G3Attachment, G3Button, G3Modal } from '@g3soft/ui'
-import type { AttachmentItem, AttachmentUploadContext } from '@g3soft/ui'
-
-const open = ref(false)
-
-// 从空列表开始：正好看到空态投放区 → 入队（底栏变"脏"）→ 上传的完整过程
-const files = ref<AttachmentItem[]>([])
-
-const lastEvent = ref('')
-
-function onUpload(incoming: File[], context: AttachmentUploadContext) {
-  files.value = [
-    ...files.value,
-    ...incoming.map((file, index) => ({
-      id: `local-${Date.now()}-${index}`,
-      name: file.name,
-      size: file.size,
-      categoryId: context.categoryId,
-      url: URL.createObjectURL(file),
-    })),
-  ]
-  lastEvent.value = `已加入 ${incoming.length} 个文件`
-}
-
-function onRemove(items: AttachmentItem[]) {
-  const removed = new Set(items.map((item) => item.id))
-  files.value = files.value.filter((file) => !removed.has(file.id))
-  lastEvent.value = `已删除 ${items.length} 个文件`
-}
-</script>
-
-<template>
-  <div>
-    <G3Button @click="open = true">打开附件管理</G3Button>
-    <p class="hint">{{ lastEvent }}</p>
-
-    <!-- 弹窗高度用 vh，附件组件再按 100% 撑满；不给 categories 就只有列表一栏 -->
-    <G3Modal v-model:open="open" title="附件管理" width="80%" :fullscreen="false">
-      <G3Attachment
-        v-model:files="files"
-        height="60vh"
-        @upload="onUpload"
-        @remove="onRemove"
-      />
-    </G3Modal>
-  </div>
-</template>
-
-<style scoped>
-.hint {
-  margin: 8px 0 0;
-  color: #8c8c8c;
-  font-size: 12px;
-}
-</style>
diff --git a/code/g3soft-libs/docs/examples/attachment/readonly.vue b/code/g3soft-libs/docs/examples/attachment/readonly.vue
deleted file mode 100644
index fc2e2563..00000000
--- a/code/g3soft-libs/docs/examples/attachment/readonly.vue
+++ /dev/null
@@ -1,20 +0,0 @@
-<script setup lang="ts">
-// 只读：隐藏上传 / 删除入口，只保留浏览与下载
-import { G3Attachment } from '@g3soft/ui'
-import type { AttachmentItem } from '@g3soft/ui'
-
-const PHOTO = `data:image/svg+xml;utf8,${encodeURIComponent(
-  '<svg xmlns="http://www.w3.org/2000/svg" width="320" height="200"><rect width="320" height="200" fill="#dbeafe"/><text x="160" y="108" font-size="18" text-anchor="middle" fill="#1d4ed8">现场照片</text></svg>',
-)}`
-
-const files: AttachmentItem[] = [
-  { id: 1, name: '立项批复.pdf', size: 320_000 },
-  { id: 2, name: '现场照片.jpg', size: 1_024_000, url: PHOTO },
-  { id: 3, name: '预算表.xlsx', size: 64_000 },
-]
-</script>
-
-<template>
-  <!-- readonly 同时关掉「全选 / 批量删除 / 底栏上传」，拖拽与粘贴也会失效 -->
-  <G3Attachment :files="files" readonly :height="420" />
-</template>
diff --git a/code/g3soft-libs/docs/examples/attachment/select.vue b/code/g3soft-libs/docs/examples/attachment/select.vue
deleted file mode 100644
index 088f3e54..00000000
--- a/code/g3soft-libs/docs/examples/attachment/select.vue
+++ /dev/null
@@ -1,61 +0,0 @@
-<script setup lang="ts">
-// 多选与批量操作：勾选后工具栏浮出「下载 / 删除」，行为全部走事件
-import { ref } from 'vue'
-import { G3Attachment } from '@g3soft/ui'
-import type { AttachmentItem } from '@g3soft/ui'
-
-const files = ref<AttachmentItem[]>([
-  { id: 'a1', name: '设备清单.xlsx', size: 128_000 },
-  { id: 'a2', name: '施工方案.pdf', size: 2_048_000 },
-  { id: 'a3', name: '进度汇报.pptx', size: 640_000 },
-  { id: 'a4', name: '材料验收单.docx', size: 32_000 },
-  { id: 'a5', name: '现场记录.zip', size: 8_192_000 },
-])
-
-const selected = ref<AttachmentItem[]>([])
-const lastEvent = ref('')
-
-function onSelect(items: AttachmentItem[]) {
-  selected.value = items
-}
-
-function onRemove(items: AttachmentItem[]) {
-  const removed = new Set(items.map((item) => item.id))
-  files.value = files.value.filter((file) => !removed.has(file.id))
-  lastEvent.value = `remove：${items.map((item) => item.name).join('、')}`
-}
-
-function onDownload(items: AttachmentItem[]) {
-  // 真实项目里在这里调接口拿签名地址再下载
-  lastEvent.value = `download：${items.map((item) => item.name).join('、')}`
-}
-</script>
-
-<template>
-  <div>
-    <!-- 每页 3 条演示分页；builtin-download 关掉后「下载」只上报事件 -->
-    <G3Attachment
-      v-model:files="files"
-      :height="420"
-      :builtin-download="false"
-      :show-size-changer="true"
-      :page-size="3"
-      :page-size-options="[3, 5]"
-      @select="onSelect"
-      @remove="onRemove"
-      @download="onDownload"
-    />
-    <p class="hint">
-      已选 {{ selected.length }} 个<span v-if="selected.length">：{{ selected.map((item) => item.name).join('、') }}</span>
-      <template v-if="lastEvent"> ｜ {{ lastEvent }}</template>
-    </p>
-  </div>
-</template>
-
-<style scoped>
-.hint {
-  margin: 8px 0 0;
-  color: #8c8c8c;
-  font-size: 12px;
-}
-</style>
diff --git a/code/g3soft-libs/docs/examples/rich-text/tools.vue b/code/g3soft-libs/docs/examples/rich-text/tools.vue
new file mode 100644
index 00000000..dc9b4b8a
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/rich-text/tools.vue
@@ -0,0 +1,39 @@
+<script setup lang="ts">
+// 列表样式 / 预览 / 打印 / 整理格式 / 源代码
+import { ref } from 'vue'
+import { G3Button, G3RichText, G3Space } from '@g3soft/ui'
+import type { RichTextCleanupResult, RichTextExpose } from '@g3soft/ui'
+
+// 内含一段带空段落的正文，便于演示「整理格式」
+const html = ref(
+  '<h2>季度总结</h2><p>本季度完成如下事项：</p><ul type="square"><li><p>上线 A 模块</p></li><li><p>修复 B 缺陷</p></li></ul><ol type="I"><li><p>需求评审</p></li><li><p>技术方案</p></li></ol><p></p><p></p><p>备注：以上内容见附件。</p>',
+)
+
+const editorRef = ref<RichTextExpose | null>(null)
+const cleanupText = ref('')
+
+/** 整理格式：清理空段落 / 空白文本 / 空行内记号，并把统计显示出来 */
+function tidy() {
+  const result: RichTextCleanupResult | undefined = editorRef.value?.tidyFormat()
+  if (!result) return
+  cleanupText.value = result.changed
+    ? `清理了 ${result.removedEmptyParagraphs} 个空段落、${result.trimmedBlankTexts} 处空白文本、${result.removedEmptyMarks} 个空格式`
+    : '没有需要整理的内容'
+}
+</script>
+
+<template>
+  <G3Space vertical :size="12" style="display: flex">
+    <G3Space :size="8">
+      <G3Button size="small" type="outline" @click="tidy">整理格式（ref）</G3Button>
+      <G3Button size="small" type="outline" @click="editorRef?.openPreview()">预览</G3Button>
+      <G3Button size="small" type="outline" @click="editorRef?.print()">打印</G3Button>
+      <G3Button size="small" type="outline" @click="editorRef?.openSourceCode()">源代码</G3Button>
+    </G3Space>
+
+    <!-- 列表样式在「更多 → 无序列表样式 / 有序列表样式」里选 -->
+    <G3RichText ref="editorRef" v-model="html" :min-height="220" />
+
+    <p v-if="cleanupText" style="font-size: 13px; color: #666">{{ cleanupText }}</p>
+  </G3Space>
+</template>
diff --git a/code/g3soft-libs/docs/examples/table/actions.vue b/code/g3soft-libs/docs/examples/table/actions.vue
new file mode 100644
index 00000000..89b9db7c
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/table/actions.vue
@@ -0,0 +1,47 @@
+<script setup lang="ts">
+import { ref } from 'vue'
+import { Pencil, Trash2 } from '@lucide/vue'
+import { G3Message, G3Table } from '@g3soft/ui'
+import type { G3TableColumn, TableRow } from '@g3soft/ui'
+
+// 操作列：列上加 actions 即可，渲染成一排小按钮。
+// - type: 'more' 的项会收进「更多」下拉（这里没配，全部内联显示）
+// - confirm 给字符串或对象时先弹确认框，确认后才执行 onClick
+// - 操作列建议显式写 resizable: false（宽度由内容决定，拖了不落库）
+const columns: G3TableColumn<TableRow>[] = [
+  { dataIndex: 'name', title: '名称', width: 180 },
+  { dataIndex: 'amount', title: '金额', width: 120, align: 'right' },
+  {
+    dataIndex: 'op',
+    title: '操作',
+    width: 160,
+    resizable: false,
+    actions: [
+      {
+        label: '编辑',
+        icon: Pencil,
+        onClick: (row) => G3Message.info(`编辑：${row.name}`),
+      },
+      {
+        label: '删除',
+        icon: Trash2,
+        type: 'danger',
+        confirm: { title: '确认删除', description: '删除后不可恢复，确定继续吗？' },
+        onClick: (row) => G3Message.success(`已删除：${row.name}`),
+      },
+    ],
+  },
+]
+
+const data = ref<TableRow[]>([
+  { id: 1, name: '框架合同', amount: 120000 },
+  { id: 2, name: '采购订单', amount: 86000 },
+  { id: 3, name: '验收单', amount: 43000 },
+])
+</script>
+
+<template>
+  <div style="height: 260px">
+    <G3Table :columns="columns" :data-source="data" />
+  </div>
+</template>
diff --git a/code/g3soft-libs/docs/examples/table/basic.vue b/code/g3soft-libs/docs/examples/table/basic.vue
new file mode 100644
index 00000000..3ab6d1d7
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/table/basic.vue
@@ -0,0 +1,25 @@
+<script setup lang="ts">
+import { ref } from 'vue'
+import { G3Table } from '@g3soft/ui'
+import type { G3TableColumn, TableRow } from '@g3soft/ui'
+
+// 列定义：dataIndex 指向行数据的字段
+const columns: G3TableColumn<TableRow>[] = [
+  { dataIndex: 'name', title: '名称', width: 180 },
+  { dataIndex: 'amount', title: '金额', width: 120, align: 'right' },
+  { dataIndex: 'owner', title: '负责人' },
+]
+
+// seq 默认开启（最前面的序号列），bordered 默认 true
+const data = ref<TableRow[]>([
+  { id: 1, name: '框架合同', amount: 120000, owner: '张三' },
+  { id: 2, name: '采购订单', amount: 86000, owner: '李四' },
+  { id: 3, name: '验收单', amount: 43000, owner: '王五' },
+])
+</script>
+
+<template>
+  <div style="height: 260px">
+    <G3Table :columns="columns" :data-source="data" />
+  </div>
+</template>
diff --git a/code/g3soft-libs/docs/examples/table/editable.vue b/code/g3soft-libs/docs/examples/table/editable.vue
new file mode 100644
index 00000000..3b73b463
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/table/editable.vue
@@ -0,0 +1,50 @@
+<script setup lang="ts">
+import { ref } from 'vue'
+import { G3Table } from '@g3soft/ui'
+import type { G3TableColumn, TableRow } from '@g3soft/ui'
+
+// 行内编辑：列上加 editor 即可。
+// 单击单元格进入编辑；Enter 确认、Esc 取消。值变化通过 change 事件抛出。
+//
+// 编辑器类型：text / number / textarea / select / checkbox
+// checkbox 约定 1 = 选中、0 = 未选中（与后端 tinyint 对齐）。
+const columns: G3TableColumn<TableRow>[] = [
+  { dataIndex: 'name', title: '名称', width: 200, editor: { type: 'text' } },
+  {
+    dataIndex: 'status',
+    title: '状态',
+    width: 140,
+    editor: {
+      type: 'select',
+      options: [
+        { label: '启用', value: 1 },
+        { label: '停用', value: 0 },
+      ],
+    },
+  },
+  { dataIndex: 'enabled', title: '启用', width: 80, editor: { type: 'checkbox' } },
+  { dataIndex: 'qty', title: '数量', width: 120, align: 'right', editor: { type: 'number' } },
+]
+
+const data = ref<TableRow[]>([
+  { id: 1, name: '框架合同', status: 1, enabled: 1, qty: 12 },
+  { id: 2, name: '采购订单', status: 0, enabled: 0, qty: 45 },
+])
+
+const lastChange = ref('')
+
+function onChange(row: TableRow, col: G3TableColumn<TableRow>, value: unknown) {
+  lastChange.value = `${row.name} 的「${col.title}」改为 ${value}`
+}
+</script>
+
+<template>
+  <div>
+    <p style="margin: 0 0 8px; color: #666; font-size: 13px">
+      最近一次修改：{{ lastChange || '（点击单元格试试）' }}
+    </p>
+    <div style="height: 240px">
+      <G3Table :columns="columns" :data-source="data" :seq="false" @change="onChange" />
+    </div>
+  </div>
+</template>
diff --git a/code/g3soft-libs/docs/examples/table/resizable.vue b/code/g3soft-libs/docs/examples/table/resizable.vue
new file mode 100644
index 00000000..6aaa083b
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/table/resizable.vue
@@ -0,0 +1,65 @@
+<script setup lang="ts">
+import { ref } from 'vue'
+import { G3Table } from '@g3soft/ui'
+import type { G3TableColumn, TableRow } from '@g3soft/ui'
+
+// 列宽 / 列序拖拽与「列定义回写」：
+// 两者都要求用 v-model:columns 绑定，否则组件拖完无处回写（松手回弹），
+// 组件检测到没绑定会直接关掉这两个功能。
+const columns = ref<G3TableColumn<TableRow>[]>([
+  { dataIndex: 'name', title: '名称（可拖宽）', width: 200 },
+  { dataIndex: 'amount', title: '金额', width: 140, align: 'right' },
+  { dataIndex: 'owner', title: '负责人', width: 140 },
+  // 操作列声明 resizable: false 后不可拖宽
+  { dataIndex: 'op', title: '操作', width: 100, resizable: false },
+])
+
+// 行拖拽排序：开启后显示拖拽手柄，拖完通过 row-order-change 回传新顺序
+const dragColumns = ref<G3TableColumn<TableRow>[]>([
+  { dataIndex: 'name', title: '名称' },
+  { dataIndex: 'amount', title: '金额', align: 'right' },
+])
+
+const data = ref<TableRow[]>([
+  { id: 1, name: '框架合同', amount: 120000, owner: '张三', op: '—' },
+  { id: 2, name: '采购订单', amount: 86000, owner: '李四', op: '—' },
+  { id: 3, name: '验收单', amount: 43000, owner: '王五', op: '—' },
+])
+
+const dragData = ref<TableRow[]>([
+  { id: 1, name: '第一步', amount: 100 },
+  { id: 2, name: '第二步', amount: 200 },
+  { id: 3, name: '第三步', amount: 300 },
+])
+
+const orderText = ref('')
+
+function onRowOrderChange(rows: TableRow[]) {
+  dragData.value = rows
+  orderText.value = rows.map((row) => row.name).join(' → ')
+}
+</script>
+
+<template>
+  <div>
+    <p style="margin: 0 0 8px; color: #666; font-size: 13px">
+      拖动表头分隔线改列宽、拖表头文字改列序。
+    </p>
+    <div style="height: 240px">
+      <G3Table v-model:columns="columns" :data-source="data" :row-selection="null" />
+    </div>
+
+    <p style="margin: 16px 0 8px; color: #666; font-size: 13px">
+      行拖拽排序：{{ orderText || '（拖动左侧手柄试试）' }}
+    </p>
+    <div style="height: 200px">
+      <G3Table
+        v-model:columns="dragColumns"
+        :data-source="dragData"
+        :seq="false"
+        row-draggable
+        @row-order-change="onRowOrderChange"
+      />
+    </div>
+  </div>
+</template>
diff --git a/code/g3soft-libs/docs/examples/table/selection.vue b/code/g3soft-libs/docs/examples/table/selection.vue
new file mode 100644
index 00000000..50fa92bb
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/table/selection.vue
@@ -0,0 +1,45 @@
+<script setup lang="ts">
+import { ref } from 'vue'
+import { G3Table } from '@g3soft/ui'
+import type { G3TableColumn, TableRow } from '@g3soft/ui'
+
+// 多选：传 rowSelection 即在最前注入选择列。
+// getCheckboxProps 可禁用个别行（禁用行不参与「全选」的分母）。
+const columns: G3TableColumn<TableRow>[] = [
+  { dataIndex: 'name', title: '名称', width: 180 },
+  { dataIndex: 'amount', title: '金额', width: 120, align: 'right' },
+]
+
+const data: TableRow[] = [
+  { id: 1, name: '框架合同', amount: 120000 },
+  { id: 2, name: '采购订单', amount: 86000, locked: true },
+  { id: 3, name: '验收单', amount: 43000 },
+]
+
+const selectedRowKeys = ref<Array<string | number>>([])
+const selectedText = ref('')
+
+function onSelectionChange(keys: Array<string | number>, rows: TableRow[]) {
+  selectedRowKeys.value = keys
+  selectedText.value = rows.map((row) => row.name).join('、')
+}
+</script>
+
+<template>
+  <div>
+    <p style="margin: 0 0 8px; color: #666; font-size: 13px">
+      已选：{{ selectedText || '（无）' }}
+    </p>
+    <div style="height: 260px">
+      <G3Table
+        :columns="columns"
+        :data-source="data"
+        :row-selection="{
+          selectedRowKeys,
+          onChange: onSelectionChange,
+          getCheckboxProps: (row) => ({ disabled: Boolean(row.locked) }),
+        }"
+      />
+    </div>
+  </div>
+</template>
diff --git a/code/g3soft-libs/docs/examples/table/sorting.vue b/code/g3soft-libs/docs/examples/table/sorting.vue
new file mode 100644
index 00000000..36552576
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/table/sorting.vue
@@ -0,0 +1,25 @@
+<script setup lang="ts">
+import { ref } from 'vue'
+import { G3Table } from '@g3soft/ui'
+import type { G3TableColumn, TableRow } from '@g3soft/ui'
+
+// 排序：列上加 sorter: true 即可点表头排序（组件内排，不请求接口）。
+// sortType 决定按数字还是字符串比较，默认按字符串。
+const columns: G3TableColumn<TableRow>[] = [
+  { dataIndex: 'name', title: '名称', width: 180 },
+  { dataIndex: 'amount', title: '金额', width: 140, align: 'right', sorter: true, sortType: 'number' },
+  { dataIndex: 'qty', title: '数量', width: 120, align: 'right', sorter: true, sortType: 'number' },
+]
+
+const data = ref<TableRow[]>([
+  { id: 1, name: '框架合同', amount: 120000, qty: 12 },
+  { id: 2, name: '采购订单', amount: 86000, qty: 45 },
+  { id: 3, name: '验收单', amount: 43000, qty: 7 },
+])
+</script>
+
+<template>
+  <div style="height: 260px">
+    <G3Table :columns="columns" :data-source="data" />
+  </div>
+</template>
diff --git a/code/g3soft-libs/docs/examples/table/virtual.vue b/code/g3soft-libs/docs/examples/table/virtual.vue
new file mode 100644
index 00000000..f88695e9
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/table/virtual.vue
@@ -0,0 +1,33 @@
+<script setup lang="ts">
+import { computed, ref } from 'vue'
+import { G3Table } from '@g3soft/ui'
+import type { G3TableColumn, TableRow } from '@g3soft/ui'
+
+// 性能门控：行数超过 100 才开启纵向虚拟滚动。
+// 组件内部按 dataSource.length 自动判断，业务不需要手动切换 virtual。
+const rowCount = ref(5000)
+const virtualColumns: G3TableColumn<TableRow>[] = [
+  { dataIndex: 'id', title: 'ID', width: 90 },
+  { dataIndex: 'name', title: '名称', width: 200 },
+  { dataIndex: 'value', title: '数值', width: 140, align: 'right' },
+]
+
+const virtualData = computed(() =>
+  Array.from({ length: rowCount.value }, (_, i) => ({
+    id: i + 1,
+    name: `记录 ${i + 1}`,
+    value: (i + 1) * 7,
+  })),
+)
+</script>
+
+<template>
+  <div>
+    <p style="margin: 0 0 8px; color: #666; font-size: 13px">
+      当前 {{ rowCount }} 行 → {{ rowCount > 100 ? '已开启' : '未开启（行数不足 100 时全量渲染）' }}纵向虚拟滚动
+    </p>
+    <div style="height: 320px">
+      <G3Table :columns="virtualColumns" :data-source="virtualData" :seq="false" />
+    </div>
+  </div>
+</template>
diff --git a/code/g3soft-libs/docs/table-design.md b/code/g3soft-libs/docs/table-design.md
new file mode 100644
index 00000000..2bc4f7c6
--- /dev/null
+++ b/code/g3soft-libs/docs/table-design.md
@@ -0,0 +1,285 @@
+# G3Table 设计方案（性能优先）
+
+> 参考实现：`D:\workspace\code\fms\fms-vue\src\components\fms-table`（`FmsTable.vue` 954 行 + 4 个 utils）
+> 底座：`stk-table-vue@1.1.0`（MIT，零运行时依赖、零 peer 依赖，纯 ESM）
+> 状态：**待评审**，确认后再开工
+
+---
+
+## 1. 先讲清楚参考实现到底是什么
+
+这一点决定后面所有取舍，所以放在最前面。
+
+**`FmsTable.vue` 不是一个表格实现，它是 `stk-table-vue` 的一层适配器（约 950 行）。**
+虚拟滚动 / 列宽拖拽 / 列序拖拽 / 区域选择 / 行拖拽排序 / 二级表头 / 固定列 / 合并单元格
+**全部是库的能力**。该文件真正的增量只有四类：
+
+| 类别 | 内容 | 是否值得搬 |
+|---|---|---|
+| **A. 性能门控启发式** | `MIN_VIRTUAL_ROW_COUNT = 100`（行数少时**关**虚拟滚动）、`MIN_VIRTUAL_X_COLUMN_COUNT = 20`、`editingActive` 抑制编辑态下的逐格 `customCell` 注入 | ✅ 这是真正的核心价值，必须搬 |
+| **B. 防抖 / 节流** | resize 150ms trailing 防抖、键盘编辑激活 100ms 合并、rAF 合并同一帧多次通知 | ✅ 直接搬 |
+| **C. 针对 v1.1.0 的 workaround** | `effectiveVirtualX`（库在 virtualX 下会把列宽钉死，破坏原生自适应）、`--bg-border-right` 局部清除、`border-left: none`、`td:has(...)` 补高等 | ⚠️ **不抄注释，按我们自己的验证结论重写** |
+| **D. 业务耦合** | `useAppStore` 取暗色模式、`@/components/ui/*` 直接 import 内部组件 | ❌ 必须替换成 `@g3soft/*` 对应物 |
+
+**C 类是最大的风险。** 该文件里约 15 条注释在描述「与库内部行为作斗争」，它们修的是
+**v1.1.0 特定内部实现**的 bug。整段照搬等于把一堆针对某个版本的补丁搬进我们的库，
+之后库一升级就要重新验证每一条。**正确做法**：只搬 A、B 两类，C 类在实现时逐条实测
+（用 E2E 锁住几何），确认仍然必要才保留，并在注释里写「为什么」而不是「库做了什么」。
+
+---
+
+## 2. 底座集成（已实测确认的四个硬约束）
+
+这些都是我实际读 `node_modules` 确认的，不是假设：
+
+### 2.1 纯 ESM，可直接用
+
+```
+lib/stk-table-vue.js  →  真实 import/export，无 require
+```
+与 `@g3soft/ui` 的 `"type": "module"` + `preserveModules` 兼容。
+`vue` 是裸导入（由宿主解析），**不会被我们打包进去**。
+
+### 2.2 样式是**独立文件**，必须单独引入
+
+实测：`lib/stk-table-vue.js` 与 `StkTable-6OMgH-gT.js` 里**没有任何 `.css` import**。
+fms 在 `src/main.js` 手动 `import 'stk-table-vue/lib/style.css'`。
+
+**对我们的影响（重要）**：`@g3soft/ui` 的产物是 `dist/style.css`（`sideEffects: ["**/*.css"]`）。
+组件库不能要求消费方额外引一次第三方样式。方案：
+
+- 在 `src/table/style/` 下建一个入口，`@import` 库样式 **+** 我们的覆盖层，由 vite 打进 `dist/style.css`；
+- 覆盖层用 `.g3-table__inner.stk-table` 双类选择器（权重 (0,2,1) > 库默认 (0,1,1)），
+  与我们现有「不用 scoped、BEM + `g3-` 前缀」的约定一致。
+
+> 待确认：库样式里是否有 `:root` 级变量可能与 `--g3-*` 冲突。开工第一步先做这件事。
+
+### 2.3 区域选择是**按需注册**的全局副作用
+
+```js
+// fms/src/main.js
+import { registerFeature, useAreaSelection } from 'stk-table-vue'
+registerFeature(useAreaSelection)   // 一次性，mount 之前
+```
+行内编辑依赖 `area-selection-change` 事件，**不注册就没有该事件**。
+
+**对我们的影响**：组件库不拥有 app 启动流程，不能在 bootstrap 里替用户调用。
+方案：在 `G3Table` 内部按需自注册（`registerFeature` 幂等，模块级一次性 flag 包住），
+并额外暴露 `G3Table.registerFeatures()` 供显式控制。避免「组件静默不工作」这类最难查的
+问题——这正好是 `docs-examples.test.ts` 那类隐形失败的同源风险。
+
+### 2.4 完整的 TS 类型可用
+
+`lib/src/StkTable/types/index.d.ts` 导出 `StkTableColumn<T>` / `SortConfig` /
+`AreaSelectionRange` / `CustomCellProps<T>` 等。我们的 `G3TableColumn<T>` 应当
+**`Omit` + 扩展**它，而不是从零重写一遍（重写会随库版本漂移）。
+
+---
+
+## 3. 组件 API
+
+### 3.1 目录结构
+
+```
+packages/ui/src/table/
+  G3Table.vue              # 主组件（对齐 FmsTable.vue 的职责划分）
+  types.ts                 # G3TableColumn / G3TableProps / emits / expose
+  index.ts
+  style/
+    index.scss             # @import 库样式 + 我们的覆盖层
+    _overrides.scss
+  utils/
+    column.ts              # 内部列注入 / 剥离（序号列、选择列、拖拽列）
+    selection.ts           # createSelectionColumn：原生 checkbox，零组件开销
+    actions.ts             # createActionsCell：操作列
+    editable.ts            # createEditableCell：行内编辑
+    focus.ts               # 编辑器焦点恢复 / 草稿保持
+  G3Table.test.ts          # 组件契约
+  utils/*.test.ts          # 纯函数
+```
+
+### 3.2 Props（对齐 fms，命名转 kebab-case，全部走 `withDefaults`）
+
+| prop | 类型 | 默认 | 说明 |
+|---|---|---|---|
+| `columns` | `G3TableColumn<T>[]` | `[]` | 列定义，配合 `v-model:columns`（列宽/列序拖拽回写） |
+| `dataSource` | `T[]` | `[]` | 数据 |
+| `rowKey` | `string \| (row) => key` | `'id'` | 行唯一键 |
+| `virtual` | `boolean` | `true` | 纵向虚拟滚动（**受 §4.1 门控**） |
+| `virtualX` | `boolean` | `true` | 横向虚拟滚动（**受 §4.2 门控**） |
+| `rowHeight` / `headerRowHeight` | `number` | `30` / `34` | 唯一真源，同时驱动虚拟计算与 CSS 变量 |
+| `bordered` | `boolean \| string` | `true` | 自绘外框 + 行分隔线 |
+| `colResizable` | `boolean \| object` | `true` | 列宽拖拽（未绑定 `v-model:columns` 时自动关闭） |
+| `columnDraggable` | `boolean \| object` | `true` | 列序拖拽 |
+| `rowDraggable` | `boolean` | `false` | 行拖拽排序 |
+| `rowSelection` | `object \| null` | `null` | `{ selectedRowKeys, onChange, getCheckboxProps }` |
+| `seq` | `boolean \| object` | `true` | 序号列 |
+| `activeRowKey` | `string \| number \| null` | `null` | 当前高亮行 |
+| `editable` | `boolean` | `true` | 行内编辑总开关 |
+| `noDataFull` / `showOverflow` | `boolean` | `true` | 空态铺满 / 溢出省略 |
+| `autoFitWidth` | `boolean` | `false` | 非横向虚拟时铺满容器 |
+| `theme` | `'light' \| 'dark'` | `undefined` | 不传则跟随全局主题（**按 §4.5 从 ConfigProvider 取，不依赖 pinia**） |
+| `footerData` / `footerConfig` | `array` / `object` | `[]` / `` | 表尾合计 |
+
+### 3.3 Events / Expose
+
+```ts
+// events
+'update:columns' | 'change' (row, col, newValue) | 'row-order-change'
+'update:selectedRowKeys' | 'area-selection-change'
+
+// expose
+scrollToRow(rowKey) | editRow(rowKey, focusCol?) | initVirtualScroll() | refreshLayout()
+getSelectedArea() | clearSelectedArea() | setRowExpand(...)
+```
+
+### 3.4 列定义 `G3TableColumn<T>`
+
+```ts
+export type G3TableColumn<T> = Omit<StkTableColumn<T>, 'customCell'> & {
+  dataIndex: keyof T & string
+  /** 表头/单元格对齐已由 §3.2 的 headerAlign 推断补齐 */
+  /** 行内编辑（首版按「全量对齐」实现） */
+  editor?: {
+    type: 'text' | 'number' | 'select' | 'checkbox' | 'textarea'
+    options?: SelectOption[] | ((row: T) => SelectOption[])  // 选项可依赖同行其它列
+    disabled?: boolean | ((row: T) => boolean)
+    allowClear?: boolean
+    emptyValue?: unknown
+    onChange?: (value, row, col) => void
+  }
+  /** 操作列 */
+  actions?: G3TableAction<T>[]
+  /** 覆盖内置 customCell 渲染（逃生舱） */
+  customCell?: (props: CustomCellProps<T>) => VNode
+  resizable?: boolean   // false = 该列禁止拖宽（操作列/展开列）
+}
+```
+
+---
+
+## 4. 性能策略（本次的核心）
+
+按「收益 ÷ 维护成本」排序，全部来自 A/B 两类：
+
+### 4.1 虚拟滚动门控：行数 ≤ 100 时**关闭**虚拟滚动
+
+```ts
+const MIN_VIRTUAL_ROW_COUNT = 100
+const effectiveVirtual = computed(
+  () => props.virtual && props.dataSource.length > MIN_VIRTUAL_ROW_COUNT,
+)
+```
+**原因（照搬并保留注释）**：库的虚拟滚动在「行数 > 单屏行数」时开启，会导致
+「容器一屏放 18 行、数据 20 行」这种情况下最后几行被虚拟化吞掉、必须滚动才可见——
+一个纯粹的正确性 bug。行数少时全量渲染没有任何性能问题。
+
+### 4.2 横向虚拟门控：列数 ≤ 20 时关闭
+
+**原因**：库在 `virtualX = true` 时会把每列宽度**钉死**为 `minWidth ?? width ?? 100`
+（`cellStyleMap` 的 `--cw` + `width/min-width/max-width` 三重锁），未设 `width` 的列
+会失去「按比例铺满容器」的原生自适应。列数少、总宽不超容器时用不上横向虚拟。
+
+### 4.3 `editingActive`：无编辑行时**不注入** `customCell`
+
+```ts
+// 有行在编辑时列才带 customCell；无编辑行时全部走库原生 td
+const displayColumns = computed(() => {
+  const cols = props.columns.map((c) => resolveCustomCell(c, editingCtx, editingActive.value))
+  // ...
+})
+```
+**这是整个方案里单点收益最大的优化**：纯展示 / 非编辑态的可编辑列不再包裹函数式组件，
+滚动时每格省掉一个组件实例。行与行之间切换编辑**不翻转** `editingActive`，避免整表列重建。
+
+### 4.4 尺寸与键盘防抖
+
+- **resize 150ms trailing 防抖**：折叠动画 / 窗口缩放期间 ResizeObserver 每帧通知，
+  但中间尺寸是瞬态的；逐帧 `initVirtualScroll()` 会每帧强制 reflow 并重渲染可见行列。
+  合并到尺寸稳定后刷新一次。并区分「仅宽度变化」→ 只重算 X 方向。
+- **rAF 合并**同一帧内的多次通知。
+- **键盘编辑 100ms 合并**：按住方向键滚动时全程保持 0 编辑器，松手后再激活；
+  快速离散连按（<150ms）也走防抖，避免每键挂载/卸载整行编辑器。
+
+### 4.5 主题：从 ConfigProvider 取，不依赖 pinia
+
+参考实现用 `useAppStore().darkMode`——那是业务 store。我们改走
+`ConfigProvider` / `documentElement.dataset`（与现有组件一致），
+并保留 `theme` prop 显式覆盖。
+
+### 4.6 零组件开销的选择列
+
+行 checkbox 用**原生 `<input type="checkbox">` + 自绘方框**，不用 `G3Checkbox` 组件。
+每行一个组件实例在滚动时的开销不可接受。样式模拟成 `G3Checkbox` 外观（CSS 层，非组件）。
+
+---
+
+## 5. 与现有约定的对齐（必改项）
+
+| 参考实现 | 我们必须改成 |
+|---|---|
+| `<style scoped>` + 非 scoped 全局覆盖 | **禁止 scoped**（CODEBUDDY.md 明确），全走 `g3-` 前缀 + BEM |
+| `@/components/ui/button` 等直接 import | `G3Button` / `G3Modal` / `G3Select` / `G3Input` |
+| `var(--fms-*)` 业务变量 | `--g3-*` 令牌，**每个都带 fallback** |
+| `useAppStore()` 取主题 | ConfigProvider |
+| `dataIndex` 无类型约束（JS） | 手写 `types.ts` + 泛型 `G3TableColumn<T>` |
+| 无 `resizable: false` 语义 | 保留（操作列/展开列必须禁止拖宽，见 §4.1 注释原因） |
+
+**RTL**：全部用逻辑属性，带符号位移走 `--g3-dir-sign`；水平方向键走
+`horizontalArrowStep(key, direction)`。表头拖拽 / 列序拖拽需单独验 RTL 几何。
+
+---
+
+## 6. 新增依赖
+
+```yaml
+# packages/ui/package.json
+dependencies:
+  stk-table-vue: ^1.1.0
+```
+- MIT，零运行时依赖、零 peer 依赖，纯 ESM，体积可控（主包 ~23KB + 分块 185KB）。
+- **不改** `pnpm-workspace.yaml` 的 `allowBuilds`（该包无安装脚本）。
+- 需确认发布物无 `exports` 字段（实测确实没有），我们按 `lib/stk-table-vue.js` 深路径引用时
+  要留意——**建议用主入口 `import { StkTable } from 'stk-table-vue'`**，样式单独引。
+
+---
+
+## 7. 测试计划
+
+按仓库三层测试约定：
+
+- **L0 类型**：`pnpm --filter @g3soft/ui typecheck`。必须单独跑——`pnpm build` 不 gate 类型错误。
+- **L1/L2 单测**（happy-dom）：
+  - `utils/column.test.ts`：内部列注入 / 剥离、`headerAlign` 推断、列宽回写
+  - `utils/selection.test.ts`：全选 / 半选 / 禁用行 / 筛选后计数
+  - `utils/editable.test.ts`：草稿保持、`notifyChange` 去重、焦点判定矩阵
+  - `G3Table.test.ts`：组件契约（列渲染、门控开关、空态、只读）
+- **L3 E2E**（必须在真浏览器，happy-dom 无布局引擎）：
+  - **虚拟滚动几何**：100 行以下不虚拟、101 行以上虚拟；滚动后行位置正确
+  - **列宽/列序拖拽**：`page.mouse` 前先 `scrollIntoViewIfNeeded()`
+  - **resize 防抖**：容器尺寸变化后不出现中间态抖动
+  - **RTL 几何**：LTR / RTL 各测一次（单侧通过可能是巧合）
+- **playground**：新增可交互元素必须挂 `data-testid`（E2E 只按 testid 找元素）。
+- `tests/docs-examples.test.ts` 会校验文档示例的 prop 契约——**新增示例的 prop 名必须与
+  运行时 props 对账**，写错会被拦（这正是它存在的意义）。
+
+**注意**：`publint` 在 `prepublishOnly` 跑，新增深路径引用可能触发 `exports` 一致性检查失败。
+
+---
+
+## 8. 实施顺序（建议分 4 批，每批可独立验证）
+
+1. **底座打通**：装依赖 → 样式合流进 `dist/style.css` → 最小可渲染表格 → 验证 ESM / 类型 / 主题变量不冲突
+2. **核心只读**：列定义 + 类型 + 虚拟门控（§4.1/4.2）+ 序号列 + 排序 + 固定列 + 空态 + 单测
+3. **交互层**：多选列（§4.6）+ resize/键盘防抖（§4.4）+ 列宽/列序拖拽 + E2E 几何
+4. **编辑与操作**：`editingActive`（§4.3）+ 行内编辑 + 操作列 + 行拖拽 + 表尾合计 + 文档/示例
+
+---
+
+## 9. 待你确认的点
+
+1. **§2.2 样式合流**：接受把库样式打进我们的 `dist/style.css` 吗？（否则消费方要多引一次）
+2. **§2.3 区域选择自注册**：组件内自动注册 vs 暴露显式 API？（我倾向自动 + 显式覆盖）
+3. **§4.1 门控阈值 100 / 20**：沿用，还是按我们的场景调整？
+4. **命名**：`G3Table` / `table`（与现有 `G3Splitter` / `splitter` 一致）
+5. **C 类 workaround**：确认「只搬 A/B、C 类逐条实测」这个原则（避免把版本补丁搬进库）
diff --git a/code/g3soft-libs/packages/ui/e2e/attachment.spec.ts b/code/g3soft-libs/packages/ui/e2e/attachment.spec.ts
deleted file mode 100644
index 09ea892c..00000000
--- a/code/g3soft-libs/packages/ui/e2e/attachment.spec.ts
+++ /dev/null
@@ -1,56 +0,0 @@
-import { expect, test } from '@playwright/test'
-
-/**
- * Attachment 的几何 / 命中类断言 —— happy-dom 没有布局引擎，这些只能在真浏览器里量。
- *
- * 回归背景（都踩过）：
- * 1. 工具栏勾选后浮出批量按钮，一度把整条工具栏撑高、下方内容跟着下移；
- * 2. 分隔线依赖 Splitter 的 barOnHover，默认只在 hover 时显示，
- *    表现为「分类栏右侧看不见边界」。
- */
-test.describe('Attachment 附件管理器', () => {
-  test.beforeEach(async ({ page }) => {
-    await page.goto('/')
-    await page.locator('[data-testid="attachment"]').scrollIntoViewIfNeeded()
-  })
-
-  test('工具栏高度恒定：勾选前后、宽窄面板下都是 40px', async ({ page }) => {
-    // 40 = --g3-control-height-sm(24) + --g3-space-2(8) * 2
-    const EXPECTED_HEIGHT = 40
-
-    for (const testId of ['attachment', 'attachment-narrow']) {
-      const toolbar = page.locator(`[data-testid="${testId}"] .g3-attachment__toolbar`)
-      const before = await toolbar.boundingBox()
-
-      await toolbar.locator('.g3-checkbox').first().click()
-      await expect(toolbar.locator('.g3-attachment__toolbar-count')).toBeVisible()
-      const after = await toolbar.boundingBox()
-
-      expect(before, `${testId}: 工具栏应可测量`).not.toBeNull()
-      expect(after, `${testId}: 工具栏应可测量`).not.toBeNull()
-      expect(before!.height, `${testId}: 未勾选时工具栏高度`).toBe(EXPECTED_HEIGHT)
-      // 勾选后浮出「已选 N 项 + 下载 + 删除」，高度必须纹丝不动
-      expect(after!.height, `${testId}: 勾选后工具栏高度`).toBe(EXPECTED_HEIGHT)
-
-      // 复位，避免影响下一个实例的断言
-      await toolbar.locator('.g3-checkbox').first().click()
-      await expect(toolbar.locator('.g3-attachment__toolbar-count')).toBeHidden()
-    }
-  })
-
-  test('分类栏右侧的分割线常显（不依赖 hover）', async ({ page }) => {
-    const line = page
-      .locator('[data-testid="attachment"] .g3-attachment__splitter .g3-splitter__bar-line')
-      .first()
-
-    await expect(line).toBeVisible()
-
-    const background = await line.evaluate((el) => getComputedStyle(el).backgroundColor)
-    // 默认是 --g3-border-color(#d9d9d9)；只要不是透明的，就说明线是画出来的
-    expect(background).not.toBe('rgba(0, 0, 0, 0)')
-
-    const box = await line.boundingBox()
-    expect(box!.width).toBeLessThanOrEqual(2)
-    expect(box!.height).toBeGreaterThan(100)
-  })
-})
diff --git a/code/g3soft-libs/packages/ui/e2e/rich-text-table.spec.ts b/code/g3soft-libs/packages/ui/e2e/rich-text-table.spec.ts
index b99859d8..fafa3224 100644
--- a/code/g3soft-libs/packages/ui/e2e/rich-text-table.spec.ts
+++ b/code/g3soft-libs/packages/ui/e2e/rich-text-table.spec.ts
@@ -14,13 +14,20 @@ import { expect, test, type Page } from '@playwright/test'
  * 这些都是布局结果，只能放 E2E（happy-dom 没有布局引擎）。
  */
 
-/** 插入表格（cols 为列数，默认 3 行 3 列） */
-async function insertTable(page: Page, cols?: number): Promise<void> {
+/**
+ * 插入表格。
+ *
+ * 面板已从「行数 / 列数」两个数字输入框换成**网格选择器**（对齐 TinyMCE）：
+ * 移入 (rows, cols) 那个格子即高亮对应矩形，点击插入。所以这里改成点格子，
+ * 不再有「插入」按钮需要按。
+ */
+async function insertTable(page: Page, cols = 3, rows = 3): Promise<void> {
   const editor = page.getByTestId('rich-text')
   await editor.scrollIntoViewIfNeeded()
   await editor.locator('button[aria-label="插入表格"]').click()
-  if (cols) await page.locator('.g3-rich-text__table-input').nth(1).fill(String(cols))
-  await page.getByRole('button', { name: '插入', exact: true }).click()
+  const cell = page.locator(`.g3-rich-text__table-grid-cell[data-row="${rows}"][data-col="${cols}"]`)
+  await cell.hover()
+  await cell.click()
   await expect(editor.locator('table')).toHaveCount(1)
   await editor.locator('table').scrollIntoViewIfNeeded()
 }
@@ -145,41 +152,64 @@ test.describe('RichText 表格', () => {
     }
   })
 
-  test('插入表格面板：label 与输入框上下排列且输入框不溢出', async ({ page }) => {
+  test('插入表格面板：网格选择器高亮矩形并实时显示尺寸', async ({ page }) => {
     await page.goto('/')
     const editor = page.getByTestId('rich-text')
     await editor.scrollIntoViewIfNeeded()
     await editor.locator('button[aria-label="插入表格"]').click()
 
-    const fields = page.locator('.g3-rich-text__table-field')
-    // 行数 / 列数 / 包含表头行 三个字段
-    await expect(fields).toHaveCount(3)
+    // 8 行 × 10 列的网格
+    const cells = page.locator('.g3-rich-text__table-grid-cell')
+    await expect(cells).toHaveCount(80)
 
-    // 只对含数字输入框的两个字段做上下排列 + 不溢出校验
-    const geometry = await fields.evaluateAll((els) =>
-      els.flatMap((el) => {
-        const label = el.querySelector('.g3-rich-text__table-label')!.getBoundingClientRect()
-        const input = el.querySelector('.g3-rich-text__table-input')
-        if (!input) return []
-        const rect = input.getBoundingClientRect()
-        return [
-          {
-            labelBottom: label.bottom,
-            inputTop: rect.top,
-            inputWidth: rect.width,
-            fieldWidth: el.getBoundingClientRect().width,
-          },
-        ]
-      }),
+    // 尺寸提示：未悬停时显示默认 3 × 3
+    const label = page.locator('.g3-rich-text__table-grid-label')
+    await expect(label).toHaveText('3 × 3')
+
+    // 悬停 4 行 6 列 → 高亮 24 格，提示同步
+    await page.locator('.g3-rich-text__table-grid-cell[data-row="4"][data-col="6"]').hover()
+    await expect(label).toHaveText('4 × 6')
+    await expect(page.locator('.g3-rich-text__table-grid-cell.is-table-grid-cell-active')).toHaveCount(
+      24,
     )
 
-    expect(geometry).toHaveLength(2)
-    for (const item of geometry) {
-      // 输入框在 label 下方
-      expect(item.inputTop).toBeGreaterThanOrEqual(item.labelBottom)
-      // content-box + width:100% 曾让输入框比容器宽 18px（padding + border）
-      expect(Math.round(item.inputWidth)).toBeLessThanOrEqual(Math.round(item.fieldWidth) + 1)
-    }
+    // 悬停更小的区域 → 高亮随之收缩（不是只增不减）
+    await page.locator('.g3-rich-text__table-grid-cell[data-row="2"][data-col="2"]').hover()
+    await expect(label).toHaveText('2 × 2')
+    await expect(page.locator('.g3-rich-text__table-grid-cell.is-table-grid-cell-active')).toHaveCount(
+      4,
+    )
+  })
+
+  test('插入表格面板：不溢出容器，含表头行勾选可用', async ({ page }) => {
+    await page.goto('/')
+    const editor = page.getByTestId('rich-text')
+    await editor.scrollIntoViewIfNeeded()
+    await editor.locator('button[aria-label="插入表格"]').click()
+
+    const form = page.locator('.g3-rich-text__table-form')
+    const grid = page.locator('.g3-rich-text__table-grid')
+    const formBox = (await form.boundingBox())!
+    const gridBox = (await grid.boundingBox())!
+
+    // 网格必须落在面板内（早期手写样式曾让内容比容器宽 18px）
+    expect(gridBox.width).toBeLessThanOrEqual(formBox.width + 1)
+    expect(gridBox.x).toBeGreaterThanOrEqual(formBox.x - 1)
+
+    // 「包含表头行」默认选中；取消后插入的表首行应为 td 而非 th。
+    // 注意：点击**包裹用的 label**，不能对内部 input 调 uncheck() ——
+    // G3Checkbox 的原生 input 是 1px + opacity:0 + pointer-events:none（视觉由 span 承担），
+    // Playwright 认为它不可见 / 不可交互，uncheck() 会直接超时。
+    const toggleInput = page.locator('.g3-rich-text__table-checkbox input')
+    const toggleLabel = page.locator('.g3-rich-text__table-header-toggle')
+    await expect(toggleInput).toBeChecked()
+    await toggleLabel.click()
+    await expect(toggleInput).not.toBeChecked()
+
+    await page.locator('.g3-rich-text__table-grid-cell[data-row="2"][data-col="2"]').click()
+    await expect(editor.locator('table tr')).toHaveCount(2)
+    await expect(editor.locator('table')).toHaveCount(1)
+    await expect(editor.locator('table tr:first-child th')).toHaveCount(0)
   })
 })
 
@@ -371,7 +401,10 @@ test.describe('RichText 表格 · 操作浮层', () => {
     // 操作栏里已不再出现单元格对齐按钮（对齐统一走顶部工具条）
     await expect(menu.getByRole('button', { name: '单元格居中' })).toHaveCount(0)
     await expect(menu.getByRole('button', { name: '取消单元格对齐' })).toHaveCount(0)
+    // 「表头」整组已移除：切换表头列 / 切换表头单元格都不再提供
     await expect(menu.getByRole('button', { name: '切换表头行' })).toHaveCount(0)
+    await expect(menu.getByRole('button', { name: '切换表头列' })).toHaveCount(0)
+    await expect(menu.getByRole('button', { name: '切换表头单元格' })).toHaveCount(0)
 
     // 删除行 / 删除列的图标是自绘 SVG（不再是拆分行列的 lucide 图标）
     for (const name of ['删除行', '删除列']) {
@@ -387,23 +420,6 @@ test.describe('RichText 表格 · 操作浮层', () => {
     await expect(editor.locator('table tr:first-child th')).toHaveCount(2)
   })
 
-  test('切换表头列 / 表头单元格', async ({ page }) => {    await page.goto('/')
-    await insertTable(page)
-    const editor = page.getByTestId('rich-text')
-    const menu = page.locator('.g3-rich-text-table-menu')
-
-    // 表头单元格：把普通单元格切换为 th
-    await openMenuInCell(page, 1)
-    await menu.getByRole('button', { name: '切换表头单元格' }).click()
-    await expect(editor.locator('table tr').nth(1).locator('th')).toHaveCount(1)
-
-    // 表头列：整列切换为 th（第 2、3 行的首格都变 th；首行本就是表头行不受影响）
-    await menu.getByRole('button', { name: '切换表头列' }).click()
-    await expect(editor.locator('table tr').nth(1).locator('th')).toHaveCount(1)
-    await expect(editor.locator('table tr').nth(2).locator('th')).toHaveCount(1)
-    await expect(editor.locator('table tr').nth(1).locator('td')).toHaveCount(2)
-  })
-
   test('单元格内文字的对齐走顶部工具条', async ({ page }) => {
     await page.goto('/')
     await insertTable(page)
@@ -418,28 +434,29 @@ test.describe('RichText 表格 · 操作浮层', () => {
     await expect(cell.locator('p')).toHaveAttribute('style', /text-align:\s*center/)
   })
 
-  test('插入面板行列数超界被夹回合法范围，且可关闭表头行', async ({ page }) => {
+  /**
+   * 「超界被夹回」这条用例已随数字输入框一起移除：网格选择器的可选范围由网格本身
+   * 硬性限定（8 行 × 10 列），用户在结构上就填不出 0 行或 99 列 —— 也就没有「夹回」可言。
+   * 这里改为断言这个上限本身，防止有人无意中把网格尺寸改大或改小。
+   */
+  test('网格选择器的上限为 8 行 × 10 列，且只能选到边界内的格子', async ({ page }) => {
     await page.goto('/')
     const editor = page.getByTestId('rich-text')
     await editor.scrollIntoViewIfNeeded()
     await editor.locator('button[aria-label="插入表格"]').click()
 
-    // 输入非法值（0 行 / 99 列）
-    await page.locator('.g3-rich-text__table-input').nth(0).fill('0')
-    await page.locator('.g3-rich-text__table-input').nth(1).fill('99')
-    await page.getByRole('button', { name: '插入', exact: true }).click()
+    const cells = page.locator('.g3-rich-text__table-grid-cell')
+    await expect(cells).toHaveCount(80)
+    // 边界格子存在，越界的不存在
+    await expect(page.locator('.g3-rich-text__table-grid-cell[data-row="8"][data-col="10"]')).toHaveCount(1)
+    await expect(page.locator('.g3-rich-text__table-grid-cell[data-row="9"]')).toHaveCount(0)
+    await expect(page.locator('.g3-rich-text__table-grid-cell[data-col="11"]')).toHaveCount(0)
 
+    // 选边界值：8 行 10 列能正常插入
+    await page.locator('.g3-rich-text__table-grid-cell[data-row="8"][data-col="10"]').click()
     const table = editor.locator('table')
     await expect(table).toHaveCount(1)
-    // 0 → 1 行，99 → 20 列
-    await expect(table.locator('tr')).toHaveCount(1)
-    await expect(table.locator('tr:first-child th')).toHaveCount(20)
-
-    // 关闭表头行：插入后首行是 td 而非 th
-    await editor.locator('button[aria-label="插入表格"]').click()
-    await page.locator('.g3-rich-text__table-checkbox').uncheck()
-    await page.getByRole('button', { name: '插入', exact: true }).click()
-    await expect(editor.locator('table')).toHaveCount(2)
-    await expect(editor.locator('table').nth(1).locator('tr:first-child th')).toHaveCount(0)
+    await expect(table.locator('tr')).toHaveCount(8)
+    await expect(table.locator('tr:first-child th')).toHaveCount(10)
   })
 })
diff --git a/code/g3soft-libs/packages/ui/e2e/rich-text-toolbar.spec.ts b/code/g3soft-libs/packages/ui/e2e/rich-text-toolbar.spec.ts
index beced501..3209e2b0 100644
--- a/code/g3soft-libs/packages/ui/e2e/rich-text-toolbar.spec.ts
+++ b/code/g3soft-libs/packages/ui/e2e/rich-text-toolbar.spec.ts
@@ -177,13 +177,21 @@ test.describe('RichText 工具条 · 更多菜单', () => {
   })
 })
 
-/** 工具条当前占几行（同一行的元素共享垂直中心） */
+/**
+ * 工具条当前占几行（同一行的元素共享垂直中心）。
+ *
+ * ⚠️ 不能遍历 `toolbar.children` —— 分组容器用了 `display: contents`，
+ * 它们的盒子不参与布局、`getBoundingClientRect()` 恒为 0，按 children 数会永远得到 1 行
+ * （哪怕实际折成了三行）。必须量**真正参与布局的按钮**。
+ */
 function toolbarRows(page: Page): Promise<number> {
   return page.evaluate(() => {
     const toolbar = document.querySelector('.g3-rich-text__toolbar') as HTMLElement
     const centers = new Set<number>()
-    for (const el of Array.from(toolbar.children) as HTMLElement[]) {
+    const buttons = toolbar.querySelectorAll('button')
+    for (const el of Array.from(buttons) as HTMLElement[]) {
       const rect = el.getBoundingClientRect()
+      if (rect.height === 0) continue
       centers.add(Math.round(rect.top + rect.height / 2))
     }
     return centers.size
@@ -191,23 +199,64 @@ function toolbarRows(page: Page): Promise<number> {
 }
 
 test.describe('RichText 工具条 · 外观', () => {
-  test('窄到 780px 仍保持一行（低频收进「更多」的预算）', async ({ page }) => {
+  test('宽容器下保持一行（低频收进「更多」的预算）', async ({ page }) => {
     await page.goto('/')
     const editor = page.getByTestId('rich-text')
     await editor.scrollIntoViewIfNeeded()
     await editor.locator('.tiptap').click()
 
     await page.evaluate(() => {
-      ;(document.querySelector('[data-testid="rich-text"]') as HTMLElement).style.width = '780px'
+      ;(document.querySelector('[data-testid="rich-text"]') as HTMLElement).style.width = '1000px'
     })
 
     await expect
       .poll(() => toolbarRows(page), {
-        message: '工具条自然宽度约 744px（32px 按钮 + 左右 10px 内边距）；新增按钮前先想清楚该不该挪进「更多」',
+        message:
+          '工具条在 1000px 宽下应当是一行；窄了就折行（折行以按钮为单位，见 .g3-rich-text__group 的 display: contents）',
       })
       .toBe(1)
   })
 
+  test('窄容器下折行时按按钮换行，不整组跳行', async ({ page }) => {
+    await page.goto('/')
+    const editor = page.getByTestId('rich-text')
+    await editor.scrollIntoViewIfNeeded()
+    await editor.locator('.tiptap').click()
+
+    // 620px：一行放不下所有按钮，必然折行
+    await page.evaluate(() => {
+      ;(document.querySelector('[data-testid="rich-text"]') as HTMLElement).style.width = '620px'
+    })
+
+    const info = await page.evaluate(() => {
+      const toolbar = document.querySelector('.g3-rich-text__toolbar') as HTMLElement
+      const barRect = toolbar.getBoundingClientRect()
+      const rows = new Map<number, { right: number; count: number }>()
+      for (const el of Array.from(toolbar.querySelectorAll('button')) as HTMLElement[]) {
+        const r = el.getBoundingClientRect()
+        if (r.height === 0) continue
+        const top = Math.round(r.top)
+        const entry = rows.get(top) ?? { right: 0, count: 0 }
+        entry.right = Math.max(entry.right, Math.round(r.right))
+        entry.count += 1
+        rows.set(top, entry)
+      }
+      const sorted = [...rows.entries()].sort((a, b) => a[0] - b[0])
+      return {
+        rowCount: sorted.length,
+        // 每行最右侧按钮距容器内容区右边缘还剩多少（越小说明填得越满）
+        slack: sorted.map(([, v]) => Math.round(barRect.right - 10 - v.right)),
+        firstRowCount: sorted[0]?.[1].count ?? 0,
+      }
+    })
+
+    // 折行了，但不是「整组跳行」导致第一行只放几个
+    expect(info.rowCount).toBeGreaterThan(1)
+    expect(info.firstRowCount).toBeGreaterThan(8)
+    // 第一行应当填得比较满：剩余空隙小于一个按钮宽（不出现「右边空一大片」）
+    expect(info.slack[0]).toBeLessThan(36)
+  })
+
   test('工具条带下投影，且抬在正文之上（滚动时投影不被正文盖住）', async ({ page }) => {
     await page.goto('/')
     const editor = page.getByTestId('rich-text')
@@ -231,3 +280,428 @@ test.describe('RichText 工具条 · 外观', () => {
     expect(Number(style.zIndex)).toBeGreaterThan(0)
   })
 })
+
+test.describe('RichText 工具条 · 键盘操作', () => {
+  /** 当前获得焦点的元素（用 aria-label 标识，便于断言「焦点在第几个按钮上」） */
+  function focusedLabel(page: Page): Promise<string | null> {
+    return page.evaluate(() => {
+      const el = document.activeElement as HTMLElement | null
+      if (!el || el.tagName !== 'BUTTON') return null
+      return el.getAttribute('aria-label')
+    })
+  }
+
+  /** 工具条里 tabindex=0 的按钮 aria-label 列表（roving tabindex 应当只有一个） */
+  function tabbableInToolbar(page: Page): Promise<(string | null)[]> {
+    return page.evaluate(() =>
+      Array.from(
+        document.querySelectorAll('.g3-rich-text__toolbar button:not(:disabled)'),
+      )
+        .filter((el) => (el as HTMLElement).tabIndex === 0)
+        .map((el) => el.getAttribute('aria-label')),
+    )
+  }
+
+  /**
+   * 工具条里**可聚焦**按钮的 aria-label，按 DOM 顺序。
+   *
+   * 必须排除 disabled：初始状态下「撤销」「重做」是禁用的（历史为空），
+   * 它们不可聚焦、也不该出现在方向键序列里。断言用真实 DOM 顺序而不是写死
+   * 按钮名，避免以后调整工具条顺序时测试变成假失败。
+   */
+  function focusableLabels(page: Page): Promise<(string | null)[]> {
+    return page.evaluate(() =>
+      Array.from(
+        document.querySelectorAll('.g3-rich-text__toolbar button:not(:disabled)'),
+      ).map((el) => el.getAttribute('aria-label')),
+    )
+  }
+
+  /**
+   * 段落格式触发器（「正文 / 标题 N」）。
+   *
+   * 用 class 定位而不是 role+name：它的可访问名是**当前块格式**、随光标变化
+   * （playground 初始内容含 `<h2>`，名字就是「标题 2」），拿它当固定名字必然不稳。
+   */
+  function headingTrigger(page: Page) {
+    return page.locator(`${EDITOR} .g3-rich-text__toolbar .g3-rich-text__trigger`)
+  }
+
+  test('工具条是 role=toolbar 的单个 Tab 停靠点', async ({ page }) => {
+    await page.goto('/')
+    const toolbar = page.locator(`${EDITOR} .g3-rich-text__toolbar`)
+    await expect(toolbar).toHaveAttribute('role', 'toolbar')
+    await expect(toolbar).toHaveAttribute('aria-orientation', 'horizontal')
+
+    // 无论有多少按钮，tabindex=0 的只有一个 —— 否则每个按钮都占一个 Tab 位
+    const tabbable = await tabbableInToolbar(page)
+    expect(tabbable).toHaveLength(1)
+    const buttonCount = await page
+      .locator(`${EDITOR} .g3-rich-text__toolbar button:not(:disabled)`)
+      .count()
+    // 14 个图标按钮 + 1 个段落格式触发器（撤销 / 重做初始禁用，不计入）
+    expect(buttonCount).toBeGreaterThanOrEqual(15)
+  })
+
+  test('方向键在按钮间漫游，Home / End 跳首尾', async ({ page }) => {
+    await page.goto('/')
+    const labels = await focusableLabels(page)
+    // 初始态「撤销 / 重做」禁用，序列从段落格式触发器开始，其后是「加粗」
+    expect(labels[0]).toBe('段落格式')
+    expect(labels[1]).toBe('加粗')
+
+    await headingTrigger(page).focus()
+    await expect.poll(() => focusedLabel(page)).toBe('段落格式')
+
+    // 右键 → 下一个
+    await page.keyboard.press('ArrowRight')
+    await expect.poll(() => focusedLabel(page)).toBe('加粗')
+
+    // 左键回退
+    await page.keyboard.press('ArrowLeft')
+    await expect.poll(() => focusedLabel(page)).toBe('段落格式')
+
+    // 首个再往左 → 两端循环到末位（「更多」）
+    await page.keyboard.press('ArrowLeft')
+    await expect.poll(() => focusedLabel(page)).toBe(labels[labels.length - 1])
+
+    // End 跳末位 / Home 跳首位
+    await page.keyboard.press('End')
+    await expect.poll(() => focusedLabel(page)).toBe(labels[labels.length - 1])
+    await page.keyboard.press('Home')
+    await expect.poll(() => focusedLabel(page)).toBe(labels[0])
+  })
+
+  test('禁用按钮（撤销 / 重做）不会被方向键走到', async ({ page }) => {
+    await page.goto('/')
+    // 初始历史为空 → 撤销 / 重做禁用
+    const undo = page.locator(`${EDITOR} .g3-rich-text__toolbar button[aria-label="撤销"]`)
+    await expect(undo).toBeDisabled()
+
+    const labels = await focusableLabels(page)
+    expect(labels).not.toContain('撤销')
+    expect(labels).not.toContain('重做')
+  })
+
+  test('方向键漫游时不会把光标带进正文（preventDefault 生效）', async ({ page }) => {
+    await page.goto('/')
+
+    // 先制造可撤销的历史，让「撤销」进入可聚焦序列（更接近真实使用）
+    const editor = page.getByTestId('rich-text')
+    await editor.locator('.tiptap').click()
+    await page.keyboard.type('键盘测试')
+    const undo = editor.locator('.g3-rich-text__toolbar button[aria-label="撤销"]')
+    await expect(undo).toBeEnabled()
+
+    await undo.focus()
+    await page.keyboard.press('End')
+    await page.keyboard.press('Home')
+    // Home / End 若没被 preventDefault，浏览器会把焦点 / 光标带出工具条
+    await expect.poll(() => focusedLabel(page)).toBe('撤销')
+    await expect(editor.locator('.tiptap')).not.toHaveClass(/ProseMirror-focused/)
+  })
+
+  test('焦点移动后 tabindex 跟着走（roving 归一化）', async ({ page }) => {
+    await page.goto('/')
+    await headingTrigger(page).focus()
+    await page.keyboard.press('ArrowRight')
+
+    expect(await focusedLabel(page)).toBe('加粗')
+    // 任意时刻恰有一个 tabindex=0，且它就是当前焦点所在按钮
+    expect(await tabbableInToolbar(page)).toEqual(['加粗'])
+  })
+})
+
+test.describe('RichText 工具条 · 链接', () => {
+  /** 地址输入框（面板里两个 input，靠 aria-label 区分） */
+  function urlInput(page: Page) {
+    return page.getByLabel('链接地址')
+  }
+
+  /** 显示文字输入框 */
+  function textInput(page: Page) {
+    return page.getByLabel('显示文字')
+  }
+
+  /** 在正文里输入文本并全选，然后打开链接面板 */
+  async function openLinkPanel(page: Page, text = '点我'): Promise<void> {
+    const editor = page.getByTestId('rich-text')
+    await editor.scrollIntoViewIfNeeded()
+    await editor.locator('.tiptap').click()
+    await page.keyboard.press('Control+A')
+    await page.keyboard.press('Delete')
+    await page.keyboard.type(text)
+    await page.keyboard.press('Control+A')
+    await editor.locator('.g3-rich-text__toolbar').getByRole('button', { name: '链接' }).click()
+    await expect(page.locator('.g3-rich-text__link-form')).toBeVisible()
+  }
+
+  test('输入地址后回车写入选区，且不弹原生 dialog', async ({ page }) => {
+    // 回归：旧实现用 window.prompt，这里断言「没有任何原生对话框被触发」
+    let dialogSeen = false
+    page.on('dialog', async (dialog) => {
+      dialogSeen = true
+      await dialog.dismiss()
+    })
+
+    await page.goto('/')
+    await openLinkPanel(page)
+
+    await urlInput(page).fill('https://example.com/a')
+    await page.keyboard.press('Enter')
+
+    const link = page.locator(`${EDITOR} .tiptap a`)
+    await expect(link).toHaveCount(1)
+    await expect(link).toHaveAttribute('href', 'https://example.com/a')
+    expect(dialogSeen, '不应再触发 window.prompt 原生弹窗').toBe(false)
+    // 应用后面板收起
+    await expect(page.locator('.g3-rich-text__link-form')).toHaveCount(0)
+  })
+
+  test('面板有「链接地址」与「显示文字」两个字段，且无 placeholder', async ({ page }) => {
+    await page.goto('/')
+    await openLinkPanel(page)
+
+    await expect(page.locator('.g3-rich-text__link-form')).toBeVisible()
+    await expect(urlInput(page)).toBeVisible()
+    await expect(textInput(page)).toBeVisible()
+
+    // 刻意不留 placeholder：字段名已说明填什么，示例文案属于噪音
+    await expect(urlInput(page)).not.toHaveAttribute('placeholder', /.*/)
+    await expect(textInput(page)).not.toHaveAttribute('placeholder', /.*/)
+
+    // 有选区时「显示文字」预填选中的文字
+    await expect(textInput(page)).toHaveValue('点我')
+  })
+
+  test('显示文字：替换选中文字', async ({ page }) => {
+    await page.goto('/')
+    await openLinkPanel(page, '点我')
+
+    await urlInput(page).fill('https://example.com/a')
+    await textInput(page).fill('查看详情')
+    await page.keyboard.press('Enter')
+
+    const link = page.locator(`${EDITOR} .tiptap a`)
+    await expect(link).toHaveCount(1)
+    await expect(link).toHaveText('查看详情')
+    await expect(link).toHaveAttribute('href', 'https://example.com/a')
+  })
+
+  test('「取消」关闭面板且不写入文档', async ({ page }) => {
+    await page.goto('/')
+    await openLinkPanel(page, '点我')
+
+    await urlInput(page).fill('https://example.com/never')
+    await page.locator('.g3-rich-text__link-form').getByRole('button', { name: '取消' }).click()
+
+    // 面板收起、正文没有产生链接
+    await expect(page.locator('.g3-rich-text__link-form')).toHaveCount(0)
+    await expect(page.locator(`${EDITOR} .tiptap a`)).toHaveCount(0)
+    await expect(page.locator(`${EDITOR} .tiptap`)).toContainText('点我')
+  })
+
+  test('「取消 / 确定」靠右成组，主操作位置稳定', async ({ page }) => {
+    await page.goto('/')
+    await openLinkPanel(page, '点我')
+
+    const form = page.locator('.g3-rich-text__link-form')
+    const cancel = form.getByRole('button', { name: '取消' })
+    const confirm = form.getByRole('button', { name: '确定' })
+
+    const cancelBox = (await cancel.boundingBox())!
+    const confirmBox = (await confirm.boundingBox())!
+    const formBox = (await form.boundingBox())!
+
+    // 确定在取消右侧
+    expect(confirmBox.x).toBeGreaterThan(cancelBox.x)
+    // 两者底边对齐（同一行）
+    expect(Math.abs(cancelBox.y - confirmBox.y)).toBeLessThan(2)
+    // 确定右边缘贴近面板右侧内边距（靠右而不是居中/通栏）
+    const formRight = formBox.x + formBox.width
+    expect(formRight - (confirmBox.x + confirmBox.width)).toBeLessThan(20)
+  })
+
+  test('操作按钮用默认尺寸而非 small（高度对齐 G3Input）', async ({ page }) => {
+    await page.goto('/')
+    await openLinkPanel(page, '点我')
+
+    const form = page.locator('.g3-rich-text__link-form')
+    const confirm = (await form.getByRole('button', { name: '确定' }).boundingBox())!
+    // 量 G3Input 的**根包裹层**（32px 的那个盒子），不是它内部的裸 <input>（21px 行盒）——
+    // getByLabel 解析到的是内部 input，直接量它会得出「按钮比输入框高」的错误结论
+    const inputBox = (await form.locator('.g3-input').first().boundingBox())!
+
+    // 默认尺寸 = --g3-control-height = 32px；small 是 24px
+    expect(confirm.height).toBeGreaterThanOrEqual(30)
+    // 与输入框等高，同一行里视觉齐平
+    expect(Math.abs(confirm.height - inputBox.height)).toBeLessThan(3)
+  })
+
+  test('编辑态：移除链接在左，取消 / 确定在右', async ({ page }) => {
+    await page.goto('/')
+    await openLinkPanel(page, '点我')
+    await urlInput(page).fill('https://example.com/x')
+    await page.keyboard.press('Enter')
+
+    await page.locator(`${EDITOR} .tiptap a`).click()
+    await page
+      .locator(`${EDITOR} .g3-rich-text__toolbar`)
+      .getByRole('button', { name: '链接' })
+      .click()
+
+    const form = page.locator('.g3-rich-text__link-form')
+    const remove = (await form.getByRole('button', { name: '移除链接' }).boundingBox())!
+    const cancel = (await form.getByRole('button', { name: '取消' }).boundingBox())!
+
+    // 移除链接在最左，取消在它右侧（危险操作与主操作分开）
+    expect(remove.x).toBeLessThan(cancel.x)
+  })
+
+  test('显示文字：空选区时插入为链接文字', async ({ page }) => {
+    await page.goto('/')
+    const editor = page.getByTestId('rich-text')
+    await editor.scrollIntoViewIfNeeded()
+    await editor.locator('.tiptap').click()
+    // 清空且不选中任何内容（光标停在空段落里）
+    await page.keyboard.press('Control+A')
+    await page.keyboard.press('Delete')
+
+    await editor.locator('.g3-rich-text__toolbar').getByRole('button', { name: '链接' }).click()
+    await expect(page.locator('.g3-rich-text__link-form')).toBeVisible()
+
+    await urlInput(page).fill('https://example.com/b')
+    // 「显示文字」不是必填（只填地址即可提交）；这里我们主动填上文字
+    await textInput(page).fill('官网')
+    await page.keyboard.press('Enter')
+
+    // 落下的文字本身带链接，href 正确、文字正确
+    const link = page.locator(`${EDITOR} .tiptap a`)
+    await expect(link).toHaveCount(1)
+    await expect(link).toHaveText('官网')
+    await expect(link).toHaveAttribute('href', 'https://example.com/b')
+  })
+
+  test('显示文字留空时沿用原选区文字', async ({ page }) => {
+    await page.goto('/')
+    await openLinkPanel(page, '保留我')
+
+    await urlInput(page).fill('https://example.com/c')
+    await textInput(page).fill('')
+    // 有原选区文字 → 仍可提交
+    await page.keyboard.press('Enter')
+
+    const link = page.locator(`${EDITOR} .tiptap a`)
+    await expect(link).toHaveText('保留我')
+    await expect(link).toHaveAttribute('href', 'https://example.com/c')
+  })
+
+  test('不带协议时自动补 https://', async ({ page }) => {
+    await page.goto('/')
+    await openLinkPanel(page)
+
+    await urlInput(page).fill('example.com/docs')
+    await page.locator('.g3-rich-text__link-form').getByRole('button', { name: '确定' }).click()
+
+    await expect(page.locator(`${EDITOR} .tiptap a`)).toHaveAttribute(
+      'href',
+      'https://example.com/docs',
+    )
+  })
+
+  test('空选区且未填显示文字：确定可用，并把地址本身作为链接文字', async ({ page }) => {
+    await page.goto('/')
+    const editor = page.getByTestId('rich-text')
+    await editor.scrollIntoViewIfNeeded()
+    await editor.locator('.tiptap').click()
+    // 只清空、不选中任何文字
+    await page.keyboard.press('Control+A')
+    await page.keyboard.press('Delete')
+
+    await editor
+      .locator('.g3-rich-text__toolbar')
+      .getByRole('button', { name: '链接' })
+      .click()
+
+    // 「显示文字」不是必填（产品要求）—— 填了地址就应当能提交
+    await urlInput(page).fill('https://example.com')
+    await expect(
+      page.locator('.g3-rich-text__link-form').getByRole('button', { name: '确定' }),
+    ).toBeEnabled()
+
+    // 兜底：没有任何文字可挂时，用地址本身当链接文字
+    await page.keyboard.press('Enter')
+    const link = page.locator(`${EDITOR} .tiptap a`)
+    await expect(link).toHaveCount(1)
+    await expect(link).toHaveText('https://example.com')
+  })
+
+  test('只填地址也能提交（显示文字留空）', async ({ page }) => {
+    await page.goto('/')
+    await openLinkPanel(page, '原文')
+    // 主动清掉预填的显示文字
+    await textInput(page).fill('')
+    await urlInput(page).fill('https://example.com/only-url')
+    await page.keyboard.press('Enter')
+
+    const link = page.locator(`${EDITOR} .tiptap a`)
+    await expect(link).toHaveAttribute('href', 'https://example.com/only-url')
+    // 有选中文字、显示文字留空 → 沿用原文字
+    await expect(link).toHaveText('原文')
+  })
+
+  test('光标在已有链接上时，面板可编辑并可移除链接', async ({ page }) => {
+    await page.goto('/')
+    await openLinkPanel(page)
+    await urlInput(page).fill('https://example.com/first')
+    await page.keyboard.press('Enter')
+    await expect(page.locator(`${EDITOR} .tiptap a`)).toHaveCount(1)
+
+    // 把光标放回链接文字里，再打开面板 → 地址被预填、可编辑
+    await page.locator(`${EDITOR} .tiptap a`).click()
+    await page
+      .locator(`${EDITOR} .g3-rich-text__toolbar`)
+      .getByRole('button', { name: '链接' })
+      .click()
+    await expect(urlInput(page)).toHaveValue('https://example.com/first')
+    // 编辑态能看到「移除链接」
+    await expect(
+      page.locator('.g3-rich-text__link-form').getByRole('button', { name: '移除链接' }),
+    ).toBeVisible()
+
+    // 改地址
+    await urlInput(page).fill('https://example.com/second')
+    await page.keyboard.press('Enter')
+    await expect(page.locator(`${EDITOR} .tiptap a`)).toHaveAttribute(
+      'href',
+      'https://example.com/second',
+    )
+
+    // 再打开 → 移除链接
+    await page.locator(`${EDITOR} .tiptap a`).click()
+    await page
+      .locator(`${EDITOR} .g3-rich-text__toolbar`)
+      .getByRole('button', { name: '链接' })
+      .click()
+    await page
+      .locator('.g3-rich-text__link-form')
+      .getByRole('button', { name: '移除链接' })
+      .click()
+    await expect(page.locator(`${EDITOR} .tiptap a`)).toHaveCount(0)
+  })
+
+  test('javascript: 之类的可执行协议不会被写入 href', async ({ page }) => {
+    await page.goto('/')
+    await openLinkPanel(page)
+
+    await urlInput(page).fill('javascript:alert(1)')
+    await page.keyboard.press('Enter')
+
+    // normalizeUrl 只放行 http/https/mailto/tel/#// 开头的地址，其余原样保留 → 不写链接
+    const href = await page
+      .locator(`${EDITOR} .tiptap a`)
+      .evaluateAll((els) => els.map((el) => el.getAttribute('href')))
+    expect(href.every((value) => !value?.toLowerCase().startsWith('javascript:'))).toBe(true)
+  })
+})
+
diff --git a/code/g3soft-libs/packages/ui/e2e/rich-text-tools.spec.ts b/code/g3soft-libs/packages/ui/e2e/rich-text-tools.spec.ts
new file mode 100644
index 00000000..4cc7461a
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/e2e/rich-text-tools.spec.ts
@@ -0,0 +1,441 @@
+import { expect, test, type Page } from '@playwright/test'
+
+/**
+ * 富文本新增能力的回归：
+ * 1. 列表样式（无序 / 有序的多档位）；
+ * 2. 「整理格式」清理空段落 / 空白文本 / 空 mark；
+ * 3. 预览（模态框只读渲染）；
+ * 4. 打印（隐藏 iframe，只打正文）；
+ * 5. 源代码（模态框编辑 HTML + 保存写回）。
+ *
+ * 这些都依赖真实的 contenteditable + 选区 / 真实 DOM（打印要 iframe、模态框要 Teleport），
+ * happy-dom 里跑不了，所以放在 E2E。
+ */
+
+const EDITOR = '[data-testid="rich-text"]'
+
+/** 清空编辑器后输入一段文本（不选中，光标落在段落末尾） */
+async function typeText(page: Page, text: string): Promise<void> {
+  const editor = page.getByTestId('rich-text')
+  await editor.scrollIntoViewIfNeeded()
+  await editor.locator('.tiptap').click()
+  await page.keyboard.press('Control+A')
+  await page.keyboard.press('Delete')
+  await page.keyboard.type(text)
+}
+
+/** 打开「更多」菜单 */
+async function openMore(page: Page): Promise<void> {
+  await page
+    .locator(`${EDITOR} .g3-rich-text__toolbar`)
+    .getByRole('button', { name: '更多' })
+    .click()
+}
+
+/**
+ * 点开某个列表按钮的样式面板（面板 Teleport 到 body）。
+ *
+ * 分裂按钮（G3ButtonGroup 组合）：点**图标**一键建/撤列表，点**右侧箭头**才打开样式面板。
+ * 箭头是 ButtonGroup 里的第二个按钮，aria-label 为「无序列表样式 / 有序列表样式」。
+ */
+async function openListPanel(page: Page, name: '无序列表' | '有序列表') {
+  await page
+    .locator(`${EDITOR} .g3-rich-text__toolbar`)
+    .getByRole('button', { name: `${name}样式` })
+    .click()
+  const panel = page.locator('.g3-rich-text__list-panel').last()
+  await expect(panel).toBeVisible()
+  return panel
+}
+
+/** 点列表按钮的**图标**（一键建/撤列表，不打开面板） */
+async function clickListIcon(page: Page, name: '无序列表' | '有序列表') {
+  await page
+    .locator(`${EDITOR} .g3-rich-text__toolbar`)
+    .getByRole('button', { name })
+    .click()
+}
+
+test.describe('RichText · 列表样式', () => {
+  test('无序列表：实心方块写进 ul 的 type 属性', async ({ page }) => {
+    await page.goto('/')
+    await typeText(page, '第一项')
+
+    // 点开无序列表按钮的样式面板，选「实心方块」—— 一步完成建列表 + 设样式
+    const panel = await openListPanel(page, '无序列表')
+    await panel.getByRole('menuitemradio', { name: '实心方块' }).click()
+
+    // 样式落在 type 属性上（不是 class）—— 属性自描述，导出即正确
+    await expect(page.locator(`${EDITOR} .tiptap ul`)).toHaveCount(1)
+    await expect(page.locator(`${EDITOR} .tiptap ul`)).toHaveAttribute('type', 'square')
+  })
+
+  test('有序列表：大写罗马数字写进 ol 的 type 属性', async ({ page }) => {
+    await page.goto('/')
+    await typeText(page, '第一步')
+
+    const panel = await openListPanel(page, '有序列表')
+    await panel.getByRole('menuitemradio', { name: '大写罗马数字' }).click()
+
+    await expect(page.locator(`${EDITOR} .tiptap ol`)).toHaveAttribute('type', 'I')
+  })
+
+  test('有序列表：小写希腊字母走 style（type="lower-greek" 是非法 HTML 值）', async ({ page }) => {
+    await page.goto('/')
+    await typeText(page, '第一步')
+
+    const panel = await openListPanel(page, '有序列表')
+    await panel.getByRole('menuitemradio', { name: '小写希腊字母' }).click()
+
+    const ol = page.locator(`${EDITOR} .tiptap ol`)
+    // 必须走 style —— 写 type="lower-greek" 会被浏览器当作未知值忽略、退回数字编号
+    await expect(ol).toHaveAttribute('style', /list-style-type:\s*lower-greek/)
+    await expect(ol).not.toHaveAttribute('type', 'lower-greek')
+  })
+
+  test('点图标一键建列表，不打开样式面板', async ({ page }) => {
+    await page.goto('/')
+    await typeText(page, '还没有列表')
+
+    await expect(page.locator(`${EDITOR} .tiptap ul`)).toHaveCount(0)
+
+    await clickListIcon(page, '无序列表')
+
+    // 只建列表、不弹面板（样式仍是默认档）
+    await expect(page.locator(`${EDITOR} .tiptap ul`)).toHaveCount(1)
+    await expect(page.locator('.g3-rich-text__list-panel')).toHaveCount(0)
+  })
+
+  test('点图标再次点击退列表（toggle 语义）', async ({ page }) => {
+    await page.goto('/')
+    await typeText(page, '第一项')
+
+    await clickListIcon(page, '无序列表')
+    await expect(page.locator(`${EDITOR} .tiptap ul`)).toHaveCount(1)
+
+    await clickListIcon(page, '无序列表')
+    await expect(page.locator(`${EDITOR} .tiptap ul`)).toHaveCount(0)
+  })
+
+  test('点右侧箭头打开样式面板，点图标不打开', async ({ page }) => {
+    await page.goto('/')
+    await typeText(page, '第一项')
+
+    // 点箭头：面板打开
+    await (await openListPanel(page, '无序列表')).getByRole('menuitemradio', { name: '默认' }).click()
+
+    // 点图标：面板不开（只 toggle 列表）
+    await clickListIcon(page, '无序列表')
+    await expect(page.locator('.g3-rich-text__list-panel')).toHaveCount(0)
+  })
+
+  test('当前档位带选中态（aria-checked），档位名是中文而非英文枚举', async ({ page }) => {
+    await page.goto('/')
+    await typeText(page, '第一项')
+
+    // 先建列表 + 选实心方块
+    const panel = await openListPanel(page, '无序列表')
+    await panel.getByRole('menuitemradio', { name: '实心方块' }).click()
+    await expect(page.locator(`${EDITOR} .tiptap ul`)).toHaveAttribute('type', 'square')
+
+    // 再打开面板：实心方块是当前档位 → 选中态；「默认」未被选中
+    const reopened = await openListPanel(page, '无序列表')
+    await expect(reopened.getByRole('menuitemradio', { name: '实心方块' })).toHaveAttribute(
+      'aria-checked',
+      'true',
+    )
+    await expect(reopened.getByRole('menuitemradio', { name: '默认' })).toHaveAttribute(
+      'aria-checked',
+      'false',
+    )
+    // 档位名是中文，不暴露 disc / circle / square 这些英文枚举
+    await expect(reopened.getByRole('menuitemradio', { name: /disc|circle|square/i })).toHaveCount(0)
+  })
+})
+
+test.describe('RichText · 整理格式', () => {
+  test('清理空段落与空白文本，并把统计报给宿主', async ({ page }) => {
+    await page.goto('/')
+
+    // 用源代码对话框塞入带空段落的正文（比敲键盘造空段落更直接）
+    await openMore(page)
+    await page.getByRole('menuitem', { name: '源代码' }).click()
+
+    const dialog = page.locator('.g3-modal')
+    await expect(dialog).toBeVisible()
+    await dialog.locator('textarea').fill('<p>第一段</p><p></p><p></p><p>第二段</p>')
+    await dialog.getByRole('button', { name: '保存' }).click()
+    await expect(dialog).toHaveCount(0)
+
+    await expect(page.locator(`${EDITOR} .tiptap p`)).toHaveCount(4)
+
+    // 「更多 → 整理格式」
+    await openMore(page)
+    await page.getByRole('menuitem', { name: '整理格式' }).click()
+
+    // 两个空段落被清掉，只剩有内容的两段
+    await expect(page.locator(`${EDITOR} .tiptap p`)).toHaveCount(2)
+    await expect(page.locator(`${EDITOR} .tiptap p`).first()).toHaveText('第一段')
+  })
+
+  test('整理格式是一次可撤销的操作（撤销栈只留一步）', async ({ page }) => {
+    await page.goto('/')
+
+    await openMore(page)
+    await page.getByRole('menuitem', { name: '源代码' }).click()
+    const dialog = page.locator('.g3-modal')
+    await dialog.locator('textarea').fill('<p>甲</p><p></p><p></p><p></p><p>乙</p>')
+    await dialog.getByRole('button', { name: '保存' }).click()
+    await expect(dialog).toHaveCount(0)
+
+    await expect(page.locator(`${EDITOR} .tiptap p`)).toHaveCount(5)
+
+    await openMore(page)
+    await page.getByRole('menuitem', { name: '整理格式' }).click()
+    await expect(page.locator(`${EDITOR} .tiptap p`)).toHaveCount(2)
+
+    // 一次 Ctrl+Z 就整体退回（若实现成逐段 dispatch，这里只会退回一个空段落）
+    await page.locator(`${EDITOR} .tiptap`).click()
+    await page.keyboard.press('Control+z')
+    await expect(page.locator(`${EDITOR} .tiptap p`)).toHaveCount(5)
+  })
+})
+
+test.describe('RichText · 预览', () => {
+  test('模态框只读渲染当前正文，排版规则与编辑区一致', async ({ page }) => {
+    await page.goto('/')
+    await typeText(page, '预览内容')
+
+    await openMore(page)
+    await page.getByRole('menuitem', { name: '预览' }).click()
+
+    const dialog = page.locator('.g3-modal')
+    await expect(dialog).toBeVisible()
+    await expect(dialog).toContainText('预览内容')
+
+    // 只读：预览区里没有 contenteditable
+    const body = dialog.locator('.g3-rich-text__preview-body')
+    await expect(body).toBeVisible()
+    await expect(body.locator('[contenteditable="true"]')).toHaveCount(0)
+  })
+
+  test('预览取的是打开那一刻的快照（之后改正文不影响已打开的预览）', async ({ page }) => {
+    await page.goto('/')
+    await typeText(page, '快照')
+
+    await openMore(page)
+    await page.getByRole('menuitem', { name: '预览' }).click()
+
+    const dialog = page.locator('.g3-modal')
+    await expect(dialog).toBeVisible()
+
+    // 预览区不复用编辑器的 DOM 节点（是 v-html 渲染的独立副本）
+    const inEditor = await page
+      .locator(`${EDITOR} .tiptap`)
+      .evaluate((editable) => editable.contains(document.querySelector('.g3-rich-text__preview-body')))
+    expect(inEditor).toBe(false)
+  })
+
+  test('预览里可以发起打印', async ({ page }) => {
+    await page.goto('/')
+    await typeText(page, '打印内容')
+
+    await openMore(page)
+    await page.getByRole('menuitem', { name: '预览' }).click()
+
+    const dialog = page.locator('.g3-modal')
+    await expect(dialog).toBeVisible()
+
+    /**
+     * 拦掉真实的打印调用。
+     *
+     * 打印走的是**隐藏 iframe 的** `contentWindow.print()`，而不是宿主的 `window.print()`。
+     * 在 iframe 的文档里注入拦截：`printHtml` 用 `srcdoc` 装载文档、等 `load` 后调 print，
+     * 所以这里在 iframe 挂载时立刻改写它自己窗口的 print（`about:srcdoc` 与父页面同源，
+     * 可以直接访问 `contentWindow`）。
+     *
+     * 不能用 `HTMLIFrameElement.prototype.contentWindow` 的 getter 覆盖 —— 那会破坏
+     * 组件自己读 `contentWindow` 的路径（`load` 回调里要拿它调 print），
+     * 结果是「为了让测试通过而把被测代码弄坏」。
+     */
+    await page.evaluate(() => {
+      const win = window as unknown as { __printed?: number }
+      win.__printed = 0
+
+      const observer = new MutationObserver((records) => {
+        for (const record of records) {
+          for (const node of Array.from(record.addedNodes)) {
+            if (!(node instanceof HTMLIFrameElement)) continue
+            // 等到 iframe 的文档就绪后再改写（srcdoc 是异步解析的）
+            node.addEventListener('load', () => {
+              try {
+                const frameWin = node.contentWindow as unknown as { print: () => void } | null
+                if (frameWin) {
+                  frameWin.print = () => {
+                    win.__printed = (win.__printed ?? 0) + 1
+                  }
+                }
+              } catch {
+                // 跨源 / 已销毁：忽略，测试会在下面的 poll 里失败并给出真实原因
+              }
+            })
+          }
+        }
+      })
+      observer.observe(document.body, { childList: true })
+    })
+
+    await dialog.getByRole('button', { name: '打印' }).click()
+    await expect
+      .poll(() => page.evaluate(() => (window as unknown as { __printed?: number }).__printed))
+      .toBeGreaterThan(0)
+  })
+})
+
+test.describe('RichText · 打印', () => {
+  test('从「更多」打印：用隐藏 iframe 承载正文，且打印后清理掉', async ({ page }) => {
+    await page.goto('/')
+    await typeText(page, '正文内容')
+
+    await page.evaluate(() => {
+      const win = window as unknown as { __printed?: number }
+      win.__printed = 0
+
+      /**
+       * 记录 iframe 里承载的正文，并拦掉它的 print。
+       * 一次 `MutationObserver` 同时做两件事：断言「打印走 iframe」与
+       * 「iframe 里装的是正文」（而不是宿主的整页 HTML）。
+       */
+      const state = window as unknown as { __iframeHtml?: string }
+      state.__iframeHtml = ''
+
+      const observer = new MutationObserver((records) => {
+        for (const record of records) {
+          for (const node of Array.from(record.addedNodes)) {
+            if (!(node instanceof HTMLIFrameElement)) continue
+            state.__iframeHtml = node.getAttribute('srcdoc') ?? ''
+            node.addEventListener('load', () => {
+              try {
+                const frameWin = node.contentWindow as unknown as { print: () => void } | null
+                if (frameWin) {
+                  frameWin.print = () => {
+                    win.__printed = (win.__printed ?? 0) + 1
+                  }
+                }
+              } catch {
+                // 忽略：poll 会暴露真实问题
+              }
+            })
+          }
+        }
+      })
+      observer.observe(document.body, { childList: true })
+    })
+
+    await openMore(page)
+    await page.getByRole('menuitem', { name: '打印' }).click()
+
+    await expect
+      .poll(() => page.evaluate(() => (window as unknown as { __printed?: number }).__printed))
+      .toBeGreaterThan(0)
+
+    // iframe 里装的是正文，而不是宿主页面的导航 / 按钮
+    const carried = await page.evaluate(
+      () => (window as unknown as { __iframeHtml?: string }).__iframeHtml ?? '',
+    )
+    expect(carried).toContain('正文内容')
+    expect(carried).not.toContain('g3-rich-text__toolbar')
+
+    // 打印后清理掉 iframe，不能在 DOM 里越积越多
+    await expect(page.locator('iframe[srcdoc]')).toHaveCount(0)
+  })
+})
+
+test.describe('RichText · 源代码', () => {
+  test('编辑 HTML 后点保存写回编辑器', async ({ page }) => {
+    await page.goto('/')
+    await typeText(page, '原内容')
+
+    await openMore(page)
+    await page.getByRole('menuitem', { name: '源代码' }).click()
+
+    const dialog = page.locator('.g3-modal')
+    await expect(dialog).toBeVisible()
+
+    // 打开时预填当前 HTML
+    const textarea = dialog.locator('textarea')
+    await expect(textarea).toHaveValue(/原内容/)
+
+    await textarea.fill('<h2>新标题</h2><p>新正文</p>')
+    await dialog.getByRole('button', { name: '保存' }).click()
+
+    // 对话框关闭 + 正文已更新
+    await expect(dialog).toHaveCount(0)
+    await expect(page.locator(`${EDITOR} .tiptap h2`)).toHaveText('新标题')
+    await expect(page.locator(`${EDITOR} .tiptap p`)).toHaveText('新正文')
+  })
+
+  test('「取消」关闭对话框且不写入文档', async ({ page }) => {
+    await page.goto('/')
+    await typeText(page, '保持不变')
+
+    await openMore(page)
+    await page.getByRole('menuitem', { name: '源代码' }).click()
+
+    const dialog = page.locator('.g3-modal')
+    await dialog.locator('textarea').fill('<p>不该出现</p>')
+    await dialog.getByRole('button', { name: '取消' }).click()
+
+    await expect(dialog).toHaveCount(0)
+    await expect(page.locator(`${EDITOR} .tiptap`)).toContainText('保持不变')
+    await expect(page.locator(`${EDITOR} .tiptap`)).not.toContainText('不该出现')
+  })
+
+  test('「重置」把草稿恢复成打开时的内容', async ({ page }) => {
+    await page.goto('/')
+    await typeText(page, '初始内容')
+
+    await openMore(page)
+    await page.getByRole('menuitem', { name: '源代码' }).click()
+
+    const dialog = page.locator('.g3-modal')
+    const textarea = dialog.locator('textarea')
+    await textarea.fill('<p>乱改的</p>')
+
+    await dialog.getByRole('button', { name: '重置' }).click()
+    await expect(textarea).toHaveValue(/初始内容/)
+  })
+
+  test('保存后的内容可以一次撤销退回', async ({ page }) => {
+    await page.goto('/')
+    await typeText(page, '原始文字')
+
+    await openMore(page)
+    await page.getByRole('menuitem', { name: '源代码' }).click()
+    const dialog = page.locator('.g3-modal')
+    await dialog.locator('textarea').fill('<p>替换后的文字</p>')
+    await dialog.getByRole('button', { name: '保存' }).click()
+    await expect(dialog).toHaveCount(0)
+
+    await expect(page.locator(`${EDITOR} .tiptap`)).toContainText('替换后的文字')
+
+    await page.locator(`${EDITOR} .tiptap`).click()
+    await page.keyboard.press('Control+z')
+    await expect(page.locator(`${EDITOR} .tiptap`)).toContainText('原始文字')
+  })
+
+  test('不认识的标签会被 schema 过滤掉（界面如实告知，不假装能完整往返）', async ({ page }) => {
+    await page.goto('/')
+
+    await openMore(page)
+    await page.getByRole('menuitem', { name: '源代码' }).click()
+
+    const dialog = page.locator('.g3-modal')
+    await dialog.locator('textarea').fill('<p>保留</p><marquee>会被丢弃</marquee>')
+    await dialog.getByRole('button', { name: '保存' }).click()
+    await expect(dialog).toHaveCount(0)
+
+    await expect(page.locator(`${EDITOR} .tiptap`)).toContainText('保留')
+    await expect(page.locator(`${EDITOR} .tiptap marquee`)).toHaveCount(0)
+  })
+})
diff --git a/code/g3soft-libs/packages/ui/e2e/table.spec.ts b/code/g3soft-libs/packages/ui/e2e/table.spec.ts
new file mode 100644
index 00000000..0243ba9b
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/e2e/table.spec.ts
@@ -0,0 +1,162 @@
+import { expect, test } from '@playwright/test'
+
+/**
+ * G3Table 的几何 / 命中类断言 —— happy-dom 没有布局引擎，这些只能在真浏览器里量。
+ *
+ * 用例只按 data-testid 找元素（不依赖文案与结构），宿主页在 playground/main.ts。
+ */
+
+test.describe('G3Table 表格', () => {
+  test.beforeEach(async ({ page }) => {
+    await page.goto('/')
+    await page.locator('[data-testid="table"]').scrollIntoViewIfNeeded()
+  })
+
+  test('基础渲染：表头与数据行都在，且序号列存在', async ({ page }) => {
+    const table = page.locator('[data-testid="table-wrap"]')
+    await expect(table.locator('.stk-table')).toBeVisible()
+    // 表头至少有我们的业务列文案
+    await expect(table.locator('th', { hasText: '名称' })).toBeVisible()
+    await expect(table.locator('th', { hasText: '金额' })).toBeVisible()
+    // 数据行渲染出来了
+    const rows = table.locator('.stk-tbody-main tr')
+    await expect(rows).toHaveCount(3)
+  })
+
+  test('小数据量（3 行）：纵向虚拟滚动关闭，DOM 里是真实 3 行', async ({ page }) => {
+    const table = page.locator('[data-testid="table-wrap"]')
+    // 库开启虚拟滚动时会给根加 .virtual 类；门控生效时不应有
+    await expect(table.locator('.stk-table')).not.toHaveClass(/virtual/)
+  })
+
+  test('大数据量（5000 行）：纵向虚拟滚动开启，DOM 行数远少于数据量', async ({ page }) => {
+    const big = page.locator('[data-testid="table-big-wrap"]')
+    await big.scrollIntoViewIfNeeded()
+    await expect(big.locator('.stk-table')).toHaveClass(/virtual/)
+
+    // 虚拟滚动的意义：只渲染视口内若干行，DOM 行数应当是个位数/几十，而不是 5000
+    const rendered = await big.locator('.stk-tbody-main tr').count()
+    expect(rendered).toBeGreaterThan(0)
+    expect(rendered).toBeLessThan(200)
+  })
+
+  test('大数据量：滚动后仍只渲染视口内行（虚拟窗口跟随）', async ({ page }) => {
+    const big = page.locator('[data-testid="table-big-wrap"]')
+    await big.scrollIntoViewIfNeeded()
+
+    const scroller = big.locator('.stk-table-scroll-container, .stk-table-main').first()
+    await scroller.evaluate((el) => {
+      el.scrollTop = 3000
+    })
+    await page.waitForTimeout(150)
+
+    const rendered = await big.locator('.stk-tbody-main tr').count()
+    expect(rendered).toBeGreaterThan(0)
+    expect(rendered).toBeLessThan(200)
+  })
+
+  test('高度约束：容器限高时表格不溢出', async ({ page }) => {
+    const wrap = page.locator('[data-testid="table-wrap"]')
+    const wrapBox = await wrap.boundingBox()
+    const inner = wrap.locator('.stk-table').first()
+    const innerBox = await inner.boundingBox()
+    expect(wrapBox).not.toBeNull()
+    expect(innerBox).not.toBeNull()
+    // 表格不应高于它的容器（留 2px 容差：边框/亚像素）
+    expect(innerBox!.height).toBeLessThanOrEqual(wrapBox!.height + 2)
+  })
+
+  test('外框圆角：bordered 时容器有圆角与描边', async ({ page }) => {
+    // 注意：data-testid 透传给了内层 StkTable（组件 inheritAttrs: false），
+    // 外框与圆角在我们自己的根节点 .g3-table 上，所以要按类名定位。
+    const root = page.locator('[data-testid="table-wrap"] .g3-table').first()
+    await expect(root).toHaveClass(/is-bordered/)
+    const radius = await root.evaluate((el) => getComputedStyle(el).borderRadius)
+    expect(radius).not.toBe('0px')
+    const borderWidth = await root.evaluate((el) => getComputedStyle(el).borderTopWidth)
+    expect(borderWidth).toBe('1px')
+  })
+
+  test('表头显示序号列（seq 默认开启）', async ({ page }) => {
+    const table = page.locator('[data-testid="table-wrap"]')
+    await expect(table.locator('th', { hasText: '序号' })).toBeVisible()
+  })
+
+  test('窄容器下不横向溢出容器宽度', async ({ page }) => {
+    const wrap = page.locator('[data-testid="table-narrow-wrap"]')
+    await wrap.scrollIntoViewIfNeeded()
+    const wrapBox = await wrap.boundingBox()
+    const rootBox = await wrap.locator('[data-testid="table-narrow"]').boundingBox()
+    expect(rootBox!.width).toBeLessThanOrEqual(wrapBox!.width + 2)
+  })
+})
+
+test.describe('G3Table 选择列（真浏览器命中）', () => {
+  test('点击行复选框：勾选态可见地变化', async ({ page }) => {
+    await page.goto('/')
+    const wrap = page.locator('[data-testid="table-wrap"]')
+    await wrap.scrollIntoViewIfNeeded()
+
+    const firstRowCheckbox = wrap.locator('.g3-table__checkbox').first()
+    await firstRowCheckbox.scrollIntoViewIfNeeded()
+    await expect(firstRowCheckbox).not.toHaveClass(/is-checked/)
+
+    await firstRowCheckbox.click()
+    await expect(firstRowCheckbox).toHaveClass(/is-checked/)
+  })
+
+  test('每行复选框数 = 选择列 + checkbox 编辑器列（演示数据定义了两列）', async ({ page }) => {
+    await page.goto('/')
+    const wrap = page.locator('[data-testid="table-wrap"]')
+    await wrap.scrollIntoViewIfNeeded()
+
+    // 演示数据的 tableColumns 里有两个复选框列：选择列（注入）+ 启用列（editor: checkbox）。
+    // 所以每行 2 个是预期值——这正是为什么不能靠「数复选框个数」判断是否有重复渲染。
+    const bodyRows = wrap.locator('.stk-tbody-main tr')
+    await expect(bodyRows).toHaveCount(3)
+    for (let i = 0; i < 3; i += 1) {
+      await expect(bodyRows.nth(i).locator('.g3-table__checkbox')).toHaveCount(2)
+    }
+  })
+
+  test('无重复渲染：每行 td 数等于表头列数', async ({ page }) => {
+    await page.goto('/')
+    const wrap = page.locator('[data-testid="table-wrap"]')
+    await wrap.scrollIntoViewIfNeeded()
+
+    // 单元格数必须与表头列数一致；固定列若被双份渲染，这里会多出来。
+    const headerCount = await wrap.locator('thead th').count()
+    const firstRowTd = await wrap.locator('.stk-tbody-main tr').first().locator('td').count()
+    expect(firstRowTd).toBe(headerCount)
+  })
+
+  test('表头全选：点击后表头与所有数据行的选择列都被勾选', async ({ page }) => {
+    await page.goto('/')
+    const wrap = page.locator('[data-testid="table-wrap"]')
+    await wrap.scrollIntoViewIfNeeded()
+
+    const headerCheckbox = wrap.locator('th .g3-table__checkbox').first()
+    await headerCheckbox.scrollIntoViewIfNeeded()
+    await headerCheckbox.click()
+
+    // 表头 choice 项 + 3 行选择列 = 4 个处于勾选态的选择框
+    // （「启用」列的 checkbox 是数据值，初始为 1 的那两行也会是勾选态，
+    //  所以这里按选择列的固定类名限定范围）
+    await expect(wrap.locator('th .g3-table__checkbox.is-checked')).toHaveCount(1)
+    await expect(wrap.locator('.stk-tbody-main td:first-child .g3-table__checkbox.is-checked')).toHaveCount(3)
+  })
+})
+
+test.describe('G3Table RTL 镜像', () => {
+  test('RTL 下固定列与表格布局不塌陷', async ({ page }) => {
+    await page.goto('/?dir=rtl')
+    const wrap = page.locator('[data-testid="table-wrap"]')
+    await wrap.scrollIntoViewIfNeeded()
+
+    const wrapBox = await wrap.boundingBox()
+    const tableBox = await wrap.locator('.stk-table').first().boundingBox()
+    expect(tableBox).not.toBeNull()
+    // 表格仍应占据容器的整宽（镜像不该把宽度算丢）
+    expect(tableBox!.width).toBeGreaterThan(wrapBox!.width * 0.9)
+  })
+})
diff --git a/code/g3soft-libs/packages/ui/package.json b/code/g3soft-libs/packages/ui/package.json
index 1295394b..6a7c2ab8 100644
--- a/code/g3soft-libs/packages/ui/package.json
+++ b/code/g3soft-libs/packages/ui/package.json
@@ -40,6 +40,7 @@
     "@lucide/vue": "^1.31.0",
     "@tiptap/extension-image": "^3.31.4",
     "@tiptap/extension-link": "^3.31.4",
+    "@tiptap/extension-list": "^3.31.4",
     "@tiptap/extension-placeholder": "^3.31.4",
     "@tiptap/extension-subscript": "^3.31.4",
     "@tiptap/extension-superscript": "^3.31.4",
@@ -49,7 +50,8 @@
     "@tiptap/extension-table-row": "^3.31.4",
     "@tiptap/extension-text-align": "^3.31.4",
     "@tiptap/extension-text-style": "^3.31.4",
-    "@tiptap/starter-kit": "^3.31.4"
+    "@tiptap/starter-kit": "^3.31.4",
+    "stk-table-vue": "1.1.0"
   },
   "devDependencies": {
     "@playwright/test": "^1.63.0",
diff --git a/code/g3soft-libs/packages/ui/playground/main.ts b/code/g3soft-libs/packages/ui/playground/main.ts
index 6a8487d6..e8a97bdf 100644
--- a/code/g3soft-libs/packages/ui/playground/main.ts
+++ b/code/g3soft-libs/packages/ui/playground/main.ts
@@ -1,7 +1,6 @@
 import { createApp, reactive, ref } from 'vue'
 import { Plus, Search, Settings } from '@lucide/vue'
 import {
-  G3Attachment,
   G3Button,
   G3ButtonGroup,
   G3ButtonGroupSeparator,
@@ -35,6 +34,7 @@ import {
   G3Splitter,
   G3SplitterPanel,
   G3Switch,
+  G3Table,
   G3TabPane,
   G3Tabs,
   G3Tag,
@@ -42,7 +42,6 @@ import {
   G3Tooltip,
   G3Tree,
 } from '@g3soft/ui'
-import type { AttachmentCategory, AttachmentItem } from '@g3soft/ui'
 import '@g3soft/tokens'
 
 /**
@@ -74,7 +73,6 @@ const LONG_TEXT = Array.from({ length: 40 }, (_, index) => `第 ${index + 1} 行
 
 const App = {
   components: {
-    G3Attachment,
     G3Button,
     G3ButtonGroup,
     G3ButtonGroupSeparator,
@@ -106,6 +104,7 @@ const App = {
     G3Splitter,
     G3SplitterPanel,
     G3Switch,
+    G3Table,
     G3TabPane,
     G3Tabs,
     G3Tag,
@@ -193,26 +192,50 @@ const App = {
       })
     }
 
-    /* ---- Attachment 附件管理器 ---- */
-    const attachmentFiles = ref<AttachmentItem[]>([
-      { id: 1, name: '2026年度框架合同.pdf', size: 512_000, categoryId: 'contract' },
-      { id: 2, name: '供应商报价明细.xlsx', size: 86_000, categoryId: 'invoice' },
-      { id: 3, name: '现场照片.jpg', size: 1_240_000, categoryId: 'photo' },
-      { id: 4, name: '验收纪要.docx', size: 24_000, categoryId: 'contract' },
-      { id: 5, name: '进度汇报.pptx', size: 640_000, categoryId: 'photo' },
-      { id: 6, name: '现场记录.zip', size: 8_192_000, categoryId: 'invoice' },
+    /* ---- Table 表格 ---- */
+    // 小数据量：用于验证「行数 ≤ 100 时关闭虚拟滚动」的门控
+    // 注意必须是 ref：模板里 v-model:columns 要能回写，否则拖列宽无处落库（松手回弹）
+    const tableColumns = ref([
+      { dataIndex: 'name', title: '名称', width: 180 },
+      { dataIndex: 'amount', title: '金额', width: 120, align: 'right' },
+      { dataIndex: 'status', title: '状态', width: 110, editor: { type: 'select', options: [
+        { label: '启用', value: 1 },
+        { label: '停用', value: 0 },
+      ] } },
+      { dataIndex: 'enabled', title: '启用', width: 80, editor: { type: 'checkbox' } },
+      { dataIndex: 'remark', title: '备注', editor: { type: 'text' } },
+      { dataIndex: 'op', title: '操作', width: 140, resizable: false, actions: [
+        { label: '编辑', onClick: () => {} },
+        { label: '删除', type: 'danger', confirm: '确认删除该行？', onClick: () => {} },
+      ] },
     ])
-    const attachmentCategories: AttachmentCategory[] = [
-      { id: 'contract', name: '合同文件' },
-      { id: 'invoice', name: '发票凭证' },
-      { id: 'photo', name: '现场照片' },
+    const tableData = ref([
+      { id: 1, name: '合同 A', amount: 12000, status: 1, enabled: 1, remark: '已归档' },
+      { id: 2, name: '合同 B', amount: 8600, status: 0, enabled: 0, remark: '' },
+      { id: 3, name: '合同 C', amount: 43000, status: 1, enabled: 1, remark: '待复核' },
+    ])
+    const tableSelectedKeys = ref([])
+
+    // 大数据量：用于验证虚拟滚动真的开启
+    const bigTableColumns = [
+      { dataIndex: 'id', title: 'ID', width: 80 },
+      { dataIndex: 'name', title: '名称', width: 200 },
+      { dataIndex: 'value', title: '数值', width: 140, align: 'right' },
     ]
+    const bigTableData = Array.from({ length: 5000 }, (_, i) => ({
+      id: i + 1,
+      name: `记录 ${i + 1}`,
+      value: (i + 1) * 7,
+    }))
 
     return {
-      attachmentFiles,
-      attachmentCategories,
       rtl,
       toggleRtl,
+      tableColumns,
+      tableData,
+      tableSelectedKeys,
+      bigTableColumns,
+      bigTableData,
       model,
       tab,
       seg,
@@ -478,27 +501,6 @@ const App = {
       <G3RichText v-model="richHtml" data-testid="rich-text" placeholder="请输入正文…" />
     </section>
 
-    <section id="s-attachment">
-      <h2>Attachment 附件管理器</h2>
-      <!-- 根节点是单元素 div，data-testid 直接落在组件上即可 -->
-      <G3Attachment
-        data-testid="attachment"
-        :files="attachmentFiles"
-        :categories="attachmentCategories"
-        :height="420"
-      />
-      <!-- 窄实例：分类栏 200 + 分割条 10 之后列表只剩 ~210px，
-           压到一行的极限（工具栏必须裁切 / 省略，而不是长高）-->
-      <div style="width: 420px; margin-top: 12px">
-        <G3Attachment
-          data-testid="attachment-narrow"
-          :files="attachmentFiles"
-          :categories="attachmentCategories"
-          :height="360"
-        />
-      </div>
-    </section>
-
     <section id="s-feedback">
       <h2>Modal / Drawer / Message / Notification</h2>
       <div class="row">
@@ -525,6 +527,41 @@ const App = {
         <G3Select v-model="model.role" :options="roleOptions" data-testid="drawer-select" placeholder="抽屉内选择" />
       </G3Drawer>
     </section>
+
+    <section id="s-table">
+      <h2>Table 表格</h2>
+
+      <!-- 小数据量（3 行）：行数 ≤ 100，纵向虚拟滚动应当关闭 -->
+      <div data-testid="table-wrap" style="height: 320px">
+        <G3Table
+          data-testid="table"
+          v-model:columns="tableColumns"
+          :data-source="tableData"
+          :row-selection="{ selectedRowKeys: tableSelectedKeys, onChange: (keys) => (tableSelectedKeys = keys) }"
+        />
+      </div>
+
+      <!-- 大数据量（5000 行）：纵向虚拟滚动应当开启；容器限高以产生滚动 -->
+      <div data-testid="table-big-wrap" style="height: 360px; margin-top: 16px">
+        <G3Table
+          data-testid="table-big"
+          :columns="bigTableColumns"
+          :data-source="bigTableData"
+          :seq="false"
+          :row-height="30"
+        />
+      </div>
+
+      <!-- 窄容器：验证列宽铺满与省略号 -->
+      <div data-testid="table-narrow-wrap" style="width: 480px; height: 240px; margin-top: 16px">
+        <G3Table
+          data-testid="table-narrow"
+          :columns="tableColumns"
+          :data-source="tableData"
+          :seq="false"
+        />
+      </div>
+    </section>
   </div>
   `,
 }
diff --git a/code/g3soft-libs/packages/ui/src/attachment/Attachment.test.ts b/code/g3soft-libs/packages/ui/src/attachment/Attachment.test.ts
deleted file mode 100644
index 3210a093..00000000
--- a/code/g3soft-libs/packages/ui/src/attachment/Attachment.test.ts
+++ /dev/null
@@ -1,273 +0,0 @@
-import { mount } from '@vue/test-utils'
-import { describe, expect, it } from 'vitest'
-import { nextTick } from 'vue'
-import G3Attachment from './Attachment.vue'
-import type { AttachmentInvalidInfo, AttachmentItem } from './types'
-
-/**
- * 契约测试：组件与业务解耦的那几条线必须成立 ——
- * 数据只从 prop 进、动作只从事件出、校验失败走 invalid、待上传队列的生命周期。
- * 三栏几何 / 拖拽分隔条依赖真实布局，放 E2E。
- */
-
-const FILES: AttachmentItem[] = [
-  { id: 1, name: '合同.pdf', size: 100 },
-  { id: 2, name: '报价.xlsx', size: 200 },
-  { id: 3, name: '照片.png', size: 300 },
-]
-
-const CATEGORIES = [
-  { id: 'c1', name: '合同资料' },
-  { id: 'c2', name: '报价资料' },
-]
-
-function makeFile(name: string, bytes = 4): File {
-  return new File(['a'.repeat(bytes)], name, { type: 'application/octet-stream' })
-}
-
-function emitted<T>(wrapper: ReturnType<typeof mount>, name: string): T[] {
-  return (wrapper.emitted(name) ?? []) as unknown as T[]
-}
-
-describe('G3Attachment 渲染', () => {
-  it('按 files 渲染卡片，分类树补上「全部」根', () => {
-    const wrapper = mount(G3Attachment, { props: { files: FILES, categories: CATEGORIES } })
-
-    expect(wrapper.findAll('.g3-attachment__card')).toHaveLength(3)
-    const categoryText = wrapper.find('.g3-attachment__category').text()
-    expect(categoryText).toContain('全部')
-    expect(categoryText).toContain('合同资料')
-  })
-
-  it('分隔线常显：Splitter 不带 is-bar-on-hover，否则分类栏右侧看不出边界', () => {
-    const wrapper = mount(G3Attachment, { props: { files: FILES, categories: CATEGORIES } })
-    const splitter = wrapper.find('.g3-attachment__splitter')
-
-    expect(splitter.exists()).toBe(true)
-    expect(splitter.classes()).not.toContain('is-bar-on-hover')
-  })
-
-  it('默认不渲染预览栏，只留列表（没有 categories 时连左栏也没有）', () => {
-    const wrapper = mount(G3Attachment, { props: { files: FILES } })
-
-    expect(wrapper.find('.g3-attachment__category').exists()).toBe(false)
-    expect(wrapper.find('.g3-attachment__preview').exists()).toBe(false)
-  })
-
-  it('showPreview 打开时才渲染右栏', () => {
-    const wrapper = mount(G3Attachment, {
-      props: { files: FILES, categories: CATEGORIES, showPreview: true },
-    })
-
-    expect(wrapper.find('.g3-attachment__category').exists()).toBe(true)
-    expect(wrapper.find('.g3-attachment__preview').exists()).toBe(true)
-  })
-
-  it('readonly 隐藏上传入口与删除按钮（底栏保留计数）', () => {
-    const wrapper = mount(G3Attachment, { props: { files: FILES, readonly: true } })
-
-    expect(wrapper.find('.g3-attachment__footer').exists()).toBe(true)
-    expect(wrapper.find('.g3-attachment__footer-actions').exists()).toBe(false)
-    expect(wrapper.find('.g3-attachment__file-input').exists()).toBe(false)
-    expect(wrapper.find('.g3-attachment__card-btn--danger').exists()).toBe(false)
-  })
-
-  it('空态是投放区：带限制提示，readonly 下不可点', () => {
-    const wrapper = mount(G3Attachment, {
-      props: { files: [], accept: '.pdf', maxSize: 1024, maxCount: 3 },
-    })
-    const empty = wrapper.find('.g3-attachment__empty')
-
-    expect(empty.exists()).toBe(true)
-    expect(empty.text()).toContain('.pdf')
-    expect(empty.text()).toContain('1.0 KB')
-    expect(empty.text()).toContain('3')
-    expect(empty.classes()).not.toContain('is-readonly')
-  })
-
-  it('readonly 下空态不可点', () => {
-    const wrapper = mount(G3Attachment, { props: { files: [], readonly: true } })
-
-    expect(wrapper.find('.g3-attachment__empty').classes()).toContain('is-readonly')
-  })
-})
-
-describe('G3Attachment 批量操作', () => {
-  it('未勾选时不渲染批量操作，勾选后浮出并显示已选数量', async () => {
-    const wrapper = mount(G3Attachment, { props: { files: FILES } })
-    expect(wrapper.find('.g3-attachment__toolbar-count').exists()).toBe(false)
-
-    wrapper.vm.selectAll()
-    await nextTick()
-
-    expect(wrapper.find('.g3-attachment__toolbar-count').text()).toBe('已选 3 项')
-    expect(emitted<[AttachmentItem[]]>(wrapper, 'select')[0][0]).toHaveLength(3)
-
-    // 批量按钮要有边界（outline / danger-outline）且同属 small 档：
-    // 整行才是同一字号，也不会像 ghost 裸文本那样飘着
-    const buttons = wrapper.findAll('.g3-attachment__toolbar .g3-button')
-    expect(buttons.map((button) => button.text())).toEqual(['下载', '删除'])
-    expect(buttons[0].classes()).toContain('g3-button--outline')
-    expect(buttons[0].classes()).toContain('g3-button--small')
-    expect(buttons[1].classes()).toContain('g3-button--danger-outline')
-  })
-})
-
-describe('G3Attachment 分类与预览', () => {
-  it('点分类抛 categoryChange（带原始分类对象）与 update:categoryKey', async () => {
-    const wrapper = mount(G3Attachment, { props: { files: FILES, categories: CATEGORIES } })
-    const nodes = wrapper.findAll('.g3-tree-node')
-    expect(nodes.length).toBe(CATEGORIES.length + 1)
-
-    await nodes[1].trigger('click')
-
-    expect(emitted<[string | number, unknown]>(wrapper, 'categoryChange')[0]).toEqual([
-      'c1',
-      CATEGORIES[0],
-    ])
-    expect(emitted<[string | number]>(wrapper, 'update:categoryKey')[0][0]).toBe('c1')
-  })
-
-  it('点卡片抛 preview，开着右栏时同步展示', async () => {
-    const wrapper = mount(G3Attachment, { props: { files: FILES, showPreview: true } })
-
-    await wrapper.findAll('.g3-attachment__card')[0].trigger('click')
-
-    expect(emitted<[AttachmentItem]>(wrapper, 'preview')[0][0]).toEqual(FILES[0])
-    expect(wrapper.find('.g3-attachment__preview-title').text()).toBe('合同.pdf')
-    expect(wrapper.find('.g3-attachment__preview-counter').text()).toBe('1 / 3')
-  })
-
-  it('关掉预览栏时 preview 事件照常抛出（业务自己开弹窗）', async () => {
-    const wrapper = mount(G3Attachment, { props: { files: FILES } })
-
-    await wrapper.findAll('.g3-attachment__card')[0].trigger('click')
-
-    expect(emitted<[AttachmentItem]>(wrapper, 'preview')[0][0]).toEqual(FILES[0])
-    expect(wrapper.find('.g3-attachment__preview').exists()).toBe(false)
-  })
-})
-
-describe('G3Attachment 分页', () => {  it('不传 total 按客户端分页切片', () => {
-    const wrapper = mount(G3Attachment, { props: { files: FILES, pageSize: 2 } })
-
-    expect(wrapper.findAll('.g3-attachment__card')).toHaveLength(2)
-    expect(wrapper.find('.g3-attachment__pagination').exists()).toBe(true)
-  })
-
-  it('传了 total 视为服务端分页，files 已是当前页不再切', () => {
-    const wrapper = mount(G3Attachment, { props: { files: FILES, pageSize: 2, total: 99 } })
-
-    expect(wrapper.findAll('.g3-attachment__card')).toHaveLength(3)
-  })
-})
-
-describe('G3Attachment 待上传队列', () => {
-  it('按 accept / maxSize 拒绝并抛 invalid，只有合法文件入队', async () => {
-    const wrapper = mount(G3Attachment, { props: { accept: '.pdf', maxSize: 100 } })
-
-    const accepted = wrapper.vm.addFiles([
-      makeFile('small.pdf', 10),
-      makeFile('big.pdf', 200),
-      makeFile('bad.exe', 10),
-    ])
-    await nextTick()
-
-    expect(accepted.map((file) => file.name)).toEqual(['small.pdf'])
-    expect(wrapper.vm.pendingFiles.map((pending) => pending.name)).toEqual(['small.pdf'])
-
-    const reasons = emitted<[AttachmentInvalidInfo]>(wrapper, 'invalid').map(
-      ([info]) => info.reason,
-    )
-    expect(reasons).toEqual(['max-size', 'accept'])
-  })
-
-  it('未提供 uploadRequest 时点上传：抛出 upload 并清空队列', async () => {
-    const wrapper = mount(G3Attachment, { props: {} })
-    wrapper.vm.addFiles([makeFile('a.pdf'), makeFile('b.pdf')])
-    await nextTick()
-    expect(wrapper.findAll('.g3-attachment__card')).toHaveLength(2)
-
-    const uploadButton = wrapper.findAll('.g3-attachment__footer .g3-button').at(-1)
-    await uploadButton?.trigger('click')
-
-    const uploads = emitted<[File[]]>(wrapper, 'upload')
-    expect(uploads).toHaveLength(1)
-    expect(uploads[0][0].map((file) => file.name)).toEqual(['a.pdf', 'b.pdf'])
-    expect(wrapper.vm.pendingFiles).toHaveLength(0)
-    expect(wrapper.findAll('.g3-attachment__card')).toHaveLength(0)
-  })
-
-  it('提供 uploadRequest 时组件托管：成功回调后回填列表', async () => {
-    const wrapper = mount(G3Attachment, {
-      props: {
-        uploadRequest: (files: File[]) =>
-          files.map((file, index) => ({ id: `remote-${index}`, name: file.name })),
-      },
-    })
-    wrapper.vm.addFiles([makeFile('a.pdf')])
-    await nextTick()
-
-    await wrapper.findAll('.g3-attachment__footer .g3-button').at(-1)?.trigger('click')
-    await nextTick()
-
-    const success = emitted<[File[], AttachmentItem[]]>(wrapper, 'uploadSuccess')
-    expect(success).toHaveLength(1)
-    const [, result] = success[0]
-    expect(result.map((item) => item.name)).toEqual(['a.pdf'])
-    expect(emitted<[AttachmentItem[]]>(wrapper, 'update:files')[0][0]).toEqual(result)
-    expect(wrapper.vm.pendingFiles).toHaveLength(0)
-  })
-})
-
-describe('G3Attachment 删除', () => {
-  it('confirmRemove 关闭时直接抛 remove 与新的 files', async () => {
-    const wrapper = mount(G3Attachment, { props: { files: FILES, confirmRemove: false } })
-
-    await wrapper.findAll('.g3-attachment__card-btn--danger')[0].trigger('click')
-    await nextTick()
-
-    expect(emitted<[AttachmentItem[]]>(wrapper, 'remove')[0][0]).toEqual([FILES[0]])
-    expect(emitted<[AttachmentItem[]]>(wrapper, 'update:files')[0][0]).toEqual([FILES[1], FILES[2]])
-  })
-
-  it('默认先出确认框，点确认后才删', async () => {
-    const wrapper = mount(G3Attachment, { props: { files: FILES } })
-
-    await wrapper.findAll('.g3-attachment__card-btn--danger')[0].trigger('click')
-    await nextTick()
-
-    const footer = document.body.querySelector('.g3-modal__footer')
-    expect(footer).not.toBeNull()
-    expect(document.body.textContent).toContain('确定删除')
-
-    const buttons = footer?.querySelectorAll('button') ?? []
-    expect(buttons).toHaveLength(2)
-    buttons[1].click()
-    await nextTick()
-    await nextTick()
-
-    expect(emitted<[AttachmentItem[]]>(wrapper, 'remove')).toHaveLength(1)
-    expect(emitted<[AttachmentItem[]]>(wrapper, 'update:files')[0][0]).toEqual([FILES[1], FILES[2]])
-  })
-
-  it('removeRequest 抛错时抛 removeError 且不动列表', async () => {
-    const error = new Error('server down')
-    const wrapper = mount(G3Attachment, {
-      props: {
-        files: FILES,
-        confirmRemove: false,
-        removeRequest: () => {
-          throw error
-        },
-      },
-    })
-
-    await wrapper.findAll('.g3-attachment__card-btn--danger')[0].trigger('click')
-    await nextTick()
-
-    expect(emitted<[unknown, AttachmentItem[]]>(wrapper, 'removeError')[0][0]).toBe(error)
-    expect(wrapper.emitted('update:files')).toBeUndefined()
-    expect(wrapper.emitted('remove')).toBeUndefined()
-  })
-})
diff --git a/code/g3soft-libs/packages/ui/src/attachment/Attachment.vue b/code/g3soft-libs/packages/ui/src/attachment/Attachment.vue
deleted file mode 100644
index 8529484f..00000000
--- a/code/g3soft-libs/packages/ui/src/attachment/Attachment.vue
+++ /dev/null
@@ -1,393 +0,0 @@
-<script setup lang="ts">
-import { computed, ref } from 'vue'
-import { G3Button } from '../button'
-import { G3Modal } from '../modal'
-import { G3Spin } from '../spin'
-import { G3Splitter, G3SplitterPanel } from '../splitter'
-import { G3Tree } from '../tree'
-import { useLocale } from '../_composables/useLocale'
-import { useNamespace } from '../_composables/useNamespace'
-import AttachmentList from './AttachmentList.vue'
-import AttachmentPreview from './AttachmentPreview.vue'
-import type { TreeKey, TreeNodeData } from '../tree'
-import type {
-  AttachmentCategory,
-  AttachmentEmits,
-  AttachmentItem,
-  AttachmentProps,
-  AttachmentUploadContext,
-} from './types'
-
-/**
- * 附件管理器 —— 分类 / 列表 / 预览三栏，上传（选择 / 拖拽 / 粘贴）、多选下载删除、分页。
- *
- * 三条解耦线：
- * 1. **数据**：只吃 `files` + `categories` 两个 prop，不请求接口、不感知业务主键；
- * 2. **动作**：用户意图一律以事件抛出（`upload` / `remove` / `download` …）；
- * 3. **可选托管**：传 `uploadRequest` / `removeRequest` 时组件替你跑请求，
- *    成功后自行 emit `update:files`，不想接管就只用事件。
- */
-defineOptions({ name: 'G3Attachment' })
-
-const props = withDefaults(defineProps<AttachmentProps>(), {
-  files: () => [],
-  categories: () => [],
-  categoryKey: '',
-  showCategory: true,
-  showPreview: false,
-  readonly: false,
-  loading: false,
-  categoryLoading: false,
-  selectable: true,
-  multiple: true,
-  accept: undefined,
-  maxSize: 0,
-  maxCount: 0,
-  pasteUpload: false,
-  confirmRemove: true,
-  builtinDownload: true,
-  pagination: true,
-  page: undefined,
-  pageSize: undefined,
-  total: undefined,
-  pageSizeOptions: () => [10, 20, 50, 100],
-  showSizeChanger: false,
-  height: undefined,
-  uploadRequest: undefined,
-  removeRequest: undefined,
-})
-
-const emit = defineEmits<AttachmentEmits>()
-
-const { b, e } = useNamespace('attachment')
-const locale = useLocale()
-
-/** 分类树里的「全部」节点 key（对外用 `''` 表示全部） */
-const ALL_CATEGORY_KEY = '__g3_attachment_all__'
-
-const listRef = ref<InstanceType<typeof AttachmentList> | null>(null)
-const activeItem = ref<AttachmentItem | null>(null)
-const pendingRemove = ref<AttachmentItem[]>([])
-const uploading = ref(false)
-const removing = ref(false)
-
-const rootStyle = computed(() => {
-  const height = props.height
-  if (height == null || height === '') return undefined
-  return { height: typeof height === 'number' ? `${height}px` : String(height) }
-})
-
-const showCategories = computed(() => props.showCategory && props.categories.length > 0)
-
-/* ---------- 分类 ---------- */
-function toCategoryNode(category: AttachmentCategory): TreeNodeData {
-  return {
-    key: category.id,
-    title: category.name,
-    disabled: category.disabled,
-    children: category.children?.map(toCategoryNode),
-  }
-}
-
-const categoryTree = computed<TreeNodeData[]>(() => {
-  if (!showCategories.value) return []
-  return [
-    {
-      key: ALL_CATEGORY_KEY,
-      title: locale.value.attachment.allCategory,
-      children: props.categories.map(toCategoryNode),
-    },
-  ]
-})
-
-const selectedCategoryKeys = computed<TreeKey[]>(() => {
-  const key = props.categoryKey
-  if (key === '' || key == null) return [ALL_CATEGORY_KEY]
-  return [String(key)]
-})
-
-/** 按字符串 key 找回原始分类对象（保留业务侧 id 的原始类型） */
-function findCategory(key: string): AttachmentCategory | null {
-  const stack: AttachmentCategory[] = [...props.categories]
-  while (stack.length) {
-    const current = stack.shift() as AttachmentCategory
-    if (String(current.id) === key) return current
-    if (current.children?.length) stack.push(...current.children)
-  }
-  return null
-}
-
-function onCategorySelect(keys: TreeKey[]) {
-  const key = keys.length ? String(keys[0]) : ALL_CATEGORY_KEY
-  const category = key === ALL_CATEGORY_KEY ? null : findCategory(key)
-  const next = category ? category.id : ''
-  activeItem.value = null
-  emit('update:categoryKey', next)
-  emit('categoryChange', next, category)
-}
-
-/* ---------- 预览 ---------- */
-/** 预览翻页就按当前页附件的顺序 */
-const previewList = computed(() => props.files)
-
-function onPreview(item: AttachmentItem) {
-  if (props.showPreview) activeItem.value = item
-  emit('preview', item)
-}
-
-function step(delta: number) {
-  const list = previewList.value
-  const current = activeItem.value
-  if (!current) return
-  const index = list.findIndex((file) => file.id === current.id)
-  const target = index + delta
-  if (index < 0 || target < 0 || target >= list.length) return
-  activeItem.value = list[target]
-  emit('preview', list[target])
-}
-
-/* ---------- 下载 ---------- */
-function onDownload(items: AttachmentItem[]) {
-  emit('download', items)
-}
-
-/* ---------- 上传 ---------- */
-const uploadContext = computed<AttachmentUploadContext>(() => ({
-  categoryId: props.categoryKey === '' ? undefined : props.categoryKey,
-}))
-
-async function onUpload(files: File[]) {
-  const request = props.uploadRequest
-  if (!request) {
-    // 交给业务：清空队列（业务拿到 File[] 后自行上传 / 落库）
-    listRef.value?.clearPending()
-    emit('upload', files, uploadContext.value)
-    return
-  }
-  uploading.value = true
-  try {
-    const result = await request(files, uploadContext.value)
-    listRef.value?.clearPending()
-    if (Array.isArray(result) && result.length) {
-      const next = [...props.files, ...result]
-      emit('update:files', next)
-      emit('change', next)
-    }
-    emit('uploadSuccess', files, result)
-  } catch (error) {
-    emit('uploadError', error, files)
-  } finally {
-    uploading.value = false
-  }
-}
-
-/* ---------- 删除 ---------- */
-const confirmOpen = computed({
-  get: () => pendingRemove.value.length > 0,
-  set: (value: boolean) => {
-    if (!value) pendingRemove.value = []
-  },
-})
-
-const confirmTitle = computed(() => {
-  const items = pendingRemove.value
-  if (items.length === 1) {
-    return locale.value.attachment.removeConfirmSingle.replace('{name}', items[0].name)
-  }
-  return locale.value.attachment.removeConfirm.replace('{count}', String(items.length))
-})
-
-async function performRemove(items: AttachmentItem[]) {
-  removing.value = true
-  try {
-    if (props.removeRequest) await props.removeRequest(items)
-    const removed = new Set(items.map((item) => item.id))
-    const next = props.files.filter((file) => !removed.has(file.id))
-    emit('update:files', next)
-    emit('change', next)
-    emit('remove', items)
-    if (activeItem.value && removed.has(activeItem.value.id)) activeItem.value = null
-    pendingRemove.value = []
-  } catch (error) {
-    emit('removeError', error, items)
-  } finally {
-    removing.value = false
-  }
-}
-
-function onRemove(items: AttachmentItem[]) {
-  if (props.readonly || !items.length) return
-  if (!props.confirmRemove) {
-    void performRemove(items)
-    return
-  }
-  pendingRemove.value = items
-}
-
-/* ---------- 对外能力 ---------- */
-function openFileDialog() {
-  listRef.value?.openFileDialog()
-}
-
-function clearSelection() {
-  listRef.value?.clearSelection()
-}
-
-function selectAll() {
-  listRef.value?.selectAll()
-}
-
-function addFiles(files: File[] | FileList) {
-  return listRef.value?.addFiles(files) ?? []
-}
-
-function clearPending() {
-  listRef.value?.clearPending()
-}
-
-defineExpose({
-  get selectedItems() {
-    return listRef.value?.selectedItems ?? []
-  },
-  get pendingFiles() {
-    return listRef.value?.pendingFiles ?? []
-  },
-  openFileDialog,
-  clearSelection,
-  selectAll,
-  addFiles,
-  clearPending,
-  listRef,
-})
-</script>
-
-<template>
-  <div :class="b()" :style="rootStyle" data-slot="attachment">
-    <G3Splitter :class="e('splitter')" :bar-on-hover="false">
-      <G3SplitterPanel v-if="showCategories" :default-size="200" :min="150" :max="320">
-        <div :class="e('category')">
-          <G3Spin :spinning="categoryLoading">
-            <G3Tree
-              :class="e('category-tree')"
-              :tree-data="categoryTree"
-              :selected-keys="selectedCategoryKeys"
-              :default-expand-all="true"
-              block-node
-              @select="onCategorySelect"
-            />
-          </G3Spin>
-        </div>
-      </G3SplitterPanel>
-
-      <G3SplitterPanel :min="280">
-        <AttachmentList
-          ref="listRef"
-          :files="files"
-          :category-id="categoryKey"
-          :loading="loading"
-          :uploading="uploading"
-          :removing="removing"
-          :readonly="readonly"
-          :selectable="selectable"
-          :multiple="multiple"
-          :accept="accept"
-          :max-size="maxSize"
-          :max-count="maxCount"
-          :paste-upload="pasteUpload"
-          :builtin-download="builtinDownload"
-          :pagination="pagination"
-          :page="page"
-          :page-size="pageSize"
-          :total="total"
-          :page-size-options="pageSizeOptions"
-          :show-size-changer="showSizeChanger"
-          @update:page="emit('update:page', $event)"
-          @update:page-size="emit('update:pageSize', $event)"
-          @select="emit('select', $event)"
-          @preview="onPreview"
-          @download="onDownload"
-          @remove="onRemove"
-          @upload="onUpload"
-          @invalid="emit('invalid', $event)"
-        />
-      </G3SplitterPanel>
-
-      <G3SplitterPanel v-if="showPreview" :default-size="360" :min="280">
-        <AttachmentPreview
-          :item="activeItem"
-          :list="previewList"
-          @prev="step(-1)"
-          @next="step(1)"
-        />
-      </G3SplitterPanel>
-    </G3Splitter>
-
-    <!-- 删除二次确认 -->
-    <G3Modal
-      v-model:open="confirmOpen"
-      :title="confirmTitle"
-      :width="416"
-      centered
-      :closable="false"
-      :fullscreen="false"
-      :resizable="false"
-      :mask-closable="false"
-      :confirm-loading="removing"
-    >
-      <template #footer>
-        <G3Button type="outline" :disabled="removing" @click="confirmOpen = false">
-          {{ locale.common.cancel }}
-        </G3Button>
-        <G3Button
-          type="danger"
-          :loading="removing"
-          @click="performRemove(pendingRemove)"
-        >
-          {{ locale.attachment.remove }}
-        </G3Button>
-      </template>
-    </G3Modal>
-  </div>
-</template>
-
-<style lang="scss">
-@use '@g3soft/tokens/scss' as *;
-
-.#{b('attachment')} {
-  display: flex;
-  flex-direction: column;
-  width: 100%;
-  height: 100%;
-  min-height: 320px;
-  overflow: hidden;
-  border: 1px solid v('border-color', #d9d9d9);
-  border-radius: v('radius-lg', 8px);
-  background: v('bg-container', #fff);
-}
-
-.#{e('attachment', 'splitter')} {
-  flex: 1;
-  min-height: 0;
-}
-
-/* 分割线常显（Splitter 的 barOnHover 已关）并收成 1px：
-   默认 3px 在「分类栏 | 卡片区」这种窄栏之间更像一根竖条而非分隔线。
-   选择器带上自己的 block 类（3 个类）以盖过 Splitter 自身的 2 类规则。 */
-.#{e('attachment', 'splitter')}.#{m('splitter', 'horizontal')} .#{e('splitter', 'bar-line')} {
-  width: 1px;
-}
-
-.#{e('attachment', 'category')} {
-  width: 100%;
-  height: 100%;
-  min-width: 0;
-  min-height: 0;
-  overflow: auto;
-  padding: v('space-2', 8px) v('space-1', 4px);
-  box-sizing: border-box;
-}
-
-.#{e('attachment', 'category-tree')} {
-  min-width: 100%;
-}
-</style>
diff --git a/code/g3soft-libs/packages/ui/src/attachment/AttachmentCard.vue b/code/g3soft-libs/packages/ui/src/attachment/AttachmentCard.vue
deleted file mode 100644
index 9079ee37..00000000
--- a/code/g3soft-libs/packages/ui/src/attachment/AttachmentCard.vue
+++ /dev/null
@@ -1,376 +0,0 @@
-<script setup lang="ts">
-import { computed } from 'vue'
-import { Download, Trash2 } from '@lucide/vue'
-import { G3Button } from '../button'
-import { G3Checkbox } from '../checkbox'
-import { G3Tag } from '../tag'
-import { useLocale } from '../_composables/useLocale'
-import { useNamespace } from '../_composables/useNamespace'
-import { ATTACHMENT_KIND_ICONS } from './icons'
-import { formatFileSize, getExtension, getFileKind, isImageFile } from './file'
-import type { AttachmentListItem } from './types'
-
-/**
- * 附件卡片 —— 网格视图的单项。
- *
- * 视觉要点：卡片本体只有「预览图 + 文件名」，操作按钮平时隐在预览图右下角，
- * hover / 键盘聚焦（`focus-within`）才浮现；触屏设备常显。信息区不再压一条操作栏，
- * 少一层边框与两条分隔线。
- *
- * 纯展示 + 事件上报，不做任何数据请求；勾选 / 预览 / 下载 / 删除均交给父级。
- */
-defineOptions({ name: 'G3AttachmentCard' })
-
-const props = withDefaults(
-  defineProps<{
-    item: AttachmentListItem
-    /** 是否勾选 */
-    selected?: boolean
-    /** 是否显示勾选框 */
-    selectable?: boolean
-    /** 只读：隐藏删除入口 */
-    readonly?: boolean
-  }>(),
-  { selected: false, selectable: true, readonly: false },
-)
-
-const emit = defineEmits<{
-  select: [item: AttachmentListItem, checked: boolean]
-  preview: [item: AttachmentListItem]
-  download: [item: AttachmentListItem]
-  remove: [item: AttachmentListItem]
-}>()
-
-const { e, em, is } = useNamespace('attachment')
-const locale = useLocale()
-
-const kind = computed(() => getFileKind(props.item.name))
-const kindIcon = computed(() => ATTACHMENT_KIND_ICONS[kind.value])
-const extension = computed(
-  () => props.item.ext || getExtension(props.item.name) || '?',
-)
-const uploading = computed(() => props.item.status === 'uploading')
-/** 信息行：上传中显示进度百分比，否则显示大小 */
-const metaText = computed(() =>
-  uploading.value ? `${props.item.percent ?? 0}%` : formatFileSize(props.item.size),
-)
-
-/** 缩略图：待上传项用 blob URL，已上传项优先 thumbnailUrl 再回退 url */
-const thumbnail = computed(() => {
-  const item = props.item
-  if (!isImageFile(item.name)) return ''
-  return item.thumbnailUrl || item.url || ''
-})
-
-const classes = computed(() => [
-  e('card'),
-  {
-    [is('selected')]: props.selected,
-    [is('pending')]: !!props.item.pending,
-  },
-])
-
-function onCheck(checked: boolean) {
-  emit('select', props.item, checked)
-}
-
-function onPreview() {
-  emit('preview', props.item)
-}
-</script>
-
-<template>
-  <div :class="classes" :title="item.name" data-slot="attachment-card" @click="onPreview">
-    <div :class="e('card-thumb')">
-      <img v-if="thumbnail" :src="thumbnail" :alt="item.name" />
-      <span v-else :class="[e('type'), em('type', kind)]">
-        <component :is="kindIcon" :size="20" :stroke-width="1.75" aria-hidden="true" />
-        <span :class="e('type-ext')">{{ extension }}</span>
-      </span>
-
-      <span v-if="selectable" :class="e('card-check')" @click.stop>
-        <G3Checkbox :model-value="selected" @update:model-value="onCheck" />
-      </span>
-
-      <span
-        v-if="uploading"
-        :class="e('card-progress')"
-        role="progressbar"
-        :aria-valuenow="item.percent ?? 0"
-      >
-        <span :style="{ inlineSize: `${item.percent ?? 0}%` }" />
-      </span>
-
-      <div :class="e('card-actions')" @click.stop>
-        <G3Button
-          type="ghost"
-          :class="e('card-btn')"
-          :disabled="!!item.pending"
-          :title="locale.attachment.download"
-          :aria-label="locale.attachment.download"
-          @click="emit('download', item)"
-        >
-          <Download :size="14" />
-        </G3Button>
-        <G3Button
-          v-if="!readonly"
-          type="ghost"
-          :class="[e('card-btn'), em('card-btn', 'danger')]"
-          :title="locale.attachment.remove"
-          :aria-label="locale.attachment.remove"
-          @click="emit('remove', item)"
-        >
-          <Trash2 :size="14" />
-        </G3Button>
-      </div>
-    </div>
-
-    <div :class="e('card-info')">
-      <span :class="e('card-name')">{{ item.name }}</span>
-      <span :class="e('card-meta')">
-        <G3Tag v-if="item.pending" variant="outline" :class="e('card-tag')">
-          {{ locale.attachment.pending }}
-        </G3Tag>
-        <span :class="e('card-size')">{{ metaText }}</span>
-      </span>
-    </div>
-  </div>
-</template>
-
-<style lang="scss">
-@use '@g3soft/tokens/scss' as *;
-
-.#{e('attachment', 'card')} {
-  position: relative;
-  display: flex;
-  flex-direction: column;
-  box-sizing: border-box;
-  overflow: hidden;
-  border: 1px solid v('border-color', #d9d9d9);
-  border-radius: v('radius', 6px);
-  background: v('bg-container', #fff);
-  cursor: pointer;
-  transition:
-    border-color v('duration-fast', 0.1s) v('ease', ease),
-    background-color v('duration-fast', 0.1s) v('ease', ease);
-}
-
-.#{e('attachment', 'card')}:hover,
-.#{e('attachment', 'card')}:focus-within {
-  border-color: v('text-3', rgba(0, 0, 0, 0.45));
-}
-
-/* 选中：主色描边 + 主色淡底（与 Tree 选中态同一套视觉） */
-.#{e('attachment', 'card')}.#{is('selected')} {
-  border-color: v('color-primary', #18181b);
-  background: v('color-primary-soft', rgba(24, 24, 27, 0.12));
-
-  &:hover {
-    border-color: v('color-primary', #18181b);
-  }
-}
-
-/* 待上传：虚线边，一眼区分「还没提交」 */
-.#{e('attachment', 'card')}.#{is('pending')} {
-  border-style: dashed;
-}
-
-/* ---------- 预览图 ---------- */
-.#{e('attachment', 'card-thumb')} {
-  position: relative;
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  aspect-ratio: 16 / 10;
-  overflow: hidden;
-  /* 与信息区的分界靠底色差，不再画线 */
-  background: v('fill', rgba(0, 0, 0, 0.04));
-
-  img {
-    width: 100%;
-    height: 100%;
-    object-fit: cover;
-  }
-}
-
-/* ---------- 类型块：图标 + 扩展名，颜色由文件族变量决定 ---------- */
-.#{e('attachment', 'type')} {
-  #{css-var('attachment-type-image')}: #{v('color-primary', #18181b)};
-  #{css-var('attachment-type-doc')}: #{v('color-danger', #ec4246)};
-  #{css-var('attachment-type-sheet')}: #{v('color-success', #45b114)};
-  #{css-var('attachment-type-slide')}: #{v('color-warning', #e79a0d)};
-  #{css-var('attachment-type-archive')}: #d98e04;
-  #{css-var('attachment-type-media')}: #1f9ea8;
-  #{css-var('attachment-type-other')}: #{v('text-3', rgba(0, 0, 0, 0.45))};
-
-  display: inline-flex;
-  flex-direction: column;
-  align-items: center;
-  justify-content: center;
-  gap: 2px;
-  min-width: 52px;
-  padding: v('space-1', 4px) 6px;
-  box-sizing: border-box;
-  border-radius: v('radius', 6px);
-  /* 淡底 + 同色前景，不再叠 1px 同色描边 */
-  background: color-mix(
-    in srgb,
-    var(#{css-var('attachment-type-color')}) 10%,
-    #{v('bg-container', #fff)}
-  );
-  color: var(#{css-var('attachment-type-color')});
-}
-
-@each $kind in image, doc, sheet, slide, archive, media, other {
-  .#{em('attachment', 'type', $kind)} {
-    #{css-var('attachment-type-color')}: var(#{css-var('attachment-type-#{$kind}')});
-  }
-}
-
-.#{e('attachment', 'type-ext')} {
-  font-size: 10px;
-  font-weight: 600;
-  letter-spacing: 0.06em;
-  line-height: 1;
-  text-transform: uppercase;
-}
-
-/* 暗色下两个非令牌色提亮一档，保证在深底上仍有对比 */
-html[data-g3-theme='dark'],
-.dark {
-  .#{e('attachment', 'type')} {
-    #{css-var('attachment-type-archive')}: #e0a63c;
-    #{css-var('attachment-type-media')}: #38bcc6;
-  }
-}
-
-/* ---------- 勾选：浮在预览图左上角 ---------- */
-.#{e('attachment', 'card-check')} {
-  position: absolute;
-  top: 6px;
-  inset-inline-start: 6px;
-  z-index: 2;
-  padding: 2px;
-  line-height: 1;
-  border-radius: v('radius-sm', 4px);
-  background: v('bg-container', #fff);
-}
-
-/* ---------- 操作：默认隐藏，hover / 键盘聚焦浮现 ---------- */
-.#{e('attachment', 'card-actions')} {
-  position: absolute;
-  inset-block-end: 6px;
-  inset-inline-end: 6px;
-  z-index: 2;
-  display: flex;
-  gap: 2px;
-  padding: 2px;
-  border-radius: v('radius-sm', 4px);
-  background: color-mix(in srgb, #{v('bg-container', #fff)} 88%, transparent);
-  opacity: 0;
-  pointer-events: none;
-  transform: translateY(2px);
-  transition:
-    opacity v('duration-fast', 0.1s) v('ease', ease),
-    transform v('duration-fast', 0.1s) v('ease', ease);
-}
-
-.#{e('attachment', 'card')}:hover .#{e('attachment', 'card-actions')},
-.#{e('attachment', 'card')}:focus-within .#{e('attachment', 'card-actions')} {
-  opacity: 1;
-  pointer-events: auto;
-  transform: none;
-}
-
-/* 触屏没有 hover：直接常显 */
-@media (hover: none) {
-  .#{e('attachment', 'card-actions')} {
-    opacity: 1;
-    pointer-events: auto;
-    transform: none;
-  }
-}
-
-.#{e('attachment', 'card-btn')} {
-  width: 24px;
-  height: 24px;
-  min-height: 0;
-  padding: 0;
-  border-radius: v('radius-sm', 4px);
-  color: v('text-2', rgba(0, 0, 0, 0.65));
-
-  svg {
-    width: 14px;
-    height: 14px;
-  }
-
-  &:hover:not(:disabled) {
-    background: v('fill-hover', rgba(0, 0, 0, 0.08));
-    color: v('text-1', rgba(0, 0, 0, 0.88));
-  }
-}
-
-.#{em('attachment', 'card-btn', 'danger')}:hover:not(:disabled) {
-  background: color-mix(in srgb, #{v('color-danger', #ec4246)} 12%, transparent);
-  color: v('color-danger', #ec4246);
-}
-
-/* ---------- 上传进度：贴着预览图底边 ---------- */
-.#{e('attachment', 'card-progress')} {
-  position: absolute;
-  inset-inline: 0;
-  inset-block-end: 0;
-  height: 2px;
-  background: v('fill-hover', rgba(0, 0, 0, 0.08));
-
-  > span {
-    display: block;
-    height: 100%;
-    background: v('color-primary', #18181b);
-    transition: inline-size v('duration', 0.2s) v('ease', ease);
-  }
-}
-
-/* ---------- 信息区 ---------- */
-.#{e('attachment', 'card-info')} {
-  display: flex;
-  flex-direction: column;
-  gap: 2px;
-  min-width: 0;
-  padding: v('space-2', 8px);
-}
-
-.#{e('attachment', 'card-name')} {
-  overflow: hidden;
-  color: v('text-1', rgba(0, 0, 0, 0.88));
-  font-size: v('font-size', 14px);
-  line-height: v('line-height', 1.5);
-  white-space: nowrap;
-  text-overflow: ellipsis;
-}
-
-.#{e('attachment', 'card-meta')} {
-  display: flex;
-  align-items: center;
-  gap: v('space-1', 4px);
-  min-width: 0;
-  font-size: v('font-size-sm', 12px);
-  line-height: 1.4;
-}
-
-.#{e('attachment', 'card-size')} {
-  color: v('text-3', rgba(0, 0, 0, 0.45));
-  font-variant-numeric: tabular-nums;
-}
-
-/* 待上传标签：压到 16px 高，不与文件名抢视线 */
-.#{e('attachment', 'card-tag')} {
-  flex: none;
-  height: 16px;
-  margin: 0;
-  padding: 0 4px;
-  font-size: 10px;
-  font-weight: 500;
-  line-height: 1;
-}
-</style>
diff --git a/code/g3soft-libs/packages/ui/src/attachment/AttachmentList.vue b/code/g3soft-libs/packages/ui/src/attachment/AttachmentList.vue
deleted file mode 100644
index c0e720db..00000000
--- a/code/g3soft-libs/packages/ui/src/attachment/AttachmentList.vue
+++ /dev/null
@@ -1,848 +0,0 @@
-<script setup lang="ts">
-import { computed, onBeforeUnmount, onMounted, ref, watch } from 'vue'
-import { CloudUpload, Download, Trash2, Upload } from '@lucide/vue'
-import { G3Button } from '../button'
-import { G3Checkbox } from '../checkbox'
-import { G3Pagination } from '../pagination'
-import { G3Spin } from '../spin'
-import { useLocale } from '../_composables/useLocale'
-import { useNamespace } from '../_composables/useNamespace'
-import AttachmentCard from './AttachmentCard.vue'
-import { formatFileSize, getExtension, isImageFile, matchesAccept } from './file'
-import type {
-  AttachmentInvalidInfo,
-  AttachmentInvalidReason,
-  AttachmentItem,
-  AttachmentListItem,
-  AttachmentPendingFile,
-} from './types'
-
-/** 待上传项的内部形态：多了稳定 uid，供选择 / 删除定位 */
-type PendingEntry = AttachmentPendingFile & { uid: string }
-
-/** 待上传项的 id 前缀（与已上传附件区分） */
-const PENDING_PREFIX = '__g3_pending__'
-
-/**
- * 附件列表 —— 工具栏 + 卡片网格 + 待上传队列 + 底栏与分页。
- *
- * 只负责「拿到的数据怎么画」与「用户想干什么」；上传 / 删除是否由组件托管，
- * 由父级（G3Attachment）决定。
- */
-defineOptions({ name: 'G3AttachmentList' })
-
-const props = withDefaults(
-  defineProps<{
-    /** 当前页已上传附件 */
-    files?: AttachmentItem[]
-    /** 当前分类（透传给上传上下文） */
-    categoryId?: string | number
-    /** 列表请求中 */
-    loading?: boolean
-    /** 上传请求中 */
-    uploading?: boolean
-    /** 删除请求中 */
-    removing?: boolean
-    readonly?: boolean
-    selectable?: boolean
-    multiple?: boolean
-    /** 原生 accept 语法 */
-    accept?: string
-    /** 单文件大小上限（字节） */
-    maxSize?: number
-    /** 待上传队列上限 */
-    maxCount?: number
-    /** 监听 document 的粘贴上传 */
-    pasteUpload?: boolean
-    /** 内建触发下载（依据 item.url） */
-    builtinDownload?: boolean
-    /** 是否显示分页 */
-    pagination?: boolean
-    page?: number
-    pageSize?: number
-    /** 总条数，不传取 files.length */
-    total?: number
-    pageSizeOptions?: Array<number | string>
-    showSizeChanger?: boolean
-  }>(),
-  {
-    files: () => [],
-    categoryId: undefined,
-    loading: false,
-    uploading: false,
-    removing: false,
-    readonly: false,
-    selectable: true,
-    multiple: true,
-    accept: undefined,
-    maxSize: 0,
-    maxCount: 0,
-    pasteUpload: false,
-    builtinDownload: true,
-    pagination: true,
-    page: undefined,
-    pageSize: undefined,
-    total: undefined,
-    pageSizeOptions: () => [10, 20, 50, 100],
-    showSizeChanger: false,
-  },
-)
-
-const emit = defineEmits<{
-  'update:page': [page: number]
-  'update:pageSize': [size: number]
-  select: [items: AttachmentItem[]]
-  preview: [item: AttachmentItem]
-  download: [items: AttachmentItem[]]
-  remove: [items: AttachmentItem[]]
-  upload: [files: File[]]
-  invalid: [info: AttachmentInvalidInfo]
-}>()
-
-const { e, is } = useNamespace('attachment')
-const locale = useLocale()
-
-/* ---------- 待上传队列 ---------- */
-const pendingFiles = ref<PendingEntry[]>([])
-const inputRef = ref<HTMLInputElement | null>(null)
-let uidSeed = 0
-
-const pendingItems = computed<AttachmentListItem[]>(() =>
-  pendingFiles.value.map((entry) => ({
-    id: entry.uid,
-    name: entry.name,
-    size: entry.size,
-    ext: entry.ext,
-    url: entry.url,
-    pending: true,
-  })),
-)
-
-/* ---------- 分页 ---------- */
-// 未传 page / pageSize 时按非受控处理，组件内部维护并自行切片
-const innerPage = ref(1)
-const innerPageSize = ref(20)
-const currentPage = computed(() => props.page ?? innerPage.value)
-const currentPageSize = computed(() => props.pageSize ?? innerPageSize.value)
-
-/**
- * 未传 `total` 视为客户端分页：`files` 是完整列表，由组件切片；
- * 传了 `total` 则是服务端分页，`files` 已经是当前页数据，不再切。
- */
-const clientPaging = computed(() => props.total == null && props.pagination)
-const pagedFiles = computed(() => {
-  if (!clientPaging.value) return props.files
-  const start = (currentPage.value - 1) * currentPageSize.value
-  return props.files.slice(start, start + currentPageSize.value)
-})
-
-/** 渲染项：待上传在前，已上传在后 */
-const items = computed<AttachmentListItem[]>(() => [...pendingItems.value, ...pagedFiles.value])
-const hasItems = computed(() => items.value.length > 0)
-const pendingCount = computed(() => pendingFiles.value.length)
-const resolvedTotal = computed(() =>
-  props.total == null ? props.files.length : Number(props.total) || 0,
-)
-
-/* ---------- 勾选 ---------- */
-const selectedIds = ref<Set<string | number>>(new Set())
-const selectedCount = computed(() => selectedIds.value.size)
-const allChecked = computed(
-  () => hasItems.value && items.value.every((item) => selectedIds.value.has(item.id)),
-)
-const indeterminate = computed(() => !allChecked.value && selectedCount.value > 0)
-
-const selectedItems = computed<AttachmentItem[]>(() =>
-  items.value.filter((item) => selectedIds.value.has(item.id)),
-)
-
-const selectedText = computed(() =>
-  locale.value.attachment.selected.replace('{count}', String(selectedCount.value)),
-)
-
-function isPendingId(id: string | number) {
-  return String(id).startsWith(PENDING_PREFIX)
-}
-
-function patchSelection(updater: (next: Set<string | number>) => void) {
-  const next = new Set(selectedIds.value)
-  updater(next)
-  selectedIds.value = next
-  emit(
-    'select',
-    items.value.filter((item) => next.has(item.id)),
-  )
-}
-
-function onItemSelect(item: AttachmentListItem, checked: boolean) {
-  patchSelection((next) => {
-    if (checked) {
-      if (!props.multiple) next.clear()
-      next.add(item.id)
-    } else {
-      next.delete(item.id)
-    }
-  })
-}
-
-function selectAll() {
-  patchSelection((next) => items.value.forEach((item) => next.add(item.id)))
-}
-
-function clearSelection() {
-  patchSelection((next) => next.clear())
-}
-
-function toggleAll(checked: boolean) {
-  if (checked) selectAll()
-  else clearSelection()
-}
-
-/* ---------- 分页 ---------- */
-const paginationVisible = computed(
-  () => props.pagination && resolvedTotal.value > currentPageSize.value,
-)
-
-function onPageChange(page: number, pageSize: number) {
-  innerPage.value = page
-  if (pageSize !== currentPageSize.value) innerPageSize.value = pageSize
-  emit('update:page', page)
-  if (pageSize !== props.pageSize) emit('update:pageSize', pageSize)
-}
-
-/* ---------- 空态里的限制说明 ---------- */
-/** 顺带说明限制，省得用户上传后才被拒 */
-const limitHints = computed(() => {
-  const text = locale.value.attachment
-  const hints: string[] = []
-  if (props.accept) hints.push(text.limitAccept.replace('{accept}', props.accept))
-  if (props.maxSize > 0) {
-    hints.push(text.limitSize.replace('{size}', formatFileSize(props.maxSize)))
-  }
-  if (props.maxCount > 0) {
-    hints.push(text.limitCount.replace('{count}', String(props.maxCount)))
-  }
-  return hints.join(' · ')
-})
-
-/* ---------- 入队与校验 ---------- */
-function reject(reason: AttachmentInvalidReason, files: File[]) {
-  const names = files.map((file) => file.name).join('、')
-  const text = locale.value.attachment
-  let message = ''
-  if (reason === 'accept') message = text.invalidAccept.replace('{name}', names)
-  else if (reason === 'max-size') {
-    message = text.invalidMaxSize
-      .replace('{name}', names)
-      .replace('{size}', formatFileSize(props.maxSize))
-  } else {
-    message = text.invalidMaxCount.replace('{count}', String(props.maxCount))
-  }
-  emit('invalid', { reason, files, message })
-}
-
-function createObjectUrl(file: File): string {
-  if (!isImageFile(file.name)) return ''
-  if (typeof URL === 'undefined' || typeof URL.createObjectURL !== 'function') return ''
-  return URL.createObjectURL(file)
-}
-
-function revokeObjectUrl(url?: string) {
-  if (url && typeof URL !== 'undefined' && typeof URL.revokeObjectURL === 'function') {
-    URL.revokeObjectURL(url)
-  }
-}
-
-/** 把本地文件加入待上传队列，返回被接受的文件（被拒绝的走 invalid 事件） */
-function addFiles(input: File[] | FileList): File[] {
-  const list = Array.from(input ?? [])
-  if (!list.length) return []
-  const accepted: File[] = []
-  for (const file of list) {
-    if (!matchesAccept(file.name, props.accept)) {
-      reject('accept', [file])
-      continue
-    }
-    if (props.maxSize > 0 && file.size > props.maxSize) {
-      reject('max-size', [file])
-      continue
-    }
-    if (props.maxCount > 0 && pendingFiles.value.length + accepted.length >= props.maxCount) {
-      reject('max-count', [file])
-      continue
-    }
-    accepted.push(file)
-  }
-  for (const file of accepted) {
-    uidSeed += 1
-    pendingFiles.value.push({
-      uid: `${PENDING_PREFIX}${uidSeed}`,
-      file,
-      name: file.name,
-      size: file.size,
-      ext: getExtension(file.name),
-      url: createObjectUrl(file),
-    })
-  }
-  return accepted
-}
-
-function dropPending(ids: Array<string | number>) {
-  const targets = new Set(ids.map(String))
-  const kept: PendingEntry[] = []
-  for (const entry of pendingFiles.value) {
-    if (targets.has(entry.uid)) revokeObjectUrl(entry.url)
-    else kept.push(entry)
-  }
-  pendingFiles.value = kept
-}
-
-function clearPending() {
-  pendingFiles.value.forEach((entry) => revokeObjectUrl(entry.url))
-  pendingFiles.value = []
-}
-
-function openFileDialog() {
-  if (props.readonly) return
-  inputRef.value?.click()
-}
-
-function onInputChange(event: Event) {
-  const target = event.target as HTMLInputElement
-  if (target.files?.length) addFiles(target.files)
-  target.value = ''
-}
-
-/* ---------- 拖拽 / 粘贴 ---------- */
-const dragOver = ref(false)
-let dragDepth = 0
-
-function onDragEnter(event: DragEvent) {
-  if (props.readonly) return
-  event.preventDefault()
-  if (event.currentTarget !== event.target) return
-  dragDepth += 1
-  dragOver.value = true
-}
-
-function onDragOver(event: DragEvent) {
-  if (props.readonly) return
-  event.preventDefault()
-  if (event.dataTransfer) event.dataTransfer.dropEffect = 'copy'
-}
-
-function onDragLeave(event: DragEvent) {
-  if (event.currentTarget !== event.target) return
-  dragDepth = Math.max(0, dragDepth - 1)
-  if (!dragDepth) dragOver.value = false
-}
-
-function onDrop(event: DragEvent) {
-  if (props.readonly) return
-  event.preventDefault()
-  dragDepth = 0
-  dragOver.value = false
-  const dropped = event.dataTransfer?.files
-  if (dropped?.length) addFiles(dropped)
-}
-
-function onPaste(event: ClipboardEvent) {
-  if (props.readonly) return
-  const items = event.clipboardData?.items
-  if (!items) return
-  const pasted: File[] = []
-  for (const item of items) {
-    if (item.kind !== 'file') continue
-    const file = item.getAsFile()
-    if (file) pasted.push(file)
-  }
-  if (!pasted.length) return
-  if (addFiles(pasted).length) event.preventDefault()
-}
-
-/* ---------- 上传 / 下载 / 删除 ---------- */
-function submitUpload() {
-  if (!pendingFiles.value.length || props.uploading) return
-  emit(
-    'upload',
-    pendingFiles.value.map((entry) => entry.file),
-  )
-}
-
-function triggerDownload(targets: AttachmentItem[]) {
-  if (!props.builtinDownload || typeof document === 'undefined') return
-  for (const item of targets) {
-    if (!item.url) continue
-    const anchor = document.createElement('a')
-    anchor.href = item.url
-    anchor.download = item.name
-    anchor.rel = 'noopener'
-    anchor.style.display = 'none'
-    document.body.appendChild(anchor)
-    anchor.click()
-    document.body.removeChild(anchor)
-  }
-}
-
-function downloadItems(targets: AttachmentItem[]) {
-  if (!targets.length) return
-  emit('download', targets)
-  triggerDownload(targets)
-}
-
-function onDownloadSelected() {
-  downloadItems(selectedItems.value.filter((item) => !item.pending))
-}
-
-function onDownloadItem(item: AttachmentListItem) {
-  downloadItems([item])
-}
-
-function removeSelected() {
-  const ids = [...selectedIds.value]
-  if (!ids.length) return
-  const pendingIds = ids.filter(isPendingId)
-  if (pendingIds.length) {
-    dropPending(pendingIds)
-    patchSelection((next) => pendingIds.forEach((id) => next.delete(id)))
-  }
-  const uploaded = props.files.filter((file) => selectedIds.value.has(file.id))
-  if (uploaded.length) emit('remove', uploaded)
-}
-
-function onRemoveItem(item: AttachmentListItem) {
-  if (item.pending) {
-    dropPending([item.id])
-    patchSelection((next) => next.delete(item.id))
-    return
-  }
-  emit('remove', [item])
-}
-
-/* ---------- 生命周期 ---------- */
-onMounted(() => {
-  if (props.pasteUpload) document.addEventListener('paste', onPaste)
-})
-
-onBeforeUnmount(() => {
-  if (props.pasteUpload) document.removeEventListener('paste', onPaste)
-  clearPending()
-})
-
-// 切分类：清空待上传队列与勾选，回到第一页
-watch(
-  () => props.categoryId,
-  () => {
-    clearPending()
-    innerPage.value = 1
-    if (selectedIds.value.size) clearSelection()
-  },
-)
-
-// 列表被父级刷新后，剔除已不存在的勾选
-watch(
-  () => props.files,
-  (files) => {
-    if (!selectedIds.value.size) return
-    const alive = new Set(files.map((file) => file.id))
-    const next = new Set([...selectedIds.value].filter((id) => isPendingId(id) || alive.has(id)))
-    if (next.size !== selectedIds.value.size) selectedIds.value = next
-  },
-)
-
-defineExpose({
-  pendingFiles,
-  selectedItems,
-  openFileDialog,
-  clearSelection,
-  selectAll,
-  addFiles,
-  clearPending,
-})
-</script>
-
-<template>
-  <div :class="e('list')" data-slot="attachment-list">
-    <!-- 工具栏：勾选后才浮出批量操作，平时只有全选 -->
-    <div :class="e('toolbar')">
-      <G3Checkbox
-        v-if="selectable"
-        :model-value="allChecked"
-        :indeterminate="indeterminate"
-        :disabled="!hasItems"
-        @update:model-value="toggleAll"
-      >
-        {{ locale.attachment.selectAll }}
-      </G3Checkbox>
-
-      <template v-if="selectedCount">
-        <span :class="e('toolbar-divider')" aria-hidden="true" />
-        <span :class="e('toolbar-count')">{{ selectedText }}</span>
-        <G3Button
-          type="outline"
-          size="small"
-          :title="locale.attachment.download"
-          :aria-label="locale.attachment.download"
-          @click="onDownloadSelected"
-        >
-          <Download :size="14" />
-          <span :class="e('toolbar-label')">{{ locale.attachment.download }}</span>
-        </G3Button>
-        <G3Button
-          v-if="!readonly"
-          type="danger-outline"
-          size="small"
-          :title="locale.attachment.remove"
-          :aria-label="locale.attachment.remove"
-          :disabled="removing"
-          @click="removeSelected"
-        >
-          <Trash2 :size="14" />
-          <span :class="e('toolbar-label')">{{ locale.attachment.remove }}</span>
-        </G3Button>
-      </template>
-    </div>
-
-    <!-- 卡片区 -->
-    <div
-      :class="[e('main'), { [is('dragover')]: dragOver && !readonly }]"
-      @dragenter="onDragEnter"
-      @dragover="onDragOver"
-      @dragleave="onDragLeave"
-      @drop="onDrop"
-    >
-      <G3Spin :spinning="loading" :class="e('spin')">
-        <div v-if="hasItems" :class="e('grid')">
-          <AttachmentCard
-            v-for="item in items"
-            :key="item.id"
-            :item="item"
-            :selected="selectedIds.has(item.id)"
-            :selectable="selectable"
-            :readonly="readonly"
-            @select="onItemSelect"
-            @preview="emit('preview', $event)"
-            @download="onDownloadItem"
-            @remove="onRemoveItem"
-          />
-        </div>
-
-        <!-- 空态即投放区：虚线框吸收拖拽，也顺手说明限制 -->
-        <div
-          v-else-if="!loading"
-          :class="[e('empty'), { [is('readonly')]: readonly }]"
-          @click="openFileDialog"
-        >
-          <CloudUpload :size="28" :stroke-width="1.5" :class="e('empty-icon')" />
-          <span :class="e('empty-title')">{{ locale.attachment.empty }}</span>
-          <span v-if="!readonly" :class="e('empty-hint')">
-            {{ locale.attachment.emptyHint }}
-          </span>
-          <span v-if="!readonly && limitHints" :class="e('empty-limit')">{{ limitHints }}</span>
-        </div>
-      </G3Spin>
-
-      <div v-if="dragOver && !readonly" :class="e('drop-mask')">
-        <Upload :size="24" :stroke-width="1.5" />
-        <span>{{ locale.attachment.dropHint }}</span>
-      </div>
-    </div>
-
-    <!-- 底栏：计数 + 上传入口 + 分页合成一块（只有一条顶边） -->
-    <div :class="[e('footer'), { [is('dirty')]: pendingCount > 0 }]">
-      <div :class="e('footer-bar')">
-        <span :class="[e('footer-count'), { [is('pending')]: pendingCount > 0 }]">
-          <template v-if="pendingCount">
-            {{ locale.attachment.pendingCount.replace('{count}', String(pendingCount)) }}
-          </template>
-          <template v-else>
-            {{ locale.attachment.total.replace('{count}', String(resolvedTotal)) }}
-          </template>
-        </span>
-
-        <div v-if="!readonly" :class="e('footer-actions')">
-          <input
-            ref="inputRef"
-            type="file"
-            :class="e('file-input')"
-            :multiple="multiple"
-            :accept="accept"
-            @change="onInputChange"
-          />
-          <G3Button type="outline" @click="openFileDialog">
-            <CloudUpload :size="14" />
-            {{ locale.attachment.select }}
-          </G3Button>
-          <G3Button
-            type="primary"
-            :disabled="!pendingCount"
-            :loading="uploading"
-            @click="submitUpload"
-          >
-            <Upload :size="14" />
-            {{ locale.attachment.upload }}
-          </G3Button>
-        </div>
-      </div>
-
-      <div v-if="paginationVisible" :class="e('pagination')">
-        <G3Pagination
-          :current="currentPage"
-          :page-size="currentPageSize"
-          :total="resolvedTotal"
-          :show-size-changer="showSizeChanger"
-          :page-size-options="pageSizeOptions"
-          @change="onPageChange"
-        />
-      </div>
-    </div>
-  </div>
-</template>
-
-<style lang="scss">
-@use '@g3soft/tokens/scss' as *;
-
-.#{e('attachment', 'list')} {
-  display: flex;
-  flex-direction: column;
-  width: 100%;
-  height: 100%;
-  min-width: 0;
-  min-height: 0;
-  background: v('bg-container', #fff);
-  /* 工具栏的窄面板适配走容器查询（按面板宽度，而不是视口宽度） */
-  container-type: inline-size;
-}
-
-/* ---------- 工具栏 ----------
-   整行统一到「24px 小控件」这一档：复选框文案 12px、按钮 size="small"、
-   计数 12px。之前混了 14px / 12px 三套字号 + 无边框 ghost 按钮，
-   一行里元素高矮不一又没有边界，看着就是歪的。 */
-.#{e('attachment', 'toolbar')} {
-  display: flex;
-  flex: none;
-  align-items: center;
-  gap: v('space-2', 8px);
-  box-sizing: border-box;
-  /* 高度写死，不用 min-height：
-     - 勾选前只有「全选」一行文字（约 18px），勾选后浮出 24px 的批量按钮 ——
-       用 min-height 兜底仍会随内容变（默认 content-box 下 min-height 只管内容盒，
-       实际高度 = 内容盒 + 上下 padding）；
-     - 一旦高度恒定，「勾选时整条工具栏长高」这类问题从结构上就不可能出现。 */
-  height: calc(#{v('control-height-sm', 24px)} + #{v('space-2', 8px)} * 2);
-  padding: 0 v('space-3', 12px);
-  border-bottom: 1px solid v('border-color', #d9d9d9);
-  /* 不换行：窄面板宁可裁切也不让工具栏变高 */
-  flex-wrap: nowrap;
-  overflow: hidden;
-}
-
-/* 行内元素一律不收缩（按钮 / 复选框的文字被压扁或折行同样会改变高度），
-   只有「已选 N 项」这个纯文本可以省略号收尾 */
-.#{e('attachment', 'toolbar')} > * {
-  flex: none;
-}
-
-/* 复选框文案跟按钮同一档字号：字号不同，文字基线看着就是歪的 */
-.#{e('attachment', 'toolbar')} .#{b('checkbox')} {
-  font-size: v('font-size-sm', 12px);
-  white-space: nowrap;
-}
-
-.#{e('attachment', 'toolbar')} .#{b('button')} svg {
-  width: 14px;
-  height: 14px;
-}
-
-/* 竖向分组线：把「选择」与「操作」分开。
-   只靠 gap 的话，间距数字一样，但左松右紧看起来不齐。 */
-.#{e('attachment', 'toolbar-divider')} {
-  flex: none;
-  width: 1px;
-  height: 16px;
-  background: v('border-color', #d9d9d9);
-}
-
-.#{e('attachment', 'toolbar-count')} {
-  flex: 0 1 auto;
-  min-width: 0;
-  overflow: hidden;
-  color: v('text-2', rgba(0, 0, 0, 0.65));
-  font-size: v('font-size-sm', 12px);
-  font-variant-numeric: tabular-nums;
-  text-overflow: ellipsis;
-  white-space: nowrap;
-}
-
-/* 窄面板：批量按钮只留图标。宁可少显示文案，也不让工具栏换行 / 变高。
-   按「面板宽度」而不是视口宽度判断 —— 组件可能被嵌在弹窗或窄侧栏里。 */
-@container (max-width: 340px) {
-  .#{e('attachment', 'toolbar-label')} {
-    display: none;
-  }
-}
-
-/* 更窄：连「全选」文案也收起，只留勾选框 */
-@container (max-width: 260px) {
-  .#{e('attachment', 'toolbar')} .#{e('checkbox', 'label')} {
-    display: none;
-  }
-}
-
-/* ---------- 卡片区 ---------- */
-.#{e('attachment', 'main')} {
-  position: relative;
-  flex: 1;
-  min-height: 0;
-  overflow: auto;
-  padding: v('space-3', 12px);
-
-  &.#{is('dragover')} {
-    background: color-mix(in srgb, var(#{css-var('color-primary')}) 4%, transparent);
-  }
-}
-
-.#{e('attachment', 'spin')} {
-  min-height: 100%;
-}
-
-.#{e('attachment', 'grid')} {
-  display: grid;
-  grid-template-columns: repeat(auto-fill, minmax(150px, 1fr));
-  gap: v('space-3', 12px);
-  align-content: start;
-}
-
-/* ---------- 空态（= 投放区）---------- */
-/* 绝对铺满列表区（相对 __main 定位），不依赖 Spin / 内容容器的高度链 */
-.#{e('attachment', 'empty')} {
-  position: absolute;
-  inset: v('space-3', 12px);
-  display: flex;
-  flex-direction: column;
-  align-items: center;
-  justify-content: center;
-  gap: v('space-1', 4px);
-  box-sizing: border-box;
-  padding: v('space-5', 24px);
-  border: 1px dashed v('border-color', #d9d9d9);
-  border-radius: v('radius', 6px);
-  color: v('text-3', rgba(0, 0, 0, 0.45));
-  text-align: center;
-  cursor: pointer;
-  transition:
-    border-color v('duration-fast', 0.1s) v('ease', ease),
-    background-color v('duration-fast', 0.1s) v('ease', ease),
-    color v('duration-fast', 0.1s) v('ease', ease);
-
-  &:hover {
-    border-color: v('color-primary', #18181b);
-    background: v('color-primary-soft', rgba(24, 24, 27, 0.12));
-    color: v('color-primary', #18181b);
-  }
-
-  &.#{is('readonly')} {
-    cursor: default;
-    background: transparent;
-
-    &:hover {
-      border-color: v('border-color', #d9d9d9);
-      color: v('text-3', rgba(0, 0, 0, 0.45));
-    }
-  }
-}
-
-.#{e('attachment', 'empty-icon')} {
-  margin-bottom: v('space-1', 4px);
-}
-
-.#{e('attachment', 'empty-title')} {
-  color: v('text-2', rgba(0, 0, 0, 0.65));
-  font-size: v('font-size', 14px);
-}
-
-.#{e('attachment', 'empty-hint')} {
-  font-size: v('font-size-sm', 12px);
-}
-
-.#{e('attachment', 'empty-limit')} {
-  margin-top: v('space-1', 4px);
-  font-size: v('font-size-sm', 12px);
-  opacity: 0.8;
-}
-
-/* ---------- 拖拽遮罩 ---------- */
-.#{e('attachment', 'drop-mask')} {
-  position: absolute;
-  inset: v('space-2', 8px);
-  z-index: 10;
-  display: flex;
-  flex-direction: column;
-  align-items: center;
-  justify-content: center;
-  gap: v('space-2', 8px);
-  border: 1px dashed v('color-primary', #18181b);
-  border-radius: v('radius', 6px);
-  background: color-mix(
-    in srgb,
-    var(#{css-var('color-primary')}) 6%,
-    var(#{css-var('bg-container')})
-  );
-  color: v('color-primary', #18181b);
-  font-size: v('font-size', 14px);
-  pointer-events: none;
-}
-
-/* ---------- 底栏（计数 + 上传 + 分页合成一块） ---------- */
-.#{e('attachment', 'footer')} {
-  flex: none;
-  border-top: 1px solid v('border-color', #d9d9d9);
-  background: v('bg-container', #fff);
-  transition: background-color v('duration', 0.2s) v('ease', ease);
-}
-
-/* 队列里有未提交文件：整块染主色淡底，做成「脏」状态 */
-.#{e('attachment', 'footer')}.#{is('dirty')} {
-  background: v('color-primary-soft', rgba(24, 24, 27, 0.12));
-}
-
-.#{e('attachment', 'footer-bar')} {
-  display: flex;
-  align-items: center;
-  justify-content: space-between;
-  gap: v('space-2', 8px);
-  padding: v('space-2', 8px) v('space-3', 12px);
-}
-
-.#{e('attachment', 'footer-count')} {
-  color: v('text-3', rgba(0, 0, 0, 0.45));
-  font-size: v('font-size-sm', 12px);
-  font-variant-numeric: tabular-nums;
-
-  &.#{is('pending')} {
-    color: v('color-primary', #18181b);
-    font-weight: 500;
-  }
-}
-
-.#{e('attachment', 'footer-actions')} {
-  display: flex;
-  align-items: center;
-  gap: v('space-2', 8px);
-
-  svg {
-    width: 14px;
-    height: 14px;
-  }
-}
-
-.#{e('attachment', 'file-input')} {
-  display: none;
-}
-
-.#{e('attachment', 'pagination')} {
-  display: flex;
-  justify-content: flex-end;
-  padding: 0 v('space-3', 12px) v('space-2', 8px);
-}
-</style>
diff --git a/code/g3soft-libs/packages/ui/src/attachment/AttachmentPreview.vue b/code/g3soft-libs/packages/ui/src/attachment/AttachmentPreview.vue
deleted file mode 100644
index 6c4cb133..00000000
--- a/code/g3soft-libs/packages/ui/src/attachment/AttachmentPreview.vue
+++ /dev/null
@@ -1,241 +0,0 @@
-<script setup lang="ts">
-import { computed } from 'vue'
-import { ChevronLeft, ChevronRight, Inbox } from '@lucide/vue'
-import { G3Button } from '../button'
-import { useLocale } from '../_composables/useLocale'
-import { useNamespace } from '../_composables/useNamespace'
-import { ATTACHMENT_KIND_ICONS } from './icons'
-import { formatFileSize, getExtension, getFileKind, isImageFile } from './file'
-import type { AttachmentItem } from './types'
-
-/**
- * 附件预览 —— 右侧预览栏（默认不显示，`:show-preview="true"` 才挂载）。
- *
- * 图片直接展示，其他类型用「文件族图标 + 扩展名」占位；
- * 上下翻页在 `list` 内按 id 定位，翻页只上报事件、不改数据。
- */
-defineOptions({ name: 'G3AttachmentPreview' })
-
-const props = withDefaults(
-  defineProps<{
-    /** 当前预览项，null 表示未选中 */
-    item?: AttachmentItem | null
-    /** 参与翻页的列表（通常是当前页附件） */
-    list?: AttachmentItem[]
-  }>(),
-  { item: null, list: () => [] },
-)
-
-const emit = defineEmits<{
-  prev: []
-  next: []
-}>()
-
-const { e, em } = useNamespace('attachment')
-const locale = useLocale()
-
-const index = computed(() => {
-  if (!props.item) return -1
-  return props.list.findIndex((file) => file.id === props.item?.id)
-})
-
-const canPrev = computed(() => index.value > 0)
-const canNext = computed(() => index.value >= 0 && index.value < props.list.length - 1)
-
-const imageUrl = computed(() => {
-  const item = props.item
-  if (!item || !isImageFile(item.name)) return ''
-  return item.url || ''
-})
-
-const kind = computed(() => getFileKind(props.item?.name || ''))
-const kindIcon = computed(() => ATTACHMENT_KIND_ICONS[kind.value])
-const extension = computed(() =>
-  (props.item?.ext || getExtension(props.item?.name || '') || '?').toUpperCase(),
-)
-const sizeText = computed(() => formatFileSize(props.item?.size))
-</script>
-
-<template>
-  <aside :class="e('preview')" data-slot="attachment-preview">
-    <div :class="e('preview-toolbar')">
-      <G3Button
-        type="ghost"
-        :class="e('icon-btn')"
-        :disabled="!canPrev"
-        :title="locale.attachment.prev"
-        :aria-label="locale.attachment.prev"
-        @click="emit('prev')"
-      >
-        <ChevronLeft :size="14" />
-      </G3Button>
-      <span v-if="index >= 0" :class="e('preview-counter')">
-        {{ index + 1 }} / {{ list.length }}
-      </span>
-      <G3Button
-        type="ghost"
-        :class="e('icon-btn')"
-        :disabled="!canNext"
-        :title="locale.attachment.next"
-        :aria-label="locale.attachment.next"
-        @click="emit('next')"
-      >
-        <ChevronRight :size="14" />
-      </G3Button>
-      <span :class="e('preview-name')" :title="item?.name">{{ item?.name || '' }}</span>
-    </div>
-
-    <div :class="e('preview-body')">
-      <template v-if="item">
-        <img v-if="imageUrl" :class="e('preview-image')" :src="imageUrl" :alt="item.name" />
-        <div v-else :class="e('preview-generic')">
-          <span :class="[e('type'), em('type', kind)]">
-            <component :is="kindIcon" :size="26" :stroke-width="1.5" aria-hidden="true" />
-            <span :class="e('type-ext')">{{ extension }}</span>
-          </span>
-          <div :class="e('preview-info')">
-            <div :class="e('preview-title')">{{ item.name }}</div>
-            <div :class="e('preview-meta')">
-              <span>{{ sizeText }}</span>
-              <span v-if="item.ext">· {{ extension }}</span>
-            </div>
-          </div>
-        </div>
-      </template>
-
-      <div v-else :class="e('preview-empty')">
-        <Inbox :size="28" :stroke-width="1.5" />
-        <span>{{ locale.attachment.previewEmpty }}</span>
-      </div>
-    </div>
-  </aside>
-</template>
-
-<style lang="scss">
-@use '@g3soft/tokens/scss' as *;
-
-.#{e('attachment', 'preview')} {
-  display: flex;
-  flex-direction: column;
-  width: 100%;
-  height: 100%;
-  min-width: 0;
-  min-height: 0;
-  background: v('bg-container', #fff);
-}
-
-.#{e('attachment', 'preview-toolbar')} {
-  display: flex;
-  flex: none;
-  align-items: center;
-  gap: v('space-1', 4px);
-  /* 与列表工具栏同高：控件高 + 上下各一份 space-2 */
-  min-height: calc(#{v('control-height', 32px)} + #{v('space-2', 8px)} * 2);
-  padding: 0 v('space-3', 12px);
-  border-bottom: 1px solid v('border-color', #d9d9d9);
-}
-
-.#{e('attachment', 'preview-counter')} {
-  min-width: 44px;
-  color: v('text-3', rgba(0, 0, 0, 0.45));
-  font-size: v('font-size-sm', 12px);
-  font-variant-numeric: tabular-nums;
-  text-align: center;
-}
-
-.#{e('attachment', 'preview-name')} {
-  flex: 1;
-  min-width: 0;
-  overflow: hidden;
-  color: v('text-1', rgba(0, 0, 0, 0.88));
-  font-size: v('font-size', 14px);
-  white-space: nowrap;
-  text-overflow: ellipsis;
-}
-
-.#{e('attachment', 'preview-body')} {
-  flex: 1;
-  min-height: 0;
-  overflow: auto;
-  background: v('fill', rgba(0, 0, 0, 0.04));
-}
-
-.#{e('attachment', 'preview-image')} {
-  display: block;
-  max-width: 100%;
-  max-height: 100%;
-  margin: auto;
-  padding: v('space-3', 12px);
-  box-sizing: border-box;
-  object-fit: contain;
-}
-
-.#{e('attachment', 'preview-generic')} {
-  display: flex;
-  flex-direction: column;
-  align-items: center;
-  justify-content: center;
-  gap: v('space-4', 16px);
-  min-height: 100%;
-  padding: v('space-4', 16px);
-  box-sizing: border-box;
-
-  /* 预览里的类型块比卡片里大一号 */
-  .#{e('attachment', 'type')} {
-    min-width: 72px;
-    padding: v('space-2', 8px);
-  }
-}
-
-.#{e('attachment', 'preview-info')} {
-  text-align: center;
-}
-
-.#{e('attachment', 'preview-title')} {
-  color: v('text-1', rgba(0, 0, 0, 0.88));
-  font-size: v('font-size', 14px);
-  font-weight: 600;
-  word-break: break-all;
-}
-
-.#{e('attachment', 'preview-meta')} {
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  gap: v('space-1', 4px);
-  margin-top: 4px;
-  color: v('text-3', rgba(0, 0, 0, 0.45));
-  font-size: v('font-size-sm', 12px);
-}
-
-.#{e('attachment', 'preview-empty')} {
-  display: flex;
-  flex-direction: column;
-  align-items: center;
-  justify-content: center;
-  gap: v('space-3', 12px);
-  min-height: 100%;
-  color: v('text-3', rgba(0, 0, 0, 0.45));
-  font-size: v('font-size', 14px);
-}
-
-/* 翻页按钮与卡片 / 表格里的小图标按钮同一规格 */
-.#{e('attachment', 'preview-toolbar')} .#{e('attachment', 'icon-btn')} {
-  width: 24px;
-  height: 24px;
-  min-height: 0;
-  padding: 0;
-  border-radius: v('radius-sm', 4px);
-  color: v('text-3', rgba(0, 0, 0, 0.45));
-
-  svg {
-    width: 14px;
-    height: 14px;
-  }
-
-  &:hover:not(:disabled) {
-    background: v('fill', rgba(0, 0, 0, 0.04));
-    color: v('text-1', rgba(0, 0, 0, 0.88));
-  }
-}
-</style>
diff --git a/code/g3soft-libs/packages/ui/src/attachment/file.test.ts b/code/g3soft-libs/packages/ui/src/attachment/file.test.ts
deleted file mode 100644
index 437ed1ea..00000000
--- a/code/g3soft-libs/packages/ui/src/attachment/file.test.ts
+++ /dev/null
@@ -1,90 +0,0 @@
-import { describe, expect, it } from 'vitest'
-import {
-  formatFileSize,
-  getExtension,
-  getFileKind,
-  getMimeType,
-  isImageFile,
-  matchesAccept,
-} from './file'
-
-describe('getExtension', () => {
-  it('取小写扩展名', () => {
-    expect(getExtension('合同.PDF')).toBe('pdf')
-  })
-
-  it('无扩展名 / 点开头 / 结尾是点都算没有扩展名', () => {
-    expect(getExtension('README')).toBe('')
-    expect(getExtension('.gitignore')).toBe('')
-    expect(getExtension('table.')).toBe('')
-    expect(getExtension('')).toBe('')
-  })
-
-  it('多点文件名取最后一段', () => {
-    expect(getExtension('2026.10.11 报表.xlsx')).toBe('xlsx')
-  })
-})
-
-describe('getFileKind', () => {
-  it('按扩展名归类', () => {
-    expect(getFileKind('a.pdf')).toBe('doc')
-    expect(getFileKind('a.xlsx')).toBe('sheet')
-    expect(getFileKind('a.pptx')).toBe('slide')
-    expect(getFileKind('a.png')).toBe('image')
-    expect(getFileKind('a.zip')).toBe('archive')
-    expect(getFileKind('a.mp4')).toBe('media')
-  })
-
-  it('未知扩展名落到 other', () => {
-    expect(getFileKind('a.unknownext')).toBe('other')
-    expect(getFileKind('noext')).toBe('other')
-  })
-})
-
-describe('isImageFile / getMimeType', () => {
-  it('图片判定不受大小写影响', () => {
-    expect(isImageFile('photo.JPG')).toBe(true)
-    expect(isImageFile('photo.svg')).toBe(true)
-    expect(isImageFile('photo.pdf')).toBe(false)
-  })
-
-  it('已登记的 MIME', () => {
-    expect(getMimeType('a.docx')).toContain('wordprocessingml')
-    expect(getMimeType('a.unknown')).toBe('')
-  })
-})
-
-describe('formatFileSize', () => {
-  it('按 1024 进制换算', () => {
-    expect(formatFileSize(0)).toBe('0 B')
-    expect(formatFileSize(512)).toBe('512 B')
-    expect(formatFileSize(2048)).toBe('2.0 KB')
-    expect(formatFileSize(1024 * 1024 * 3)).toBe('3.0 MB')
-    expect(formatFileSize(1024 * 1024 * 1024 * 2)).toBe('2.00 GB')
-  })
-
-  it('非法输入退化为 0 B', () => {
-    expect(formatFileSize(undefined)).toBe('0 B')
-    expect(formatFileSize(-1)).toBe('0 B')
-    expect(formatFileSize('abc')).toBe('0 B')
-  })
-})
-
-describe('matchesAccept', () => {
-  it('未设置 accept 一律通过', () => {
-    expect(matchesAccept('a.exe', undefined)).toBe(true)
-    expect(matchesAccept('a.exe', '')).toBe(true)
-  })
-
-  it('支持扩展名写法', () => {
-    expect(matchesAccept('a.pdf', '.pdf,.docx')).toBe(true)
-    expect(matchesAccept('a.PDF', '.pdf')).toBe(true)
-    expect(matchesAccept('a.png', '.pdf')).toBe(false)
-  })
-
-  it('支持 mime 通配与精确写法', () => {
-    expect(matchesAccept('a.png', 'image/*')).toBe(true)
-    expect(matchesAccept('a.mp4', 'image/*')).toBe(false)
-    expect(matchesAccept('a.pdf', 'application/pdf')).toBe(true)
-  })
-})
diff --git a/code/g3soft-libs/packages/ui/src/attachment/file.ts b/code/g3soft-libs/packages/ui/src/attachment/file.ts
deleted file mode 100644
index 2d9dce88..00000000
--- a/code/g3soft-libs/packages/ui/src/attachment/file.ts
+++ /dev/null
@@ -1,116 +0,0 @@
-/**
- * 附件视觉与校验工具（纯函数，无副作用，可单测）。
- *
- * 文件族只决定**语义色令牌名**，实际颜色由样式层从 `--g3-color-*` 取，
- * 因此换肤 / 暗色主题下无需改动这里。
- */
-
-/** 图片扩展名 */
-export const IMAGE_EXTENSIONS = ['jpg', 'jpeg', 'png', 'gif', 'bmp', 'webp', 'svg', 'avif', 'ico']
-
-/** 文件族：决定类型色块的颜色 */
-export type AttachmentFileKind = 'image' | 'doc' | 'sheet' | 'slide' | 'archive' | 'media' | 'other'
-
-const KIND_EXTENSIONS: Record<Exclude<AttachmentFileKind, 'other'>, string[]> = {
-  image: IMAGE_EXTENSIONS,
-  doc: ['doc', 'docx', 'pdf', 'txt', 'md', 'rtf', 'odt', 'wps'],
-  sheet: ['xls', 'xlsx', 'csv', 'ods', 'et'],
-  slide: ['ppt', 'pptx', 'odp', 'dps'],
-  archive: ['zip', 'rar', '7z', 'tar', 'gz', 'bz2'],
-  media: ['mp3', 'wav', 'flac', 'aac', 'mp4', 'mov', 'avi', 'mkv', 'webm'],
-}
-
-const MIME_BY_EXT: Record<string, string> = {
-  jpg: 'image/jpeg',
-  jpeg: 'image/jpeg',
-  png: 'image/png',
-  gif: 'image/gif',
-  bmp: 'image/bmp',
-  webp: 'image/webp',
-  svg: 'image/svg+xml',
-  avif: 'image/avif',
-  ico: 'image/x-icon',
-  pdf: 'application/pdf',
-  txt: 'text/plain',
-  md: 'text/markdown',
-  csv: 'text/csv',
-  rtf: 'application/rtf',
-  doc: 'application/msword',
-  docx: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
-  xls: 'application/vnd.ms-excel',
-  xlsx: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
-  ppt: 'application/vnd.ms-powerpoint',
-  pptx: 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
-  zip: 'application/zip',
-  rar: 'application/vnd.rar',
-  '7z': 'application/x-7z-compressed',
-  tar: 'application/x-tar',
-  gz: 'application/gzip',
-  mp3: 'audio/mpeg',
-  wav: 'audio/wav',
-  flac: 'audio/flac',
-  aac: 'audio/aac',
-  mp4: 'video/mp4',
-  mov: 'video/quicktime',
-  avi: 'video/x-msvideo',
-  mkv: 'video/x-matroska',
-  webm: 'video/webm',
-}
-
-/** 取扩展名（小写、不含点）；无扩展名返回 '' */
-export function getExtension(name: string): string {
-  const text = name || ''
-  const index = text.lastIndexOf('.')
-  if (index <= 0 || index === text.length - 1) return ''
-  return text.slice(index + 1).toLowerCase()
-}
-
-/** 推断文件族 */
-export function getFileKind(name: string): AttachmentFileKind {
-  const ext = getExtension(name)
-  if (!ext) return 'other'
-  for (const [kind, extensions] of Object.entries(KIND_EXTENSIONS)) {
-    if (extensions.includes(ext)) return kind as AttachmentFileKind
-  }
-  return 'other'
-}
-
-/** 是否图片 */
-export function isImageFile(name: string): boolean {
-  return IMAGE_EXTENSIONS.includes(getExtension(name))
-}
-
-/** 扩展名 → MIME（未知返回 ''） */
-export function getMimeType(name: string): string {
-  return MIME_BY_EXT[getExtension(name)] || ''
-}
-
-/** 格式化文件大小（B / KB / MB / GB） */
-export function formatFileSize(bytes?: number | string | null): string {
-  const size = Number(bytes || 0)
-  if (!Number.isFinite(size) || size <= 0) return '0 B'
-  if (size < 1024) return `${size} B`
-  if (size < 1024 * 1024) return `${(size / 1024).toFixed(1)} KB`
-  if (size < 1024 * 1024 * 1024) return `${(size / 1024 / 1024).toFixed(1)} MB`
-  return `${(size / 1024 / 1024 / 1024).toFixed(2)} GB`
-}
-
-/**
- * 是否命中原生 accept 语法（`.pdf,image/*,application/pdf`）。
- * 未设置 accept 时一律通过。
- */
-export function matchesAccept(name: string, accept?: string): boolean {
-  if (!accept) return true
-  const ext = getExtension(name)
-  const mime = getMimeType(name)
-  const tokens = accept
-    .split(',')
-    .map((token) => token.trim().toLowerCase())
-    .filter(Boolean)
-  if (!tokens.length) return true
-  return tokens.some((token) => {
-    if (token.startsWith('.')) return token.slice(1) === ext
-    if (token.endsWith('/*')) return mime.startsWith(`${token.slice(0, token.indexOf('/'))}/`)
-    return mime === token
-  })
-}
diff --git a/code/g3soft-libs/packages/ui/src/attachment/icons.ts b/code/g3soft-libs/packages/ui/src/attachment/icons.ts
deleted file mode 100644
index ff85cb2f..00000000
--- a/code/g3soft-libs/packages/ui/src/attachment/icons.ts
+++ /dev/null
@@ -1,26 +0,0 @@
-import {
-  FileArchive,
-  FileImage,
-  FileSpreadsheet,
-  FileText,
-  Files,
-  Film,
-  Presentation,
-} from '@lucide/vue'
-import type { Component } from 'vue'
-import type { AttachmentFileKind } from './file'
-
-/**
- * 文件族 → 图标。卡片、表格、预览三处共用，保证同一文件在任何视图里长得一样。
- *
- * 比「扩展名三个字母」的方块信息量更高：图标先传达类型，扩展名文字只是补充。
- */
-export const ATTACHMENT_KIND_ICONS: Record<AttachmentFileKind, Component> = {
-  image: FileImage,
-  doc: FileText,
-  sheet: FileSpreadsheet,
-  slide: Presentation,
-  archive: FileArchive,
-  media: Film,
-  other: Files,
-}
diff --git a/code/g3soft-libs/packages/ui/src/attachment/index.ts b/code/g3soft-libs/packages/ui/src/attachment/index.ts
deleted file mode 100644
index 275af32d..00000000
--- a/code/g3soft-libs/packages/ui/src/attachment/index.ts
+++ /dev/null
@@ -1,29 +0,0 @@
-export { default as G3Attachment } from './Attachment.vue'
-export { default as G3AttachmentList } from './AttachmentList.vue'
-export { default as G3AttachmentCard } from './AttachmentCard.vue'
-export { default as G3AttachmentPreview } from './AttachmentPreview.vue'
-export {
-  IMAGE_EXTENSIONS,
-  formatFileSize,
-  getExtension,
-  getFileKind,
-  getMimeType,
-  isImageFile,
-  matchesAccept,
-} from './file'
-export type { AttachmentFileKind } from './file'
-export type {
-  AttachmentCategory,
-  AttachmentEmits,
-  AttachmentExpose,
-  AttachmentInvalidInfo,
-  AttachmentInvalidReason,
-  AttachmentItem,
-  AttachmentListItem,
-  AttachmentPendingFile,
-  AttachmentProps,
-  AttachmentRemoveRequest,
-  AttachmentStatus,
-  AttachmentUploadContext,
-  AttachmentUploadRequest,
-} from './types'
diff --git a/code/g3soft-libs/packages/ui/src/attachment/types.ts b/code/g3soft-libs/packages/ui/src/attachment/types.ts
deleted file mode 100644
index da3ca088..00000000
--- a/code/g3soft-libs/packages/ui/src/attachment/types.ts
+++ /dev/null
@@ -1,204 +0,0 @@
-/**
- * 附件管理器类型定义。
- *
- * 设计原则：**与业务解耦**。组件不请求接口、不感知「模块 / 业务主键」等概念，
- * 只消费 `files` / `categories` 两份数据，并把用户意图以事件抛给业务；
- * 需要开箱即用时可传 `uploadRequest` / `removeRequest` 让组件托管请求过程。
- */
-
-/** 附件状态：ready 已上传、uploading 上传中、error 上传失败 */
-export type AttachmentStatus = 'ready' | 'uploading' | 'error'
-
-/** 附件项（组件不解读业务字段，事件里原样回传） */
-export interface AttachmentItem {
-  /** 唯一标识 */
-  id: string | number
-  /** 文件名（含扩展名） */
-  name: string
-  /** 文件大小（字节） */
-  size?: number
-  /** 扩展名（小写、不含点）；不传时从 name 推断 */
-  ext?: string
-  /** 预览 / 下载地址 */
-  url?: string
-  /** 缩略图地址；图片类型不传时回退到 url */
-  thumbnailUrl?: string
-  /** 所属分类标识，与 AttachmentCategory.id 对应 */
-  categoryId?: string | number
-  /** 状态，默认 ready */
-  status?: AttachmentStatus
-  /** 上传进度 0-100，status 为 uploading 时展示 */
-  percent?: number
-  /** 业务原始数据，组件不解读 */
-  raw?: unknown
-  /** 允许附加业务字段 */
-  [key: string]: unknown
-}
-
-/** 分类节点；提供 categories 时左侧渲染分类树 */
-export interface AttachmentCategory {
-  /** 唯一标识 */
-  id: string | number
-  /** 分类名称 */
-  name: string
-  /** 数量角标（预留字段，组件不渲染） */
-  count?: number
-  /** 禁用该分类 */
-  disabled?: boolean
-  /** 子分类 */
-  children?: AttachmentCategory[]
-  /** 允许附加业务字段 */
-  [key: string]: unknown
-}
-
-/** 待上传的本地文件（尚未提交给业务） */
-export interface AttachmentPendingFile {
-  /** 本地 File 对象 */
-  file: File
-  /** 文件名 */
-  name: string
-  /** 字节大小 */
-  size: number
-  /** 扩展名（小写、不含点） */
-  ext: string
-  /** 本地预览地址（图片为 blob URL） */
-  url?: string
-}
-
-/** 列表渲染项：已上传附件 或 待上传本地文件 */
-export interface AttachmentListItem extends AttachmentItem {
-  /** 是否为待上传（本地队列）项 */
-  pending?: boolean
-}
-
-/** 校验未通过的原因 */
-export type AttachmentInvalidReason = 'accept' | 'max-size' | 'max-count'
-
-/** 校验未通过信息 */
-export interface AttachmentInvalidInfo {
-  /** 原因：类型不接受 / 超出大小 / 超出数量 */
-  reason: AttachmentInvalidReason
-  /** 被拒绝的本地文件 */
-  files: File[]
-  /** 组件按 locale 生成的提示原文（业务可直接 toast） */
-  message: string
-}
-
-/** 上传上下文（把当前分类透传给业务） */
-export interface AttachmentUploadContext {
-  /** 当前选中分类；「全部」时为 undefined */
-  categoryId?: string | number
-}
-
-/** 上传请求：组件托管上传，成功后可返回落库结果用于回填列表 */
-export type AttachmentUploadRequest = (
-  files: File[],
-  context: AttachmentUploadContext,
-) => Promise<AttachmentItem[] | void> | AttachmentItem[] | void
-
-/** 删除请求：组件托管删除 */
-export type AttachmentRemoveRequest = (items: AttachmentItem[]) => Promise<void> | void
-
-export interface AttachmentProps {
-  /** 附件列表（受控，配合 `update:files` 使用 v-model:files） */
-  files?: AttachmentItem[]
-  /** 分类数据；为空则不渲染左栏 */
-  categories?: AttachmentCategory[]
-  /** 选中分类标识，`''` 表示「全部」（v-model:categoryKey） */
-  categoryKey?: string | number
-  /** 是否显示左侧分类栏（无 categories 时自动隐藏） */
-  showCategory?: boolean
-  /**
-   * 是否显示右侧预览栏。
-   * 默认 `false`（只留分类 + 列表）—— 关掉时 `preview` 事件照常抛出，
-   * 业务可以自己开弹窗或抽屉做预览。
-   */
-  showPreview?: boolean
-  /** 只读：隐藏上传 / 删除入口 */
-  readonly?: boolean
-  /** 列表请求中（骨架 / 遮罩） */
-  loading?: boolean
-  /** 分类数据请求中 */
-  categoryLoading?: boolean
-  /** 是否可勾选 */
-  selectable?: boolean
-  /** 是否允许多选 */
-  multiple?: boolean
-  /** 接受的文件类型，同原生 `accept`（`.pdf,image/*`） */
-  accept?: string
-  /** 单文件大小上限（字节），0 或未传表示不限制 */
-  maxSize?: number
-  /** 待上传队列上限（不含已上传文件） */
-  maxCount?: number
-  /** 允许在列表区域 Ctrl/Cmd+V 粘贴上传（监听 document，默认关闭） */
-  pasteUpload?: boolean
-  /** 删除前二次确认（默认开启） */
-  confirmRemove?: boolean
-  /** 下载时由组件内建触发（依据 `item.url` 造 a[download]），默认开启 */
-  builtinDownload?: boolean
-  /** 是否显示分页（默认开启，数据不足一页时自动隐藏） */
-  pagination?: boolean
-  /** 当前页（v-model:page） */
-  page?: number
-  /** 每页条数（v-model:pageSize） */
-  pageSize?: number
-  /** 总条数；不传时取 `files.length` */
-  total?: number
-  /** 每页条数选项 */
-  pageSizeOptions?: Array<number | string>
-  /** 显示每页条数切换器 */
-  showSizeChanger?: boolean
-  /** 根容器高度，数字按 px；默认撑满父容器（父级无高度时保底 320px） */
-  height?: number | string
-  /** 托管上传：不传时改为 emit `upload` 交给业务 */
-  uploadRequest?: AttachmentUploadRequest
-  /** 托管删除：不传时改为 emit `remove` 交给业务 */
-  removeRequest?: AttachmentRemoveRequest
-}
-
-export interface AttachmentEmits {
-  /** files 受控更新（删除成功 / 上传回填后触发） */
-  (e: 'update:files', files: AttachmentItem[]): void
-  (e: 'update:categoryKey', key: string | number): void
-  (e: 'update:page', page: number): void
-  (e: 'update:pageSize', size: number): void
-  /** 列表发生增删（上传成功 / 删除成功） */
-  (e: 'change', files: AttachmentItem[]): void
-  /** 勾选变化 */
-  (e: 'select', items: AttachmentItem[]): void
-  /** 分类切换 */
-  (e: 'categoryChange', key: string | number, category: AttachmentCategory | null): void
-  /** 点击某项预览（取消选中时 item 为 null） */
-  (e: 'preview', item: AttachmentItem | null): void
-  /** 下载（配合 `builtin-download` 可关闭内建行为） */
-  (e: 'download', items: AttachmentItem[]): void
-  /** 用户确认删除（`confirm-remove` 通过且请求成功后才触发） */
-  (e: 'remove', items: AttachmentItem[]): void
-  /** 删除失败 */
-  (e: 'removeError', error: unknown, items: AttachmentItem[]): void
-  /** 未提供 `uploadRequest` 时把待上传文件交给业务 */
-  (e: 'upload', files: File[], context: AttachmentUploadContext): void
-  /** 托管上传成功 */
-  (e: 'uploadSuccess', files: File[], result: AttachmentItem[] | void): void
-  /** 上传失败（待上传队列保留，可重试） */
-  (e: 'uploadError', error: unknown, files: File[]): void
-  /** 文件被 accept / maxSize / maxCount 拒绝 */
-  (e: 'invalid', info: AttachmentInvalidInfo): void
-}
-
-export interface AttachmentExpose {
-  /** 当前勾选的附件 */
-  readonly selectedItems: AttachmentItem[]
-  /** 待上传的本地文件 */
-  readonly pendingFiles: AttachmentPendingFile[]
-  /** 打开系统文件选择框 */
-  openFileDialog: () => void
-  /** 清空勾选 */
-  clearSelection: () => void
-  /** 全选当前页 */
-  selectAll: () => void
-  /** 直接入队待上传文件（返回被接受的文件） */
-  addFiles: (files: File[] | FileList) => File[]
-  /** 清空待上传队列（业务自行接管上传时调用） */
-  clearPending: () => void
-}
diff --git a/code/g3soft-libs/packages/ui/src/index.ts b/code/g3soft-libs/packages/ui/src/index.ts
index 68d92f89..485dbcb8 100644
--- a/code/g3soft-libs/packages/ui/src/index.ts
+++ b/code/g3soft-libs/packages/ui/src/index.ts
@@ -5,7 +5,6 @@ import { setBaseZIndex } from './_utils/z-index'
 import './_styles/rtl.scss'
 
 // ---------------- 组件 ----------------
-import { G3Attachment } from './attachment'
 import { G3Button } from './button'
 import { G3ButtonGroup, G3ButtonGroupSeparator } from './button-group'
 import { G3SliderCaptcha } from './captcha'
@@ -32,12 +31,12 @@ import { G3Space } from './space'
 import { G3Spin } from './spin'
 import { G3Splitter, G3SplitterPanel } from './splitter'
 import { G3Switch } from './switch'
+import { G3Table } from './table'
 import { G3TabPane, G3Tabs } from './tabs'
 import { G3Tag } from './tag'
 import { G3Tooltip } from './tooltip'
 import { G3Tree } from './tree'
 
-export * from './attachment'
 export * from './button'
 export * from './button-group'
 export * from './captcha'
@@ -64,6 +63,7 @@ export * from './space'
 export * from './spin'
 export * from './splitter'
 export * from './switch'
+export * from './table'
 export * from './tabs'
 export * from './tag'
 export * from './tooltip'
@@ -125,7 +125,6 @@ export type { Locale } from './locale'
 export interface G3UIOptions extends GlobalConfig {}
 
 const components = {
-  G3Attachment,
   G3Button,
   G3ButtonGroup,
   G3ButtonGroupSeparator,
@@ -161,6 +160,7 @@ const components = {
   G3Splitter,
   G3SplitterPanel,
   G3Switch,
+  G3Table,
   G3TabPane,
   G3Tabs,
   G3Tag,
diff --git a/code/g3soft-libs/packages/ui/src/input/Input.test.ts b/code/g3soft-libs/packages/ui/src/input/Input.test.ts
index bbd017f3..81624ab0 100644
--- a/code/g3soft-libs/packages/ui/src/input/Input.test.ts
+++ b/code/g3soft-libs/packages/ui/src/input/Input.test.ts
@@ -134,3 +134,110 @@ describe('Input 暴露的方法', () => {
     expect(() => (textarea.vm as unknown as { focus: () => void }).focus()).not.toThrow()
   })
 })
+
+/**
+ * 透传属性（$attrs）落点。
+ *
+ * 组件的根是包裹层 `<div>`，真正的控件在里面。这几条锁的是「谁该收到什么」：
+ * - 归属**输入行为**的属性（id / name / autocomplete / 原生事件）→ 内部控件；
+ * - 表达**布局与组件身份**的（class / style / data-*）→ 留在包裹层。
+ */
+describe('Input 透传属性', () => {
+  it('id / name / autocomplete 等落在内部 input 上，而不是包裹层', () => {
+    const wrapper = mount(G3Input, {
+      props: { modelValue: '' },
+      attrs: { id: 'my-input', name: 'account', autocomplete: 'off' },
+    })
+
+    const input = wrapper.find('input')
+    expect(input.attributes('id')).toBe('my-input')
+    expect(input.attributes('name')).toBe('account')
+    expect(input.attributes('autocomplete')).toBe('off')
+    expect(input.attributes('data-x')).toBeUndefined()
+
+    // 包裹层不该出现这些 —— 否则 <label for> 会指向 div，点 label 聚焦不到输入框
+    const root = wrapper.find('.g3-input')
+    expect(root.attributes('id')).toBeUndefined()
+    expect(root.attributes('name')).toBeUndefined()
+  })
+
+  /**
+   * `data-*` 必须留在包裹层。
+   *
+   * 它标识的是「这个组件」，而 `data-testid="input-password"` 配 `[data-testid] input`
+   * 是很常见的查询写法；透到内部 input 会让这类选择器全部失效
+   * （真实回归：form.spec.ts 有 4 个用例因此找不到元素而超时）。
+   */
+  it('data-* 留在包裹层（组件身份不随内部结构漂移）', () => {
+    const wrapper = mount(G3Input, {
+      props: { modelValue: '' },
+      attrs: { 'data-testid': 'input-password', 'data-x': '1' },
+    })
+
+    const root = wrapper.find('.g3-input')
+    expect(root.attributes('data-testid')).toBe('input-password')
+    expect(root.attributes('data-x')).toBe('1')
+    // 内部控件不该被外部 data-* 污染
+    expect(wrapper.find('input').attributes('data-testid')).toBeUndefined()
+  })
+
+  it('textarea 模式下 data-* 同样留在包裹层', () => {
+    const wrapper = mount(G3Input, {
+      props: { modelValue: '', type: 'textarea' },
+      attrs: { 'data-testid': 'ta-wrap' },
+    })
+
+    expect(wrapper.find('.g3-input').attributes('data-testid')).toBe('ta-wrap')
+    expect(wrapper.find('textarea').attributes('data-testid')).toBeUndefined()
+  })
+
+  it('原生事件落在内部 input 上（keydown / enter 能拿到正确的 target）', async () => {
+    const onKeydown = vi.fn()
+    const wrapper = mount(G3Input, {
+      props: { modelValue: '' },
+      attrs: { onKeydown },
+    })
+
+    await wrapper.find('input').trigger('keydown', { key: 'Enter' })
+
+    expect(onKeydown).toHaveBeenCalledTimes(1)
+    // target 必须是真正的输入框，而不是包裹用的 div
+    expect((onKeydown.mock.calls[0][0] as KeyboardEvent).target).toBe(
+      wrapper.find('input').element,
+    )
+  })
+
+  it('textarea 模式下同样透传到内部 textarea', () => {
+    const wrapper = mount(G3Input, {
+      props: { modelValue: '', type: 'textarea' },
+      attrs: { id: 'ta', name: 'content' },
+    })
+
+    expect(wrapper.find('textarea').attributes('id')).toBe('ta')
+    expect(wrapper.find('textarea').attributes('name')).toBe('content')
+  })
+
+  it('class / style 留在包裹层（参与父级布局的才是这个盒子）', () => {
+    const wrapper = mount(G3Input, {
+      props: { modelValue: '' },
+      attrs: { class: 'my-input', style: 'width: 200px' },
+    })
+
+    const root = wrapper.find('.g3-input')
+    expect(root.classes()).toContain('my-input')
+    expect(root.attributes('style')).toContain('width: 200px')
+    // 内部控件不该被外部 class 污染
+    expect(wrapper.find('input').classes()).not.toContain('my-input')
+  })
+
+  it('外部 class 不覆盖组件自身的状态类', () => {
+    const wrapper = mount(G3Input, {
+      props: { modelValue: '', disabled: true },
+      attrs: { class: 'my-input' },
+    })
+
+    const root = wrapper.find('.g3-input')
+    expect(root.classes()).toContain('g3-input--disabled')
+    expect(root.classes()).toContain('my-input')
+  })
+})
diff --git a/code/g3soft-libs/packages/ui/src/input/Input.vue b/code/g3soft-libs/packages/ui/src/input/Input.vue
index 72161941..0f6a53f6 100644
--- a/code/g3soft-libs/packages/ui/src/input/Input.vue
+++ b/code/g3soft-libs/packages/ui/src/input/Input.vue
@@ -1,5 +1,5 @@
 <script setup lang="ts">
-import { computed, nextTick, onBeforeUnmount, onMounted, ref, useSlots, watch } from 'vue'
+import { computed, nextTick, onBeforeUnmount, onMounted, ref, useAttrs, useSlots, watch } from 'vue'
 import { Eye, EyeOff, MoveDiagonal2, X } from '@lucide/vue'
 import { useLocale } from '../_composables/useLocale'
 import { useNamespace } from '../_composables/useNamespace'
@@ -9,8 +9,18 @@ import type { InputFocusOptions, InputProps } from './types'
  * 输入框 —— 支持单行 / 密码 / 数字 / 多行四种模式，以及清除、字数统计、前后缀插槽。
  *
  * 多行模式自带右下角高度拖拽手柄（可拖拽与方向键调整），不改变内部滚动行为。
+ *
+ * ## 透传属性（$attrs）落在真正的控件上
+ *
+ * 组件根节点是包裹用的 `<div>`，真正的 `<input>` / `<textarea>` 在它内部。
+ * 因此必须 `inheritAttrs: false` + 手工 `v-bind="$attrs"` 到控件上 —— 否则 Vue 会把
+ * `id` / `name` / `autocomplete` / `@keydown` 全都挂到包裹层：
+ * - `id` 挂外层 → `<label for>` 指向包裹 div，点 label 聚焦不到输入框；
+ * - `type` 挂外层 → 原生类型语义丢失；
+ * - 事件虽然能靠冒泡侥幸生效，但 `event.target` 是内部 input 而非用户以为的元素，
+ *   且 `@keydown.enter` 这类会受包裹层其它子元素（清除按钮 / 密码切换按钮）影响。
  */
-defineOptions({ name: 'G3Input' })
+defineOptions({ name: 'G3Input', inheritAttrs: false })
 
 const props = withDefaults(defineProps<InputProps>(), {
   modelValue: '',
@@ -44,9 +54,46 @@ const emit = defineEmits<{
 }>()
 
 const slots = useSlots()
+const attrs = useAttrs()
 const { b, e, m, is } = useNamespace('input')
 const locale = useLocale()
 
+/**
+ * 分流 `$attrs`：哪些留在**根包裹层**，哪些落到**内部控件**。
+ *
+ * 留在包裹层（`wrapperAttrs`）：
+ * - `class` / `style`：表达「这个输入框在页面里占多大、怎么排」，而外层 div 才是参与
+ *   父级布局的那个盒子（inline-flex + 边框 + 内边距）。挂到内部 `<input>` 上则只是给
+ *   控件加样式，外层盒子纹丝不动，`style="width: 200px"` 这类常见用法会失效。
+ * - `data-*`：**约定用于标识「这个组件」而不是「里面的原生控件」**。
+ *   `data-testid="input-password"` 这类写法配上 `[data-testid] input` 的查询很常见，
+ *   把它们透到内部 input 会让这类选择器全部失效（实测回归：form.spec.ts 的 4 个用例
+ *   因为找不到 `[data-testid="input-password"] input` 而失败）——
+ *   组件的外层身份应当稳定，不该随内部结构变化而漂移。
+ *
+ * 落到内部控件（`controlAttrs`）：其余全部（`id` / `name` / `autocomplete` /
+ * `autofocus` / `@keydown` / `@click` …）—— 它们描述的是**输入行为本身**，
+ * 挂在外层 div 上不会生效或语义错误（如 `id` 挂外层会让 `<label for>` 指错元素）。
+ */
+const wrapperAttrs = computed(() => {
+  const { class: cls, style, ...rest } = attrs
+  const dataAttrs: Record<string, unknown> = {}
+  for (const [key, value] of Object.entries(rest)) {
+    if (key.startsWith('data-')) dataAttrs[key] = value
+  }
+  return { class: cls, style, ...dataAttrs }
+})
+
+const controlAttrs = computed(() => {
+  const result: Record<string, unknown> = {}
+  for (const [key, value] of Object.entries(attrs)) {
+    if (key === 'class' || key === 'style') continue
+    if (key.startsWith('data-')) continue
+    result[key] = value
+  }
+  return result
+})
+
 const focused = ref(false)
 const hovered = ref(false)
 const inputEl = ref<HTMLInputElement | null>(null)
@@ -297,7 +344,20 @@ defineExpose({
 </script>
 
 <template>
-  <div :class="classes" @mouseenter="hovered = true" @mouseleave="hovered = false">
+  <div
+    v-bind="wrapperAttrs"
+    :class="[classes, wrapperAttrs.class]"
+    @mouseenter="hovered = true"
+    @mouseleave="hovered = false"
+  >
+    <!--
+      根包裹层：`inheritAttrs: false` 之后 Vue 不再自动落 attrs，所以 class / style / data-*
+      要显式接上 —— 它们属于这个「组件身份 + 参与父级布局」的盒子（见 wrapperAttrs 的注释）。
+      class 单独用 `:class` 合并（不放进 v-bind，否则同一次绑定里会写两遍 class）。
+
+      这段注释必须留在**元素内部**：模板顶层的注释会被编译器提成组件根节点，
+      让 `wrapper.classes()` 之类的根元素查询落到注释上（已经踩过一次）。
+    -->
     <span v-if="!isTextarea && $slots.prefix" :class="e('prefix')">
       <slot name="prefix" />
     </span>
@@ -305,6 +365,7 @@ defineExpose({
     <input
       v-if="!isTextarea"
       ref="inputEl"
+      v-bind="controlAttrs"
       :class="e('control')"
       data-slot="input"
       :type="inputType"
@@ -326,6 +387,7 @@ defineExpose({
     <textarea
       v-else
       ref="textareaEl"
+      v-bind="controlAttrs"
       :class="e('textarea')"
       data-slot="textarea"
       :value="modelValue"
diff --git a/code/g3soft-libs/packages/ui/src/locale/index.ts b/code/g3soft-libs/packages/ui/src/locale/index.ts
index a6c99b98..454c970c 100644
--- a/code/g3soft-libs/packages/ui/src/locale/index.ts
+++ b/code/g3soft-libs/packages/ui/src/locale/index.ts
@@ -70,36 +70,6 @@ export interface Locale {
     /** 滑块验证：手柄的可访问名称（读屏 / 键盘聚焦时播报） */
     sliderLabel: string
   }
-  /**
-   * 附件管理器文案，`{count}` / `{name}` / `{size}` 为占位符。
-   */
-  attachment: {
-    allCategory: string
-    selectAll: string
-    selected: string
-    select: string
-    upload: string
-    download: string
-    remove: string
-    preview: string
-    pending: string
-    pendingCount: string
-    total: string
-    empty: string
-    emptyHint: string
-    limitAccept: string
-    limitSize: string
-    limitCount: string
-    dropHint: string
-    previewEmpty: string
-    prev: string
-    next: string
-    removeConfirm: string
-    removeConfirmSingle: string
-    invalidAccept: string
-    invalidMaxSize: string
-    invalidMaxCount: string
-  }
   /** 结果 / 缺省页文案（403 / 404 / 500 / 离线 / 空状态）。 */
   result: {
     '403': { title: string; desc: string }
@@ -171,33 +141,6 @@ export const zhCN: Locale = {
     verified: '验证通过',
     sliderLabel: '滑动验证',
   },
-  attachment: {
-    allCategory: '全部',
-    selectAll: '全选',
-    selected: '已选 {count} 项',
-    select: '选择',
-    upload: '上传',
-    download: '下载',
-    remove: '删除',
-    preview: '预览',
-    pending: '待上传',
-    pendingCount: '待上传 {count} 个',
-    total: '共 {count} 个文件',
-    empty: '暂无文件',
-    emptyHint: '拖拽文件到此处，或点击选择',
-    limitAccept: '支持格式：{accept}',
-    limitSize: '单个文件不超过 {size}',
-    limitCount: '最多 {count} 个待上传',
-    dropHint: '释放文件到此处',
-    previewEmpty: '选择文件查看预览',
-    prev: '上一个',
-    next: '下一个',
-    removeConfirm: '确定删除选中的 {count} 个文件？',
-    removeConfirmSingle: '确定删除「{name}」？',
-    invalidAccept: '「{name}」类型不支持',
-    invalidMaxSize: '「{name}」超过大小限制（{size}）',
-    invalidMaxCount: '待上传文件最多 {count} 个',
-  },
   result: {
     '403': {
       title: '无权访问',
@@ -282,33 +225,6 @@ export const enUS: Locale = {
     verified: 'Verified',
     sliderLabel: 'Slide verification',
   },
-  attachment: {
-    allCategory: 'All',
-    selectAll: 'Select all',
-    selected: '{count} selected',
-    select: 'Choose',
-    upload: 'Upload',
-    download: 'Download',
-    remove: 'Delete',
-    preview: 'Preview',
-    pending: 'Pending',
-    pendingCount: '{count} pending',
-    total: '{count} files',
-    empty: 'No files',
-    emptyHint: 'Drop files here, or click to choose',
-    limitAccept: 'Accepted: {accept}',
-    limitSize: 'Up to {size} per file',
-    limitCount: 'At most {count} pending',
-    dropHint: 'Drop files here',
-    previewEmpty: 'Select a file to preview',
-    prev: 'Previous',
-    next: 'Next',
-    removeConfirm: 'Delete the {count} selected files?',
-    removeConfirmSingle: 'Delete "{name}"?',
-    invalidAccept: '"{name}" is not an accepted file type',
-    invalidMaxSize: '"{name}" exceeds the size limit ({size})',
-    invalidMaxCount: 'At most {count} pending files',
-  },
   result: {
     '403': {
       title: 'Access Denied',
diff --git a/code/g3soft-libs/packages/ui/src/popover/Popover.vue b/code/g3soft-libs/packages/ui/src/popover/Popover.vue
index ce177423..9964516f 100644
--- a/code/g3soft-libs/packages/ui/src/popover/Popover.vue
+++ b/code/g3soft-libs/packages/ui/src/popover/Popover.vue
@@ -261,7 +261,7 @@ onBeforeUnmount(() => {
 
 .#{e('popover', 'content')} {
   position: relative;
-  padding: v('space-2', 8px);
+  padding: v('space-1', 4px);
   /* 不描边：投影统一由 .g3-popover__popup 的 drop-shadow 施加（含箭头）。
      留下 1px 边框时箭头与主体之间会露出接缝，Tooltip 还会多一圈描边 */
   border: 0;
diff --git a/code/g3soft-libs/packages/ui/src/rich-text/LinkMenu.vue b/code/g3soft-libs/packages/ui/src/rich-text/LinkMenu.vue
new file mode 100644
index 00000000..a5392063
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/rich-text/LinkMenu.vue
@@ -0,0 +1,308 @@
+<script setup lang="ts">
+import { computed, onBeforeUnmount, onMounted, ref, watch } from 'vue'
+import type { Editor } from '@tiptap/vue-3'
+import { ExternalLink, Pencil, Trash2 } from '@lucide/vue'
+import { nextZIndex, releaseZIndex } from '../_utils/z-index'
+import { useNamespace } from '../_composables/useNamespace'
+
+/**
+ * 链接右键菜单 —— 在编辑器正文里的**链接**上右键时，在鼠标位置弹出「编辑 / 打开 / 删除」。
+ *
+ * 为什么不复用 `G3Popover` 的 `trigger="contextmenu"`：
+ * Popover 的右键模式要求浮层**包住**触发器元素（它靠注入事件处理器到触发器的 vnode 上工作），
+ * 而这里的「触发器」是 Tiptap 文档里的 `<a>` —— 它由 ProseMirror 渲染、内容随时被重建，
+ * 我们没法把它声明式地塞进任何组件的插槽里。
+ *
+ * 所以改用与 `TableMenu` 相同的手法：**在编辑器根节点上监听右键**，判断落点是否命中 `<a>`，
+ * 命中则把菜单 `position: fixed` 摆到鼠标位置。菜单本体是 Teleport 到 body 的普通 DOM，
+ * 层级从 `popup` 档领取（与 Popover / Dropdown 同一套机制，保证在 Modal / Drawer 里也压得住）。
+ */
+defineOptions({ name: 'G3RichTextLinkMenu' })
+
+const props = defineProps<{
+  editor?: Editor
+  /** 由 Toolbar 传入：点「编辑」时把该链接交给链接面板（预填地址与文字） */
+  onEdit: (href: string, text: string) => void
+}>()
+
+const { b, e } = useNamespace('rich-text-link-menu')
+
+/** 菜单可见性 + 定位 */
+const visible = ref(false)
+const menuStyle = ref<{ top: string; left: string; zIndex?: number }>({
+  top: '0px',
+  left: '0px',
+})
+
+/** 当前右键命中的链接信息 */
+const targetHref = ref('')
+const targetText = ref('')
+
+/**
+ * 命中链接的文档位置。
+ *
+ * 右键**不一定**会移动光标，所以「删除 / 编辑」不能依赖当前选区 —— 必须记住
+ * 用户实际点中的是哪一个 `<a>`，操作前把选区移过去，否则会作用到上一次光标处。
+ */
+const anchorPos = ref<number | null>(null)
+
+let menuZIndex = 0
+
+function acquireZIndex(): void {
+  if (!menuZIndex) menuZIndex = nextZIndex('popup')
+}
+
+function releaseMenuZIndex(): void {
+  if (menuZIndex) {
+    releaseZIndex(menuZIndex)
+    menuZIndex = 0
+  }
+}
+
+function hide(): void {
+  if (!visible.value && !menuZIndex) return
+  visible.value = false
+  releaseMenuZIndex()
+}
+
+/**
+ * 从右键落点向上找最近的 `<a>`。
+ *
+ * 用 `closest('a')` 而不是「拿选区判断是否在链接里」：右键**不一定**会移动光标
+ * （浏览器只在部分情况更新选区），按落点 DOM 判断才与用户所见一致 ——
+ * 他右键点在哪条链接上，菜单就作用于哪条。
+ */
+function findAnchor(target: EventTarget | null): HTMLAnchorElement | null {
+  const el = target as HTMLElement | null
+  if (!el || typeof el.closest !== 'function') return null
+  const anchor = el.closest('a')
+  return anchor instanceof HTMLAnchorElement ? anchor : null
+}
+
+function onContextMenu(event: MouseEvent): void {
+  const editor = props.editor
+  if (!editor || editor.isDestroyed) return
+
+  const anchor = findAnchor(event.target)
+  if (!anchor) {
+    // 右键落在非链接处：让浏览器自己的菜单正常工作，同时收起我们的
+    hide()
+    return
+  }
+
+  // 命中链接：接管这次右键（阻止原生菜单），在鼠标位置弹出
+  event.preventDefault()
+
+  targetHref.value = anchor.getAttribute('href') ?? ''
+  targetText.value = anchor.textContent ?? ''
+  // 记录该 <a> 在文档中的起点，供「编辑 / 删除」把选区移过去
+  try {
+    anchorPos.value = editor.view.posAtDOM(anchor, 0)
+  } catch {
+    // posAtDOM 在 DOM 与文档不同步（刚被重建）时会抛，此时退化为「按当前选区操作」
+    anchorPos.value = null
+  }
+
+  // 固定尺寸的菜单，直接用鼠标坐标；flip 不必做 —— 菜单只有三行，
+  // 这里用 min 把右下越界夹回来即可（比引入完整定位引擎轻）
+  acquireZIndex()
+  const MENU_W = 160
+  const MENU_H = 132
+  menuStyle.value = {
+    top: `${Math.min(event.clientY, window.innerHeight - MENU_H)}px`,
+    left: `${Math.min(event.clientX, window.innerWidth - MENU_W)}px`,
+    zIndex: menuZIndex,
+  }
+  visible.value = true
+}
+
+/** 打开链接：新标签页，带上 noopener 防反向控制 */
+function openLink(): void {
+  if (!targetHref.value) return
+  window.open(targetHref.value, '_blank', 'noopener,noreferrer')
+  hide()
+}
+
+/** 编辑：交给链接面板（它负责预填与写回），菜单本身不直接改文档 */
+function editLink(): void {
+  props.onEdit(targetHref.value, targetText.value)
+  hide()
+}
+
+/**
+ * 删除链接：**只去掉链接、保留文字**。
+ *
+ * 与「删除」的字面意思相比这更符合预期 —— 用户想删的通常是「这里不该是链接」，
+ * 而不是「这段字也不要了」（那用选中 + Delete 更直接）。
+ *
+ * 先把光标放进该链接再 unset：右键不一定移动了选区，直接 `unsetLink()` 会作用在
+ * 上一次光标所在处，可能删错链接。`setTextSelection` 定位到该 `<a>` 的文档位置。
+ */
+function removeLink(): void {
+  const editor = props.editor
+  if (!editor || editor.isDestroyed) return
+
+  const pos = anchorPos.value
+  const chain = editor.chain().focus()
+  if (pos != null) chain.setTextSelection(pos)
+  chain.extendMarkRange('link').unsetLink().run()
+  hide()
+}
+
+/* ---------- 全局关闭 ---------- */
+// 点击别处（左键）/ 滚动 / 窗口尺寸变化都收起菜单。
+// 用 capture + 冒泡阶段双保险：左键点菜单内部时不该关（由 @click 自行处理）。
+function onDocumentPointerDown(event: MouseEvent): void {
+  if (!visible.value) return
+  const el = event.target as HTMLElement | null
+  if (el && typeof el.closest === 'function' && el.closest(`.${b()}`)) return
+  hide()
+}
+
+function onScrollOrResize(): void {
+  if (visible.value) hide()
+}
+
+function bindGlobal(): void {
+  document.addEventListener('mousedown', onDocumentPointerDown, true)
+  window.addEventListener('scroll', onScrollOrResize, { passive: true, capture: true })
+  window.addEventListener('resize', onScrollOrResize, { passive: true })
+  window.addEventListener('blur', onScrollOrResize)
+}
+
+function unbindGlobal(): void {
+  document.removeEventListener('mousedown', onDocumentPointerDown, true)
+  window.removeEventListener('scroll', onScrollOrResize, { capture: true } as EventListenerOptions)
+  window.removeEventListener('resize', onScrollOrResize)
+  window.removeEventListener('blur', onScrollOrResize)
+}
+
+/**
+ * 编辑器根节点上监听右键（捕获阶段）。
+ *
+ * 挂在**编辑器 DOM** 而不是 document：只对正文里的链接生效，不影响宿主页面别处的右键菜单。
+ * 编辑器实例在挂载后才出现，所以在 setup 里直接绑定 view.dom（此时已存在）。
+ */
+const boundDom = ref<HTMLElement | null>(null)
+
+function bindEditor(): void {
+  const dom = props.editor?.view?.dom
+  if (!dom) return
+  dom.addEventListener('contextmenu', onContextMenu)
+  boundDom.value = dom
+}
+
+function unbindEditor(): void {
+  boundDom.value?.removeEventListener('contextmenu', onContextMenu)
+  boundDom.value = null
+}
+
+// 编辑器实例可能晚于组件挂载出现（useEditor 在 onMounted 创建），用 watch immediate 兜住
+watch(
+  () => props.editor,
+  (editor) => {
+    unbindEditor()
+    if (editor && !editor.isDestroyed) bindEditor()
+  },
+  { immediate: true },
+)
+
+// 全局监听放在 onMounted：setup 顶层直接碰 document / window 在 SSR 下会炸
+// （文档站是 SSR 预渲染，组件即使只在客户端用，也应当守住这条线）。
+onMounted(() => {
+  bindGlobal()
+})
+
+onBeforeUnmount(() => {
+  unbindEditor()
+  unbindGlobal()
+  releaseMenuZIndex()
+})
+
+/** 菜单项定义：图标 + 文案 + 动作（顺序按使用频率：编辑 > 打开 > 删除） */
+const items = computed(() => [
+  { key: 'edit', label: '编辑链接', icon: Pencil, action: editLink },
+  { key: 'open', label: '打开链接', icon: ExternalLink, action: openLink },
+  { key: 'remove', label: '删除链接', icon: Trash2, action: removeLink, danger: true },
+])
+</script>
+
+<template>
+  <Teleport to="body">
+    <div v-show="visible" :class="b()" :style="menuStyle" role="menu" @contextmenu.prevent>
+      <button
+        v-for="item in items"
+        :key="item.key"
+        type="button"
+        :class="[e('item'), { 'is-danger': item.danger }]"
+        role="menuitem"
+        @click="item.action"
+      >
+        <component :is="item.icon" :class="e('item-icon')" aria-hidden="true" />
+        <span :class="e('item-label')">{{ item.label }}</span>
+      </button>
+    </div>
+  </Teleport>
+</template>
+
+<style lang="scss">
+@use '@g3soft/tokens/scss' as *;
+
+/* 链接右键菜单：fixed 定位于鼠标位置，带边框 + 阴影 + 圆角（与表格操作浮层同一套观感） */
+.#{b('rich-text-link-menu')} {
+  position: fixed;
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+  min-width: 148px;
+  padding: v('space-1', 4px);
+  border: 1px solid v('border-color', #d9d9d9);
+  border-radius: v('radius', 6px);
+  background: v('bg-container', #fff);
+  box-shadow: v('shadow-popup', 0 6px 16px rgba(0, 0, 0, 0.12));
+}
+
+.#{e('rich-text-link-menu', 'item')} {
+  display: flex;
+  align-items: center;
+  gap: v('space-2', 8px);
+  width: 100%;
+  padding: v('space-1', 4px) v('space-2', 8px);
+  border: 0;
+  border-radius: v('radius-sm', 4px);
+  background: transparent;
+  color: v('text-1', rgba(0, 0, 0, 0.88));
+  font-family: inherit;
+  font-size: v('font-size', 14px);
+  line-height: 1.5;
+  text-align: start;
+  white-space: nowrap;
+  cursor: pointer;
+  transition: background-color v('duration-fast', 0.1s) v('ease', ease);
+
+  &:hover {
+    background: v('fill', rgba(0, 0, 0, 0.04));
+  }
+
+  /* 删除：危险语义用红色，与上方两项拉开 */
+  &.#{is('danger')} {
+    color: v('color-danger', #ec4246);
+
+    &:hover {
+      background: color-mix(in srgb, #{v('color-danger', #ec4246)} 10%, transparent);
+    }
+  }
+}
+
+.#{e('rich-text-link-menu', 'item-icon')} {
+  flex-shrink: 0;
+  width: 16px;
+  height: 16px;
+  /* 图标比文字浅一档（与工具条 / 表格浮层同源），危险项继承父级红色 */
+  color: v('text-2', rgba(0, 0, 0, 0.65));
+}
+
+.#{e('rich-text-link-menu', 'item')}.#{is('danger')} .#{e('rich-text-link-menu', 'item-icon')} {
+  color: inherit;
+}
+</style>
diff --git a/code/g3soft-libs/packages/ui/src/rich-text/ListTypeIcon.vue b/code/g3soft-libs/packages/ui/src/rich-text/ListTypeIcon.vue
new file mode 100644
index 00000000..47a941c2
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/rich-text/ListTypeIcon.vue
@@ -0,0 +1,124 @@
+<script setup lang="ts">
+import { computed } from 'vue'
+
+/**
+ * 列表样式预览图标（对齐 TinyMCE 的 `bullist` / `numlist` 图标画法）。
+ *
+ * ## 为什么要自己画，而不是用文字符号
+ *
+ * 早前菜单项的文字是「`•  实心圆点`」这种「符号 + 档位名」的组合。它能用，但不够形象：
+ * 一列竖排的 `•`、`○`、`■` 挤在文字前，读者仍要**逐条读文字**才能确认哪条是方块；
+ * 而 TinyMCE 的菜单项左边是一张**缩略图** —— 三条内容线 + 左侧真实的项目符号 / 编号，
+ * 扫一眼就知道「这档长什么样」，根本不用读字。
+ *
+ * ## 画法
+ *
+ * 与 TinyMCE 一致地用 24 网格（TinyMCE 是 48 网格，此处等比折半）：
+ * 左侧 x≈5 放标记、右侧 x=9..20 放三条内容线。
+ * - **内容线**用 `opacity=".2"` 的淡色（TinyMCE 用 `fill-rule="evenodd"` + 半透明路径），
+ *   让视觉重心落在左侧的**标记**上 —— 那才是这一档真正要传达的信息；
+ * - **标记**按档位真实绘制：圆点 / 圆圈用 `<circle>`（实心与空心之分）、方块用 `<rect>`、
+ *   编号与字母用 `<text>`（希腊字母 α 也走 `<text>`，浏览器用系统字体渲染即可）。
+ *
+ * 颜色一律用 `currentColor`：图标跟随菜单项的文字色，选中态 / hover 态自动一致，
+ * 不需要为每个状态各写一份颜色。
+ */
+defineOptions({ name: 'G3RichTextListIcon' })
+
+const props = withDefaults(
+  defineProps<{
+    /** 列表种类：无序（项目符号）/ 有序（编号） */
+    kind: 'bullet' | 'ordered'
+    /**
+     * 样式值：
+     * 无序 —— `'' | 'disc' | 'circle' | 'square'`；
+     * 有序 —— `'' | 'a' | 'i' | 'lower-greek' | 'I' | 'A'`。
+     */
+    type?: string
+    /** 图标像素尺寸 */
+    size?: number
+  }>(),
+  { type: '', size: 24 },
+)
+
+/**
+ * 内容线：三条等距横线。
+ *
+ * 对应 TinyMCE 的 `M18 12h22v4H18z / M18 22h22v4H18z / M18 32h22v4H18z`（48 网格），
+ * 折半到 24 网格即 `M9 6h11v2H9z` 等 —— 线宽 2、间距 3、右端到 20。
+ */
+const LINES = ['M9 6h11v2H9z', 'M9 11h11v2H9z', 'M9 16h11v2H9z']
+
+/**
+ * 编号预览的字符：只画**第一行**的编号。
+ *
+ * 三行都画编号（`1. / 2. / 3.`）会让图标在 24px 里几乎糊成一团；只标第一行配上三条线，
+ * 「这是个编号列表」的语义已经足够（TinyMCE 的画法也是这样）。
+ * 每种档位取它最有代表性的字符：罗马数字取小写 `i`（最易辨认）、希腊字母取 `α`。
+ */
+const ORDERED_GLYPHS: Record<string, string> = {
+  '': '1',
+  a: 'a',
+  i: 'i',
+  I: 'I',
+  A: 'A',
+  'lower-greek': 'α',
+}
+
+/** 当前档位对应的编号字符（未登记的档位回落到 `1`） */
+const glyph = computed(() => ORDERED_GLYPHS[props.type] ?? '1')
+</script>
+
+<template>
+  <svg
+    xmlns="http://www.w3.org/2000/svg"
+    :width="size"
+    :height="size"
+    viewBox="0 0 24 24"
+    fill="none"
+    focusable="false"
+    aria-hidden="true"
+  >
+    <!-- 三条内容线：淡色，让视觉焦点落在左侧标记上 -->
+    <path v-for="d in LINES" :key="d" :d="d" fill="currentColor" opacity="0.2" />
+
+    <!-- 无序列表：实心圆点 / 空心圆圈 / 实心方块 -->
+    <template v-if="kind === 'bullet'">
+      <!-- 默认与 disc 都画实心圆点（默认即浏览器的 disc） -->
+      <circle v-if="!type || type === 'disc'" cx="5" cy="7" r="1.8" fill="currentColor" />
+      <circle
+        v-else-if="type === 'circle'"
+        cx="5"
+        cy="7"
+        r="1.4"
+        fill="none"
+        stroke="currentColor"
+        stroke-width="1.2"
+      />
+      <rect
+        v-else-if="type === 'square'"
+        x="3.3"
+        y="5.3"
+        width="3.4"
+        height="3.4"
+        rx="0.3"
+        fill="currentColor"
+      />
+      <!-- 未知档位回落到实心圆点 -->
+      <circle v-else cx="5" cy="7" r="1.8" fill="currentColor" />
+    </template>
+
+    <!-- 有序列表：第一行的编号（罗马数字 / 字母 / 希腊字母） -->
+    <text
+      v-else
+      x="1"
+      y="9.1"
+      fill="currentColor"
+      font-size="7.5"
+      font-family="ui-sans-serif, system-ui, sans-serif"
+      font-weight="600"
+    >
+      {{ glyph }}
+    </text>
+  </svg>
+</template>
diff --git a/code/g3soft-libs/packages/ui/src/rich-text/PreviewDialog.vue b/code/g3soft-libs/packages/ui/src/rich-text/PreviewDialog.vue
new file mode 100644
index 00000000..e6e7d9d9
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/rich-text/PreviewDialog.vue
@@ -0,0 +1,250 @@
+<script setup lang="ts">
+import { computed } from 'vue'
+import { Printer } from '@lucide/vue'
+import { G3Button } from '../button'
+import { G3Modal } from '../modal'
+import { useNamespace } from '../_composables/useNamespace'
+import { printHtml } from './print'
+
+/**
+ * 预览对话框（对齐 TinyMCE 的 `preview` 插件）。
+ *
+ * 用模态框而不是 `window.open`：
+ * - 嵌入式 WebView / iframe 里 `window.open` 常被拦截，点了没反应；
+ * - 模态框复用 G3Modal，观感与全库一致（新窗口是个浏览器原生窗口，样式无法控制）；
+ * - E2E 不用处理多页 / 等待新标签。
+ *
+ * ## 渲染方式：v-html + 独立样式作用域
+ *
+ * 预览要把**正文真实的排版**呈现出来（标题层级、列表、表格、颜色、对齐），
+ * 所以直接 `v-html` 渲染，而不是走一遍编辑器（那会把 ProseMirror 的编辑态
+ * 装饰 —— 占位符、选中节点描边 —— 一起带进来）。
+ *
+ * 为了不依赖宿主是否给正文写了样式，这里复刻一份与编辑器内一致的排版规则
+ * （与 RichText.vue 里 `.tiptap` 那套保持同步），让「预览看到的」与「编辑时看到的」
+ * 以及「打印出来的」三者一致。
+ */
+defineOptions({ name: 'G3RichTextPreview' })
+
+const props = defineProps<{
+  /** 受控开合；由 Toolbar 控制，因为按钮在那边 */
+  open: boolean
+  /** 要预览的 HTML（打开时由 Toolbar 取一份快照传入） */
+  html: string
+  /** 打印文档的标题（「另存为 PDF」的默认文件名） */
+  title?: string
+}>()
+
+const emit = defineEmits<{
+  'update:open': [value: boolean]
+  /** 从预览里发起打印 */
+  print: []
+}>()
+
+const { e } = useNamespace('rich-text')
+
+const resolvedTitle = computed(() => props.title ?? '正文预览')
+
+/** 从预览发起打印：直接复用同一份快照，保证「看到的」与「打出来的」一致 */
+function onPrint(): void {
+  printHtml(props.html, resolvedTitle.value)
+  emit('print')
+}
+</script>
+
+<template>
+  <G3Modal
+    :open="open"
+    :title="resolvedTitle"
+    :width="720"
+    :centered="true"
+    :resizable="true"
+    :footer="false"
+    @update:open="(value: boolean) => emit('update:open', value)"
+  >
+    <div :class="e('preview')">
+      <!--
+        预览区：`v-html` 的内容来自编辑器自身产出的 HTML。
+        这里不加 `sandbox`（也不是 iframe）—— 内容是用户在本编辑器里写的，
+        与编辑器内渲染同一份数据，风险面没有扩大。
+      -->
+      <div :class="e('preview-body')" v-html="html" />
+
+      <div :class="e('preview-actions')">
+        <G3Button type="ghost" @click="onPrint">
+          <Printer />
+          <span>打印</span>
+        </G3Button>
+
+        <div :class="e('preview-actions-main')">
+          <G3Button type="primary" @click="emit('update:open', false)">关闭</G3Button>
+        </div>
+      </div>
+    </div>
+  </G3Modal>
+</template>
+
+<style lang="scss">
+@use '@g3soft/tokens/scss' as *;
+
+.#{e('rich-text', 'preview')} {
+  display: flex;
+  flex-direction: column;
+  gap: v('space-2', 8px);
+}
+
+/**
+ * 预览正文区：白底 + 可滚。
+ *
+ * `max-height: 60vh` 与源码框同理 —— 让弹窗在小屏上也不顶出视口。
+ * 内边距给到 16px：预览没有编辑器那圈边框，紧贴边缘会让文字显得被切断。
+ */
+.#{e('rich-text', 'preview-body')} {
+  box-sizing: border-box;
+  max-height: 60vh;
+  padding: v('space-4', 16px);
+  border: 1px solid v('border-color', #d9d9d9);
+  border-radius: v('radius-sm', 4px);
+  background: v('bg-container', #fff);
+  color: v('text-1', rgba(0, 0, 0, 0.88));
+  font-size: v('font-size', 14px);
+  line-height: v('line-height', 1.5);
+  overflow: auto;
+  /* 长 URL / 无空格文本换行，与编辑器内一致 */
+  overflow-wrap: anywhere;
+
+  /**
+   * 以下排版规则与 RichText.vue 里 `.tiptap` 的规则**逐条对应**（标题字号、
+   * 段间距、列表缩进、引用竖线、链接蓝色、表格边框）。
+   *
+   * 两边必须同步：预览的意义就是「所见即所得」，一旦这里与编辑区不一致，
+   * 预览就会撒谎 —— 而这正是用户用来确认「保存后会是什么样」的那一眼。
+   */
+  p {
+    margin: 0 0 0.25em;
+  }
+
+  > :first-child {
+    margin-top: 0;
+  }
+
+  > :last-child {
+    margin-bottom: 0;
+  }
+
+  h1 {
+    font-size: 2em;
+    font-weight: 600;
+    line-height: 1.3;
+    margin: 0.5em 0 0.25em;
+  }
+  h2 {
+    font-size: 1.5em;
+    font-weight: 600;
+    line-height: 1.3;
+    margin: 0.5em 0 0.25em;
+  }
+  h3 {
+    font-size: 1.25em;
+    font-weight: 600;
+    line-height: 1.3;
+    margin: 0.5em 0 0.25em;
+  }
+  h4 {
+    font-size: 1em;
+    font-weight: 600;
+    line-height: 1.3;
+    margin: 0.5em 0 0.25em;
+  }
+  h5 {
+    font-size: 0.875em;
+    font-weight: 600;
+    line-height: 1.3;
+    margin: 0.5em 0 0.25em;
+  }
+  h6 {
+    font-size: 0.85em;
+    font-weight: 600;
+    line-height: 1.3;
+    margin: 0.5em 0 0.25em;
+    color: v('text-2', rgba(0, 0, 0, 0.65));
+  }
+
+  ul,
+  ol {
+    padding-inline-start: 1.5em;
+    margin: 0.25em 0;
+  }
+
+  blockquote {
+    border-inline-start: 2px solid v('color-primary', #18181b);
+    margin: 1em 0;
+    padding-inline-start: 1em;
+    color: v('text-2', rgba(0, 0, 0, 0.65));
+  }
+
+  /* 链接色与编辑器内同一份变量（宿主换链接色时两处一起变） */
+  a {
+    color: v('rich-text-link-color', #1677ff);
+    text-decoration: underline;
+    text-underline-offset: 2px;
+  }
+
+  img,
+  video {
+    max-width: 100%;
+    height: auto;
+    border-radius: v('radius-sm', 4px);
+  }
+
+  table {
+    display: table;
+    width: 100%;
+    margin: 0;
+    border-collapse: collapse;
+    /* 预览不做列宽拖拽，按内容分配更自然（与打印样式一致） */
+    table-layout: auto;
+
+    th,
+    td {
+      border: 1px solid v('border-color', #d9d9d9);
+      padding: v('space-2', 8px);
+      vertical-align: top;
+      /* 单元格里的首尾块去掉外边距，避免行高被撑开 */
+      > * {
+        margin: 0;
+      }
+
+      > * + * {
+        margin-top: 0.5em;
+      }
+    }
+
+    th {
+      background: v('fill', rgba(0, 0, 0, 0.04));
+      font-weight: 500;
+      text-align: start;
+    }
+  }
+
+  hr {
+    border: 0;
+    border-top: 1px solid v('border-color', #d9d9d9);
+    margin: 1em 0;
+  }
+}
+
+.#{e('rich-text', 'preview-actions')} {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: v('space-2', 8px);
+  margin-top: v('space-1', 4px);
+}
+
+.#{e('rich-text', 'preview-actions-main')} {
+  display: flex;
+  gap: v('space-2', 8px);
+  margin-inline-start: auto;
+}
+</style>
diff --git a/code/g3soft-libs/packages/ui/src/rich-text/RichText.vue b/code/g3soft-libs/packages/ui/src/rich-text/RichText.vue
index 98dba6e9..fa74f2fe 100644
--- a/code/g3soft-libs/packages/ui/src/rich-text/RichText.vue
+++ b/code/g3soft-libs/packages/ui/src/rich-text/RichText.vue
@@ -5,8 +5,16 @@ import { columnResizingPluginKey, TableMap } from '@tiptap/pm/tables'
 import type { Node as ProseMirrorNode } from '@tiptap/pm/model'
 import { useLocale } from '../_composables/useLocale'
 import { useNamespace } from '../_composables/useNamespace'
-import { createExtensions, DEFAULT_FONTS, DEFAULT_FONT_SIZES } from './extensions'
-import type { RichTextEmits, RichTextExpose, RichTextProps, RichTextUploadResult } from './types'
+import { createExtensions, DEFAULT_BULLET_LIST_TYPES, DEFAULT_FONTS, DEFAULT_FONT_SIZES, DEFAULT_ORDERED_LIST_TYPES } from './extensions'
+import { cleanupFormat } from './format'
+import type {
+  RichTextCleanupResult,
+  RichTextEmits,
+  RichTextExpose,
+  RichTextProps,
+  RichTextUploadResult,
+} from './types'
+import LinkMenu from './LinkMenu.vue'
 import TableMenu from './TableMenu.vue'
 import Toolbar from './Toolbar.vue'
 import type { UploadHandlers } from './upload'
@@ -33,6 +41,8 @@ const props = withDefaults(defineProps<RichTextProps>(), {
   uploadVideo: undefined,
   fonts: () => DEFAULT_FONTS,
   fontSizes: () => DEFAULT_FONT_SIZES,
+  bulletListTypes: () => DEFAULT_BULLET_LIST_TYPES,
+  orderedListTypes: () => DEFAULT_ORDERED_LIST_TYPES,
 })
 
 const emit = defineEmits<RichTextEmits>()
@@ -42,6 +52,8 @@ const locale = useLocale()
 
 const mergedFonts = computed(() => props.fonts ?? DEFAULT_FONTS)
 const mergedFontSizes = computed(() => props.fontSizes ?? DEFAULT_FONT_SIZES)
+const mergedBulletListTypes = computed(() => props.bulletListTypes ?? DEFAULT_BULLET_LIST_TYPES)
+const mergedOrderedListTypes = computed(() => props.orderedListTypes ?? DEFAULT_ORDERED_LIST_TYPES)
 
 /** 上传回调集：注入 Toolbar / upload 逻辑 */
 const handlers: UploadHandlers = {
@@ -95,9 +107,18 @@ let normalizationScheduled = false
 
 /**
  * 把当前表格所有列的实际渲染宽度写回 colwidth。
+ *
  * @param tablePos table 节点在文档中的内容区起点（绝对位置）
+ * @param fitToContainer 是否把列宽压缩到容器宽度以内
+ *
+ * `fitToContainer` 是这次拆出来的关键开关，两个调用时机需要相反的行为：
+ * - **插入表格**（`true`）：刚生成的表各列宽度是浏览器按内容均分的，列一多就会超出容器。
+ *   这里按比例压回容器宽，保证「插入 10 列也不出横向滚动条」。
+ * - **拖拽列宽结束**（`false`）：用户是**有意**把某列拖宽的，超宽正是他要的结果
+ *   （Excel 语义：表格可变宽，超出部分在 `.tableWrapper` 里横向滚动）。
+ *   此时若也压缩，拖动就会被立刻撤销 —— 表现是「拖了没反应」，拖拽功能直接失效。
  */
-function writeRenderedColumnWidths(tablePos: number): void {
+function writeRenderedColumnWidths(tablePos: number, fitToContainer: boolean): void {
   const instance = editor.value
   if (!instance) return
   const view = instance.view
@@ -119,6 +140,44 @@ function writeRenderedColumnWidths(tablePos: number): void {
     return Math.round(col.getBoundingClientRect().width)
   })
 
+  /**
+   * 归一化：把列宽总和压回容器可用宽度，避免插入多列表格就出现横向滚动条。
+   *
+   * 背景：`table-layout: fixed` 下 `colwidth` 是**硬宽度**，一旦所有列都被写上明确宽度，
+   * 表格总宽就是它们之和 —— 与容器无关。插入 10 列时每列取到的"实测宽度"往往是
+   * `cellMinWidth` 或内容宽，加起来很容易超过内容区，于是 `.tableWrapper` 立刻出横向滚动条。
+   *
+   * 处理原则（仅在 `fitToContainer` 时）：
+   * - **总宽 ≤ 容器**：原样保留（不改动用户设的宽度）；
+   * - **总宽 > 容器**：按比例等比缩小到目标宽度。等比而不是把差额平摊给某一列，
+   *   是为了保持各列原有的宽度比例关系。
+   */
+  const available = tableEl.parentElement?.getBoundingClientRect().width ?? 0
+  const total = widths.reduce((sum, w) => sum + w, 0)
+
+  /**
+   * 预留 1px 余量 —— 这不是拍脑袋的容差，是 `border-collapse: collapse` 的舍入修正。
+   *
+   * 实测（10 列、容器 1060px）：列宽被压到每列 106px、总和精确等于 1060，表格的
+   * 声明宽度也是 `1060px`；但**计算后的宽度是 1061px** —— 折叠边框下浏览器会在
+   * 表格外沿各补半个像素，四舍五入后多出 1px。
+   * 而 `.tableWrapper` 只要 `scrollWidth > clientWidth`（哪怕仅 1px）就出滚动条，
+   * 于是「明明算准了」仍然横滚。
+   *
+   * 所以目标宽度取 `available - 1`：让舍入后的结果恰好落在容器内。
+   */
+  const target = Math.max(1, available - 1)
+  let finalWidths = widths
+  if (fitToContainer && available > 0 && total > target) {
+    const scale = target / total
+    // 逐列取整后再修正尾差，保证总和精确等于目标宽度（否则会差 1~2px 仍触发滚动条）
+    finalWidths = widths.map((w) => Math.max(1, Math.floor(w * scale)))
+    let diff = target - finalWidths.reduce((sum, w) => sum + w, 0)
+    for (let i = 0; diff > 0; i = (i + 1) % finalWidths.length, diff--) {
+      finalWidths[i] += 1
+    }
+  }
+
   const tr = view.state.tr
   for (let row = 0; row < map.height; row++) {
     for (let col = 0; col < map.width; col++) {
@@ -126,7 +185,7 @@ function writeRenderedColumnWidths(tablePos: number): void {
       if (row && cellPos === map.map[(row - 1) * map.width + col]) continue // 跨行合并跳过
       const cellNode = tableNode.nodeAt(cellPos)
       if (!cellNode) continue
-      const colwidth = widths.slice(col, col + cellNode.attrs.colspan)
+      const colwidth = finalWidths.slice(col, col + cellNode.attrs.colspan)
       tr.setNodeMarkup(tablePos + cellPos, null, { ...cellNode.attrs, colwidth })
     }
   }
@@ -170,7 +229,12 @@ function tableNeedsInit(tablePos: number): boolean {
   return true
 }
 
-function scheduleColumnWidthNormalization(): void {
+/**
+ * 调度一次列宽写回。
+ *
+ * @param fitToContainer 见 writeRenderedColumnWidths 的说明：插入时压缩、拖拽时保留
+ */
+function scheduleColumnWidthNormalization(fitToContainer: boolean): void {
   if (normalizationScheduled) return
   normalizationScheduled = true
   // 等 DOM 更新（transaction 已提交、表格按新列宽重排）后再读实际宽度
@@ -183,7 +247,7 @@ function scheduleColumnWidthNormalization(): void {
     const pos = instance.view.state.selection.from
     const tablePos = tablePosAround(pos)
     if (tablePos < 0) return
-    writeRenderedColumnWidths(tablePos)
+    writeRenderedColumnWidths(tablePos, fitToContainer)
   })
 }
 
@@ -197,15 +261,18 @@ function onEditorTransaction(): void {
   wasDragging = dragging
 
   if (justFinished) {
-    scheduleColumnWidthNormalization()
+    // 拖拽结束：**不压缩**。用户是故意把列拖宽的，超宽部分交给 .tableWrapper 横向滚动
+    // （Excel 语义）。这里只把「被拖列的新宽度」固化进 colwidth，让其余列继续保持原宽。
+    scheduleColumnWidthNormalization(false)
     return
   }
 
-  // 插入表格（或粘贴 / setContent 进来的表）尚未归一化：首次进入时给所有列等分固化为 colwidth
+  // 插入表格（或粘贴 / setContent 进来的表）尚未归一化：首次进入时给所有列固化 colwidth。
+  // 这一路要**压缩到容器宽**，否则列一多（如 10 列）就会立即出现横向滚动条。
   const pos = instance.view.state.selection.from
   const tablePos = tablePosAround(pos)
   if (tablePos >= 0 && tableNeedsInit(tablePos)) {
-    scheduleColumnWidthNormalization()
+    scheduleColumnWidthNormalization(true)
   }
 }
 
@@ -284,12 +351,57 @@ function clear(): void {
   editor.value?.commands.clearContent()
 }
 
+/**
+ * 整理格式：清理空段落 / 空白文本 / 空 mark。
+ *
+ * 逻辑本身在 `format.ts`，工具条那边也有一份入口（「更多」菜单里的「整理格式」）。
+ * 这里再透出一份，是为了让宿主能在**保存前**主动规整一遍（比如提交表单时顺手清理），
+ * 而不必去操作工具条的内部实例。
+ *
+ * 返回清理统计，宿主可据此决定是否提示用户（`changed: false` = 本来就很干净）。
+ */
+function tidyFormat(): RichTextCleanupResult {
+  const instance = editor.value
+  if (!instance || instance.isDestroyed) {
+    return { removedEmptyParagraphs: 0, trimmedBlankTexts: 0, removedEmptyMarks: 0, changed: false }
+  }
+  const result = cleanupFormat(instance)
+  emit('cleanup', result)
+  return result
+}
+
+/* ---------- 工具条透传（预览 / 打印 / 源代码）---------- */
+/**
+ * 这三个能力的对话框与状态都在工具条内部（按钮在那边），RichText 只做透传。
+ * 工具条未渲染时（`toolbar: false`）这些方法安全地什么都不做 ——
+ * 宿主要用它们就必须显示工具条，这是「对话框寄居在工具条里」的自然结果。
+ */
+function openSourceCode(): void {
+  toolbarRef.value?.openSourceCode()
+}
+function openPreviewDialog(): void {
+  toolbarRef.value?.openPreview()
+}
+function printContent(): void {
+  toolbarRef.value?.print()
+  emit('print')
+}
+
+/** 工具条在「源代码」对话框保存后回传 HTML（透传成事件给宿主） */
+function onSourceSave(html: string): void {
+  emit('source-save', html)
+}
+
 defineExpose<RichTextExpose>({
   editor: editor as unknown as RichTextExpose['editor'],
   getHTML,
   getText,
   focus,
   clear,
+  openSourceCode,
+  openPreview: openPreviewDialog,
+  print: printContent,
+  tidyFormat,
 })
 
 const classes = computed(() => [
@@ -303,6 +415,27 @@ const classes = computed(() => [
 
 const showToolbar = computed(() => props.toolbar !== false && !!editor.value)
 
+/**
+ * 工具条实例引用 —— 链接右键菜单的「编辑链接」要唤起工具条里的链接面板。
+ *
+ * 面板状态（URL / 文字 / 开合）都在 Toolbar 内部，这里只拿一个「打开并预填」的入口，
+ * 不把这些状态提到 RichText 层（它们与工具条内的校验、按钮耦合很紧，提上去会散）。
+ *
+ * 预览 / 源代码 / 打印 / 整理格式同样如此：对话框与状态都在工具条里，
+ * 这里只透传方法入口。
+ */
+const toolbarRef = ref<{
+  openLinkEditor: (href: string, text: string) => void
+  openSourceCode: () => void
+  openPreview: () => void
+  print: () => void
+  tidyFormat: () => void
+} | null>(null)
+
+function onLinkMenuEdit(href: string, text: string): void {
+  toolbarRef.value?.openLinkEditor(href, text)
+}
+
 const contentStyle = computed(() => ({
   minHeight: typeof props.minHeight === 'number' ? `${props.minHeight}px` : props.minHeight,
   maxHeight: props.maxHeight
@@ -318,11 +451,15 @@ const contentStyle = computed(() => ({
     <!-- 工具条：上 / 下 -->
     <Toolbar
       v-if="showToolbar && toolbar === 'top'"
+      ref="toolbarRef"
       :editor="editor!"
       :fonts="mergedFonts"
       :font-sizes="mergedFontSizes"
+      :bullet-list-types="mergedBulletListTypes"
+      :ordered-list-types="mergedOrderedListTypes"
       :handlers="handlers"
       placement="top"
+      @source-save="onSourceSave"
     />
 
     <div :class="e('content')" :style="contentStyle" @mousedown="onContentMousedown">
@@ -333,13 +470,20 @@ const contentStyle = computed(() => ({
 
     <TableMenu :editor="editor" />
 
+    <!-- 链接右键菜单：在正文的 <a> 上右键时弹出「编辑 / 打开 / 删除」 -->
+    <LinkMenu :editor="editor" :on-edit="onLinkMenuEdit" />
+
     <Toolbar
       v-if="showToolbar && toolbar === 'bottom'"
+      ref="toolbarRef"
       :editor="editor!"
       :fonts="mergedFonts"
       :font-sizes="mergedFontSizes"
+      :bullet-list-types="mergedBulletListTypes"
+      :ordered-list-types="mergedOrderedListTypes"
       :handlers="handlers"
       placement="bottom"
+      @source-save="onSourceSave"
     />
   </div>
 </template>
@@ -358,6 +502,15 @@ const contentStyle = computed(() => ({
   font-size: v('font-size', 14px);
   line-height: v('line-height', 1.5);
 
+  /**
+   * 链接色（标准蓝，不跟主题色，理由见下方 `.tiptap a` 的注释）。
+   *
+   * 挂在容器上供宿主覆盖：`.g3-rich-text { --g3-rich-text-link-color: #0958d9; }`。
+   * 只作用于**编辑器内**的链接 —— 输出到邮件 / 公告里的颜色由宿主自己的渲染样式决定。
+   */
+  #{css-var('rich-text-link-color')}: #1677ff;
+  #{css-var('rich-text-link-hover-color')}: #4096ff;
+
   &.#{m('rich-text', 'disabled')} {
     background: v('bg-disabled', rgba(0, 0, 0, 0.04));
     color: v('text-disabled', rgba(0, 0, 0, 0.25));
@@ -418,8 +571,25 @@ const contentStyle = computed(() => ({
        既避免正文被撑出横向滚动，也避免表格列被长内容撑宽（auto 布局按内容最小宽度分配） */
     overflow-wrap: anywhere;
 
+    /**
+     * 块间距。
+     *
+     * 用 `0.25em`（14px 正文下约 3.5px）而不是原来的 `0.75em`：
+     * 段间距是**叠加在行高之上**的 —— 行高 1.5 已经给了每行之间 0.5 行（约 7px）的
+     * 视觉呼吸，再叠 0.75em（≈10.5px）的全高间距，两段正文之间就空出了近 18px，
+     * 看着比正常段落间距大一倍，回车换行时尤其明显。
+     *
+     * 这里刻意**不用 UA 默认的 `margin: 1em`**：那个在中文正文里更夸张（14px 全高）。
+     * 0.25em 是「能分辨出是两个段落、又不显得断开」的量。
+     */
     > * + * {
-      margin-top: 0.75em;
+      margin-top: 0.25em;
+    }
+
+    /* 段落自身的 UA 上下外边距（各 1em）要归零，否则会与本条规则叠加。
+       Tiptap 的段落是 <p>，不归零的话真实段间距 = 1em + 0.25em。 */
+    p {
+      margin: 0;
     }
 
     /* 首 / 末块去掉外边距，避免与容器内边距叠加，顶部（底部）间距统一为内边距值 */
@@ -436,7 +606,15 @@ const contentStyle = computed(() => ({
       cursor: col-resize;
     }
 
-    /* 基础排版，让编辑器输出与渲染一致 */
+    /**
+     * 基础排版，让编辑器输出与渲染一致。
+     *
+     * ⚠️ 这六个级别的 font-size / font-weight 必须与 Toolbar 里 `headingLevels` 的
+     * 预览值保持一致 —— 下拉面板是按那份数据画出「每一级长什么样」的，两边不一致
+     * 会让预览撒谎（选了菜单里显示很大的标题、落到正文里却变小）。
+     *
+     * H1 的 2em 等相对值基于容器 14px 字号，实际约 28 / 21 / 17.5 / 14 / 12.25 / 11.9px。
+     */
     h1 {
       font-size: 2em;
       font-weight: 600;
@@ -452,6 +630,23 @@ const contentStyle = computed(() => ({
       font-weight: 600;
       line-height: 1.3;
     }
+    h4 {
+      font-size: 1em;
+      font-weight: 600;
+      line-height: 1.3;
+    }
+    h5 {
+      font-size: 0.875em;
+      font-weight: 600;
+      line-height: 1.3;
+    }
+    h6 {
+      font-size: 0.85em;
+      font-weight: 600;
+      line-height: 1.3;
+      /* H6 与正文（14px）只差一点点，靠颜色区分层级 —— 否则和正文段落几乎一样 */
+      color: v('text-2', rgba(0, 0, 0, 0.65));
+    }
 
     ul,
     ol {
@@ -465,9 +660,26 @@ const contentStyle = computed(() => ({
       color: v('text-2', rgba(0, 0, 0, 0.65));
     }
 
+    /**
+     * 链接：标准蓝 + 下划线，**不跟主题色**。
+     *
+     * 主题色在 G3 体系里是近黑色（`--g3-color-primary: #18181b`），拿它当链接色会让
+     * 链接与正文「长得一模一样」，只剩一条下划线可辨 —— 而这恰恰是链接最需要的信号。
+     * 蓝色是链接的通用语汇（浏览器默认、Word / Google Docs / 各 CMS 一致），
+     * 用户扫一眼就知道可点，不必依赖下划线。
+     *
+     * 走独立的 CSS 变量而不是写死蓝色：宿主想换品牌链接色直接覆盖，
+     * 不必碰组件代码（与色板变量同一套思路）。
+     */
     a {
-      color: v('color-primary', #18181b);
+      color: v('rich-text-link-color', #1677ff);
       text-decoration: underline;
+      text-underline-offset: 2px;
+      cursor: pointer;
+
+      &:hover {
+        color: v('rich-text-link-hover-color', #4096ff);
+      }
     }
 
     img {
@@ -489,9 +701,10 @@ const contentStyle = computed(() => ({
       }
     }
 
-    /* 可拖拽表格的 <table> 被 Tiptap 包在 .tableWrapper 里：
-       列数极多、各列最小宽度之和超过容器时，让它在这一层横向滚动，
-       避免把横向滚动条带进编辑器内容区 */
+    /* 可拖拽表格的 <table> 被 Tiptap 包在 .tableWrapper 里。
+       这一层保留横向滚动只作为**兜底**：正常情况下列宽由下面的归一化逻辑
+       （writeRenderedColumnWidths 等比压缩到容器宽）保证总宽不超容器，
+       所以插入表格不会出现滚动条；只有用户手动把某列拖得特别宽时才需要在这里滚。 */
     .tableWrapper {
       max-width: 100%;
       overflow-x: auto;
@@ -507,7 +720,6 @@ const contentStyle = computed(() => ({
          这样拖宽某列后表格总宽超过容器时，会在这层（而非内容区）横向滚动，
          也就是 Excel 式「拖列宽只动相邻列、表格可变宽」的语义。 */
       width: 100%;
-      min-width: 0;
       margin: 0;
       border-collapse: collapse;
       /* 用 fixed 而非 auto：fixed 布局下列宽由 <col> 的宽度硬性决定，不受单元格内容影响。
diff --git a/code/g3soft-libs/packages/ui/src/rich-text/SourceCodeDialog.vue b/code/g3soft-libs/packages/ui/src/rich-text/SourceCodeDialog.vue
new file mode 100644
index 00000000..821b429a
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/rich-text/SourceCodeDialog.vue
@@ -0,0 +1,263 @@
+<script setup lang="ts">
+import { computed, nextTick, ref, watch } from 'vue'
+import type { Editor } from '@tiptap/vue-3'
+import { G3Button } from '../button'
+import { G3Modal } from '../modal'
+import { useNamespace } from '../_composables/useNamespace'
+
+/**
+ * 源代码编辑对话框（对齐 TinyMCE 的 `code` 插件 / 「源代码」按钮）。
+ *
+ * ## 为什么是模态框而不是「整块编辑区变 textarea」
+ *
+ * TinyMCE 的 code 插件就是一个对话框：左边（或整块）是 HTML 源码，点「保存」写回。
+ * 相比内联切换，模态框有三个实际好处：
+ * - **不会毁掉视图状态**：内联切换要把 `.tiptap` 换成 textarea，会话期间的滚动位置、
+ *   选区、表格浮层全都要保存与恢复，而对话框只是叠在上面；
+ * - **保存是显式的**：需求明确要「允许保存」—— 对话框的「保存」按钮是唯一写回点，
+ *   用户改到一半反悔可以直接关掉（内联切换没有「取消」的自然表达）；
+ * - **可测**：对话框有稳定的 DOM 边界（`.g3-modal`），E2E 能断言「打开 → 改 → 保存 → 正文变了」。
+ *
+ * ## 校验：不合法时不允许保存
+ *
+ * 用户手改 HTML 很容易写出不闭合的标签。这里不自己写 HTML 校验器（正则校验 HTML
+ * 是出了名的不可靠），而是**让浏览器与 ProseMirror 自己判断**：
+ * 用 `DOMParser` 解析一次，若能解析出 `body` 就认为结构可接受；真正的「能不能进编辑器」
+ * 由 Tiptap 的 `setContent` 决定 —— 它会用 schema 过滤掉不认识的标签（这正是我们要的
+ * 「清洗」行为，而不是把整段源码原样塞进去）。
+ *
+ * 因此**只拦「明显解析失败」的情况**（`DOMParser` 抛错），其余交给 schema 过滤，
+ * 并在界面上如实告知「不认识的标签会被过滤」—— 比假装能完整往返更诚实。
+ */
+defineOptions({ name: 'G3RichTextSourceCode' })
+
+const props = defineProps<{
+  /** 受控开合；由 Toolbar 控制，因为按钮在那边 */
+  open: boolean
+  /** 编辑器实例；用于读写当前 HTML */
+  editor: Editor
+}>()
+
+const emit = defineEmits<{
+  'update:open': [value: boolean]
+  /** 保存成功（已写回编辑器）；供外层做埋点 / 提示 */
+  save: [html: string]
+}>()
+
+const { e } = useNamespace('rich-text')
+
+/** 对话框里的源码草稿 —— 只有点「保存」才写回编辑器 */
+const draft = ref('')
+
+/** 校验错误文案（空串 = 无错误） */
+const error = ref('')
+
+/** 保存后是否与原始内容完全一致（用于「没有改动」提示，不算错误） */
+const unchanged = computed(() => draft.value === (props.editor?.getHTML() ?? ''))
+
+const textareaRef = ref<HTMLTextAreaElement | null>(null)
+
+/**
+ * 每次**打开**时用编辑器当前 HTML 重置草稿。
+ *
+ * 依赖 `props.open` 而不是 `props.editor.getHTML()`：编辑器内容在对话框打开期间
+ * 也可能变化（比如外部 v-model 回写），若跟着同步，用户正在改的草稿会被覆盖掉。
+ * 「打开那一刻取一次快照」是对话框的标准语义。
+ */
+watch(
+  () => props.open,
+  async (open) => {
+    if (!open) return
+    draft.value = props.editor?.getHTML() ?? ''
+    error.value = ''
+    // 等对话框挂载/渲染完再聚焦，否则 textarea 还不存在
+    await nextTick()
+    textareaRef.value?.focus()
+  },
+  { immediate: true },
+)
+
+/**
+ * 校验草稿是否是「结构可接受」的 HTML。
+ *
+ * 用 `DOMParser` 而不是正则：它能暴露真正的解析失败，且对 HTML 的容错行为与浏览器一致。
+ * 注意 **HTML 解析本身极其宽容** —— `<p><div>` 这种也会被解析成功（浏览器会隐式闭合），
+ * 所以这个函数拦得住的是「彻底坏掉」的输入，而不是所有不规范的写法。
+ * 不规范的写法交给 Tiptap 的 schema 过滤，界面上已说明这一点。
+ */
+function validate(html: string): string {
+  if (!html.trim()) return '' // 空内容合法（等于清空正文）
+  if (typeof DOMParser === 'undefined') return '' // 非浏览器环境不做校验
+  try {
+    const parsed = new DOMParser().parseFromString(html, 'text/html')
+    if (!parsed.body) return '无法解析这段 HTML'
+    return ''
+  } catch {
+    return 'HTML 解析失败，请检查标签是否闭合'
+  }
+}
+
+/** 保存：校验通过才写回编辑器 */
+function onSave(): void {
+  const message = validate(draft.value)
+  error.value = message
+  if (message) return
+
+  const instance = props.editor
+  if (!instance || instance.isDestroyed) return
+
+  /**
+   * 写回用 `setContent`，并**把这次改动标成一次可撤销的操作**。
+   *
+   * `emitUpdate: true`（默认）是必须的：Toolbar 之外还有 `v-model` —— 不触发 update
+   * 的话外层拿到的 HTML 仍是旧值，「保存」看起来成功了、实际宿主表单里没变。
+   *
+   * 之所以能保持「一次撤销」：`setContent` 生成的是**一个**事务，Tiptap 的 history
+   * 把它当作一步，用户按一次 Ctrl+Z 就能退回改源码之前。
+   */
+  instance.commands.setContent(draft.value, { emitUpdate: true })
+  emit('save', instance.getHTML())
+  emit('update:open', false)
+}
+
+/** 关闭（不写回） */
+function onClose(): void {
+  emit('update:open', false)
+}
+
+/** 恢复为打开对话框时的内容（撤销草稿里的所有修改） */
+function onReset(): void {
+  draft.value = props.editor?.getHTML() ?? ''
+  error.value = ''
+}
+</script>
+
+<template>
+  <G3Modal
+    :open="open"
+    title="源代码"
+    :width="720"
+    :centered="true"
+    :resizable="true"
+    :footer="false"
+    @update:open="(value: boolean) => emit('update:open', value)"
+  >
+    <div :class="e('source-code')">
+      <!--
+        用原生 textarea 而不是 G3Input：源码编辑需要**多行 + 等宽字体 + 大块高度**，
+        G3Input 是单行文本控件（textarea 形态的高度、字体、滚动都要另写一套样式）。
+        这里直接给一套「代码框」外观，与库内控件不冲突（它不是表单字段）。
+      -->
+      <textarea
+        ref="textareaRef"
+        v-model="draft"
+        :class="e('source-code-textarea')"
+        spellcheck="false"
+        autocomplete="off"
+        aria-label="HTML 源代码"
+        :aria-invalid="error ? 'true' : undefined"
+        @keydown.esc.prevent="onClose"
+      />
+
+      <!-- 校验错误：用 role=alert 让读屏用户也能感知（不是纯视觉提示） -->
+      <p v-if="error" :class="e('source-code-error')" role="alert">{{ error }}</p>
+
+      <p v-else :class="e('source-code-hint')">
+        不认识的标签与属性会被编辑器过滤掉 —— 保存后请确认正文符合预期。
+      </p>
+
+      <div :class="e('source-code-actions')">
+        <!-- 左侧「重置」是次要操作，与右侧的「取消 / 保存」拉开距离 -->
+        <G3Button type="ghost" :disabled="unchanged" @click="onReset">重置</G3Button>
+
+        <div :class="e('source-code-actions-main')">
+          <G3Button type="ghost" @click="onClose">取消</G3Button>
+          <G3Button type="primary" @click="onSave">保存</G3Button>
+        </div>
+      </div>
+    </div>
+  </G3Modal>
+</template>
+
+<style lang="scss">
+@use '@g3soft/tokens/scss' as *;
+
+.#{e('rich-text', 'source-code')} {
+  display: flex;
+  flex-direction: column;
+  gap: v('space-2', 8px);
+}
+
+/**
+ * 代码框：等宽字体 + 固定高度 + 纵向可滚。
+ *
+ * 高度取 46vh（而不是固定 px）：源码可能很长，固定高度在小屏上会顶出视口；
+ * 46vh + 弹窗的上下留白，在常见屏幕上都能露出下方按钮区（按钮区本来在
+ * Modal 的 footer 位置，这里为了与「取消 / 保存」成组放在了内容里）。
+ */
+.#{e('rich-text', 'source-code-textarea')} {
+  box-sizing: border-box;
+  width: 100%;
+  min-height: 240px;
+  max-height: 46vh;
+  padding: v('space-2', 8px) v('space-3', 12px);
+  border: 1px solid v('border-color', #d9d9d9);
+  border-radius: v('radius-sm', 4px);
+  background: v('bg-container', #fff);
+  color: v('text-1', rgba(0, 0, 0, 0.88));
+  /**
+   * 等宽字体栈：源码对齐全靠等宽，缺了它 HTML 的缩进层级完全看不出来。
+   * 前三项覆盖 Win / macOS / Linux 的常见等宽字体，最后兜底到 monospace。
+   */
+  font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, 'Courier New', monospace;
+  font-size: v('font-size-sm', 12px);
+  line-height: 1.6;
+  /* 缩进按制表符存、按 2 空格显示，避免 Tab 与 Space 混用后对齐错乱 */
+  tab-size: 2;
+  resize: vertical;
+  outline: none;
+  transition: border-color v('duration', 0.2s) v('ease', ease);
+
+  &:focus {
+    border-color: v('color-primary', #18181b);
+  }
+
+  /* 长行不折行：源码折行会让缩进层级彻底看不出来，改为横向滚动 */
+  white-space: pre;
+  overflow: auto;
+
+  &[aria-invalid='true'] {
+    border-color: v('color-danger', #ec4246);
+  }
+}
+
+.#{e('rich-text', 'source-code-hint')},
+.#{e('rich-text', 'source-code-error')} {
+  margin: 0;
+  font-size: v('font-size-sm', 12px);
+  line-height: 1.5;
+}
+
+.#{e('rich-text', 'source-code-hint')} {
+  color: v('text-2', rgba(0, 0, 0, 0.65));
+}
+
+.#{e('rich-text', 'source-code-error')} {
+  color: v('color-danger', #ec4246);
+}
+
+/* 操作区：左「重置」、右「取消 / 保存」，与链接面板同一套语义 */
+.#{e('rich-text', 'source-code-actions')} {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: v('space-2', 8px);
+  margin-top: v('space-1', 4px);
+}
+
+.#{e('rich-text', 'source-code-actions-main')} {
+  display: flex;
+  gap: v('space-2', 8px);
+  margin-inline-start: auto;
+}
+</style>
diff --git a/code/g3soft-libs/packages/ui/src/rich-text/TableMenu.vue b/code/g3soft-libs/packages/ui/src/rich-text/TableMenu.vue
index dec5504c..27e36861 100644
--- a/code/g3soft-libs/packages/ui/src/rich-text/TableMenu.vue
+++ b/code/g3soft-libs/packages/ui/src/rich-text/TableMenu.vue
@@ -6,10 +6,8 @@ import {
   ArrowLeftToLine,
   ArrowRightToLine,
   ArrowUpToLine,
-  BetweenHorizontalStart,
   TableCellsMerge,
   TableCellsSplit,
-  TableProperties,
   Trash2,
 } from '@lucide/vue'
 import { G3Button } from '../button'
@@ -24,7 +22,7 @@ import { useNamespace } from '../_composables/useNamespace'
  * 编辑表格时突然变长、跳动。定位靠表格 DOM 的 getBoundingClientRect 计算，
  * 操作栏 fixed 定位于表格正下方（用 rAF 对齐渲染帧，避免读到未更新的布局）。
  *
- * 只放结构操作：行 / 列增删、单元格合并与拆分、表头列 / 表头单元格、删表。
+ * 只放结构操作：行 / 列增删、单元格合并与拆分、表头单元格、删表。
  * 文字与单元格对齐交给顶部工具条（单元格内容同样是 paragraph，对齐走 textAlign）。
  */
 defineOptions({ name: 'G3RichTextTableMenu' })
@@ -143,20 +141,16 @@ const actionGroups: TableAction[][] = [
       disabled: () => !props.editor?.can().splitCell(),
     },
   ],
-  [
-    {
-      label: '切换表头列',
-      icon: BetweenHorizontalStart,
-      action: () => editor().chain().focus().toggleHeaderColumn().run(),
-      disabled: () => !props.editor?.can().toggleHeaderColumn(),
-    },
-    {
-      label: '切换表头单元格',
-      icon: TableProperties,
-      action: () => editor().chain().focus().toggleHeaderCell().run(),
-      disabled: () => !props.editor?.can().toggleHeaderCell(),
-    },
-  ],
+  /**
+   * 原「表头」组（切换表头列 / 切换表头单元格）整组移除。
+   *
+   * 两个按钮都撤掉：
+   * - 「切换表头列」把整列变成 `<th>`，与「表头单元格」在观感上高度重叠，
+   *   用户难以分辨「这一格是表头」和「这一列都是表头」；
+   * - 「切换表头单元格」虽然语义清晰，但 ERP 场景里插入的表格默认就带表头行
+   *   （网格选择器里的「包含表头行」勾选），事后逐格调整表头的需求极低。
+   * 少一组易混淆的操作，浮层更短、也更贴近「增删行列 + 合并拆分」这几个高频动作。
+   */
   [
     {
       label: '删除表格',
diff --git a/code/g3soft-libs/packages/ui/src/rich-text/Toolbar.vue b/code/g3soft-libs/packages/ui/src/rich-text/Toolbar.vue
index db8cde56..c97425fa 100644
--- a/code/g3soft-libs/packages/ui/src/rich-text/Toolbar.vue
+++ b/code/g3soft-libs/packages/ui/src/rich-text/Toolbar.vue
@@ -1,15 +1,19 @@
 <script setup lang="ts">
-import { computed, ref } from 'vue'
+import { computed, onMounted, ref, watch } from 'vue'
 import type { Editor } from '@tiptap/vue-3'
+import { TextSelection } from '@tiptap/pm/state'
 import {
   AlignCenter,
   AlignLeft,
   AlignRight,
   Baseline,
   Bold,
+  Check,
   ChevronDown,
+  CodeXml,
   Ellipsis,
   Eraser,
+  Eye,
   Highlighter,
   Image,
   Italic,
@@ -17,6 +21,7 @@ import {
   List,
   ListOrdered,
   Palette,
+  Printer,
   Quote,
   Redo2,
   Strikethrough,
@@ -26,20 +31,35 @@ import {
   Underline,
   Undo2,
   Video,
+  WandSparkles,
 } from '@lucide/vue'
 import { G3Button } from '../button'
+import { G3ButtonGroup } from '../button-group'
 import { G3Checkbox } from '../checkbox'
 import { G3Dropdown, type DropdownItemData } from '../dropdown'
+import { G3Input } from '../input'
 import { G3Popover } from '../popover'
 import { G3Tooltip } from '../tooltip'
 import { useNamespace } from '../_composables/useNamespace'
+import { useDirection } from '../_composables/useDirection'
+import { horizontalArrowStep } from '../_utils/direction'
 import {
-  DEFAULT_BACKGROUND_COLORS,
+  BACKGROUND_COLOR_VARS,
+  DEFAULT_BACKGROUND_COLOR_VALUES,
+  DEFAULT_BULLET_LIST_TYPES,
   DEFAULT_FONTS,
   DEFAULT_FONT_SIZES,
-  DEFAULT_TEXT_COLORS,
+  DEFAULT_ORDERED_LIST_TYPES,
+  DEFAULT_TEXT_COLOR_VALUES,
+  TEXT_COLOR_VARS,
 } from './extensions'
+import { cleanupFormat } from './format'
+import { printHtml } from './print'
+import type { RichTextListTypeOption } from './types'
 import { insertImage, insertVideo, type UploadHandlers } from './upload'
+import ListTypeIcon from './ListTypeIcon.vue'
+import PreviewDialog from './PreviewDialog.vue'
+import SourceCodeDialog from './SourceCodeDialog.vue'
 
 defineOptions({ name: 'G3RichTextToolbar' })
 
@@ -48,30 +68,54 @@ const props = withDefaults(
     editor: Editor
     fonts?: { label: string; value: string }[]
     fontSizes?: { label: string; value: string }[]
+    /** 无序列表的项目符号样式选项 */
+    bulletListTypes?: RichTextListTypeOption[]
+    /** 有序列表的编号样式选项 */
+    orderedListTypes?: RichTextListTypeOption[]
     handlers: UploadHandlers
     placement?: 'top' | 'bottom'
   }>(),
   {
     fonts: () => DEFAULT_FONTS,
     fontSizes: () => DEFAULT_FONT_SIZES,
+    bulletListTypes: () => DEFAULT_BULLET_LIST_TYPES,
+    orderedListTypes: () => DEFAULT_ORDERED_LIST_TYPES,
     placement: 'top',
   },
 )
 
-const { e, em, is } = useNamespace('rich-text')
+const emit = defineEmits<{
+  /** 「源代码」对话框保存并写回后回传 HTML（RichText 再透传给宿主） */
+  'source-save': [html: string]
+}>()
 
-/* ---------- 标题（正文 / H1 / H2 / H3）---------- */
+const { e, em, is, cssVar } = useNamespace('rich-text')
+
+/* ---------- 标题（正文 / H1 - H6）---------- */
+/**
+ * 段落格式的候选项。
+ *
+ * 带上 `tag` / `fontSize` / `fontWeight` 是为了让下拉面板**把每一级的真实样式画出来**：
+ * 只写「标题 1 / 标题 2」这类文字，用户得凭经验猜哪一级更大；直接按级别的字号与字重
+ * 渲染菜单项，选择就变成「看起来像我要的那级」而不是「记住它是几号」。
+ * 这三个值必须与 `RichText.vue` 里 `.tiptap h1/h2/h3` 的排版规则一致，否则预览会撒谎。
+ */
 const headingLevels = [
-  { key: 'paragraph', label: '正文', level: null as null },
-  { key: 'h1', label: '标题 1', level: 1 as const },
-  { key: 'h2', label: '标题 2', level: 2 as const },
-  { key: 'h3', label: '标题 3', level: 3 as const },
-]
+  { key: 'paragraph', label: '正文', level: null, tag: 'p', fontSize: '14px', fontWeight: '400' },
+  { key: 'h1', label: '标题 1', level: 1, tag: 'h1', fontSize: '2em', fontWeight: '600' },
+  { key: 'h2', label: '标题 2', level: 2, tag: 'h2', fontSize: '1.5em', fontWeight: '600' },
+  { key: 'h3', label: '标题 3', level: 3, tag: 'h3', fontSize: '1.25em', fontWeight: '600' },
+  { key: 'h4', label: '标题 4', level: 4, tag: 'h4', fontSize: '1em', fontWeight: '600' },
+  { key: 'h5', label: '标题 5', level: 5, tag: 'h5', fontSize: '0.875em', fontWeight: '600' },
+  { key: 'h6', label: '标题 6', level: 6, tag: 'h6', fontSize: '0.85em', fontWeight: '600' },
+] as const
+
+type HeadingLevel = (typeof headingLevels)[number]
 
 const currentHeading = computed(() => {
-  if (props.editor.isActive('heading', { level: 1 })) return 'h1'
-  if (props.editor.isActive('heading', { level: 2 })) return 'h2'
-  if (props.editor.isActive('heading', { level: 3 })) return 'h3'
+  for (const level of [1, 2, 3, 4, 5, 6] as const) {
+    if (props.editor.isActive('heading', { level })) return `h${level}`
+  }
   return 'paragraph'
 })
 
@@ -79,18 +123,10 @@ const currentHeadingLabel = computed(
   () => headingLevels.find((h) => h.key === currentHeading.value)?.label ?? '正文',
 )
 
-const headingItems = computed(() =>
-  headingLevels.map((h) => ({
-    key: h.key,
-    label: h.label,
-    onClick: () => setHeading(h),
-  })),
-)
-
-function setHeading(h: { key: string; level: 1 | 2 | 3 | null }) {
+function setHeading(h: HeadingLevel) {
   const chain = props.editor.chain().focus()
   if (h.level === null) chain.setParagraph()
-  else chain.setHeading({ level: h.level })
+  else chain.setHeading({ level: h.level as 1 | 2 | 3 | 4 | 5 | 6 })
   chain.run()
 }
 
@@ -122,42 +158,347 @@ const fontSizeItems = computed<DropdownItemData[]>(() =>
 )
 
 /* ---------- 链接 ---------- */
-function toggleLink() {
-  if (props.editor.isActive('link')) {
-    props.editor.chain().focus().unsetLink().run()
+/**
+ * 链接面板：点击「链接」按钮弹出，填地址（与显示文字）后回车或点「确定」写入选区。
+ *
+ * 为什么不再用 `window.prompt`：
+ * - 观感割裂 —— 全库其它弹层都走 G3Popover / G3Dropdown，只有链接插入弹一个原生窗口；
+ * - 无法校验 —— prompt 返回什么就写什么，`javascript:` 之类也会被塞进 href；
+ * - 会被环境拦截 —— 嵌入式 WebView / iframe 里 prompt 常被禁用，点按钮毫无反应；
+ * - 不可测 —— E2E 无法对原生弹窗断言（Playwright 虽能监听 dialog，但那是绕过而非验证 UI）。
+ *
+ * 两个输入框：
+ * - **地址**（必填）：写进 `href`；
+ * - **显示文字**（可选）：选区为空时用它作为链接文字插入（等价于先打字再选中）；
+ *   选区非空时把它当作「替换选区文字」——即同时改 href 与文本。
+ */
+const linkOpen = ref(false)
+const linkUrl = ref('')
+
+/** 显示文字：空选区时作为链接文字插入；非空时替换选中文字（留空则保持原文字） */
+const linkText = ref('')
+
+/** 打开面板时选区是否非空 */
+const linkHasSelection = ref(false)
+
+/** 光标已在某个链接上（面板切成「编辑 / 移除」） */
+const linkEditing = ref(false)
+
+/**
+ * 准备链接面板状态，并可带入外部指定的链接（右键菜单的「编辑链接」用）。
+ *
+ * ⚠️ **不写 `linkOpen`** —— 开合由 `v-model:open` / `@update:open` 单一驱动。
+ * 面板的触发器包在 Popover 的 `<span @click="toggle()">` 里，处理器里再置一次 open
+ * 会被随后的 toggle 翻转回去，导致面板打不开（表格面板踩过同一个坑，见 resetTableGrid）。
+ *
+ * 不带参数时走「读当前光标所在链接」的常规路径；带参数（右键菜单唤起）时用传入的
+ * href / text 覆盖 —— 右键的落点不一定是当前光标位置，以它为准才符合「点哪条编哪条」。
+ */
+function openLinkPanel(preset?: { href?: string; text?: string }): void {
+  const instance = props.editor
+
+  if (preset) {
+    linkEditing.value = !!preset.href
+    linkUrl.value = preset.href ?? ''
+    linkText.value = preset.text ?? ''
+    linkHasSelection.value = false
     return
   }
-  const url = window.prompt('请输入链接地址')
-  if (url) props.editor.chain().focus().setLink({ href: url }).run()
+
+  // 已在链接上：面板变成「编辑 / 移除」
+  const existing = instance.getAttributes('link').href as string | undefined
+  linkEditing.value = !!existing
+  linkUrl.value = existing ?? ''
+
+  // 选区状态决定「显示文字」的预填方式
+  const { from, to } = instance.state.selection
+  linkHasSelection.value = from !== to
+
+  if (linkHasSelection.value) {
+    // 有选中文字：预填它，让「替换文字」有个可见的起点而不是空框
+    linkText.value = instance.state.doc.textBetween(from, to)
+  } else if (existing) {
+    // 光标在链接内但没选中（最常见：点进链接再点工具条按钮）：
+    // 预填该链接自身的文字，否则框是空的、看不出「当前链接文字是什么」。
+    // 用 extendMarkRange 的等价手段算出链接 mark 的真实范围 —— 直接读段落会把
+    // 链接之外的文本也带进来。这里手动向两侧扫同 mark 的文本节点。
+    linkText.value = linkTextAtCursor(instance)
+  } else {
+    linkText.value = ''
+  }
 }
 
-/* ---------- 表格（弹窗选行列）---------- */
+/**
+ * 取「光标所在链接」的完整文字。
+ *
+ * Tiptap 有 `extendMarkRange('link')` 命令能直接给出这个范围，但它会**改动编辑器选区** ——
+ * 面板只是打开一下就想知道文字，不该有副作用（用户取消时选区已经变了）。所以这里只读地扫。
+ *
+ * ⚠️ 扫描必须基于**文本节点自身携带的 marks**，不能用 `doc.resolve(pos).marks()`：
+ * 后者在位置边界上返回的是「该位置**之后**」的 marks，于是每走一步都会在
+ * 字符边界处断掉 —— 实测表现为只取到第一个字符（「点我」只拿到「点」）。
+ * 那会让后续 `applyLink` 误判「文字变了」而插入这段残缺文字，
+ * 把一个链接**拆成三段**（`点` / `点我` / `我` 各成一个 `<a>`）。
+ *
+ * 正确做法是遍历段落里的**文本节点**、按节点自带的 marks 拼接范围。
+ */
+function linkTextAtCursor(instance: Editor): string {
+  const { state } = instance
+  const { $from } = state.selection
+  const linkType = state.schema.marks.link
+  if (!linkType) return ''
+
+  // 光标所在文本节点上是否带 link mark
+  const hasLink = $from.marks().some((mark) => mark.type === linkType)
+  if (!hasLink) return ''
+
+  const href = $from.marks().find((mark) => mark.type === linkType)?.attrs.href
+
+  /**
+   * 同一个链接的判定：mark 类型 + href 都相同。
+   *
+   * 逐个子节点扫段落，收集属于本链接的文本节点范围。用 `closed` 标记收尾，
+   * 避免「已结束又碰到匹配节点」时把范围错误地接回去（相邻但 href 不同的链接
+   * 不能算作同一条，中间隔开的也不该合并）。
+   */
+  const parent = $from.parent
+  let pos = $from.start() // 段落内容区起点（绝对位置）
+  let start = -1
+  let end = -1
+  let closed = false
+
+  parent.forEach((node) => {
+    const nodeStart = pos
+    const nodeEnd = pos + node.nodeSize
+    pos = nodeEnd
+
+    if (closed) return
+
+    const link = node.isText ? node.marks.find((mark) => mark.type === linkType) : undefined
+    const isSameLink = !!link && link.attrs.href === href
+
+    if (isSameLink) {
+      if (start < 0) start = nodeStart
+      end = nodeEnd
+    } else if (start >= 0) {
+      // 已经起头、又遇到不属于本链接的节点 → 链接到此为止
+      closed = true
+    }
+  })
+
+  if (start < 0 || end < 0) return ''
+  return state.doc.textBetween(start, end, undefined, '\uFFFC')
+}
+
+/**
+ * 应用链接。
+ *
+ * 判据的核心是「最终要落的文字」与**当前链接文字**的关系，而两个坑都在这里：
+ *
+ * - `selectedText` 只在**有选区**时才有值；点进已有链接后光标是塌缩的（`from === to`），
+ *   此时它恒为空串。若拿它跟 `text` 比，就会把「编辑已有链接」误判成「文字变了」，
+ *   进而在光标处插入一段相同文字，把一个链接**劈成三段**（实测 `点` / `点我` / `我`）。
+ * - 所以编辑态要用**链接自身的文字**（`linkTextAtCursor`）作基准，而不是选区文字。
+ */
+function applyLink(): void {
+  if (!linkCanSubmit.value) return
+  const url = linkUrl.value.trim()
+  if (!url) return
+
+  const instance = props.editor
+  const { from, to } = instance.state.selection
+  const selectedText = from !== to ? instance.state.doc.textBetween(from, to) : ''
+  const href = normalizeUrl(url)
+  const hasSelection = from !== to
+
+  /**
+   * 链接文字的兜底顺序：填的「显示文字」→ 选中文字 → 地址本身。
+   *
+   * 第三档是刻意的：既然「显示文字」不是必填，用户在空选区、又没填文字时
+   * 也得能插进一个链接 —— 拿地址当文字是最符合直觉的默认（粘贴 URL 后回车即成链接）。
+   */
+  const text = linkText.value.trim() || selectedText || url
+
+  // 光标是否落在一条已有链接内（点进链接后改地址走这条；右键菜单的「编辑」也走这条）
+  const existingHref = instance.getAttributes('link').href as string | undefined
+  const cursorInsideLink = !hasSelection && !!existingHref
+
+  if (cursorInsideLink) {
+    /**
+     * 编辑已有链接。
+     *
+     * 文字没改 → 原地更新 href（`extendMarkRange` 把范围扩到整条链接，只改 mark、不动文字）。
+     * 文字改了 → 先把整条链接选中再整体替换，绝不能只插在光标处（那会劈裂链接）。
+     */
+    const currentLinkText = linkTextAtCursor(instance)
+    if (text === currentLinkText) {
+      instance.chain().focus().extendMarkRange('link').setLink({ href }).run()
+      linkOpen.value = false
+      return
+    }
+
+    // 替换整条链接的文字：先 extendMarkRange 选中它，再 insertContent 覆盖
+    instance
+      .chain()
+      .focus()
+      .extendMarkRange('link')
+      .insertContent(text)
+      // insertContent 把选区塌缩到插入内容之后，回退 text.length 重新选中刚落的文字再加链接
+      .command(({ tr, dispatch }) => {
+        const end = tr.selection.to
+        const start = Math.max(0, end - text.length)
+        if (dispatch) tr.setSelection(TextSelection.create(tr.doc, start, end))
+        return true
+      })
+      .setLink({ href })
+      .run()
+    linkOpen.value = false
+    return
+  }
+
+  if (text !== selectedText) {
+    // 空选区插入新链接，或替换选中文字：insertContent 后回退选中刚落的文字再加链接。
+    instance
+      .chain()
+      .focus()
+      .insertContent(text)
+      .command(({ tr, dispatch }) => {
+        const end = tr.selection.to
+        const start = Math.max(0, end - text.length)
+        if (dispatch) tr.setSelection(TextSelection.create(tr.doc, start, end))
+        return true
+      })
+      .setLink({ href })
+      .run()
+    linkOpen.value = false
+    return
+  }
+
+  // 有选区、文字未变：直接对选区加链接
+  instance.chain().focus().extendMarkRange('link').setLink({ href }).run()
+  linkOpen.value = false
+}
+
+function removeLink(): void {
+  props.editor.chain().focus().extendMarkRange('link').unsetLink().run()
+  linkOpen.value = false
+}
+
+/**
+ * 补全协议：用户输入 `example.com` 时补成 `https://example.com`。
+ *
+ * 只对「看起来像域名」的输入补全 —— 已经是完整 URL（含 `://`）、锚点（`#`）、
+ * 站内相对路径（`/`）、邮件（`mailto:`）的一律不动。
+ * 顺带挡掉 `javascript:` / `data:` 这类可执行协议（富文本内容常被回显到页面里，
+ * 这是 XSS 的经典入口；原生 prompt 时代完全没有这层防护）。
+ */
+function normalizeUrl(raw: string): string {
+  const value = raw.trim()
+  if (/^(https?:|mailto:|tel:|#|\/)/i.test(value)) return value
+  // 不含协议且不像域名（没有点、也没有冒号）：原样返回，交给宿主校验
+  if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value) && !value.includes('.')) return value
+  if (/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value)) return `mailto:${value}`
+  return `https://${value}`
+}
+
+/**
+ * 输入是否可提交。
+ *
+ * **只看地址**：「显示文字」不是必填项。
+ *
+ * 早前这里要求「必须有文字可挂」（选中文字 / 填了显示文字 / 已在链接上），
+ * 想法是「链接 mark 必须挂在文字上」，但那是把实现细节当成了用户约束 ——
+ * 用户不该为了插个链接先去编辑器里选一段字。当前的兜底顺序是：
+ * 1. 填了「显示文字」→ 用它（插入或替换）；
+ * 2. 有选中文字 → 用它；
+ * 3. 都没有 → **用地址本身当链接文字**（`applyLink` 里处理）。
+ * 所以只要地址非空就能提交。
+ */
+const linkCanSubmit = computed(() => linkUrl.value.trim().length > 0)
+
+/* ---------- 表格（网格选行列）---------- */
 const tableOpen = ref(false)
-const tableRows = ref(3)
-const tableCols = ref(3)
 const tableWithHeader = ref(true)
 
-function openTablePanel() {
-  tableRows.value = 3
-  tableCols.value = 3
+/**
+ * 网格选择器的悬停尺寸（未悬停时为 0，显示提示用）。
+ *
+ * 交互对齐 TinyMCE / Word 的插入表格：移入网格即高亮出 `rows × cols` 的矩形区域，
+ * 下方实时显示 `3 × 4`，点击即插入。比让用户手填两个数字快得多，
+ * 也让「我要几行几列」这件事变成看一眼就能决定的选择而不是输入。
+ */
+const TABLE_GRID_ROWS = 8
+const TABLE_GRID_COLS = 10
+
+const hoverRows = ref(0)
+const hoverCols = ref(0)
+
+/** 是否已按下鼠标并在网格上拖拽（拖拽时 hover 更新，移出也不清除，与 TinyMCE 一致） */
+const gridDragging = ref(false)
+
+/** 实际生效的行列：悬停值，未悬停时回落到 3×3 的默认插入尺寸 */
+const tableRows = computed(() => hoverRows.value || 3)
+const tableCols = computed(() => hoverCols.value || 3)
+
+/**
+ * 重置网格选择状态。
+ *
+ * ⚠️ **只重置状态，不写 `tableOpen`** —— 开合由 `v-model:open` 单一驱动。
+ *
+ * Popover 把触发器包在 `<span @click="onClick">` 里，那个 onClick 会 `toggle()`。
+ * 早前这里顺手写了 `tableOpen = true`，于是同一次点击被处理两遍：
+ * 先置 true、再被 toggle 翻成 false —— **面板永远打不开**（正是「点表格没反应」的原因）。
+ * 留一个「谁负责开」的来源，这个 bug 就不会重现。
+ */
+function resetTableGrid(): void {
+  hoverRows.value = 0
+  hoverCols.value = 0
+  gridDragging.value = false
   tableWithHeader.value = true
-  tableOpen.value = true
 }
 
-/** 行 / 列数范围（与输入框 min/max 一致）：超出时在「插入」时夹回，而非静默失败 */
-const TABLE_SIZE_MIN = 1
+/** 行 / 列数上限：网格本身限制了上限，这里只做防御性夹取 */
 const TABLE_SIZE_MAX = 20
 
 function clampSize(value: number): number {
   if (!Number.isFinite(value)) return 3
-  return Math.min(TABLE_SIZE_MAX, Math.max(TABLE_SIZE_MIN, Math.trunc(value)))
+  return Math.min(TABLE_SIZE_MAX, Math.max(1, Math.trunc(value)))
+}
+
+/** 悬停 / 拖拽经过某个格子：把高亮区域扩到 (row, col) 这个矩形 */
+function onGridEnter(row: number, col: number): void {
+  hoverRows.value = row
+  hoverCols.value = col
+}
+
+/**
+ * 鼠标按下开始拖拽选择。
+ *
+ * 网格选择器有两种用法，都要支持：**单击**（移到目标格松手即插入）与**拖拽**
+ * （按下后划过一片区域再松手）。TinyMCE 也是两者皆可。
+ */
+function onGridMouseDown(row: number, col: number): void {
+  gridDragging.value = true
+  onGridEnter(row, col)
+}
+
+function onGridMouseUp(): void {
+  if (!gridDragging.value) return
+  gridDragging.value = false
+  insertTable()
+}
+
+/** 拖拽中鼠标移出网格：保留已选区（不清理），否则划出去就前功尽弃 */
+function onGridMouseLeave(): void {
+  if (!gridDragging.value) {
+    hoverRows.value = 0
+    hoverCols.value = 0
+  }
 }
 
 function insertTable() {
   const rows = clampSize(tableRows.value)
   const cols = clampSize(tableCols.value)
-  tableRows.value = rows
-  tableCols.value = cols
 
   const inserted = props.editor
     .chain()
@@ -266,6 +607,13 @@ const moreItems = computed<DropdownItemData[]>(() => [
     disabled: btn.disabled?.(),
     onClick: btn.action,
   })),
+  // 整理格式：与「格式」组同属排版，但它作用于**整篇**而不是选区
+  {
+    key: 'tidy',
+    label: '整理格式',
+    icon: WandSparkles,
+    onClick: tidyFormat,
+  },
   { divider: true },
   { type: 'label', label: '插入' },
   {
@@ -274,6 +622,32 @@ const moreItems = computed<DropdownItemData[]>(() => [
     icon: Video,
     onClick: () => insertVideo(props.editor, props.handlers),
   },
+  { divider: true },
+  /**
+   * 预览 / 打印 / 源代码：这三个都不是「改内容」的工具，而是「看内容 / 导出内容」
+   * 的处理方式，所以单独一组放在最下面（用分组标签与上面的编辑类操作分开）。
+   */
+  { type: 'label', label: '查看与导出' },
+  {
+    key: 'preview',
+    label: '预览',
+    icon: Eye,
+    onClick: openPreview,
+  },
+  {
+    key: 'print',
+    label: '打印',
+    icon: Printer,
+    onClick: printContent,
+  },
+  {
+    key: 'source',
+    label: '源代码',
+    icon: CodeXml,
+    onClick: () => {
+      sourceOpen.value = true
+    },
+  },
 ])
 
 /**
@@ -299,24 +673,83 @@ const alignmentButtons: ToolButton[] = ALIGNMENTS.map((item) => ({
 }))
 
 /* ---------- 颜色：字体颜色 / 背景颜色 ---------- */
+/**
+ * 一个色块 = 「落笔的色值」+ 「面板上显示的变量引用」。
+ *
+ * 拆成两项是这次变量化的关键：色板**显示**走 CSS 变量（宿主 / 暗色可以覆盖），
+ * 而写进文档的**色值**必须解析成具体颜色 —— 正文里存 `var(--g3-…)` 是错的：
+ * 邮件正文、复制出去的内容、别人家的页面都没有这个变量，会渲染成透明 / 黑色。
+ *
+ * 解析时机在「点色块」那一刻（`resolveSwatchColor`），此时色块自身已经挂载、
+ * `getComputedStyle` 能拿到变量在当前主题下的真实值。
+ */
+interface Swatch {
+  /** 变量名（不含 `--g3-` 前缀），用于挂到色块的 style 上 */
+  varName: string
+  /** 兜底色值：变量未定义时使用（宿主没引 tokens 也能工作） */
+  fallback: string
+}
+
 interface ColorControl {
   key: 'color' | 'background'
   label: string
   icon: typeof Baseline
-  /** 预设色板 */
-  palette: string[]
+  /** 预设色板（变量名 + 兜底值） */
+  palette: Swatch[]
   /** 选区当前颜色（未设置时为空串），用于触发器色条与面板选中环 */
   current: () => string
   apply: (color: string) => void
   clear: () => void
 }
 
+/** 把变量名 + 兜底值拼成 `var(--g3-xxx, #fallback)` —— 变量没被定义时仍能显示颜色 */
+function swatchStyle(swatch: Swatch): string {
+  return `var(${cssVar(swatch.varName)}, ${swatch.fallback})`
+}
+
+function toSwatches(varNames: string[], values: string[]): Swatch[] {
+  return varNames.map((varName, index) => ({
+    varName,
+    fallback: values[index] ?? '#000000',
+  }))
+}
+
+/**
+ * 已挂载的色块 DOM 注册表：`<control.key>:<varName>` → 元素。
+ *
+ * 为什么要存元素引用而不是只靠 `$event.currentTarget`：
+ * 点击时当然能拿到 `currentTarget`（用不着注册表），但**选中环**是在渲染期判断的
+ * （`isCurrentColor` 在模板里求值），那时没有事件对象可依赖 —— 必须能在面板已打开、
+ * 色块已挂载的前提下，主动读某个色块解析出的颜色。两者共用同一套解析逻辑
+ * （`resolveSwatchColor`），保证「点下去写进文档的颜色」与「显示为选中的色块」一致。
+ */
+const swatchEls = ref<Record<string, HTMLElement | null>>({})
+
+function setSwatchEl(key: string, el: unknown): void {
+  swatchEls.value[key] = (el as HTMLElement | null) ?? null
+}
+
+/**
+ * 解析色块当前**实际**颜色，用于写进文档。
+ *
+ * `getComputedStyle` 只在色块已挂载时可用（面板打开时必然已挂载）；
+ * 读不到就退回兜底值，绝不把 `var(...)` 写进正文。
+ */
+function resolveSwatchColor(el: HTMLElement | null, swatch: Swatch): string {
+  if (el && typeof window !== 'undefined') {
+    const resolved = window.getComputedStyle(el).backgroundColor
+    // 浏览器会把颜色统一成 rgb()/rgba()；未解析出颜色（空串 / transparent）时退回兜底
+    if (resolved && resolved !== 'transparent') return resolved
+  }
+  return swatch.fallback
+}
+
 const colorControls: ColorControl[] = [
   {
     key: 'color',
     label: '字体颜色',
     icon: Baseline,
-    palette: DEFAULT_TEXT_COLORS,
+    palette: toSwatches(TEXT_COLOR_VARS, DEFAULT_TEXT_COLOR_VALUES),
     current: () => (props.editor.getAttributes('textStyle').color as string | undefined) ?? '',
     apply: (color) => {
       props.editor.chain().focus().setColor(color).run()
@@ -329,7 +762,7 @@ const colorControls: ColorControl[] = [
     key: 'background',
     label: '背景颜色',
     icon: Highlighter,
-    palette: DEFAULT_BACKGROUND_COLORS,
+    palette: toSwatches(BACKGROUND_COLOR_VARS, DEFAULT_BACKGROUND_COLOR_VALUES),
     current: () =>
       (props.editor.getAttributes('textStyle').backgroundColor as string | undefined) ?? '',
     apply: (color) => {
@@ -354,14 +787,42 @@ function applyColor(control: ColorControl, color: string): void {
   openColor.value = ''
 }
 
+/** 点色块：从 DOM 解析出变量当前的真实色值再落笔 */
+function onSwatchClick(control: ColorControl, swatch: Swatch, event: MouseEvent): void {
+  applyColor(control, resolveSwatchColor(event.currentTarget as HTMLElement | null, swatch))
+}
+
 function clearColor(control: ColorControl): void {
   control.clear()
   openColor.value = ''
 }
 
-/** 面板里当前色是否命中该色块（选中环）：HTML 里的 hex 大小写不固定，统一小写比对 */
-function isCurrentColor(control: ColorControl, color: string): boolean {
-  return control.current().toLowerCase() === color
+/**
+ * 面板里当前色是否命中该色块（选中环）。
+ *
+ * 两侧都要归一化后比对：文档里存的可能是 `rgb(245, 34, 45)`（从变量解析而来）
+ * 或历史内容里的 `#f5222d`，而色块渲染出的也是 `rgb(...)` —— 统一用一次
+ * 「临时元素 + getComputedStyle」把两边都归一化成 `rgb()` 再比。
+ */
+function normalizeColor(value: string): string {
+  if (!value || typeof document === 'undefined') return value.toLowerCase()
+  const probe = document.createElement('span')
+  probe.style.color = value
+  // 未解析出颜色时 color 属性为空串，回退到原值
+  if (!probe.style.color) return value.toLowerCase()
+  const holder = document.createElement('span')
+  holder.style.display = 'none'
+  holder.style.color = probe.style.color
+  document.body.appendChild(holder)
+  const resolved = window.getComputedStyle(holder).color
+  holder.remove()
+  return (resolved || value).toLowerCase()
+}
+
+function isCurrentColor(control: ColorControl, swatch: Swatch, el: HTMLElement | null): boolean {
+  const current = control.current()
+  if (!current) return false
+  return normalizeColor(current) === normalizeColor(resolveSwatchColor(el, swatch))
 }
 
 /** 自定义颜色（原生取色器）：只接受完整 hex，避免半截输入写进文档 */
@@ -370,26 +831,15 @@ function onCustomColor(control: ColorControl, event: Event): void {
   if (/^#[0-9a-f]{6}$/i.test(value)) applyColor(control, value)
 }
 
-/** 列表与插入：无序 / 有序 / 链接 / 图片（引用、视频已收进「更多」） */
+/**
+ * 列表与插入：无序列表 / 有序列表 / 图片。
+ *
+ * 前两个是**分裂下拉按钮**（点击图标 = 一键建 / 撤列表，点右侧箭头 = 展开样式选择面板），
+ * 所以不在这份数组里，模板单独渲染（见组 6 里两个 G3Dropdown）。
+ *
+ * 「链接」「引用」「视频」同样不在 —— 它们各有自己的面板或已收进「更多」。
+ */
 const blockButtons: ToolButton[] = [
-  {
-    label: '无序列表',
-    icon: List,
-    action: () => props.editor.chain().focus().toggleBulletList().run(),
-    active: () => props.editor.isActive('bulletList'),
-  },
-  {
-    label: '有序列表',
-    icon: ListOrdered,
-    action: () => props.editor.chain().focus().toggleOrderedList().run(),
-    active: () => props.editor.isActive('orderedList'),
-  },
-  {
-    label: '链接',
-    icon: Link,
-    action: toggleLink,
-    active: () => props.editor.isActive('link'),
-  },
   {
     label: '图片',
     icon: Image,
@@ -397,6 +847,149 @@ const blockButtons: ToolButton[] = [
   },
 ]
 
+/* ---------- 列表样式（无序的项目符号 / 有序的编号体系）---------- */
+/**
+ * 列表样式：无序 4 档（默认 / 实心圆点 / 空心圆圈 / 实心方块）、
+ * 有序 6 档（默认 / 小写字母 / 小写罗马 / 小写希腊 / 大写罗马 / 大写字母）。
+ *
+ * 对齐 TinyMCE 的 bullist / numlist 的样式子菜单。
+ *
+ * ## 交互：菜单项直接落笔，不是「选中态切换」
+ *
+ * 点某一档 = 把**光标所在的列表**设成该样式；若光标不在列表里，则**先建列表再设样式**
+ * （`toggleBulletList` / `toggleOrderedList` 负责建立），这样「想插一个方块列表」
+ * 一步就能完成，而不必「先点无序列表、再从子菜单里挑样式」两步。
+ *
+ * ## 为什么样式存在节点属性上而不是套一层 CSS 类
+ *
+ * 属性（`<ul type="square">` / `<ol type="I">`）是**自描述**的：导出的 HTML 到哪儿
+ * 都保持原样，邮件客户端、别人家的页面都能正确渲染。若改用 `class="g3-list-square"`，
+ * 离开本组件的样式表就退化成默认圆点 —— 而富文本正文的第一要求就是「导出即正确」。
+ */
+type ListKind = 'bullet' | 'ordered'
+
+/** 当前光标所在列表的样式值（不在列表里时为空串） */
+function currentListType(kind: ListKind): string {
+  const instance = props.editor
+  const name = kind === 'bullet' ? 'bulletList' : 'orderedList'
+  if (!instance.isActive(name)) return ''
+  const attrs = instance.getAttributes(name) as { type?: string | null }
+  return attrs.type ?? ''
+}
+
+/**
+ * 一键建 / 撤列表（点击图标按钮的本体）。
+ *
+ * 与 TinyMCE 一样：点图标只是 `toggleBulletList` / `toggleOrderedList`，
+ * **不打开样式面板** —— 样式面板由按钮右侧的箭头（Dropdown 的触发区）打开。
+ * 这样高频的「建列表 / 退列表」仍然是一键，低频的「换样式」走箭头。
+ */
+function toggleList(kind: ListKind): void {
+  const instance = props.editor
+  if (kind === 'bullet') instance.chain().focus().toggleBulletList().run()
+  else instance.chain().focus().toggleOrderedList().run()
+}
+
+/**
+ * 应用列表样式。
+ *
+ * 用 `updateAttributes` 而不是 `setAttributes`：前者作用于**当前所在的列表节点**
+ * （Tiptap 会自动向上找到该类型的祖先节点），后者需要显式位置。
+ *
+ * 空值要显式写 `null`：Tiptap 的 `type` 属性默认值就是 `null`，写 `undefined`
+ * 会让 `updateAttributes` 跳过该属性、旧样式反而留着（表现为「选了默认但没变」）。
+ *
+ * ## ⚠️ 为什么「先建列表」不能和设样式串在**同一条 chain** 里
+ *
+ * `updateAttributes` 内部是按 `state.doc`（**本次事务开始前**的文档）去找目标节点的
+ * （见 Tiptap 的 `updateAttributes` 实现：空选区走 `state.doc.nodesBetween`）。
+ * 于是 `chain().toggleBulletList().updateAttributes('bulletList', { type }).run()` 里，
+ * 后一步扫的仍是**还没有列表**的旧文档 —— 找不到 `bulletList`，`canUpdate` 保持 false，
+ * **静默什么都不做**，表现就是「选了方块列表，结果只是建了个默认圆点列表」。
+ *
+ * 所以这里**分两次执行**：先建列表（第一个事务提交、文档里真的有列表了），
+ * 再设样式。代价是撤销栈里两步 —— 但这正是「建列表」与「调样式」两件事的诚实反映，
+ * 用户按两次 Ctrl+Z 依次退回也符合直觉。
+ */
+function applyListType(kind: ListKind, value: string): void {
+  const instance = props.editor
+  const name = kind === 'bullet' ? 'bulletList' : 'orderedList'
+  const type = value || null
+
+  if (!instance.isActive(name)) {
+    // 第一次事务：建立列表（光标处没有列表时才需要）
+    const created =
+      kind === 'bullet'
+        ? instance.chain().focus().toggleBulletList().run()
+        : instance.chain().focus().toggleOrderedList().run()
+    // 建列表失败（如选区是不可插入块的位置）时不要继续动属性
+    if (!created) return
+  }
+
+  // 第二次事务：此时文档里已经有列表节点，updateAttributes 能正常定位到它
+  instance.chain().focus().updateAttributes(name, { type }).run()
+}
+
+/**
+ * 无序列表的样式候选项（给「点击无序列表按钮展开的样式面板」用）。
+ *
+ * 面板里用 `ListTypeIcon` 把每档画成 TinyMCE 同款的**缩略图**（三条内容线 + 左侧
+ * 项目符号 / 编号），下面还带档位名（「实心圆点」「大写罗马数字」等），
+ * 让人「看着选」而不是「记英文枚举」。当前档位打勾。
+ */
+const bulletListOptions = computed(() => props.bulletListTypes)
+
+/** 有序列表的样式候选项 */
+const orderedListOptions = computed(() => props.orderedListTypes)
+
+/** 当前光标所在无序列表的样式值（不在列表里时为空串） */
+const currentBulletType = computed(() => currentListType('bullet'))
+
+/** 当前光标所在有序列表的样式值（不在列表里时为空串） */
+const currentOrderedType = computed(() => currentListType('ordered'))
+
+/* ---------- 预览 / 打印 / 整理格式 / 源代码 ---------- */
+/**
+ * 预览与源代码对话框的开合。
+ *
+ * 两个对话框都挂在**工具条内部**（而不是 RichText 那一层）：它们的按钮都在工具条上，
+ * 状态跟着按钮走最自然；RichText 只需要把按钮渲染出来，不必知道对话框的存在。
+ * Modal 会 Teleport 到 body，所以嵌套在工具条 DOM 里不会受 `overflow: hidden` 影响。
+ */
+const previewOpen = ref(false)
+const sourceOpen = ref(false)
+
+/**
+ * 预览内容快照。
+ *
+ * 打开时**取一份拷贝**而不是预览期间实时读 `getHTML()`：预览的语义是「看一眼当前
+ * 成果」，若期间编辑器内容变了（理论上可能，比如外部 v-model 回写），
+ * 预览跟着变会让人以为自己在看两份不同的东西。快照也保证了预览与「从预览里打印」
+ * 输出的是同一份内容。
+ */
+const previewHtml = ref('')
+
+function openPreview(): void {
+  previewHtml.value = props.editor.getHTML()
+  previewOpen.value = true
+}
+
+/** 打印：直接打印正文 HTML（用隐藏 iframe，不带宿主页面） */
+function printContent(): void {
+  printHtml(props.editor.getHTML(), '打印')
+}
+
+/**
+ * 整理格式。
+ *
+ * 清理逻辑在 `format.ts`（空段落 / 空白文本 / 空 mark），这里只负责调用与
+ * 「无改动时不打扰用户」——`cleanupFormat` 在没有任何可清理项时不会 dispatch，
+ * 撤销栈保持干净。
+ */
+function tidyFormat(): void {
+  cleanupFormat(props.editor)
+}
+
 /** 撤销 / 重做：历史操作，放工具条末尾 */
 const historyButtons: ToolButton[] = [
   {
@@ -412,87 +1005,321 @@ const historyButtons: ToolButton[] = [
     disabled: () => !props.editor.can().redo(),
   },
 ]
+
+/* ---------- 键盘导航（roving tabindex） ---------- */
+/**
+ * 工具条是一个 `role="toolbar"` 的复合控件，按 ARIA 作者实践，它应当是**单个 Tab 停靠点**：
+ * Tab 进去到工具条，之后用左右方向键在按钮之间移动，再 Tab 出去落到正文。
+ * 这条规则在本组件尤其重要 —— 工具条上有 20 多个可聚焦按钮，若每个都参与 Tab 序列，
+ * 键盘用户想从正文走到工具条另一侧要按二十几次 Tab。
+ *
+ * 实现用 roving tabindex：只有「当前按钮」的 tabindex 是 0，其余是 -1。
+ * 焦点位置用一个索引记录，而不是给每个按钮挂 ref —— 按钮是 v-for 渲染的，
+ * 且分散在多个组里（历史 / 段落 / 行内 / 对齐 / 颜色 / 列表 / 表格 / 更多），
+ * 按 index 统一管理比逐个登记 ref 简单可靠。
+ *
+ * 禁用按钮不参与漫游（`focusableButtons` 用 `:not(:disabled)` 过滤）：
+ * 初始状态历史为空，「撤销 / 重做」是禁用的，方向键不该停在上面。
+ */
+const textDirection = useDirection()
+
+const toolbarEl = ref<HTMLElement | null>(null)
+
+/** 当前持有 tabindex=0 的按钮索引（在「可聚焦按钮」列表里的序号） */
+const activeIndex = ref(0)
+
+/**
+ * 工具条里所有可聚焦的按钮，按 DOM 顺序。
+ *
+ * 用 DOM 查询而不是维护一份声明式列表：按钮由多组数据拼出、还有 Dropdown / Popover
+ * 的触发器，声明式列表要跟着模板改、很容易漏。DOM 顺序天然等于视觉顺序。
+ * 过滤掉禁用按钮 —— 禁用按钮不该被方向键走到（`:not(:disabled)` 已足够，
+ * 原生 `disabled` 的按钮本就不可聚焦）。
+ */
+function focusableButtons(): HTMLButtonElement[] {
+  if (!toolbarEl.value) return []
+  return Array.from(
+    toolbarEl.value.querySelectorAll<HTMLButtonElement>('button:not(:disabled)'),
+  )
+}
+
+/** 把焦点移到第 index 个按钮（对数组长度取模，两端循环） */
+function focusButtonAt(index: number): void {
+  const buttons = focusableButtons()
+  if (!buttons.length) return
+  const target = ((index % buttons.length) + buttons.length) % buttons.length
+  activeIndex.value = target
+  buttons[target]?.focus()
+}
+
+function onToolbarKeydown(event: KeyboardEvent): void {
+  const buttons = focusableButtons()
+  if (!buttons.length) return
+
+  // 当前焦点所在按钮的索引；焦点不在按钮上时退回记录的索引
+  const current = buttons.indexOf(document.activeElement as HTMLButtonElement)
+  const pos = current >= 0 ? current : activeIndex.value
+
+  let next = -1
+  switch (event.key) {
+    case 'ArrowRight':
+    case 'ArrowLeft': {
+      // 左右键按「行内方向」解释：RTL 下屏幕左侧才是「下一个」，
+      // 否则键盘走向与视觉走向相反（与 Tabs / Segmented 同一套工具函数）。
+      const step = horizontalArrowStep(event.key, textDirection.value)
+      if (!step) return
+      next = pos + step
+      break
+    }
+    case 'Home':
+      next = 0
+      break
+    case 'End':
+      next = buttons.length - 1
+      break
+    default:
+      return
+  }
+
+  // 阻止默认：方向键在 contenteditable 里会移动光标、Home/End 会滚页
+  event.preventDefault()
+  focusButtonAt(next)
+}
+
+/**
+ * 把 tabindex 归一化成 roving 模式：当前按钮 0，其余 -1。
+ *
+ * 为什么在 focusin 阶段统一改、而不是渲染期逐按钮绑定：按钮集合是动态的
+ * （禁用态跟随编辑器选区变化），渲染期重算既啰嗦又容易和浏览器自身的焦点状态打架。
+ * 「焦点落在谁身上，谁就是停靠点」是单一事实来源。
+ */
+function syncRovingTabindex(): void {
+  const buttons = focusableButtons()
+  buttons.forEach((el, i) => {
+    el.tabIndex = i === activeIndex.value ? 0 : -1
+  })
+}
+
+function onToolbarFocus(event: FocusEvent): void {
+  const target = event.target as HTMLElement | null
+  if (!target || target.tagName !== 'BUTTON') return
+  const index = focusableButtons().indexOf(target as HTMLButtonElement)
+  if (index >= 0) activeIndex.value = index
+  syncRovingTabindex()
+}
+
+/**
+ * 工具条挂载后把 roving 初始态铺好：首个按钮 tabindex=0，其余 -1。
+ *
+ * 不在模板里写 `:tabindex="i === activeIndex ? 0 : -1"` 是刻意的 —— 按钮分散在
+ * 多个 v-for 与独立触发器里，没有统一的 index 可用，而 DOM 顺序是我们唯一可靠的
+ * 顺序来源（也是方向键要走的那份顺序）。
+ */
+onMounted(() => {
+  syncRovingTabindex()
+})
+
+/**
+ * 按钮的禁用态跟随编辑器选区变化（撤销 / 重做、对齐在图片上时禁用），
+ * 而**禁用按钮不在 `focusableButtons()` 里** —— 集合一变，原先「第 N 个」的含义就变了。
+ * 若不重算，可能出现「所有按钮 tabindex 都是 -1」导致 Tab 进不来工具条。
+ * 用 flush: 'post' 等 DOM 更新完再同步。
+ */
+watch(
+  () => {
+    const instance = props.editor
+    if (!instance) return ''
+    // 依赖：可撤销 / 可重做 / 对齐可用性 —— 都是影响按钮 disabled 的判定
+    return [
+      instance.can().undo(),
+      instance.can().redo(),
+      instance.can().setTextAlign('left'),
+      instance.isEditable,
+    ].join('|')
+  },
+  () => syncRovingTabindex(),
+  { flush: 'post' },
+)
+
+/**
+ * 供外层（RichText 的链接右键菜单）唤起「编辑链接」面板。
+ *
+ * 链接面板的状态（`linkUrl` / `linkText` / `linkOpen`）都在工具条里，菜单在
+ * `RichText.vue` 那一层，跨组件只能靠 expose —— 不把这几个 ref 提上去是因为
+ * 它们与工具条内的按钮、校验逻辑耦合很紧，提上去反而散。
+ *
+ * 这里的 `linkOpen = true` 是**唯一**的显式开启点：右键菜单不经过 Popover 的
+ * 触发器（它触发的是编辑器 DOM 上的 contextmenu），没有 toggle 会跟我们抢这个状态。
+ */
+defineExpose({
+  openLinkEditor: (href: string, text: string) => {
+    openLinkPanel({ href, text })
+    linkOpen.value = true
+  },
+  /** 打开「源代码」对话框（供 RichText 层透传给宿主） */
+  openSourceCode: () => {
+    sourceOpen.value = true
+  },
+  /** 打开「预览」对话框（供 RichText 层透传给宿主） */
+  openPreview,
+  /** 打印正文（供 RichText 层透传给宿主，行为与菜单里的「打印」一致） */
+  print: printContent,
+  /** 整理格式（供 RichText 层透传给宿主） */
+  tidyFormat,
+})
 </script>
 
 <template>
-  <div :class="[e('toolbar'), { [em('toolbar', 'bottom')]: placement === 'bottom' }]">
-    <!-- 撤销 / 重做放最前：历史是「先于格式」的一类操作 -->
-    <G3Tooltip v-for="btn in historyButtons" :key="btn.label" :content="btn.label" placement="top">
-      <G3Button
-        :class="e('button')"
-        type="ghost"
-        size="small"
-        :disabled="btn.disabled?.()"
-        :aria-label="btn.label"
-        @click="btn.action()"
+  <!--
+    role="toolbar"：按 ARIA 作者实践，工具条是**单个 Tab 停靠点**，内部用方向键漫游。
+    工具条上有 20 多个可聚焦按钮，若每个都占一个 Tab 位，键盘用户要按二十几次 Tab
+    才能从正文走到工具条的另一侧。aria-orientation 恒为 horizontal —— 工具条虽然可能
+    折行，但折行是布局结果、不是「竖排工具条」的语义（见文档「工具条」一节）。
+  -->
+  <div
+    :class="[e('toolbar'), { [em('toolbar', 'bottom')]: placement === 'bottom' }]"
+    role="toolbar"
+    aria-orientation="horizontal"
+    :aria-label="placement === 'bottom' ? '编辑工具条（下）' : '编辑工具条'"
+    ref="toolbarEl"
+    @keydown="onToolbarKeydown"
+    @focusin="onToolbarFocus"
+  >
+    <!-- 组 1：历史 —— 撤销 / 重做放最前（历史是「先于格式」的一类操作） -->
+    <div :class="e('group')" role="group" aria-label="历史">
+      <G3Tooltip
+        v-for="btn in historyButtons"
+        :key="btn.label"
+        :content="btn.label"
+        placement="top"
       >
-        <component :is="btn.icon" />
-      </G3Button>
-    </G3Tooltip>
-
-    <span :class="e('divider')" />
-
-    <!-- 段落格式（紧接历史操作；字体 / 字号已收进「更多」） -->
-    <G3Dropdown :items="headingItems" trigger="click" placement="bottom-start">
-      <template #trigger>
-        <G3Button :class="e('trigger')" type="ghost" size="small">
-          <span :class="e('trigger-label')">{{ currentHeadingLabel }}</span>
-          <ChevronDown :class="e('trigger-caret')" />
+        <G3Button
+          :class="e('button')"
+          type="ghost"
+          size="small"
+          :disabled="btn.disabled?.()"
+          :aria-label="btn.label"
+          @click="btn.action()"
+        >
+          <component :is="btn.icon" />
         </G3Button>
-      </template>
-    </G3Dropdown>
+      </G3Tooltip>
+    </div>
 
-    <span :class="e('divider')" />
+    <!-- 组 2：段落格式（紧接历史操作；字体 / 字号已收进「更多」） -->
+    <div :class="e('group')" role="group" aria-label="段落格式">
+      <!--
+        用 `#menu` 逃生舱而不是 `:items`：菜单项要把每一级的**真实排版**画出来
+        （字号 + 字重），而 DropdownItem 的图标位只适合放小图标 —— 塞一整块文字排版
+        进去会被 item 的行高与省略号规则裁掉。走 #menu 自己渲染列表，样式完全可控。
+      -->
+      <G3Dropdown trigger="click" placement="bottom-start">
+        <template #trigger>
+          <!--
+            aria-label 用固定文案「段落格式」而不是可见文字（当前块格式：正文 / 标题 N）：
+            可见文字随光标所在块变化，读屏用户听到「标题 2」只会以为这是个标题，
+            不知道按下去能改段落格式。可见文字保留当前值 —— 那是给视力用户看的「当前态」。
+          -->
+          <G3Button
+            :class="e('trigger')"
+            type="secondary"
+            aria-label="段落格式"
+            :aria-description="currentHeadingLabel"
+          >
+            <span :class="e('trigger-label')">{{ currentHeadingLabel }}</span>
+            <ChevronDown :class="e('trigger-caret')" />
+          </G3Button>
+        </template>
 
-    <!-- 行内格式：加粗 / 斜体 / 下划线 -->
-    <G3Tooltip v-for="btn in inlineButtons" :key="btn.label" :content="btn.label" placement="top">
-      <G3Button
-        :class="[e('button'), { [is('active')]: btn.active?.() }]"
-        type="ghost"
-        size="small"
-        :disabled="btn.disabled?.()"
-        :aria-label="btn.label"
-        :aria-pressed="btn.active?.() || undefined"
-        @click="btn.action()"
+        <template #menu="{ close }">
+          <div :class="e('heading-menu')" role="menu">
+            <button
+              v-for="item in headingLevels"
+              :key="item.key"
+              type="button"
+              :class="[
+                e('heading-item'),
+                { [is('selected')]: currentHeading === item.key },
+              ]"
+              role="menuitem"
+              :aria-current="currentHeading === item.key ? 'true' : undefined"
+              :data-level="item.key"
+              @click="
+                () => {
+                  setHeading(item)
+                  close()
+                }
+              "
+            >
+              <!-- 按该级的真实字号 / 字重渲染，选择变成「看起来像我要的那级」 -->
+              <span
+                :class="e('heading-item-text')"
+                :style="{ fontSize: item.fontSize, fontWeight: item.fontWeight }"
+                >{{ item.label }}</span
+              >
+              <!-- 当前所在级别的勾选标记 -->
+              <Check v-if="currentHeading === item.key" :class="e('heading-item-check')" />
+            </button>
+          </div>
+        </template>
+      </G3Dropdown>
+    </div>
+
+    <!-- 组 3：行内格式 —— 加粗 / 斜体 / 下划线 -->
+    <div :class="e('group')" role="group" aria-label="行内格式">
+      <G3Tooltip
+        v-for="btn in inlineButtons"
+        :key="btn.label"
+        :content="btn.label"
+        placement="top"
       >
-        <component :is="btn.icon" />
-      </G3Button>
-    </G3Tooltip>
+        <G3Button
+          :class="[e('button'), { [is('active')]: btn.active?.() }]"
+          type="ghost"
+          size="small"
+          :disabled="btn.disabled?.()"
+          :aria-label="btn.label"
+          :aria-pressed="btn.active?.() || undefined"
+          @click="btn.action()"
+        >
+          <component :is="btn.icon" />
+        </G3Button>
+      </G3Tooltip>
+    </div>
 
-    <span :class="e('divider')" />
-
-    <!-- 对齐：左 / 中 / 右（再点当前档位即取消对齐） -->
-    <G3Tooltip
-      v-for="btn in alignmentButtons"
-      :key="btn.label"
-      :content="btn.label"
-      placement="top"
-    >
-      <G3Button
-        :class="[e('button'), { [is('active')]: btn.active?.() }]"
-        type="ghost"
-        size="small"
-        :disabled="btn.disabled?.()"
-        :aria-label="btn.label"
-        :aria-pressed="btn.active?.() || undefined"
-        @click="btn.action()"
+    <!-- 组 4：对齐 —— 左 / 中 / 右（再点当前档位即取消对齐） -->
+    <div :class="e('group')" role="group" aria-label="对齐">
+      <G3Tooltip
+        v-for="btn in alignmentButtons"
+        :key="btn.label"
+        :content="btn.label"
+        placement="top"
       >
-        <component :is="btn.icon" />
-      </G3Button>
-    </G3Tooltip>
+        <G3Button
+          :class="[e('button'), { [is('active')]: btn.active?.() }]"
+          type="ghost"
+          size="small"
+          :disabled="btn.disabled?.()"
+          :aria-label="btn.label"
+          :aria-pressed="btn.active?.() || undefined"
+          @click="btn.action()"
+        >
+          <component :is="btn.icon" />
+        </G3Button>
+      </G3Tooltip>
+    </div>
 
-    <span :class="e('divider')" />
-
-    <!-- 字体颜色 / 背景颜色：图标 + 当前色条，点开启预设色板 -->
-    <G3Popover
-      v-for="control in colorControls"
-      :key="control.key"
-      :open="openColor === control.key"
-      trigger="click"
-      placement="bottom-start"
-      :arrow="false"
-      :offset="4"
-      :content-class="e('color-panel-wrap')"
+    <!-- 组 5：颜色 —— 字体颜色 / 背景颜色（图标 + 当前色条，点开启预设色板） -->
+    <div :class="e('group')" role="group" aria-label="颜色">
+      <G3Popover
+        v-for="control in colorControls"
+        :key="control.key"
+        :open="openColor === control.key"
+        trigger="click"
+        placement="bottom-start"
+        :arrow="false"
+        :offset="4"
+        :content-class="e('color-panel-wrap')"
       @update:open="(value: boolean) => onColorOpen(control.key, value)"
     >
       <template #trigger>
@@ -546,39 +1373,259 @@ const historyButtons: ToolButton[] = [
           </div>
 
           <div :class="e('color-grid')">
+            <!--
+              色块的底色挂的是 CSS 变量（swatchStyle），不是写死的 hex —— 宿主 / 暗色
+              主题可以直接覆盖 `--g3-rich-text-swatch-*` 换掉整块面板。
+              写进文档的色值在点击时从色块自身解析（onSwatchClick → getComputedStyle），
+              保证正文里落到具体颜色而不是 `var(...)`。
+              色块同时用 data-color 暴露当前解析出的色值，供 E2E / 宿主断言用。
+            -->
             <button
-              v-for="color in control.palette"
-              :key="color"
+              v-for="swatch in control.palette"
+              :key="swatch.varName"
               type="button"
               :class="[
                 e('color-swatch'),
-                { [is('active')]: isCurrentColor(control, color) },
+                { [is('active')]: isCurrentColor(control, swatch, swatchEls[`${control.key}:${swatch.varName}`] ?? null) },
               ]"
-              :style="{ background: color }"
-              :aria-label="color"
-              @click="applyColor(control, color)"
+              :style="{ background: swatchStyle(swatch) }"
+              :data-color-var="swatch.varName"
+              :aria-label="swatch.fallback"
+              :ref="(el) => setSwatchEl(`${control.key}:${swatch.varName}`, el)"
+              @click="onSwatchClick(control, swatch, $event)"
             />
           </div>
         </div>
       </template>
     </G3Popover>
+    </div>
 
-    <span :class="e('divider')" />
+    <!-- 组 6：列表与插入 —— 无序 / 有序（样式下拉）/ 图片 / 链接 / 表格 -->
+    <div :class="e('group')" role="group" aria-label="列表与插入">
+      <!--
+        无序列表（分裂按钮，用 G3ButtonGroup 组合）：点图标 = 一键建 / 撤列表；
+        点右侧箭头 = 打开项目符号样式面板。样式面板里每一项画成 TinyMCE 同款的缩略图
+        （三条线 + 左侧符号），当前档位打勾。
+      -->
+      <G3ButtonGroup>
+        <G3Tooltip content="无序列表" placement="top">
+          <G3Button
+            :class="[e('button'), { [is('active')]: editor.isActive('bulletList') }]"
+            type="ghost"
+            size="small"
+            aria-label="无序列表"
+            :aria-pressed="editor.isActive('bulletList') || undefined"
+            @click="toggleList('bullet')"
+          >
+            <List />
+          </G3Button>
+        </G3Tooltip>
 
-    <!-- 列表与插入：无序 / 有序 / 链接 / 图片（表格在后面，同组不分隔） -->
-    <G3Tooltip v-for="btn in blockButtons" :key="btn.label" :content="btn.label" placement="top">
-      <G3Button
-        :class="[e('button'), { [is('active')]: btn.active?.() }]"
-        type="ghost"
-        size="small"
-        :disabled="btn.disabled?.()"
-        :aria-label="btn.label"
-        :aria-pressed="btn.active?.() || undefined"
-        @click="btn.action()"
-      >
-        <component :is="btn.icon" />
-      </G3Button>
-    </G3Tooltip>
+        <G3Dropdown trigger="click" placement="bottom-start" :offset="4">
+          <template #trigger>
+            <G3Button
+              :class="[e('button'), e('list-caret')]"
+              type="ghost"
+              size="small"
+              aria-label="无序列表样式"
+            >
+              <ChevronDown />
+            </G3Button>
+          </template>
+
+          <template #menu="{ close }">
+            <div :class="e('list-panel')" role="menu" aria-label="无序列表样式">
+              <div :class="e('list-grid')">
+                <button
+                  v-for="item in bulletListOptions"
+                  :key="item.value || 'default'"
+                  type="button"
+                  :class="[
+                    e('list-item'),
+                    { [is('selected')]: currentBulletType === item.value },
+                  ]"
+                  role="menuitemradio"
+                  :aria-checked="currentBulletType === item.value ? 'true' : 'false'"
+                  :aria-label="item.label"
+                  :data-value="item.value"
+                  @click="
+                    () => {
+                      applyListType('bullet', item.value)
+                      close()
+                    }
+                  "
+                >
+                  <ListTypeIcon kind="bullet" :type="item.value" :size="28" />
+                  <span :class="e('list-item-label')">{{ item.label }}</span>
+                  <Check v-if="currentBulletType === item.value" :class="e('list-item-check')" />
+                </button>
+              </div>
+            </div>
+          </template>
+        </G3Dropdown>
+      </G3ButtonGroup>
+
+      <!-- 有序列表：与无序列表同构，样式面板换成编号体系 -->
+      <G3ButtonGroup>
+        <G3Tooltip content="有序列表" placement="top">
+          <G3Button
+            :class="[e('button'), { [is('active')]: editor.isActive('orderedList') }]"
+            type="ghost"
+            size="small"
+            aria-label="有序列表"
+            :aria-pressed="editor.isActive('orderedList') || undefined"
+            @click="toggleList('ordered')"
+          >
+            <ListOrdered />
+          </G3Button>
+        </G3Tooltip>
+
+        <G3Dropdown trigger="click" placement="bottom-start" :offset="4">
+          <template #trigger>
+            <G3Button
+              :class="[e('button'), e('list-caret')]"
+              type="ghost"
+              size="small"
+              aria-label="有序列表样式"
+            >
+              <ChevronDown />
+            </G3Button>
+          </template>
+
+          <template #menu="{ close }">
+            <div :class="e('list-panel')" role="menu" aria-label="有序列表样式">
+              <div :class="e('list-grid')">
+                <button
+                  v-for="item in orderedListOptions"
+                  :key="item.value || 'default'"
+                  type="button"
+                  :class="[
+                    e('list-item'),
+                    { [is('selected')]: currentOrderedType === item.value },
+                  ]"
+                  role="menuitemradio"
+                  :aria-checked="currentOrderedType === item.value ? 'true' : 'false'"
+                  :aria-label="item.label"
+                  :data-value="item.value"
+                  @click="
+                    () => {
+                      applyListType('ordered', item.value)
+                      close()
+                    }
+                  "
+                >
+                  <ListTypeIcon kind="ordered" :type="item.value" :size="28" />
+                  <span :class="e('list-item-label')">{{ item.label }}</span>
+                  <Check v-if="currentOrderedType === item.value" :class="e('list-item-check')" />
+                </button>
+              </div>
+            </div>
+          </template>
+        </G3Dropdown>
+      </G3ButtonGroup>
+
+      <!-- 图片：唯一还在 blockButtons 数组里的常驻按钮 -->
+      <G3Tooltip v-for="btn in blockButtons" :key="btn.label" :content="btn.label" placement="top">
+        <G3Button
+          :class="[e('button'), { [is('active')]: btn.active?.() }]"
+          type="ghost"
+          size="small"
+          :disabled="btn.disabled?.()"
+          :aria-label="btn.label"
+          :aria-pressed="btn.active?.() || undefined"
+          @click="btn.action()"
+        >
+          <component :is="btn.icon" />
+        </G3Button>
+      </G3Tooltip>
+
+    <!--
+      链接：点开是输入面板（替代原先的 window.prompt）。
+      光标已在链接上时，面板标题变「编辑链接」并多一个「移除链接」按钮 ——
+      比原来「再点一次按钮才取消」更直白（原逻辑靠 isActive('link') 分支切行为，
+      用户看不出按钮此刻是「加链接」还是「去链接」）。
+    -->
+    <G3Popover
+      v-model:open="linkOpen"
+      trigger="click"
+      placement="bottom-start"
+      :arrow="false"
+      :offset="4"
+      :content-class="e('link-panel')"
+      @update:open="(value: boolean) => value && openLinkPanel()"
+    >
+      <template #trigger>
+        <G3Tooltip content="链接" placement="top">
+          <G3Button
+            :class="[e('button'), { [is('active')]: editor.isActive('link') }]"
+            type="ghost"
+            size="small"
+            aria-label="链接"
+            :aria-pressed="editor.isActive('link') || undefined"
+          >
+            <Link />
+          </G3Button>
+        </G3Tooltip>
+      </template>
+
+      <template #content>
+        <div :class="e('link-form')" @keydown.enter.prevent="applyLink">
+          <div :class="e('link-field')">
+            <label :class="e('link-label')" for="g3-rich-text-link-url">链接地址</label>
+            <!--
+              用 G3Input 而不是裸 <input>：库内的文本控件只该有一种长相与行为，
+              手抄它的边框 / 聚焦环 / 高度等于给自己留一份要跟着上游同步的副本。
+              `id` 靠 G3Input 的 $attrs 透传落到真正的 <input> 上，`<label for>` 才指得准。
+            -->
+            <G3Input
+              id="g3-rich-text-link-url"
+              v-model="linkUrl"
+              aria-label="链接地址"
+              @keydown.esc="linkOpen = false"
+            />
+          </div>
+
+          <!--
+            显示文字：选区为空时它是链接文字本身；选区非空时改它就是替换选中文字。
+            不留 placeholder —— 字段名已经说清楚要填什么，预填的「已选文字」也比
+            示例文案更有信息量（能看到当前会用什么文字）。
+          -->
+          <div :class="e('link-field')">
+            <label :class="e('link-label')" for="g3-rich-text-link-text">显示文字</label>
+            <G3Input
+              id="g3-rich-text-link-text"
+              v-model="linkText"
+              aria-label="显示文字"
+            />
+          </div>
+
+          <!--
+            操作区：左「移除链接」（仅编辑态，危险语义离主操作远一点），
+            右侧「取消 / 确定」成对靠右。
+            用默认尺寸（32px，等于 --g3-control-height）而不是 small（24px）——
+            这是面板里唯一的决定动作，24px 在弹层里偏小、也不与 G3Input 的 32px 等高。
+            取消走 Ghost（低强调），确定走 Primary（主操作）。
+          -->
+          <div :class="e('link-actions')">
+            <G3Button
+              v-if="linkEditing"
+              :class="e('link-remove')"
+              type="ghost"
+              @click="removeLink"
+            >
+              移除链接
+            </G3Button>
+
+            <div :class="e('link-actions-main')">
+              <G3Button type="ghost" @click="linkOpen = false">取消</G3Button>
+              <G3Button type="primary" :disabled="!linkCanSubmit" @click="applyLink">
+                确定
+              </G3Button>
+            </div>
+          </div>
+        </div>
+      </template>
+    </G3Popover>
 
     <!-- 表格按钮 + 行列选择面板（需要选行列，所以留在工具条而不是收进「更多」） -->
     <G3Popover
@@ -588,6 +1635,7 @@ const historyButtons: ToolButton[] = [
       :arrow="false"
       :offset="4"
       :content-class="e('table-panel')"
+      @update:open="(value: boolean) => value && resetTableGrid()"
     >
       <template #trigger>
         <G3Tooltip content="插入表格" placement="top">
@@ -598,48 +1646,82 @@ const historyButtons: ToolButton[] = [
       </template>
 
       <template #content>
-        <div :class="e('table-form')" @keydown.enter.prevent="insertTable">
-          <div :class="e('table-field')">
-            <label :class="e('table-label')">行数</label>
-            <input
-              v-model.number="tableRows"
-              :class="e('table-input')"
-              type="number"
-              :min="TABLE_SIZE_MIN"
-              :max="TABLE_SIZE_MAX"
-            />
+        <div :class="e('table-form')">
+          <!--
+            网格选择器（对齐 TinyMCE / Word）：移入高亮出 rows × cols 矩形，
+            下方实时显示尺寸，点击直接插入。取代了原来的「行数 / 列数」两个数字输入框 ——
+            那句话把「选一个 3×4」变成了两次输入 + 一次确认，而用户心里的模型是「这么大一块」。
+          -->
+          <div
+            :class="e('table-grid')"
+            role="grid"
+            :aria-label="`选择表格大小，当前 ${tableRows} 行 ${tableCols} 列`"
+            @mouseleave="onGridMouseLeave"
+            @mouseup="onGridMouseUp"
+          >
+            <div
+              v-for="row in TABLE_GRID_ROWS"
+              :key="row"
+              :class="e('table-grid-row')"
+              role="row"
+            >
+              <button
+                v-for="col in TABLE_GRID_COLS"
+                :key="col"
+                type="button"
+                :class="[
+                  e('table-grid-cell'),
+                  { [is('table-grid-cell-active')]: row <= tableRows && col <= tableCols },
+                ]"
+                role="gridcell"
+                :aria-label="`${row} 行 ${col} 列`"
+                :data-row="row"
+                :data-col="col"
+                @mouseenter="onGridEnter(row, col)"
+                @mousedown.prevent="onGridMouseDown(row, col)"
+              />
+            </div>
           </div>
-          <div :class="e('table-field')">
-            <label :class="e('table-label')">列数</label>
-            <input
-              v-model.number="tableCols"
-              :class="e('table-input')"
-              type="number"
-              :min="TABLE_SIZE_MIN"
-              :max="TABLE_SIZE_MAX"
-            />
-          </div>
-          <div :class="e('table-field')">
-            <label :class="e('table-label')">包含表头行</label>
+
+          <!-- 实时尺寸提示：未悬停时显示默认尺寸（3 × 3），让「点下去会得到什么」始终可见 -->
+          <p :class="e('table-grid-label')" aria-live="polite">
+            {{ tableRows }} × {{ tableCols }}
+          </p>
+
+          <label :class="e('table-header-toggle')">
             <G3Checkbox v-model="tableWithHeader" :class="e('table-checkbox')" />
-          </div>
-          <G3Button type="primary" size="small" block @click="insertTable">插入</G3Button>
+            <span>包含表头行</span>
+          </label>
         </div>
       </template>
     </G3Popover>
+    </div>
 
-    <span :class="e('divider')" />
-
-    <!-- 更多：低频功能按组收进菜单，工具条保持一行。
+    <!-- 组 7：更多 —— 低频功能收进菜单。
          菜单内容约 295px，Dropdown 的上限默认按视口算（calc(100vh - 48px)），
          所以面板内部不会出滚动条 —— 不需要在这里传 menuMaxHeight。 -->
-    <G3Dropdown :items="moreItems" trigger="click" placement="bottom-end" :offset="4">
-      <template #trigger>
-        <G3Button :class="e('button')" type="ghost" size="small" aria-label="更多">
-          <Ellipsis />
-        </G3Button>
-      </template>
-    </G3Dropdown>
+    <div :class="e('group')" role="group" aria-label="更多">
+      <G3Dropdown :items="moreItems" trigger="click" placement="bottom-end" :offset="4">
+        <template #trigger>
+          <G3Button :class="e('button')" type="ghost" size="small" aria-label="更多">
+            <Ellipsis />
+          </G3Button>
+        </template>
+      </G3Dropdown>
+    </div>
+
+    <!--
+      预览 / 源代码对话框。
+      放在工具条内部（而不是 RichText 层）：按钮与开合状态都在这边，
+      少一层状态提升。Modal 自身 Teleport 到 body，所以这里的 DOM 嵌套
+      不会受工具条的 flex / overflow 影响。
+    -->
+    <PreviewDialog v-model:open="previewOpen" :html="previewHtml" />
+    <SourceCodeDialog
+      v-model:open="sourceOpen"
+      :editor="editor"
+      @save="(html: string) => emit('source-save', html)"
+    />
   </div>
 </template>
 
@@ -653,13 +1735,20 @@ const historyButtons: ToolButton[] = [
   display: flex;
   flex-wrap: wrap;
   align-items: center;
-  /* 组内 4px：图标回到 16px 后，16px 图形落在 24px 按钮正中（左右各 4px 空），
-     再给 4px 间隙，两个图标的墨迹之间就有 12px，不会再显得挤 */
-  gap: v('space-1', 4px);
   /**
-   * 上下 8px / 左右 10px：图标 24px 之后，原来的 4px / 8px 会让图标几乎贴住上边框与左边框。
-   * 左右取 10px 而不是 12px：图标在 24px 按钮里自己还留了 2px，10 + 2 = 12px 正好和正文的
-   * 12px 内边距对齐（首列视觉齐平）。
+   * 不用 `gap` 控制间距，改由按钮自己的 `margin-inline-end` 承担。
+   *
+   * 原因：分组容器用了 `display: contents`（见下方 `.group` 的说明），组的盒子不参与
+   * 布局，按钮被提升为工具条的直接 flex 项 —— 此时 `gap` 会在**每个按钮之间**都生效，
+   * 无法区分「组内」与「组间」，分组感就没了。用 margin 才能让组内 / 组间的间距不同。
+   */
+  gap: 0;
+  /**
+   * 上下 8px / 左右 10px。
+   *
+   * 左右取 10px 对齐的是「按钮盒子」而不是「图标墨迹」：32px 按钮里 18px 图标居中，
+   * 图标左边缘距按钮左边缘 7px，加上 10px 内边距，图标墨迹距容器左边缘 17px ——
+   * 与正文区的 12px 内边距观感上齐平。
    */
   padding: v('space-2', 8px) 10px;
   background: v('bg-container', #fff);
@@ -687,53 +1776,202 @@ const historyButtons: ToolButton[] = [
   }
 }
 
-/* 下拉触发器：ghost 按钮承载「当前值 + 箭头」 */
+/**
+ * 预设色板的 CSS 变量默认值。
+ *
+ * 挂在工具条根上（而不是 `:root`）：变量只服务取色面板，作用域收紧到组件内部，
+ * 不污染宿主全局命名空间；宿主仍可在任意祖先上覆盖（就近原则生效）。
+ *
+ * 覆盖方式（换品牌色 / 暗色调色板，无需改组件代码）：
+ *   .g3-rich-text__toolbar { --g3-rich-text-swatch-text-5: #ff4d4f; }
+ *
+ * 注意变量的**默认值同时也写进了 TS**（extensions.ts 的 DEFAULT_*_COLOR_VALUES）：
+ * TS 那份是「变量未定义时的兜底 + 写进文档前的兜底色」，两边必须一致。
+ * 实际上色块渲染走 `var(--g3-…, 兜底)`，变量存在时以 CSS 为准。
+ */
+.#{e('rich-text', 'toolbar')} {
+  #{css-var('rich-text-swatch-text-1')}: #000000;
+  #{css-var('rich-text-swatch-text-2')}: #434343;
+  #{css-var('rich-text-swatch-text-3')}: #8c8c8c;
+  #{css-var('rich-text-swatch-text-4')}: #bfbfbf;
+  #{css-var('rich-text-swatch-text-5')}: #f5222d;
+  #{css-var('rich-text-swatch-text-6')}: #fa8c16;
+  #{css-var('rich-text-swatch-text-7')}: #52c41a;
+  #{css-var('rich-text-swatch-text-8')}: #1677ff;
+  #{css-var('rich-text-swatch-text-9')}: #722ed1;
+  #{css-var('rich-text-swatch-text-10')}: #eb2f96;
+
+  #{css-var('rich-text-swatch-bg-1')}: #f5f5f5;
+  #{css-var('rich-text-swatch-bg-2')}: #fff1f0;
+  #{css-var('rich-text-swatch-bg-3')}: #fff7e6;
+  #{css-var('rich-text-swatch-bg-4')}: #feffe6;
+  #{css-var('rich-text-swatch-bg-5')}: #f6ffed;
+  #{css-var('rich-text-swatch-bg-6')}: #e6fffb;
+  #{css-var('rich-text-swatch-bg-7')}: #e6f4ff;
+  #{css-var('rich-text-swatch-bg-8')}: #f0f5ff;
+  #{css-var('rich-text-swatch-bg-9')}: #f9f0ff;
+  #{css-var('rich-text-swatch-bg-10')}: #fff0f6;
+}
+
+/**
+ * 下拉触发器：ghost 按钮承载「当前值 + 箭头」。
+ *
+ * 尺寸与工具条里的图标按钮**对齐到同一档**（32px = `--g3-control-height`）：
+ * 早前它用 `size="small"`（24px），在一排 32px 图标按钮中间明显塌下去一块，
+ * 整条工具条的高度参差不齐。这里用 `min-height` 而不是固定 `height`，
+ * 免得长文案（如本地化后的「Paragraph」）被压出省略号。
+ */
 .#{e('rich-text', 'trigger')} {
-  gap: v('space-1', 4px);
+  min-height: v('control-height', 32px);
   padding: 0 v('space-2', 8px);
   /* 与图标按钮同一份前景色（见 .g3-rich-text__button） */
   color: v('text-1', rgba(0, 0, 0, 0.88));
+
+  /**
+   * ⚠️ 字与箭头的间距必须写在 `.g3-button__content` 上，不能写在本元素（`<button>`）上。
+   *
+   * G3Button 会把默认插槽的内容整体包进一个 `<span class="g3-button__content">`
+   * （见 Button.vue 模板），所以「正文」和箭头是那个 span 的**直接子元素**，
+   * 而不是 `<button>` 的子元素。写在 `<button>` 上的 `gap` 只作用于
+   * 「图标插槽 ↔ content 包裹层」这一层 —— 而这里没有图标插槽，
+   * 于是 gap 形同虚设，两个子元素依旧紧紧贴在一起（这正是「怎么调都没变化」的原因）。
+   *
+   * 8px（而非原来的 4px）：挨太近时箭头会被读成文字的一部分（「正文⌄」），
+   * 下拉的语义就丢了；8px 让箭头成为一个独立符号。
+   */
+  .#{e('button', 'content')} {
+    gap: v('space-2', 8px);
+  }
 }
 
 .#{e('rich-text', 'trigger-label')} {
-  /* 图标 24px 之后，12px 的按钮文字会显得偏小，提到正文档位 */
   font-size: v('font-size', 14px);
+  /* 标签变化（正文 ↔ 标题 1）时按钮宽度会变，给个下限减少跳动 */
+  min-width: 2em;
+  text-align: start;
 }
 
 .#{e('rich-text', 'trigger-caret')} {
-  width: 14px;
-  height: 14px;
+  /* 与工具条图标同为 18px，视觉分量一致 */
+  width: 18px;
+  height: 18px;
+  flex-shrink: 0;
   /* 箭头是二级信息：比文字浅一档，描边也不加重 */
   color: v('text-2', rgba(0, 0, 0, 0.65));
 }
 
-/* 分隔线 */
-.#{e('rich-text', 'divider')} {
-  flex-shrink: 0;
-  width: 1px;
-  height: 16px;
-  margin: 0 v('space-1', 4px);
-  background: v('border-color', #d9d9d9);
+/* ---------- 段落格式下拉面板 ---------- */
+/**
+ * 每项按该级别的**真实排版**渲染（见 headingLevels 的 fontSize / fontWeight）。
+ *
+ * 面板宽度固定 200px：各级字号差异大（2em 的「标题 1」比「标题 6」宽一倍多），
+ * 不固定的话面板会随最长项撑开、显得松散，且触发器的 min-width 对齐也不好看。
+ */
+.#{e('rich-text', 'heading-menu')} {
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+  min-width: 200px;
 }
 
-/* 图标按钮：ghost，激活态主色底；图标 16px，hit 区 32px（等于 --g3-control-height） */
+.#{e('rich-text', 'heading-item')} {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: v('space-2', 8px);
+  width: 100%;
+  /* 最小高度按最高的 H1（2em ≈ 28px）留足，免得选中态的背景高度随级别跳动 */
+  min-height: 34px;
+  padding: v('space-1', 4px) v('space-2', 8px);
+  border: 0;
+  border-radius: v('radius-sm', 4px);
+  background: transparent;
+  color: v('text-1', rgba(0, 0, 0, 0.88));
+  font-family: inherit;
+  text-align: start;
+  cursor: pointer;
+  transition: background-color v('duration-fast', 0.1s) v('ease', ease);
+
+  &:hover {
+    background: v('fill', rgba(0, 0, 0, 0.04));
+  }
+
+  /* 当前所在级别：主色淡底 + 勾选标记，菜单一打开就能看出「现在在哪一级」 */
+  &.#{is('selected')} {
+    background: v('color-primary-soft', rgba(0, 0, 0, 0.12));
+  }
+}
+
+.#{e('rich-text', 'heading-item-text')} {
+  /* 行高收到 1.3：H1 的 2em 字号在全高行距下会把菜单项撑得很高 */
+  line-height: 1.3;
+  white-space: nowrap;
+}
+
+.#{e('rich-text', 'heading-item-check')} {
+  flex-shrink: 0;
+  width: 16px;
+  height: 16px;
+  color: v('color-primary', #18181b);
+}
+
+/**
+ * 分组容器（对齐 TinyMCE 的 `tox-toolbar__group`）。
+ *
+ * 分组靠**内边距**而不是分割线来表达：TinyMCE 的工具条里没有竖线，
+ * 每个 `role="group"` 自己带左右 padding，组与组之间自然形成比组内更大的留白。
+ *
+ * ## 为什么用 `display: contents`
+ *
+ * 直接后果：组的盒子**不参与布局**，组里的按钮被提升为工具条的**直接 flex 项**，
+ * 于是它们能各自换行、把每一行的空隙填满。
+ *
+ * 这是被实测纠正过的结论 —— 先前试过两条路，都不通：
+ * 1. 组做成不可拆单元（`flex: 0 0 auto`）：一行放不下整个「列表与插入」组时，
+ *    整组被推到第二行，右边留下大片空白；
+ * 2. 给组加 `flex-wrap: wrap` + `min-width: 0`：**没有用**。`flex-wrap` 只影响
+ *    **组自己的子元素**如何排列，而组对工具条来说仍是**一个不可分割的 flex 项** ——
+ *    一行放不下它，整体仍然换行。实测（620px 宽、组宽 176px）第 1 行只用了 448px、
+ *    空着 160px，而 176px 的组照样被推到第 2 行。
+ *
+ * `display: contents` 是唯一能让「组的子元素参与父级换行」的做法。代价是组盒子消失，
+ * 所以组内/组间的**间距不能再用组的 padding 与 gap 表达** —— 改由每个按钮的
+ * margin 承担（见下方 `.g3-rich-text__button` 的 `margin-inline-end`），
+ * 并在组的首/末按钮上收掉外侧那一份。分组语义（`role="group"` + `aria-label`）不受影响。
+ */
+.#{e('rich-text', 'group')} {
+  display: contents;
+}
+
+/**
+ * 分组间距的承担者：每个按钮自己带右侧 margin。
+ *
+ * `display: contents` 之后不存在「组盒子」，间距只能落在按钮上：
+ * - **组内**（相邻按钮）：2px —— 按钮本身有 32px 的 hit 区、图标只占 18px，
+ *   视觉上已有充足留白，这里只补一点点让同组图标看起来是一簇；
+ * - **组间**（组的最后一个按钮）：再额外加 6px，合计 8px —— 与组内的 2px 形成 4 倍对比，
+ *   这就是「分组感」的全部来源（没有分割线）。
+ */
 .#{e('rich-text', 'button')} {
   flex-shrink: 0;
   width: 32px;
   height: 32px;
   padding: 0;
+  /* 组内间距 */
+  margin-inline-end: 2px;
   /**
    * 图标分量取「深色 + 标准描边」的组合：前景从 ghost 默认的 text-2（65% 黑）提到
-   * text-1（88%），描边保持 lucide 原生的 2（16px 显示 ≈ 1.33px）。
+   * text-1（88%），描边保持 lucide 原生的 2。
    *
-   * 之前试过把描边加到 2.5、甚至把图标放大到 24px，都会偏重；实测「发虚」的主因是
-   * 浅灰前景而不是线宽，所以只动颜色这一项最稳。
+   * 尺寸 16 → 18px：16px 下 lucide 的描边渲染成约 1.33px，配合 32px 的 hit 区显得偏轻；
+   * 18px 让图标在按钮里的占比更饱满（18 / 32），且描边约 1.5px，不必再动 stroke-width。
+   * （先前试过把描边加到 2.5、或放大到 24px 都偏重 —— 18px 是介于两者之间的档位。）
    */
   color: v('text-1', rgba(0, 0, 0, 0.88));
 
   svg {
-    width: 16px;
-    height: 16px;
+    width: 18px;
+    height: 18px;
   }
 
   &.#{is('active')} {
@@ -742,7 +1980,23 @@ const historyButtons: ToolButton[] = [
   }
 }
 
-/* 取色按钮：图标在上（16px）、当前色条在下（3px），竖排后 20px，24px 按钮里居中 */
+/**
+ * 组间间距：给每组**最后一个**直接子元素补足到 12px。
+ *
+ * 用 `:last-child` 而不是「给组加 padding-right」：组盒子已经 `display: contents`，
+ * 加 padding 不会生效。`> :last-child` 选中组内最后一个元素（按钮或 Popover 包装），
+ * 与按钮自身的 2px 叠加 —— 注意这里是**覆盖**而非相加，得到 12px（组内的 6 倍）。
+ */
+.#{e('rich-text', 'group')} > :last-child {
+  margin-inline-end: 12px;
+}
+
+/* 末组的最后一个按钮不需要外侧留白：工具条自身的 padding 已经给了 */
+.#{e('rich-text', 'group')}:last-child > :last-child {
+  margin-inline-end: 0;
+}
+
+/* 取色按钮：图标在上（18px）、当前色条在下（3px）竖排 */
 .#{e('rich-text', 'color-button')} {
   .#{e('button', 'content')} {
     flex-direction: column;
@@ -750,8 +2004,8 @@ const historyButtons: ToolButton[] = [
   }
 
   svg {
-    width: 16px;
-    height: 16px;
+    width: 18px;
+    height: 18px;
   }
 }
 
@@ -759,7 +2013,7 @@ const historyButtons: ToolButton[] = [
 .#{e('rich-text', 'color-bar')} {
   display: block;
   box-sizing: border-box;
-  width: 16px;
+  width: 18px;
   height: 3px;
   border-radius: 1px;
   background-image: linear-gradient(
@@ -844,25 +2098,45 @@ const historyButtons: ToolButton[] = [
   cursor: pointer;
 }
 
-/* 色块：白/浅色也要看得见边界，所以每个都加内描边；选中态用 outline，避免与内描边打架 */
+/**
+ * 色块：白/浅色也要看得见边界，所以每个都加内描边；选中态用 outline，避免与内描边打架。
+ *
+ * 尺寸 24px（= `--g3-control-height-sm`）：原先是 20px，是整条工具条里最小的点击目标
+ * （工具条按钮 32px、表格浮层 28px），低于 WCAG 2.2 目标尺寸建议的 24px 下限。
+ * 面板宽度随之从 10×20+9×4 = 236px 变成 10×24+9×4 = 276px，仍在 Popover 的常规宽度内。
+ *
+ * hover 用背景色变亮而不是 `transform: scale(1.1)`：缩放会让相邻色块在视觉上互相挤压
+ * （放大后越出自身盒子、盖住邻居），且 transform 是合成层动画，在密集小方块上会糊。
+ * 这里与工具条其余交互一致，用 0.2s 的颜色过渡。
+ */
 .#{e('rich-text', 'color-grid')} {
   display: grid;
-  grid-template-columns: repeat(10, 20px);
+  grid-template-columns: repeat(10, 24px);
   gap: v('space-1', 4px);
 }
 
 .#{e('rich-text', 'color-swatch')} {
   box-sizing: border-box;
-  width: 20px;
-  height: 20px;
+  width: 24px;
+  height: 24px;
   padding: 0;
   border: 0;
   border-radius: v('radius-sm', 4px);
+  /* 浅色块（#f5f5f5 等）在白底面板上几乎不可见，内描边是它们的唯一边界 */
   box-shadow: inset 0 0 0 1px rgb(0 0 0 / 8%);
   cursor: pointer;
+  transition: box-shadow v('duration', 0.2s) v('ease', ease);
 
   &:hover {
-    transform: scale(1.1);
+    /* 不描边、不改尺寸：只在原内描边外再叠一圈更深的环，色相不受影响 */
+    box-shadow:
+      inset 0 0 0 1px rgb(0 0 0 / 8%),
+      0 0 0 2px v('fill-hover', rgba(0, 0, 0, 0.08));
+  }
+
+  &:focus-visible {
+    outline: 2px solid v('color-primary', #18181b);
+    outline-offset: 1px;
   }
 
   &.#{is('active')} {
@@ -871,41 +2145,231 @@ const historyButtons: ToolButton[] = [
   }
 }
 
-/* 表格选择面板 */
+/* ---------- 表格选择面板（网格选择器）---------- */
 .#{e('rich-text', 'table-form')} {
   display: flex;
   flex-direction: column;
+  align-items: center;
   gap: v('space-2', 8px);
   padding: v('space-3', 12px);
 }
 
-/* 行 / 列数：label 与输入框上下排列 */
-.#{e('rich-text', 'table-field')} {
+/**
+ * 网格：8 行 × 10 列的方格矩阵。
+ *
+ * 格子 18px（含 2px 间隙后每格占 20px），整体宽 10 × 18 + 9 × 2 = 198px，
+ * 与链接面板（260px）同量级，在弹层里不显笨重；同时 18px 已经足够当点击目标 ——
+ * 这里靠「划一片」选取，不需要 32px 的单击精度。
+ */
+.#{e('rich-text', 'table-grid')} {
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+  /* 拖拽划选时不要选中文本 / 触发原生拖拽 */
+  user-select: none;
+}
+
+.#{e('rich-text', 'table-grid-row')} {
+  display: flex;
+  gap: 2px;
+}
+
+.#{e('rich-text', 'table-grid-cell')} {
+  box-sizing: border-box;
+  width: 18px;
+  height: 18px;
+  padding: 0;
+  border: 1px solid v('border-color', #d9d9d9);
+  border-radius: 2px;
+  background: v('bg-container', #fff);
+  cursor: pointer;
+  transition:
+    background-color v('duration-fast', 0.1s) v('ease', ease),
+    border-color v('duration-fast', 0.1s) v('ease', ease);
+
+  /* 已选中的格子：主色描边 + 淡底，形成连续矩形 */
+  &.#{is('table-grid-cell-active')} {
+    border-color: v('color-primary', #18181b);
+    background: v('color-primary-soft', rgba(0, 0, 0, 0.12));
+  }
+}
+
+/* 尺寸提示：等宽数字，避免 3 × 3 → 10 × 10 时文字宽度跳动 */
+.#{e('rich-text', 'table-grid-label')} {
+  margin: 0;
+  color: v('text-1', rgba(0, 0, 0, 0.88));
+  font-size: v('font-size', 14px);
+  font-variant-numeric: tabular-nums;
+  /* 固定高度：未悬停 / 悬停都占一行，面板不随提示文字长短抖动 */
+  line-height: 1.2;
+}
+
+.#{e('rich-text', 'table-header-toggle')} {
+  display: inline-flex;
+  align-items: center;
+  gap: v('space-1', 4px);
+  color: v('text-2', rgba(0, 0, 0, 0.65));
+  font-size: v('font-size-sm', 12px);
+  cursor: pointer;
+  user-select: none;
+}
+
+/* ---------- 列表样式面板 ---------- */
+/**
+ * 无序 / 有序列表按钮点右侧箭头后弹出的样式选择面板（对齐 TinyMCE 的 bullist / numlist 面板）。
+ *
+ * 结构：一个**网格** —— 每个格子 = 一个档位，画成 TinyMCE 同款的缩略图
+ * （`ListTypeIcon`：三条内容线 + 左侧项目符号 / 编号），下方是档位名。
+ * 当前档位打勾并高亮。一键建 / 撤列表由图标按钮承担（G3ButtonGroup 组合里的前一个按钮）。
+ */
+.#{e('rich-text', 'list-panel')} {
+  display: flex;
+  flex-direction: column;
+  gap: v('space-1', 4px);
+  padding: v('space-1', 4px);
+  min-width: 240px;
+}
+
+/**
+ * 分裂按钮里的箭头（「无序列表样式 / 有序列表样式」两个下拉的触发器）。
+ *
+ * 列表按钮用 G3ButtonGroup 组合「图标按钮 + 箭头按钮」：图标按钮是 32px 宽的主操作，
+ * 箭头按钮是 G3Dropdown 的触发器（点它打开样式面板）。箭头按钮刻意收窄到 **16px**，
+ * 让视觉重心留在左侧的列表图标上 —— 箭头只是「还能展开」的提示，不必与图标等宽。
+ *
+ * 边框 / 贴合 / 圆角 / hover 抬层全由 ButtonGroup 承担，这里只负责宽度与内边距。
+ *
+ * ⚠️ 三条覆写都要比 `.g3-rich-text__button` 更强才生效：
+ * - `width`：`.button` 写了 `width: 32px`，`.list-caret` 定义在它之后、同优先级，后写的赢；
+ * - `svg` 尺寸：`.button svg`（后代选择器，特异度 0-1-1）会压过单独的 `.list-caret-icon`
+ *   （0-1-0），所以这里必须写成 `.list-caret svg`（0-2-0）才盖得过去 —— 单写
+ *   `.list-caret-icon` 会被工具条默认的 18px 顶回，箭头就收不小。
+ */
+.#{e('rich-text', 'list-caret')} {
+  width: 16px;
+  min-width: 16px;
+  height: 32px;
+  padding: 0;
+
+  svg {
+    width: 12px;
+    height: 12px;
+    color: v('text-2', rgba(0, 0, 0, 0.65));
+  }
+}
+
+/* 网格：每行 3 个格子，图标在上、档位名在下 */
+.#{e('rich-text', 'list-grid')} {
+  display: grid;
+  grid-template-columns: repeat(3, 1fr);
+  gap: v('space-1', 4px);
+}
+
+.#{e('rich-text', 'list-item')} {
+  position: relative;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: v('space-1', 4px);
+  padding: v('space-2', 8px) v('space-1', 4px);
+  border: 1px solid transparent;
+  border-radius: v('radius-sm', 4px);
+  background: transparent;
+  color: v('text-1', rgba(0, 0, 0, 0.88));
+  cursor: pointer;
+  transition:
+    background-color v('duration-fast', 0.1s) v('ease', ease),
+    border-color v('duration-fast', 0.1s) v('ease', ease);
+
+  &:hover {
+    background: v('fill', rgba(0, 0, 0, 0.04));
+  }
+
+  /* 当前档位：主色淡底 + 主色描边，与全库选中态一致 */
+  &.#{is('selected')} {
+    background: v('color-primary-soft', rgba(0, 0, 0, 0.12));
+    border-color: v('color-primary', #18181b);
+  }
+}
+
+.#{e('rich-text', 'list-item-label')} {
+  font-size: v('font-size-sm', 12px);
+  line-height: 1.3;
+  text-align: center;
+  /* 长档位名（如「大写罗马数字」）在窄格子里换行而不是溢出 */
+  overflow-wrap: anywhere;
+}
+
+/* 选中勾：贴在格子右上角 */
+.#{e('rich-text', 'list-item-check')} {
+  position: absolute;
+  top: 2px;
+  right: 2px;
+  width: 14px;
+  height: 14px;
+  color: v('color-primary', #18181b);
+}
+
+/* ---------- 链接面板 ---------- */
+/**
+ * 与表格面板同一套视觉语言（label 在上、控件在下、底部通栏按钮），
+ * 两个面板都是「点工具条图标后弹出的小表单」，观感必须一致。
+ */
+.#{e('rich-text', 'link-form')} {
+  display: flex;
+  flex-direction: column;
+  gap: v('space-2', 8px);
+  padding: v('space-3', 12px);
+  /* 宽度给足：输入框里要能看清完整 URL（默认宽度下长链接只能看到头几个字符） */
+  width: 260px;
+}
+
+.#{e('rich-text', 'link-field')} {
   display: flex;
   flex-direction: column;
   gap: v('space-1', 4px);
 }
 
-.#{e('rich-text', 'table-label')} {
+.#{e('rich-text', 'link-label')} {
   color: v('text-2', rgba(0, 0, 0, 0.65));
   font-size: v('font-size-sm', 12px);
 }
 
-.#{e('rich-text', 'table-input')} {
-  box-sizing: border-box;
-  width: 100%;
-  height: v('control-height-sm', 24px);
-  padding: 0 v('space-2', 8px);
-  border: 1px solid v('border-color', #d9d9d9);
-  border-radius: v('radius-sm', 4px);
-  background: v('bg-container', #fff);
-  color: v('text-1', rgba(0, 0, 0, 0.88));
-  font-size: v('font-size', 14px);
-  outline: none;
+/**
+ * 操作区：一行 —— 「移除链接」靠左，「取消 / 确定」成对靠右。
+ *
+ * 用 `justify-content: space-between` 而不是让两组各占一半：编辑态下左侧只有
+ * 「移除链接」、非编辑态下左侧为空，靠右的两个按钮位置始终不变（不会被左侧内容挤动），
+ * 这是对话框类 UI 的常规预期 —— 主操作的位置应当稳定。
+ */
+.#{e('rich-text', 'link-actions')} {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: v('space-2', 8px);
+  /* 与上方字段拉开一点：操作区是「决定」，不该和输入框挤在一起 */
+  margin-top: v('space-1', 4px);
+}
 
-  &:focus {
-    border-color: v('color-primary', #18181b);
-    box-shadow: 0 0 0 2px v('color-primary-ring', rgba(24, 24, 27, 0.2));
+.#{e('rich-text', 'link-actions-main')} {
+  display: flex;
+  /* 右侧成对按钮内部间距，比字段间距小一点，视觉上成组 */
+  gap: v('space-2', 8px);
+  margin-inline-start: auto;
+}
+
+/**
+ * 面板里的输入框 = `G3Input`，这里只补一件它管不到的事：撑满字段宽度。
+ *
+ * 之前这里手抄了一整套 input 外观（height / padding / border / border-radius /
+ * `:focus` 聚焦环），是「库内文本控件只该有一种长相」的反例 —— 抄来的副本不会跟着
+ * `G3Input` 演进，上游改聚焦环它就过期了。现在这些全部由 `G3Input` 自带。
+ */
+.#{e('rich-text', 'link-field')} {
+  .#{b('input')} {
+    width: 100%;
+    /* 链接地址：URL 是本面板唯一的输入目标，给到常规控件高度 */
+    min-height: v('control-height', 32px);
   }
 }
 </style>
diff --git a/code/g3soft-libs/packages/ui/src/rich-text/extensions.test.ts b/code/g3soft-libs/packages/ui/src/rich-text/extensions.test.ts
new file mode 100644
index 00000000..225485db
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/rich-text/extensions.test.ts
@@ -0,0 +1,87 @@
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { describe, expect, it } from 'vitest'
+import {
+  BACKGROUND_COLOR_VARS,
+  DEFAULT_BACKGROUND_COLOR_VALUES,
+  DEFAULT_FONTS,
+  DEFAULT_FONT_SIZES,
+  DEFAULT_TEXT_COLOR_VALUES,
+  TEXT_COLOR_VARS,
+} from './extensions'
+
+/**
+ * 色板的一致性校验。
+ *
+ * 背景：取色面板的色块由「变量名数组」和「默认值数组」按**下标**配对拼出
+ * （见 Toolbar 的 `toSwatches`）。两个数组一旦不等长，后果是静默的 ——
+ *   - 变量多、值少：`values[index]` 为 undefined，兜底成黑色，色板末尾多出几个黑块；
+ *   - 值多、变量少：多出来的色值直接消失，宿主看不到任何提示。
+ * 这类错误在浏览器里只是「颜色不太对」，靠肉眼很难发现，所以在单测里锁死。
+ *
+ * 另外校验 SCSS 侧声明的默认值与 TS 侧一致：色块实际渲染的是
+ * `var(--g3-xxx, 兜底值)`，样式表里存在该变量时以 CSS 为准 —— 两边不一致会导致
+ * 「TS 里写红色、面板显示成灰色」这种极难排查的偏差。
+ *
+ * 读文件而不是 import SCSS：vitest 不处理 .scss，且我们只需要其中的变量名 / 值文本。
+ */
+
+const TOOLBAR_SCSS = readFileSync(
+  resolve(process.cwd(), 'src/rich-text/Toolbar.vue'),
+  'utf8',
+)
+
+/** 从 Toolbar.vue 的样式块里取某个 CSS 变量的默认值 */
+function scssDefaultValue(varName: string): string | undefined {
+  // 形如：#{css-var('rich-text-swatch-text-1')}: #000000;
+  const pattern = new RegExp(`css-var\\('${varName}'\\)\\}\\s*:\\s*([^;]+);`)
+  return pattern.exec(TOOLBAR_SCSS)?.[1]?.trim()
+}
+
+describe('RichText 色板', () => {
+  it('变量名与默认值数量一致（10 个文字色 + 10 个背景色）', () => {
+    expect(TEXT_COLOR_VARS).toHaveLength(10)
+    expect(DEFAULT_TEXT_COLOR_VALUES).toHaveLength(10)
+    expect(BACKGROUND_COLOR_VARS).toHaveLength(10)
+    expect(DEFAULT_BACKGROUND_COLOR_VALUES).toHaveLength(10)
+  })
+
+  it('默认值都是合法 hex（写进文档前要能解析）', () => {
+    for (const value of [...DEFAULT_TEXT_COLOR_VALUES, ...DEFAULT_BACKGROUND_COLOR_VALUES]) {
+      expect(value).toMatch(/^#[0-9a-f]{6}$/i)
+    }
+  })
+
+  it('SCSS 里为每个变量都声明了同名默认值，且取值与 TS 一致', () => {
+    const pairs: [string[], string[]][] = [
+      [TEXT_COLOR_VARS, DEFAULT_TEXT_COLOR_VALUES],
+      [BACKGROUND_COLOR_VARS, DEFAULT_BACKGROUND_COLOR_VALUES],
+    ]
+    for (const [varNames, values] of pairs) {
+      varNames.forEach((varName, index) => {
+        const declared = scssDefaultValue(varName)
+        expect(declared, `Toolbar.vue 样式块缺少 ${varName} 的默认值声明`).toBeDefined()
+        expect(declared, `${varName} 的 SCSS 默认值与 TS 不一致`).toBe(values[index])
+      })
+    }
+  })
+})
+
+describe('RichText 字体 / 字号预设', () => {
+  it('字体表非空，且每项都有 label 与 value', () => {
+    expect(DEFAULT_FONTS.length).toBeGreaterThan(0)
+    for (const font of DEFAULT_FONTS) {
+      expect(font.label).toBeTruthy()
+      // value 允许为空串（「默认」项用它表示「不设置 font-family」）
+      expect(typeof font.value).toBe('string')
+    }
+  })
+
+  it('字号表非空，value 都是合法的 CSS 长度', () => {
+    expect(DEFAULT_FONT_SIZES.length).toBeGreaterThan(0)
+    for (const size of DEFAULT_FONT_SIZES) {
+      expect(size.label).toBeTruthy()
+      expect(size.value).toMatch(/^\d+(\.\d+)?(px|rem|em)$/)
+    }
+  })
+})
diff --git a/code/g3soft-libs/packages/ui/src/rich-text/extensions.ts b/code/g3soft-libs/packages/ui/src/rich-text/extensions.ts
index e415071d..ad1827ef 100644
--- a/code/g3soft-libs/packages/ui/src/rich-text/extensions.ts
+++ b/code/g3soft-libs/packages/ui/src/rich-text/extensions.ts
@@ -1,7 +1,8 @@
-import type { Extensions } from '@tiptap/core'
+import { mergeAttributes, type Extensions } from '@tiptap/core'
 import StarterKit from '@tiptap/starter-kit'
 import Image from '@tiptap/extension-image'
 import Link from '@tiptap/extension-link'
+import { OrderedList } from '@tiptap/extension-list'
 import Placeholder from '@tiptap/extension-placeholder'
 import Subscript from '@tiptap/extension-subscript'
 import Superscript from '@tiptap/extension-superscript'
@@ -29,7 +30,11 @@ export function createExtensions(props: Pick<RichTextProps, 'placeholder' | 'upl
       codeBlock: false,
       // 链接已在下方单独配置 openOnClick，这里关闭 starter-kit 内置的默认 link
       link: false,
+      // 有序列表换成下面的 OrderedListWithGreek（补了「小写希腊字母」档位的读写），
+      // starter-kit 内置的那份必须关掉，否则同名扩展重复注册会直接报错
+      orderedList: false,
     }),
+    OrderedListWithGreek,
     Link.configure({
       openOnClick: false,
       autolink: true,
@@ -89,6 +94,143 @@ export const DEFAULT_FONTS = [
   { label: 'Times New Roman', value: 'Times New Roman, serif' },
 ] satisfies { label: string; value: string }[]
 
+/**
+ * 无序列表的项目符号样式（对应 `<ul type="…">`）。
+ *
+ * TinyMCE 的 bullist 提供 default / disc / circle / square 四档，这里一一对齐。
+ *
+ * `value` 是**写进文档的属性值**，不是给 CSS 用的字面量：
+ * - `default` 不写 `type` 属性（用空串表示），走浏览器 / 组件样式的默认圆点 ——
+ *   与 Word 一样，「默认」应当是一个**没有额外声明**的状态，而不是显式写 `disc`；
+ * - `glyph` 是下拉面板里画出来的**真实符号**：面板要能让人一眼看出「点」和「方块」的区别，
+ *   只写「disc / circle / square」这种英文枚举等于让用户去记单词。
+ */
+export const DEFAULT_BULLET_LIST_TYPES = [
+  { label: '默认', value: '', glyph: '•' },
+  { label: '实心圆点', value: 'disc', glyph: '•' },
+  { label: '空心圆圈', value: 'circle', glyph: '○' },
+  { label: '实心方块', value: 'square', glyph: '■' },
+] satisfies { label: string; value: string; glyph: string }[]
+
+/**
+ * 有序列表的编号样式（对应 `<ol type="…">`）。
+ *
+ * TinyMCE 的 numlist 提供 default / lower alpha / lower roman / lower greek /
+ * upper roman / upper alpha 六档，这里一一对齐。
+ *
+ * ⚠️ **`lower greek` 在 HTML 里没有原生对应值**：`<ol type>` 规范只认 `1 / a / A / i / I`
+ * 五种。TinyMCE 之所以有这一档，是因为它把编号渲染在自己的样式层里。本组件输出的是
+ * 干净的 HTML（邮件正文等场景要直接取用），所以这一档用 `list-style-type: lower-greek`
+ * 的**内联样式**表达（见 `ORDERED_LIST_CSS_ONLY_TYPES`）—— 属性值取 `lower-greek`，
+ * 落进文档时转成样式而不是 `type` 属性，否则浏览器会当作非法值忽略、静默退回数字编号。
+ */
+export const DEFAULT_ORDERED_LIST_TYPES = [
+  { label: '默认', value: '', glyph: '1.' },
+  { label: '小写字母', value: 'a', glyph: 'a.' },
+  { label: '小写罗马数字', value: 'i', glyph: 'i.' },
+  { label: '小写希腊字母', value: 'lower-greek', glyph: 'α.' },
+  { label: '大写罗马数字', value: 'I', glyph: 'I.' },
+  { label: '大写字母', value: 'A', glyph: 'A.' },
+] satisfies { label: string; value: string; glyph: string }[]
+
+/**
+ * 有序列表里「必须用 CSS 表达」的编号样式。
+ *
+ * 目前只有小写希腊字母：`<ol type="lower-greek">` 不是合法 HTML 属性值，浏览器会
+ * 当作未知值忽略、退回阿拉伯数字。TinyMCE 同款档位在它的样式层里能画出来，我们
+ * 输出纯 HTML 时只能落到 `list-style-type` 上。
+ *
+ * 读写两端都由下面的 `OrderedListWithGreek` 补齐，所以这一档能与其它档位一样
+ * 完整往返（设置 → 保存 → 重新载入）。
+ */
+export const ORDERED_LIST_CSS_ONLY_TYPES = ['lower-greek'] satisfies string[]
+
+/** 属性值 → 写进 `style` 的 `list-style-type` 值（仅 CSS-only 档位需要） */
+export function orderedListTypeToStyle(type: string): string | null {
+  return ORDERED_LIST_CSS_ONLY_TYPES.includes(type) ? type : null
+}
+
+/**
+ * 有序列表扩展：在官方 OrderedList 之上补两件事，专门服务「小写希腊字母」这一档。
+ *
+ * 官方的 `type` 属性有两个缺口，不补的话这一档只做对一半：
+ *
+ * 1. **写出去会生成非法 HTML**：官方 `renderHTML` 对任何非 `"1"` 的 type 都写成
+ *    `type` 属性，于是 `lower-greek` 变成 `<ol type="lower-greek">` —— 浏览器不认，
+ *    静默退回数字编号，导出的邮件里看不到希腊字母；
+ * 2. **读回来会丢**：官方 `parseHTML` 里把 `style` 映射回 type 的
+ *    `cssListStyleTypeToHtmlType()` 只认 roman / alpha 六种写法，没有 `lower-greek`
+ *    分支，返回 null 后该属性就没了。
+ *
+ * 所以这里覆写 `renderHTML`（CSS-only 档位改写 `style`、不写非法 `type`）与
+ * `addAttributes().type.parseHTML`（先按官方逻辑走，官方认不出时补认 `lower-greek`）。
+ * 其余五个档位的行为与官方完全一致，不受影响。
+ */
+export const OrderedListWithGreek = OrderedList.extend({
+  addAttributes() {
+    /**
+     * 官方 OrderedList 的属性定义。
+     *
+     * `this.parent?.()` 由 Tiptap 的 `getExtensionField` 注入（返回**已解析的**父扩展字段值，
+     * 即官方那个 `{ start, type }` 对象），但类型上只知道是个 `` —— 这里补一个显式形状，
+     * 否则拿不到 `.type`。属性定义里 `parseHTML` 的签名在 Tiptap 内部是宽泛的
+     * `(element: HTMLElement) => any`，这里按用到的部分结构化声明即可。
+     */
+    type AttributeSpec = {
+      default?: unknown
+      parseHTML?: (element: HTMLElement) => unknown
+      [key: string]: unknown
+    }
+
+    const parent = (this.parent?.() ?? {}) as Record<string, AttributeSpec>
+    const officialType = parent.type
+    if (!officialType) return parent
+
+    return {
+      ...parent,
+      type: {
+        ...officialType,
+        parseHTML: (element: HTMLElement) => {
+          // 官方逻辑优先：`type` 属性、roman / alpha 的 style、首个 li 的 style
+          const parsed = officialType.parseHTML?.(element)
+          if (parsed) return parsed
+
+          // 官方认不出的 CSS-only 档位：直接读 style 里的 list-style-type
+          const style = element.getAttribute('style')
+          const match = style?.match(/list-style-type\s*:\s*([^;]+)/i)
+          const cssValue = match?.[1]?.trim().toLowerCase()
+          return cssValue && orderedListTypeToStyle(cssValue) ? cssValue : null
+        },
+      },
+    }
+  },
+  renderHTML({ HTMLAttributes }) {
+    const { start, type, ...rest } = HTMLAttributes as {
+      start?: number
+      type?: string | null
+      [key: string]: unknown
+    }
+
+    // CSS-only 档位：不写 `type` 属性，改写内联 style
+    const cssType = type ? orderedListTypeToStyle(type) : null
+    if (cssType) {
+      const style = typeof rest.style === 'string' ? rest.style : ''
+      const merged = style
+        ? `${style.replace(/;?\s*$/, ';')} list-style-type: ${cssType};`
+        : `list-style-type: ${cssType};`
+      const attrs = mergeAttributes(this.options.HTMLAttributes, rest, { style: merged })
+      if (typeof start === 'number' && start !== 1) attrs.start = start
+      return ['ol', attrs, 0]
+    }
+
+    // 其余档位与官方实现一致
+    const attrs = mergeAttributes(this.options.HTMLAttributes, rest)
+    if (typeof start === 'number' && start !== 1) attrs.start = start
+    if (type && type !== '1') attrs.type = type
+    return ['ol', attrs, 0]
+  },
+})
+
 /** 预设字号列表 */
 export const DEFAULT_FONT_SIZES = [
   { label: '12px', value: '12px' },
@@ -102,11 +244,56 @@ export const DEFAULT_FONT_SIZES = [
 ] satisfies { label: string; value: string }[]
 
 /**
- * 字体颜色预设色板：黑 / 灰两档中性色 + 常用彩色（取 Ant Design 的 6 号色）。
+ * 预设色板的 CSS 变量名（不含 `--g3-` 前缀，由 Toolbar 用命名空间拼出）。
  *
- * 只放一屏能看全的量（10 个 = 面板一行），需要其它颜色时用面板里的「自定义」取色器。
+ * 为什么色值要走变量而不是直接写 hex：
+ * - 写死的 hex 在暗色主题下毫无办法 —— `theme.scss` 只翻 `--g3-text-*` / `--g3-bg-*`
+ *   这类语义变量，翻不到 TS 常量里的字面量，取色面板于是永远是「亮色面板」；
+ * - 宿主想整体换一套品牌色板（或按暗色换一套变体）时，不必改组件代码、不必发版，
+ *   覆盖 `--g3-rich-text-swatch-text-3` 之类的变量即可。
+ *
+ * ## 色值本身保持不变
+ *
+ * 变量化只解决「可覆盖」，不改默认观感：默认值仍是文档里反复出现的 Ant Design 色阶
+ * （文字色取 6 号色、背景色取 1 号色），已发布文档的渲染结果不会因为这次改动而变化。
+ * 暗色下**不自动换一套色值** —— 正文颜色是文档内容的一部分，同一份 HTML 在不同主题下
+ * 显示成不同颜色会让「所见即所得」失效。需要暗色调色板的宿主自行覆盖这些变量。
  */
-export const DEFAULT_TEXT_COLORS = [
+export const TEXT_COLOR_VARS = [
+  'rich-text-swatch-text-1',
+  'rich-text-swatch-text-2',
+  'rich-text-swatch-text-3',
+  'rich-text-swatch-text-4',
+  'rich-text-swatch-text-5',
+  'rich-text-swatch-text-6',
+  'rich-text-swatch-text-7',
+  'rich-text-swatch-text-8',
+  'rich-text-swatch-text-9',
+  'rich-text-swatch-text-10',
+] satisfies string[]
+
+/** 背景色板同上（10 个浅色档） */
+export const BACKGROUND_COLOR_VARS = [
+  'rich-text-swatch-bg-1',
+  'rich-text-swatch-bg-2',
+  'rich-text-swatch-bg-3',
+  'rich-text-swatch-bg-4',
+  'rich-text-swatch-bg-5',
+  'rich-text-swatch-bg-6',
+  'rich-text-swatch-bg-7',
+  'rich-text-swatch-bg-8',
+  'rich-text-swatch-bg-9',
+  'rich-text-swatch-bg-10',
+] satisfies string[]
+
+/**
+ * 色板的**默认值**（与变量一一对应、同序）。
+ *
+ * 与变量名分开导出：Toolbar 用 `useNamespace().cssVar()` 拼出当前命名空间下的变量名，
+ * 这里只提供「哪个变量该是什么颜色」。两个数组必须等长、同序 —— 长度不一致时
+ * Toolbar 传色板给面板时会直接缺项，由单测 `extensions.test.ts` 兜住。
+ */
+export const DEFAULT_TEXT_COLOR_VALUES = [
   '#000000',
   '#434343',
   '#8c8c8c',
@@ -119,11 +306,7 @@ export const DEFAULT_TEXT_COLORS = [
   '#eb2f96',
 ] satisfies string[]
 
-/**
- * 背景颜色预设色板：全部取浅色档（Ant Design 的 1 号色），
- * 深底会把正文文字盖掉 —— 背景色是「标记重点」而非「反色」。
- */
-export const DEFAULT_BACKGROUND_COLORS = [
+export const DEFAULT_BACKGROUND_COLOR_VALUES = [
   '#f5f5f5',
   '#fff1f0',
   '#fff7e6',
diff --git a/code/g3soft-libs/packages/ui/src/rich-text/format.ts b/code/g3soft-libs/packages/ui/src/rich-text/format.ts
new file mode 100644
index 00000000..b4092f12
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/rich-text/format.ts
@@ -0,0 +1,237 @@
+import type { Editor } from '@tiptap/core'
+import type { Node as ProseMirrorNode } from '@tiptap/pm/model'
+
+/**
+ * 整理格式（TinyMCE 的「清理格式 / Remove formatting」+ Word 的「清除格式」那一类操作）。
+ *
+ * ## 它不是什么
+ *
+ * 它**不是**工具条上的「橡皮擦」`unsetAllMarks()` —— 那个只作用于**选区**、且只管
+ * 行内记号（加粗、颜色、链接），段落级的东西（空段落、多余空行、对齐、层级）一律不动。
+ * 这里做的是通篇的结构整理，作用范围是**整篇文档**，不需要先选中。
+ *
+ * ## 清理项（以及每一项为什么值得清）
+ *
+ * 富文本正文的绝大部分脏数据来自「从 Word / 网页 / 邮件里粘贴」：
+ * 1. **空段落**：粘贴后常见 `<p></p>` 连排，视觉上是一大块空白，但用户按退格删不掉
+ *    （光标会跳过去），因为它们是真实节点；
+ * 2. **连续空行**：空段落连在一起，等价于上面的问题但更集中，压成一个；
+ * 3. **行内空白残留**：`<p>   </p>` 里的空格让「看起来是空的」段落躲过空段落判断；
+ * 4. **无内容的内联记号**：`<strong></strong>`、空的 `<span style="color:…">`，
+ *    Word 粘贴的重灾区，会在正文里留下看不见的样式片段。
+ *
+ * ## 为什么用 ProseMirror 事务而不是正则改 HTML
+ *
+ * 直接对 HTML 字符串跑正则（`replace(/<p><\/p>/g, '')`）看起来更短，但它对**嵌套**与
+ * **属性顺序**都不安全：`<p><span></span></p>` 不是空段落但正则可能误伤，
+ * 而 `<p style="text-align:center"></p>` 里的属性会让简单的 `<p></p>` 匹配失效。
+ * 走事务则是在**文档模型**上判断 —— 「这个段落节点的 `content.size === 0`」是精确的、
+ * 与序列化形式无关的判据，而且天生只改需要改的地方、其余内容原样保留。
+ *
+ * ## 关于「保留内容」的边界
+ *
+ * 整理**只删真正的空**：段落里只要还有一个可见字符（含 `&nbsp;` 之外的空白判断见下），
+ * 就原样保留。图片 / 视频 / 表格 / 分割线都是叶子或含内容的节点，不受「空段落」判据影响
+ * —— 一个只含 `<img>` 的段落 `content.size` 不为 0，会被正确保留。
+ */
+export interface FormatCleanupResult {
+  /** 删掉的空段落数（含被压掉的空行） */
+  removedEmptyParagraphs: number
+  /** 去掉的空白文本节点数（`<p>a<span> </span>b</p>` 里那种只有空格的片段） */
+  trimmedBlankTexts: number
+  /** 取消掉的空行内记号数（`<strong> </strong>` 之类挂了个寂寞的 mark） */
+  removedEmptyMarks: number
+  /** 是否有任何改动（false 时不需要 dispatch，避免污染撤销栈） */
+  changed: boolean
+}
+
+/**
+ * 判断一个文本节点是否「视觉上为空」—— 只有空白字符。
+ *
+ * ⚠️ **必须把 `\u00a0`（不间断空格）算作空白**：Word / 网页粘贴的空段落里经常放的是
+ * `&nbsp;` 而不是普通空格，只判 `\s` 的话（JS 的 `\s` 确实包含 `\u00a0`，但这里
+ * 显式写出来是为了让意图可见、不依赖实现细节）会漏掉，表现为「点了整理格式但空行还在」。
+ */
+function isBlankText(text: string): boolean {
+  return /^[\s\u00a0\u200b]*$/.test(text)
+}
+
+/** 段落类节点名：只有这些「装文字的块」才参与空段落清理，表格单元格等不碰 */
+const TEXT_BLOCK_TYPES = new Set(['paragraph', 'heading'])
+
+/**
+ * 清理文档里的空段落 / 空行内记号。
+ *
+ * @returns 清理统计；`changed === false` 时调用方**不应** dispatch（保持撤销栈干净）
+ *
+ * 实现方式是**一次遍历收集所有待删区间，最后合成一个事务**：
+ * 逐个 dispatch 会让撤销栈里出现 N 步（用户按一次 Ctrl+Z 只撤销掉一个空行的删除，
+ * 得按十几次才能退回原状）—— 一次事务 = 一步撤销，符合「整理格式」是一次操作的直觉。
+ */
+export function cleanupFormat(editor: Editor): FormatCleanupResult {
+  const { state } = editor
+  const { doc, schema } = state
+
+  const result: FormatCleanupResult = {
+    removedEmptyParagraphs: 0,
+    trimmedBlankTexts: 0,
+    removedEmptyMarks: 0,
+    changed: false,
+  }
+
+  /**
+   * 待删除的区间集合（`{ from, to }`）。
+   *
+   * 用「文档位置区间」而不是节点引用：事务删除时位置会变，但**同一事务内**的多个
+   * 区间只要按 `from` **从后往前**删就不会互相影响（后面的删除不影响前面的偏移）。
+   */
+  const ranges: { from: number; to: number }[] = []
+
+  /**
+   * 标记段落是否「含有有意义的内容」。
+   *
+   * 判据是递归看子树里有没有：非空文本、或非文本叶子（图片 / 视频 / 分割线 / 硬换行）。
+   * 只看 `content.size === 0` 不够 —— `<p><strong> </strong></p>` 的 size 不为 0，
+   * 但整段视觉上是空的。
+   */
+  function hasMeaningfulContent(node: ProseMirrorNode): boolean {
+    if (node.isText) return !isBlankText(node.text ?? '')
+    if (node.isLeaf) return true // 图片 / 视频 / hr / hardBreak 都算有内容
+    let found = false
+    node.forEach((child) => {
+      if (!found && hasMeaningfulContent(child)) found = true
+    })
+    return found
+  }
+
+  /**
+   * 遍历整篇文档，收集空段落区间。
+   *
+   * `descendants` 的回调给出的是**每个节点的绝对位置**（相对于文档起点），
+   * 所以 `pos` 就是段落节点的起点、`pos + node.nodeSize` 是终点。
+   */
+  doc.descendants((node, pos) => {
+    // 只要「装文字的块」；且必须是空的
+    if (TEXT_BLOCK_TYPES.has(node.type.name) && !hasMeaningfulContent(node)) {
+      ranges.push({ from: pos, to: pos + node.nodeSize })
+      result.removedEmptyParagraphs += 1
+      // 空段落内部不可能再有需要清理的东西，跳过其子树
+      return false
+    }
+
+    /**
+     * 清理**只有空白的文本节点**。
+     *
+     * ProseMirror 里通常不存在「完全空的文本节点」（会被归一化掉），但**只有空白**的
+     * 文本节点是可以存在的 —— 它们正是「看起来空、按退格却删不掉」的元凶
+     * （`<p>   </p>` 里那三个空格）。
+     *
+     * 注意这**不算作「空段落」**：它是段落里的内容，不是段落本身。
+     * 只含空白文本的段落会被上面那个分支整段收走（`hasMeaningfulContent` 判为 false，
+     * 且 `return false` 已跳过子树），所以走到这里的是「段内混着空白文本」的情况，
+     * 比如 `<p>a<span> </span>b</p>`。
+     */
+    const blankNode = node.isText && isBlankText(node.text ?? '')
+    if (blankNode) {
+      ranges.push({ from: pos, to: pos + node.nodeSize })
+      result.trimmedBlankTexts += 1
+      return false
+    }
+
+    return true
+  })
+
+  /**
+   * 空的 mark 覆盖区间（`<strong> </strong>` 这类）。
+   *
+   * mark 不是节点、删不掉「mark 本身」，只能对它覆盖的区间调 `removeMark`。
+   * 判据：某个文本节点**整体是空白**，那它身上的每个 mark 都是「挂了个寂寞」。
+   *
+   * 这些区间不参与上面的段落 `ranges` 合并 —— 两者是不同的操作（删节点 vs 取消标记），
+   * 但**位置会一起变**：因为最终是同一个事务，先删节点会让 mark 区间的坐标失效。
+   * 所以下面统一按「从后往前」执行，且 mark 区间用**事务映射后**的位置。
+   */
+  const markRanges: { from: number; to: number; markName: string }[] = []
+  doc.descendants((node, pos) => {
+    if (!node.isText) return true
+    const text = node.text ?? ''
+    if (!text || !isBlankText(text)) return true
+    for (const mark of node.marks) {
+      markRanges.push({ from: pos, to: pos + node.nodeSize, markName: mark.type.name })
+    }
+    return true
+  })
+
+  if (ranges.length === 0 && markRanges.length === 0) return result
+
+  /**
+   * 合成一个事务。
+   *
+   * **必须先按位置从后往前删**：一个事务里的每个 `delete` 都会改变后续位置的含义，
+   * 从后往前才能保证前面那些区间的 `from` / `to` 仍然有效（这是 ProseMirror
+   * 事务里处理多区间的通用做法）。
+   */
+  const tr = state.tr
+
+  /**
+   * 合并重叠 / 嵌套区间，再按位置**从后往前**删。
+   *
+   * `doc.descendants` 会把「空段落」和「它内部的空白文本」都收进 ranges，
+   * 于是天然出现 `[5,8]`（段落）与 `[6,7]`（段内空白文本）这种**嵌套**区间；
+   * 也可能出现两个区间部分重叠。直接逐个 `delete` 会因为区间重叠而删出错位的内容
+   * （后一个 `delete` 的坐标在前一次删除后已经失去意义）。
+   *
+   * 正确做法是先做一次**区间归一化**：按 `from` 升序排好，把「起点落在上一个区间内」
+   * 的区间吸收掉（端点取两者的最大值），得到一组**互不相交**的区间；
+   * 之后从后往前删就不会互相影响。
+   *
+   * 之前这里用的是「从后往前扫 + 维护一个游标」的写法，逻辑是反的 ——
+   * `[5,8]` 与 `[6,7]` 处理时会把**外层段落**判为「已被覆盖」而跳过、
+   * 只删了里面那段空白文本，结果是段落根本没被清掉。归一化写法没有这个歧义。
+   */
+  const merged: { from: number; to: number }[] = []
+  for (const range of [...ranges].sort((a, b) => a.from - b.from || a.to - b.to)) {
+    const last = merged[merged.length - 1]
+    if (last && range.from <= last.to) {
+      // 与上一个区间相交或嵌套 → 合并（终点取更远的那个）
+      last.to = Math.max(last.to, range.to)
+      continue
+    }
+    merged.push({ ...range })
+  }
+
+  // 从后往前删：后面的删除不会影响前面区间的坐标
+  for (const range of [...merged].sort((a, b) => b.from - a.from)) {
+    tr.delete(range.from, range.to)
+  }
+
+  /**
+   * 空的 mark：对其覆盖范围取消该 mark。
+   *
+   * ⚠️ **顺序很关键**：`markRanges` 里的位置是**删除前**的坐标，而现在事务里已经
+   * 执行过节点删除 —— 直接用原坐标会落到错误的位置（表现为「取消了一个别处的加粗」）。
+   * 所以每次 `removeMark` 之前，先用 `tr.mapping` 把原区间映射到当前文档坐标。
+   *
+   * 从后往前处理同样是为了让映射更直观：靠后的区间不受前面删除的影响。
+   * 映射后区间长度可能变成 0（该文本节点已被当作空白删掉）—— 这类直接跳过，
+   * 因为节点都没了，它身上的 mark 自然也没了。
+   */
+  for (const item of [...markRanges].sort((a, b) => b.from - a.from)) {
+    const markType = schema.marks[item.markName]
+    if (!markType) continue
+
+    const from = tr.mapping.map(item.from, -1)
+    const to = tr.mapping.map(item.to, 1)
+    if (to <= from) continue // 已被删除，无需取消标记
+
+    tr.removeMark(from, to, markType)
+    result.removedEmptyMarks += 1
+  }
+
+  if (tr.docChanged) {
+    result.changed = true
+    editor.view.dispatch(tr)
+  }
+
+  return result
+}
diff --git a/code/g3soft-libs/packages/ui/src/rich-text/index.ts b/code/g3soft-libs/packages/ui/src/rich-text/index.ts
index 71bc7127..2a712eea 100644
--- a/code/g3soft-libs/packages/ui/src/rich-text/index.ts
+++ b/code/g3soft-libs/packages/ui/src/rich-text/index.ts
@@ -6,4 +6,15 @@ export type {
   RichTextUploadResult,
   RichTextFontOption,
   RichTextFontSizeOption,
+  RichTextListTypeOption,
+  RichTextCleanupResult,
 } from './types'
+
+/**
+ * 列表样式的内置选项 —— 宿主想「只给其中几档」或换成本地化文案时，
+ * 以它为基础裁剪后传给 `bullet-list-types` / `ordered-list-types`。
+ */
+export {
+  DEFAULT_BULLET_LIST_TYPES,
+  DEFAULT_ORDERED_LIST_TYPES,
+} from './extensions'
diff --git a/code/g3soft-libs/packages/ui/src/rich-text/print.ts b/code/g3soft-libs/packages/ui/src/rich-text/print.ts
new file mode 100644
index 00000000..215536ac
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/rich-text/print.ts
@@ -0,0 +1,177 @@
+/**
+ * 预览与打印 —— 两个都要求「只呈现正文 HTML」，但出现在完全不同的地方。
+ *
+ * ## 预览
+ *
+ * 直接在模态框里用 `v-html` 渲染当前 HTML（见 PreviewDialog.vue）。
+ * 不走 `window.open`：嵌入式 WebView / iframe 里新窗口常被拦截，且 E2E 要处理多页；
+ * 模态框复用库内 G3Modal，观感与全库一致、也能断言。
+ *
+ * ## 打印
+ *
+ * 用**隐藏 iframe** 装载正文 HTML，再调 `iframe.contentWindow.print()`。
+ * 不直接 `window.print()` 打印当前页面 —— 那会把宿主页面的导航、按钮、工具条
+ * 一起打出来；也要临时把编辑器切只读/隐藏再 `window.print()` 的做法，那会依赖
+ * 调用方的页面结构，且打印期间页面会闪。
+ *
+ * TinyMCE 的 print 插件走的是同一套思路（打开一个只含正文的文档再打印）。
+ */
+
+/**
+ * 打印用的基础样式。
+ *
+ * 刻意**从简**且不引组件样式表：打印时要的是「像文档」而不是「像编辑器」——
+ * 页边距交给 `@page`，正文只保留必要的排版（标题层级、列表缩进、表格边框、
+ * 图片不溢出）。把编辑器的 `.tiptap` 那一整套样式搬进去反而会把屏幕上的
+ * 交互样式（hover、聚焦环、占位符）也带进纸面。
+ */
+const PRINT_STYLES = `
+  @page { margin: 16mm; }
+  html, body { margin: 0; padding: 0; }
+  body {
+    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Microsoft YaHei', sans-serif;
+    font-size: 14px;
+    line-height: 1.6;
+    color: #000;
+  }
+  p { margin: 0 0 0.25em; }
+  h1 { font-size: 2em; font-weight: 600; line-height: 1.3; margin: 0.5em 0 0.25em; }
+  h2 { font-size: 1.5em; font-weight: 600; line-height: 1.3; margin: 0.5em 0 0.25em; }
+  h3 { font-size: 1.25em; font-weight: 600; line-height: 1.3; margin: 0.5em 0 0.25em; }
+  h4 { font-size: 1em; font-weight: 600; line-height: 1.3; margin: 0.5em 0 0.25em; }
+  h5 { font-size: 0.875em; font-weight: 600; line-height: 1.3; margin: 0.5em 0 0.25em; }
+  h6 { font-size: 0.85em; font-weight: 600; line-height: 1.3; margin: 0.5em 0 0.25em; }
+  ul, ol { padding-inline-start: 1.5em; margin: 0.25em 0; }
+  blockquote {
+    border-inline-start: 2px solid #999;
+    margin: 0.5em 0;
+    padding-inline-start: 1em;
+    color: #444;
+  }
+  a { color: #1677ff; text-decoration: underline; }
+  img, video { max-width: 100%; height: auto; }
+  table {
+    width: 100%;
+    border-collapse: collapse;
+    /**
+     * 表格用 auto 布局（而不是屏幕上的 fixed）：纸上没有「拖列宽」这回事，
+     * 按内容分配宽度才不会把某一列压成一条缝。
+     */
+    table-layout: auto;
+  }
+  th, td { border: 1px solid #999; padding: 6px 8px; vertical-align: top; }
+  th { background: #f0f0f0; font-weight: 600; text-align: start; }
+  hr { border: 0; border-top: 1px solid #999; margin: 1em 0; }
+  /* 长 URL / 无空格文本在纸上换行，否则会把页面撑宽、右侧被裁掉 */
+  body * { overflow-wrap: anywhere; }
+`
+
+/**
+ * 打印一段 HTML（只打印这段内容，不带宿主页面）。
+ *
+ * @param html 要打印的正文 HTML
+ * @param title 打印文档的标题（浏览器会用作「另存为 PDF」的默认文件名）
+ * @returns 是否成功发起打印
+ *
+ * ## 为什么不复用同一个 iframe
+ *
+ * 每次打印都新建、打完就移除：复用需要在「上一次的 onload 是否已经跑完」上做状态
+ * 管理，而打印是低频操作，这点开销换来的逻辑简单得多，也避免「连续点两次打印，
+ * 第二次拿到的是上一次的文档」这种脏状态。
+ *
+ * ## 时序：必须等 iframe 内的资源就绪
+ *
+ * 直接把 `srcdoc` 写进去再立刻 `print()` 会打印出**空白页** —— 此刻 iframe 的文档
+ * 还没解析完。所以写 `srcdoc` 后要等 `load` 事件。
+ *
+ * 正文里的图片是**外链**（上传后的 URL），`load` 事件只保证 DOM 与同源资源就绪，
+ * 不保证跨域图片已解码；实际打印时浏览器会等布局稳定再出图，这里不再额外等待 ——
+ * 过度等待（比如强行等所有 img.onload）会让「点了打印没反应」的观感更糟。
+ */
+export function printHtml(html: string, title = '打印'): boolean {
+  if (typeof document === 'undefined') return false
+
+  const iframe = document.createElement('iframe')
+
+  /**
+   * 隐藏 iframe 的两种做法：
+   * - `display: none`：部分浏览器（尤其是 WebKit）会**跳过渲染**，导致打印空白；
+   * - 固定定位 + 零尺寸挪出视口：仍然参与布局与渲染，打印正常，也不会被用户看到。
+   *
+   * 用后者。注意**不要**加 `visibility: hidden` —— 该属性会被打印管线继承，
+   * 结果是「打印出一张白纸」（比 display:none 更隐蔽，因为 iframe 确实渲染了）。
+   * 这里只做「零尺寸 + 移出视口」这一件事。
+   */
+  iframe.setAttribute('aria-hidden', 'true')
+  iframe.style.position = 'fixed'
+  iframe.style.right = '0'
+  iframe.style.bottom = '0'
+  iframe.style.width = '0'
+  iframe.style.height = '0'
+  iframe.style.border = '0'
+
+  /** 打印完（或失败）后清理 DOM，避免 iframe 越积越多 */
+  let cleaned = false
+  const cleanup = (): void => {
+    if (cleaned) return
+    cleaned = true
+    iframe.remove()
+  }
+
+  /**
+   * 完整的打印文档。
+   *
+   * `charset=utf-8` 必须显式声明：不写的话中文在部分浏览器 / 打印引擎里会变乱码
+   * （iframe 的 srcdoc 继承的是父文档编码，但打印管线是另一条路径）。
+   */
+  const doc = `<!DOCTYPE html>
+<html>
+<head>
+<meta charset="utf-8">
+<title>${escapeHtml(title)}</title>
+<style>${PRINT_STYLES}</style>
+</head>
+<body>${html}</body>
+</html>`
+
+  iframe.addEventListener('load', () => {
+    const win = iframe.contentWindow
+    if (!win) {
+      cleanup()
+      return
+    }
+
+    /**
+     * `print()` 在多数浏览器里是**同步阻塞**的（打印对话框关闭后才返回），
+     * 但 WebKit 系不是。所以清理放在 `afterprint` 上更可靠，同时用
+     * `setTimeout` 兜底 —— 否则一旦浏览器不派发 `afterprint`，iframe 就永远留在 DOM 里。
+     */
+    win.addEventListener('afterprint', cleanup, { once: true })
+    // 兜底清理：打印对话框最长给 60 秒，超时后无论如何都移除
+    window.setTimeout(cleanup, 60_000)
+
+    try {
+      win.focus() // 部分浏览器要求文档先获得焦点才会弹出打印对话框
+      win.print()
+    } catch {
+      // 打印被环境拦截（如无权限的嵌入式 WebView）：清理并放弃，不抛给调用方
+      cleanup()
+    }
+  })
+
+  // srcdoc 必须先赋值再挂载（顺序无所谓，但赋值完才会开始加载）
+  iframe.srcdoc = doc
+  document.body.appendChild(iframe)
+
+  return true
+}
+
+/** 转义写进 `<title>` 的文本，避免标题里的 `</title>` 之类破坏文档结构 */
+function escapeHtml(text: string): string {
+  return text
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;')
+}
diff --git a/code/g3soft-libs/packages/ui/src/rich-text/types.ts b/code/g3soft-libs/packages/ui/src/rich-text/types.ts
index b530a1a4..30730d13 100644
--- a/code/g3soft-libs/packages/ui/src/rich-text/types.ts
+++ b/code/g3soft-libs/packages/ui/src/rich-text/types.ts
@@ -28,6 +28,33 @@ export interface RichTextFontSizeOption {
   value: string
 }
 
+/**
+ * 列表样式选项。
+ *
+ * - `value` 是**写进文档的值**：无序对应 `<ul type="…">`、有序对应 `<ol type="…">`
+ *   （小写希腊字母是唯一例外，写成 `style="list-style-type: lower-greek"`，
+ *   因为 `type="lower-greek"` 不是合法 HTML 值）；空串表示「默认」，不写任何属性；
+ * - `glyph` 是下拉面板里画出来的真实符号（`•` / `○` / `■` / `a.` / `I.` …），
+ *   让用户「看着选」而不是「记英文枚举」。
+ */
+export interface RichTextListTypeOption {
+  label: string
+  value: string
+  glyph: string
+}
+
+/** 整理格式的清理统计 */
+export interface RichTextCleanupResult {
+  /** 删掉的空段落数 */
+  removedEmptyParagraphs: number
+  /** 去掉的空白文本节点数 */
+  trimmedBlankTexts: number
+  /** 取消掉的空行内记号数 */
+  removedEmptyMarks: number
+  /** 是否有任何改动 */
+  changed: boolean
+}
+
 export interface RichTextProps {
   /** v-model：HTML 字符串 */
   modelValue?: string
@@ -51,6 +78,10 @@ export interface RichTextProps {
   fonts?: RichTextFontOption[]
   /** 预设字号列表（toolbar 下拉） */
   fontSizes?: RichTextFontSizeOption[]
+  /** 无序列表的项目符号样式（「更多」菜单里的二级菜单） */
+  bulletListTypes?: RichTextListTypeOption[]
+  /** 有序列表的编号样式（「更多」菜单里的二级菜单） */
+  orderedListTypes?: RichTextListTypeOption[]
 }
 
 export interface RichTextEmits {
@@ -62,6 +93,12 @@ export interface RichTextEmits {
   (e: 'upload-inline', result: RichTextUploadResult, kind: 'image' | 'video'): void
   /** 上传失败 */
   (e: 'upload-error', error: Error, kind: 'image' | 'video'): void
+  /** 「源代码」对话框保存并写回编辑器后触发（参数为规范化后的 HTML） */
+  (e: 'source-save', html: string): void
+  /** 整理格式执行完成（`changed` 为 false 表示本来就没有可清理的内容） */
+  (e: 'cleanup', result: RichTextCleanupResult): void
+  /** 从工具条 / 预览里发起打印 */
+  (e: 'print'): void
 }
 
 export interface RichTextExpose {
@@ -75,4 +112,12 @@ export interface RichTextExpose {
   focus: () => void
   /** 清空内容 */
   clear: () => void
+  /** 打开「源代码」对话框 */
+  openSourceCode: () => void
+  /** 打开「预览」对话框 */
+  openPreview: () => void
+  /** 打印正文（只打印正文，不带宿主页面） */
+  print: () => void
+  /** 整理格式：清理空段落 / 空白文本 / 空行内记号 */
+  tidyFormat: () => RichTextCleanupResult
 }
diff --git a/code/g3soft-libs/packages/ui/src/table/G3Table.test.ts b/code/g3soft-libs/packages/ui/src/table/G3Table.test.ts
new file mode 100644
index 00000000..d33b17b6
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/table/G3Table.test.ts
@@ -0,0 +1,368 @@
+import { mount } from '@vue/test-utils'
+import { describe, expect, it, vi } from 'vitest'
+import { nextTick } from 'vue'
+import G3Table from './G3Table.vue'
+import { isSelectionColumn } from './utils/selection'
+import type { G3TableColumn, TableRow } from './types'
+
+/**
+ * G3Table 组件契约测试。
+ *
+ * 重点锁住**性能门控**：这是整个组件最核心也最容易在后续重构中被改坏的逻辑。
+ * 门控是纯计算（行数 / 列数与阈值比较），不依赖布局引擎，所以能在 happy-dom 里测。
+ *
+ * 依赖实测几何的行为（虚拟滚动的真实行位置、拖拽）放 E2E。
+ */
+
+interface Row extends TableRow {
+  id: number
+  name: string
+  amount: number
+}
+
+function makeRows(count: number): Row[] {
+  return Array.from({ length: count }, (_, i) => ({
+    id: i + 1,
+    name: `行 ${i + 1}`,
+    amount: (i + 1) * 100,
+  }))
+}
+
+// 组件 props 是按 TableRow 声明的，泛型不变性下 G3TableColumn<Row> 不能直接赋值给它，
+// 这里统一用 G3TableColumn<TableRow> 声明，测试里仍按 Row 取值。
+const columns: G3TableColumn<TableRow>[] = [
+  { dataIndex: 'name', title: '名称' },
+  { dataIndex: 'amount', title: '金额' },
+]
+
+function mountTable(props: Record<string, unknown> = {}) {
+  return mount(G3Table, {
+    props: { columns, dataSource: makeRows(3), seq: false, ...props },
+    attachTo: document.body,
+  })
+}
+
+/**
+ * 读取传给底座 StkTable 的实际 props。
+ * 门控结果最终体现在 `virtual` / `virtual-x` 这两个 prop 上。
+ */
+function stkProps(wrapper: ReturnType<typeof mountTable>) {
+  const stk = wrapper.findComponent({ name: 'StkTable' })
+  expect(stk.exists()).toBe(true)
+  return stk.props() as Record<string, unknown>
+}
+
+describe('性能门控：纵向虚拟滚动', () => {
+  it('行数 ≤ 100 时关闭虚拟滚动（避免最后几行被吞）', () => {
+    const wrapper = mountTable({ dataSource: makeRows(20) })
+    expect(stkProps(wrapper).virtual).toBe(false)
+  })
+
+  it('恰好 100 行仍关闭（边界：阈值是 > 100 才开）', () => {
+    const wrapper = mountTable({ dataSource: makeRows(100) })
+    expect(stkProps(wrapper).virtual).toBe(false)
+  })
+
+  it('101 行时开启虚拟滚动', () => {
+    const wrapper = mountTable({ dataSource: makeRows(101) })
+    expect(stkProps(wrapper).virtual).toBe(true)
+  })
+
+  it('显式传 virtual=false 时不开启（即便行数超过阈值）', () => {
+    const wrapper = mountTable({ dataSource: makeRows(500), virtual: false })
+    expect(stkProps(wrapper).virtual).toBe(false)
+  })
+
+  it('空数据不开启', () => {
+    const wrapper = mountTable({ dataSource: [] })
+    expect(stkProps(wrapper).virtual).toBe(false)
+  })
+})
+
+describe('性能门控：横向虚拟滚动', () => {
+  function manyColumns(count: number): G3TableColumn<Row>[] {
+    return Array.from({ length: count }, (_, i) => ({
+      dataIndex: `c${i}`,
+      title: `列 ${i}`,
+    })) as G3TableColumn<Row>[]
+  }
+
+  it('列数少时关闭横向虚拟（保住原生列宽自适应）', () => {
+    const wrapper = mountTable({ columns: manyColumns(5), seq: false })
+    expect(stkProps(wrapper).virtualX).toBe(false)
+  })
+
+  it('恰好 20 列仍关闭（边界）', () => {
+    const wrapper = mountTable({ columns: manyColumns(20), seq: false })
+    expect(stkProps(wrapper).virtualX).toBe(false)
+  })
+
+  it('超过 20 列时开启', () => {
+    const wrapper = mountTable({ columns: manyColumns(25), seq: false })
+    expect(stkProps(wrapper).virtualX).toBe(true)
+  })
+
+  it('内部列（序号列）也计入列数', () => {
+    // 20 个业务列 + 序号列 = 21 > 20，应当开启
+    const wrapper = mountTable({ columns: manyColumns(20), seq: true })
+    expect(stkProps(wrapper).virtualX).toBe(true)
+  })
+
+  it('显式传 virtual-x=false 时不开启', () => {
+    const wrapper = mountTable({ columns: manyColumns(30), virtualX: false, seq: false })
+    expect(stkProps(wrapper).virtualX).toBe(false)
+  })
+})
+
+describe('内部列注入', () => {
+  it('seq 默认开启，注入序号列', () => {
+    const wrapper = mountTable({ seq: true })
+    const cols = stkProps(wrapper).columns as G3TableColumn<Row>[]
+    expect(cols[0].type).toBe('seq')
+  })
+
+  it('seq=false 时不注入序号列', () => {
+    const wrapper = mountTable({ seq: false })
+    const cols = stkProps(wrapper).columns as G3TableColumn<Row>[]
+    expect(cols.some((c) => c.type === 'seq')).toBe(false)
+  })
+
+  it('传入 rowSelection 时在最前注入选择列', () => {
+    const wrapper = mountTable({
+      seq: false,
+      rowSelection: { selectedRowKeys: [], onChange: () => {} },
+    })
+    const cols = stkProps(wrapper).columns as G3TableColumn<Row>[]
+    // 用导出的判定函数读内部标识，不直接摸私有字段
+    expect(isSelectionColumn(cols[0])).toBe(true)
+  })
+
+  it('未传 rowSelection 时不注入选择列', () => {
+    const wrapper = mountTable({ seq: false })
+    const cols = stkProps(wrapper).columns as G3TableColumn<Row>[]
+    expect(cols.some((c) => isSelectionColumn(c))).toBe(false)
+  })
+
+  it('rowDraggable 开启时注入拖拽列', () => {
+    const wrapper = mountTable({ seq: false, rowDraggable: true })
+    const cols = stkProps(wrapper).columns as G3TableColumn<Row>[]
+    expect(cols[0].type).toBe('dragRow')
+  })
+
+  it('业务列不透传我们自己的 editor / actions 字段给库', () => {
+    const wrapper = mountTable({
+      columns: [
+        { dataIndex: 'name', title: '名称', editor: { type: 'text' } },
+      ] as G3TableColumn<Row>[],
+      seq: false,
+      editable: false,
+    })
+    const cols = stkProps(wrapper).columns as Array<Record<string, unknown>>
+    const nameCol = cols.find((c) => c.dataIndex === 'name')!
+    // editor 是我们自己的扩展字段，不应该被当作库的列配置传下去
+    expect(nameCol.editor).toBeDefined()
+    // 但 customCell 在无编辑态时**不该**被注入（性能关键）
+    expect(nameCol.customCell).toBeUndefined()
+  })
+})
+
+describe('editingActive 门控：无编辑行时不注入 customCell', () => {
+  it('全表无编辑行时，可编辑列不注入 customCell（走库原生 td）', () => {
+    const wrapper = mountTable({
+      columns: [{ dataIndex: 'name', title: '名称', editor: { type: 'text' } }] as G3TableColumn<Row>[],
+      seq: false,
+    })
+    const cols = stkProps(wrapper).columns as Array<Record<string, unknown>>
+    expect(cols[0].customCell).toBeUndefined()
+  })
+
+  it('select 列例外：始终注入（需要把值解析成 label 展示）', () => {
+    const wrapper = mountTable({
+      columns: [
+        {
+          dataIndex: 'name',
+          title: '名称',
+          editor: { type: 'select', options: [{ label: 'A', value: 'a' }] },
+        },
+      ] as G3TableColumn<Row>[],
+      seq: false,
+    })
+    const cols = stkProps(wrapper).columns as Array<Record<string, unknown>>
+    expect(typeof cols[0].customCell).toBe('function')
+  })
+
+  it('checkbox 列例外：始终注入（要能随时点）', () => {
+    const wrapper = mountTable({
+      columns: [{ dataIndex: 'amount', title: '启用', editor: { type: 'checkbox' } }] as G3TableColumn<Row>[],
+      seq: false,
+    })
+    const cols = stkProps(wrapper).columns as Array<Record<string, unknown>>
+    expect(typeof cols[0].customCell).toBe('function')
+  })
+
+  it('actions 列始终注入 customCell', () => {
+    const wrapper = mountTable({
+      columns: [
+        { dataIndex: 'name', title: '操作', actions: [{ label: '编辑', onClick: () => {} }] },
+      ] as G3TableColumn<Row>[],
+      seq: false,
+    })
+    const cols = stkProps(wrapper).columns as Array<Record<string, unknown>>
+    expect(typeof cols[0].customCell).toBe('function')
+  })
+
+  it('调用方自带的 customCell 被尊重，不被覆盖', () => {
+    const custom = () => 'x'
+    const wrapper = mountTable({
+      columns: [{ dataIndex: 'name', title: '名称', customCell: custom }] as unknown as G3TableColumn<Row>[],
+      seq: false,
+    })
+    const cols = stkProps(wrapper).columns as Array<Record<string, unknown>>
+    expect(cols[0].customCell).toBe(custom)
+  })
+})
+
+describe('列宽 / 列序拖拽的绑定门控', () => {
+  it('未绑定 v-model:columns 时关闭列宽拖拽（拖了无处回写）', () => {
+    const wrapper = mountTable()
+    expect(stkProps(wrapper).colResizable).toBe(false)
+  })
+
+  it('绑定了 v-model:columns 时开启列宽拖拽', () => {
+    const wrapper = mount(G3Table, {
+      props: {
+        columns,
+        dataSource: makeRows(3),
+        seq: false,
+        'onUpdate:columns': () => {},
+      },
+      attachTo: document.body,
+    })
+    const resizable = stkProps(wrapper).colResizable
+    expect(resizable).not.toBe(false)
+    expect(typeof (resizable as { disabled: unknown }).disabled).toBe('function')
+  })
+
+  it('autoFitWidth 开启时关闭列宽拖拽（两者语义冲突）', () => {
+    const wrapper = mount(G3Table, {
+      props: {
+        columns,
+        dataSource: makeRows(3),
+        seq: false,
+        autoFitWidth: true,
+        'onUpdate:columns': () => {},
+      },
+      attachTo: document.body,
+    })
+    expect(stkProps(wrapper).colResizable).toBe(false)
+  })
+
+  it('列宽拖拽的 disabled：操作列被禁止拖宽', () => {
+    const wrapper = mount(G3Table, {
+      props: {
+        columns: [
+          { dataIndex: 'name', title: '名称' },
+          {
+            dataIndex: 'op',
+            title: '操作',
+            resizable: false,
+            actions: [{ label: '删' }],
+          } as G3TableColumn<TableRow>,
+        ],
+        dataSource: makeRows(3),
+        seq: false,
+        editable: false,
+        'onUpdate:columns': () => {},
+      },
+      attachTo: document.body,
+    })
+    const config = stkProps(wrapper).colResizable as { disabled: (col: unknown) => boolean }
+    expect(config.disabled({ dataIndex: 'name', title: '名称' })).toBe(false)
+    expect(config.disabled({ dataIndex: 'op', resizable: false })).toBe(true)
+  })
+})
+
+describe('主题', () => {
+  it('不传 theme 时跟随 documentElement（默认 light）', () => {
+    const wrapper = mountTable()
+    expect(stkProps(wrapper).theme).toBe('light')
+  })
+
+  it('显式传 theme 时以 prop 为准', () => {
+    const wrapper = mountTable({ theme: 'dark' })
+    expect(stkProps(wrapper).theme).toBe('dark')
+  })
+
+  it('documentElement 标记为 dark 时跟随', async () => {
+    document.documentElement.dataset.g3Theme = 'dark'
+    const wrapper = mountTable()
+    await nextTick()
+    expect(stkProps(wrapper).theme).toBe('dark')
+    delete document.documentElement.dataset.g3Theme
+  })
+})
+
+describe('空态', () => {
+  it('无数据时渲染默认空态文案', () => {
+    const wrapper = mountTable({ dataSource: [] })
+    expect(wrapper.text()).toContain('暂无数据')
+  })
+
+  it('提供 empty 插槽时用插槽内容', () => {
+    const wrapper = mount(G3Table, {
+      props: { columns, dataSource: [], seq: false },
+      slots: { empty: '<div class="my-empty">自定义空态</div>' },
+      attachTo: document.body,
+    })
+    expect(wrapper.find('.my-empty').exists()).toBe(true)
+  })
+})
+
+describe('事件', () => {
+  it('列回写时剥离内部列后才 emit', async () => {
+    const onUpdate = vi.fn()
+    const wrapper = mount(G3Table, {
+      props: {
+        columns,
+        dataSource: makeRows(3),
+        seq: true,
+        'onUpdate:columns': onUpdate,
+      },
+      attachTo: document.body,
+    })
+    const stk = wrapper.findComponent({ name: 'StkTable' })
+    // 模拟库回写：把序号列也带回来
+    await stk.vm.$emit('update:columns', [
+      { type: 'seq', dataIndex: '', width: 70 },
+      { dataIndex: 'name', title: '名称', width: 200 },
+      { dataIndex: 'amount', title: '金额' },
+    ])
+    await nextTick()
+
+    expect(onUpdate).toHaveBeenCalled()
+    const emitted = onUpdate.mock.calls[0][0] as G3TableColumn<Row>[]
+    // 序号列必须被剥离
+    expect(emitted.some((c) => c.type === 'seq')).toBe(false)
+    expect(emitted.map((c) => c.dataIndex)).toEqual(['name', 'amount'])
+    // 业务列的新宽度要带上
+    expect(emitted[0].width).toBe(200)
+  })
+})
+
+describe('暴露的方法', () => {
+  it('暴露预期的方法', () => {
+    const wrapper = mountTable()
+    const vm = wrapper.vm as unknown as Record<string, unknown>
+    for (const name of [
+      'scrollToRow',
+      'editRow',
+      'initVirtualScroll',
+      'refreshLayout',
+      'getSelectedArea',
+      'clearSelectedArea',
+      'setRowExpand',
+    ]) {
+      expect(typeof vm[name]).toBe('function')
+    }
+  })
+})
diff --git a/code/g3soft-libs/packages/ui/src/table/G3Table.vue b/code/g3soft-libs/packages/ui/src/table/G3Table.vue
new file mode 100644
index 00000000..b1c21515
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/table/G3Table.vue
@@ -0,0 +1,868 @@
+<script lang="ts">
+import { registerFeature, useAreaSelection } from 'stk-table-vue'
+
+/**
+ * 区域选择特性注册。
+ *
+ * 库的区域选择是**按需全局注册**的，不注册则 `area-selection-change` 永不触发
+ * （行内编辑依赖它）。组件库不拥有 app 启动流程，不能要求消费方在 main.ts 里调用，
+ * 所以组件挂载时会自动注册一次；这个函数用于需要显式控制的场景
+ * （例如想在挂载前就注册好，或单测里手动重置状态）。
+ *
+ * `registerFeature` 本身是幂等的；这里再兜一层模块级 + 全局 flag，
+ * 避免多实例、多入口重复注册。
+ */
+const AREA_SELECTION_FEATURE_KEY = '__g3TableAreaSelectionRegistered__'
+let areaSelectionRegistered = false
+
+export function registerTableFeatures(): void {
+  if (areaSelectionRegistered) return
+  const globalFlag = globalThis as unknown as Record<string, boolean>
+  if (!globalFlag[AREA_SELECTION_FEATURE_KEY]) {
+    registerFeature(useAreaSelection)
+    globalFlag[AREA_SELECTION_FEATURE_KEY] = true
+  }
+  areaSelectionRegistered = true
+}
+</script>
+
+<script setup lang="ts">
+import {
+  computed,
+  getCurrentInstance,
+  nextTick,
+  onBeforeUnmount,
+  onMounted,
+  ref,
+  shallowRef,
+  useSlots,
+  watch,
+} from 'vue'
+import { StkTable } from 'stk-table-vue'
+import type { StkTableColumn } from 'stk-table-vue'
+import { useNamespace } from '../_composables/useNamespace'
+import { createSelectionColumn, isSelectionColumn, SELECTION_COLUMN_KEY } from './utils/selection'
+import {
+  DRAG_ROW_COLUMN_TYPE,
+  getHeaderAlign,
+  readInternalWidths,
+  resolveCustomCell,
+  resolveSeqConfig,
+  stripInternalColumns,
+} from './utils/column'
+import type { EditableContext } from './utils/editable'
+import type { G3TableColumn, TableRow, TableRowKey, TableRowSelection } from './types'
+
+/**
+ * G3Table —— 高性能表格。
+ *
+ * 底座 `stk-table-vue`：虚拟滚动 / 列宽拖拽 / 列序拖拽 / 区域选择 / 行拖拽排序
+ * 都由它提供。本组件负责三件事：**性能门控**、**内部列管理**、**编辑态管理**。
+ */
+
+defineOptions({ name: 'G3Table', inheritAttrs: false })
+
+const props = withDefaults(
+  defineProps<{
+    columns?: G3TableColumn<TableRow>[]
+    dataSource?: TableRow[]
+    rowKey?: TableRowKey<TableRow>
+    virtual?: boolean
+    virtualX?: boolean
+    rowHeight?: number
+    headerRowHeight?: number
+    bordered?: boolean | string
+    colResizable?: boolean | { disabled?: boolean | ((col: G3TableColumn<TableRow>) => boolean) }
+    columnDraggable?:
+      | boolean
+      | {
+          mode?: 'none' | 'insert' | 'swap'
+          disabled?: boolean | ((col: G3TableColumn<TableRow>) => boolean)
+        }
+    rowDraggable?: boolean
+    rowSelection?: TableRowSelection<TableRow> | null
+    seq?: boolean | { title?: string; width?: number }
+    activeRowKey?: string | number | null
+    editable?: boolean
+    noDataFull?: boolean
+    showOverflow?: boolean
+    autoFitWidth?: boolean
+    theme?: 'light' | 'dark'
+    footerData?: TableRow[]
+    footerConfig?: Record<string, unknown>
+  }>(),
+  {
+    columns: () => [],
+    dataSource: () => [],
+    rowKey: 'id',
+    virtual: true,
+    virtualX: true,
+    rowHeight: 30,
+    headerRowHeight: 34,
+    bordered: true,
+    colResizable: true,
+    columnDraggable: true,
+    rowDraggable: false,
+    rowSelection: null,
+    seq: true,
+    activeRowKey: null,
+    editable: true,
+    noDataFull: true,
+    showOverflow: true,
+    autoFitWidth: false,
+    theme: undefined,
+    footerData: () => [],
+    footerConfig: () => ({}),
+  },
+)
+
+const emit = defineEmits<{
+  (e: 'update:columns', columns: G3TableColumn<TableRow>[]): void
+  (e: 'update:selectedRowKeys', keys: Array<string | number>): void
+  (e: 'change', row: TableRow, col: G3TableColumn<TableRow>, value: unknown): void
+  (e: 'row-order-change', rows: TableRow[], sourceIndex: number, targetIndex: number): void
+  (e: 'area-selection-change', ranges: unknown[]): void
+}>()
+
+const { b, e, is } = useNamespace('table')
+const slots = useSlots()
+
+/* ---------- 性能门控 ---------- */
+
+/**
+ * 纵向虚拟滚动门控：行数不超过阈值时**关闭**。
+ *
+ * 库的虚拟滚动在「行数 > 单屏行数」时开启，会导致行数略大于一屏
+ * （如容器一屏 18 行、数据 20 行）时最后几行被虚拟化吞掉、必须滚动才可见。
+ * 行数少时全量渲染没有性能问题，却换来确定性正确的渲染。
+ */
+const MIN_VIRTUAL_ROW_COUNT = 100
+const effectiveVirtual = computed(
+  () => props.virtual && props.dataSource.length > MIN_VIRTUAL_ROW_COUNT,
+)
+
+/**
+ * 横向虚拟滚动门控：列数不超过阈值时关闭。
+ *
+ * 库在 `virtualX = true` 时会把每列宽度**钉死**为 minWidth ?? width ?? 100
+ * （cellStyleMap 的 --cw + width/min-width/max-width 三重锁），
+ * 未设 width 的列会失去「按比例铺满容器」的原生自适应。
+ * 列数少、总宽不超容器时用不上横向虚拟，关掉以保住原生列宽分配。
+ */
+const MIN_VIRTUAL_X_COLUMN_COUNT = 20
+const effectiveVirtualX = computed(
+  () => props.virtualX && displayColumns.value.length > MIN_VIRTUAL_X_COLUMN_COUNT,
+)
+
+/* ---------- 主题 ---------- */
+
+/** 主题：显式 prop 优先，否则跟随 documentElement（tokens 的 data-g3-theme 约定） */
+const documentTheme = ref<'light' | 'dark'>('light')
+let themeObserver: MutationObserver | null = null
+const tableTheme = computed(() => props.theme ?? documentTheme.value)
+
+function readDocumentTheme() {
+  if (typeof document === 'undefined') return
+  documentTheme.value = document.documentElement.dataset.g3Theme === 'dark' ? 'dark' : 'light'
+}
+
+/* ---------- 布局刷新 ---------- */
+
+const rootRef = ref<HTMLElement | null>(null)
+const tableRef = ref<{ initVirtualScroll?: () => void; initVirtualScrollX?: () => void } | null>(
+  null,
+)
+
+/** rAF 合并同一帧内的多次通知，避免重复重排 */
+let refreshRafId = 0
+function refreshLayout(xOnly = false) {
+  if (typeof requestAnimationFrame === 'undefined') return
+  if (refreshRafId) cancelAnimationFrame(refreshRafId)
+  refreshRafId = requestAnimationFrame(async () => {
+    refreshRafId = 0
+    await nextTick()
+    // 高度未变、仅宽度变化时只重算 X 方向，省掉 Y 方向重算
+    if (xOnly) tableRef.value?.initVirtualScrollX?.()
+    else tableRef.value?.initVirtualScroll?.()
+    await nextTick()
+  })
+}
+
+/**
+ * 尺寸防抖（trailing）。
+ *
+ * 折叠动画 / 窗口缩放 / 拖拽调宽期间 ResizeObserver 每帧都会通知，
+ * 但中间尺寸是瞬态的——逐帧 initVirtualScroll 会每帧强制 reflow 并重渲染可见行列，
+ * 造成动画掉帧。这里合并通知，尺寸稳定后才刷新一次，动画期间表格仅随 CSS 拉伸。
+ */
+const RESIZE_DEBOUNCE_MS = 150
+let resizeDebounceTimer: ReturnType<typeof setTimeout> | undefined
+let lastSize: { width: number; height: number } | null = null
+let resizeObserver: ResizeObserver | null = null
+
+/* ---------- 行编辑态 ---------- */
+
+/**
+ * 每行的编辑状态存在 WeakMap 里（key 是行对象本身）。
+ * 用 WeakMap 而不是给行对象打标记：不污染业务数据，行被回收时状态自动释放。
+ */
+const rowEditingStates = new WeakMap<TableRow, ReturnType<typeof shallowRef>>()
+let activeEditingRow: TableRow | null = null
+let pendingFocusKey: string | null = null
+
+/**
+ * 是否存在活动编辑行。
+ *
+ * **性能关键**：为 false 时可编辑列不注入 customCell，全部走库原生 td 渲染，
+ * 滚动时每格省掉一个函数式组件。行与行之间切换编辑**不翻转**此值，避免整表列重建。
+ */
+const editingActive = ref(false)
+
+function getRowKey(row: TableRow): string | number {
+  if (typeof props.rowKey === 'function') return props.rowKey(row)
+  const key = props.rowKey as string
+  return row?.[key] as string | number
+}
+
+function getRowEditingState(row: TableRow) {
+  if (!row || typeof row !== 'object') return null
+  let state = rowEditingStates.get(row)
+  if (!state) {
+    state = shallowRef({ editing: false, focusCol: null as string | null, focused: false })
+    rowEditingStates.set(row, state)
+  }
+  return state
+}
+
+function deactivateRowEditing(row: TableRow) {
+  const state = rowEditingStates.get(row)
+  if (state && (state.value as { editing: boolean }).editing) {
+    state.value = { editing: false, focusCol: null, focused: false }
+  }
+}
+
+function clearActiveEditing() {
+  if (!activeEditingRow) return
+  const state = rowEditingStates.get(activeEditingRow)
+  activeEditingRow = null
+  editingActive.value = false
+  if (state && (state.value as { editing: boolean }).editing) {
+    state.value = { editing: false, focusCol: null, focused: false }
+  }
+}
+
+function activateEditing(row: TableRow, focusCol: string | null) {
+  if (!props.editable || !row) return
+  const state = getRowEditingState(row)
+  if (!state) return
+
+  if (activeEditingRow !== row) {
+    if (activeEditingRow) deactivateRowEditing(activeEditingRow)
+    activeEditingRow = row
+    editingActive.value = true
+    state.value = { editing: true, focusCol, focused: false }
+    pendingFocusKey = String(getRowKey(row))
+    return
+  }
+
+  const current = state.value as { editing: boolean; focusCol: string | null; focused: boolean }
+  if (current.editing && current.focusCol === focusCol) return
+  state.value = { ...current, editing: true, focusCol }
+  pendingFocusKey = String(getRowKey(row))
+}
+
+const editingCtx: EditableContext<TableRow> = {
+  isEditing: (row) =>
+    props.editable && Boolean((getRowEditingState(row)?.value as { editing: boolean })?.editing),
+  shouldFocus: (row, col) =>
+    (getRowEditingState(row)?.value as { focusCol: string | null })?.focusCol === col.dataIndex,
+  wasFocused: (row) => Boolean((getRowEditingState(row)?.value as { focused: boolean })?.focused),
+  consumePendingFocus: (row) => {
+    if (pendingFocusKey == null) return false
+    if (pendingFocusKey !== String(getRowKey(row))) return false
+    pendingFocusKey = null
+    return true
+  },
+  onEditorFocus: (row) => {
+    const state = getRowEditingState(row)
+    if (state?.value) state.value = { ...(state.value as object), focused: true }
+  },
+  onEditorBlur: (row) => {
+    const state = getRowEditingState(row)
+    if (state?.value) state.value = { ...(state.value as object), focused: false }
+  },
+  shouldNotify: () => true,
+  onChange: (row, col, value) => {
+    emit('change', row, col, value)
+  },
+}
+
+/* ---------- 列 ---------- */
+
+const seqConfig = computed(() => resolveSeqConfig(props.seq))
+const seqWidth = ref(seqConfig.value.width)
+const selectionWidth = ref(44)
+const dragRowWidth = ref(40)
+
+const hasRowSelection = computed(() => Boolean(props.rowSelection))
+
+const selectionColumn = createSelectionColumn<TableRow>({
+  getDataSource: () => props.dataSource,
+  getRowKey,
+  getSelectedRowKeys: () => props.rowSelection?.selectedRowKeys ?? [],
+  isRowDisabled: (row) => Boolean(props.rowSelection?.getCheckboxProps?.(row)?.disabled),
+  onChange: (keys, rows) => {
+    props.rowSelection?.onChange?.(keys, rows)
+    emit('update:selectedRowKeys', keys)
+  },
+})
+
+/** 列宽拖拽 / 列序拖拽都要求父级绑定 v-model:columns，否则拖了无处回写（松手回弹），直接关掉 */
+const columnsBound = 'onUpdate:columns' in (getCurrentInstance()?.vnode.props ?? {})
+
+const effectiveColResizable = (() => {
+  if (!columnsBound || props.autoFitWidth || !props.colResizable) return false
+  const configured: { disabled?: boolean | ((col: G3TableColumn<TableRow>) => boolean) } =
+    props.colResizable === true ? {} : props.colResizable
+  return {
+    // 入参用库自己的列类型：库的 props 泛型是 any，若这里收窄成 G3TableColumn<TableRow>，
+    // 函数参数逆变会判定不兼容（库可能传任意列进来）。收宽再在内部窄化是唯一正解。
+    disabled: (column: StkTableColumn<TableRow>) => {
+      const col = column as G3TableColumn<TableRow>
+      // 操作列 / 展开列宽度由代码算，拖了不落库、列重建即丢，一律禁止
+      if (col.resizable === false) return true
+      return typeof configured.disabled === 'function'
+        ? Boolean(configured.disabled(col))
+        : Boolean(configured.disabled)
+    },
+  }
+})()
+
+const columnDragConfig = computed(() => {
+  if (!columnsBound || !props.columnDraggable) return false
+  const configured: {
+    mode?: 'none' | 'insert' | 'swap'
+    disabled?: boolean | ((col: G3TableColumn<TableRow>) => boolean)
+  } = props.columnDraggable === true ? {} : props.columnDraggable
+  return {
+    ...configured,
+    disabled: (column: StkTableColumn<TableRow>) => {
+      const col = column as G3TableColumn<TableRow>
+      if (
+        isSelectionColumn(col) ||
+        col.type === 'seq' ||
+        col.type === DRAG_ROW_COLUMN_TYPE ||
+        col.type === 'expand' ||
+        col.dataIndex === '' ||
+        col.dataIndex === '__actions__'
+      ) {
+        return true
+      }
+      return typeof configured.disabled === 'function'
+        ? configured.disabled(col)
+        : Boolean(configured.disabled)
+    },
+  }
+})
+
+const displayColumns = computed<G3TableColumn<TableRow>[]>(() => {
+  const cols = props.columns.map((col) =>
+    resolveCustomCell(col, editingCtx, editingActive.value),
+  )
+  const seq = seqConfig.value
+  if (seq.enabled) {
+    cols.unshift({
+      type: 'seq',
+      width: seqWidth.value,
+      dataIndex: '',
+      title: seq.title,
+    } as unknown as G3TableColumn<TableRow>)
+  }
+  if (props.rowDraggable) {
+    cols.unshift({
+      type: DRAG_ROW_COLUMN_TYPE,
+      dataIndex: '__g3DragRow',
+      title: '',
+      width: dragRowWidth.value,
+    } as unknown as G3TableColumn<TableRow>)
+  }
+  if (hasRowSelection.value) {
+    cols.unshift({
+      ...selectionColumn,
+      width: selectionWidth.value,
+    } as G3TableColumn<TableRow>)
+  }
+  return cols.map((column) => ({ ...column, headerAlign: getHeaderAlign(column) }))
+})
+
+/** 库回写列：同步内部列宽度，剥离内部列后回传业务列 */
+// 入参用库的类型（props 泛型是 any），内部再窄化——与 colResizable 同因
+function onColumnsUpdate(rawColumns: StkTableColumn<TableRow>[]) {
+  const columns = rawColumns as G3TableColumn<TableRow>[]
+  const widths = readInternalWidths(columns)
+  if (widths.selection != null) selectionWidth.value = widths.selection
+  if (widths.seq != null) seqWidth.value = widths.seq
+  if (widths.dragRow != null) dragRowWidth.value = widths.dragRow
+  emit('update:columns', stripInternalColumns(columns, props.columns))
+}
+
+/**
+ * 行拖拽结束。
+ *
+ * 库回传的是**行 key**（dragStartKey / targetRowKey），不是索引；
+ * 这里换算成索引再抛给业务——索引更通用，业务不必知道 rowKey 怎么取值。
+ */
+function handleRowOrderChange(dragStartKey: string, targetRowKey: string) {
+  const rows =
+    (tableRef.value as unknown as { getTableData?: () => TableRow[] })?.getTableData?.() ??
+    props.dataSource
+  const sourceIndex = rows.findIndex((row) => String(getRowKey(row)) === String(dragStartKey))
+  const targetIndex = rows.findIndex((row) => String(getRowKey(row)) === String(targetRowKey))
+  emit('row-order-change', [...rows], sourceIndex, targetIndex)
+}
+
+function handleAreaSelectionChange(ranges: unknown[]) {
+  if (!props.editable) return
+  const list = ranges as Array<{ index?: { end?: { row: number; col: number } } }>
+  const target = list?.at(-1)?.index?.end
+  if (!target) {
+    clearActiveEditing()
+    return
+  }
+  const row = props.dataSource[target.row]
+  const col = displayColumns.value[target.col]
+  if (!row) {
+    clearActiveEditing()
+    return
+  }
+  activateEditing(row, col?.editor ? col.dataIndex : null)
+  emit('area-selection-change', ranges)
+}
+
+/* ---------- 对外方法 ---------- */
+
+async function scrollToRow(rowKey: string | number) {
+  await nextTick()
+  const idx = props.dataSource.findIndex((row) => String(getRowKey(row)) === String(rowKey))
+  if (idx < 0) return
+  ;(tableRef.value as unknown as { scrollTo?: (top: number, left: number | null) => void })?.scrollTo?.(
+    idx * props.rowHeight,
+    null,
+  )
+}
+
+async function editRow(rowKey: string | number, focusCol: string | null = null) {
+  await scrollToRow(rowKey)
+  await nextTick()
+  const row = props.dataSource.find((item) => String(getRowKey(item)) === String(rowKey))
+  if (!row) return
+  ;(tableRef.value as unknown as { setCurrentRow?: (r: TableRow, o: object) => void })?.setCurrentRow?.(
+    row,
+    { silent: true },
+  )
+  activateEditing(row, focusCol)
+}
+
+function initVirtualScroll() {
+  tableRef.value?.initVirtualScroll?.()
+}
+
+function getSelectedArea() {
+  return (tableRef.value as unknown as { getSelectedArea?: () => unknown })?.getSelectedArea?.()
+}
+
+function clearSelectedArea() {
+  ;(tableRef.value as unknown as { clearSelectedArea?: () => void })?.clearSelectedArea?.()
+}
+
+function setRowExpand(...args: unknown[]) {
+  return (tableRef.value as unknown as { setRowExpand?: (...a: unknown[]) => unknown })?.setRowExpand?.(
+    ...args,
+  )
+}
+
+/* ---------- 生命周期 ---------- */
+
+onMounted(() => {
+  registerTableFeatures()
+  readDocumentTheme()
+
+  if (typeof MutationObserver !== 'undefined' && typeof document !== 'undefined') {
+    themeObserver = new MutationObserver(readDocumentTheme)
+    themeObserver.observe(document.documentElement, {
+      attributes: true,
+      attributeFilter: ['data-g3-theme'],
+    })
+  }
+
+  if (typeof ResizeObserver !== 'undefined' && rootRef.value) {
+    resizeObserver = new ResizeObserver(([entry]) => {
+      const { width, height } = entry.contentRect
+      if (width <= 0 || height <= 0) return
+      clearTimeout(resizeDebounceTimer)
+      resizeDebounceTimer = setTimeout(() => {
+        resizeDebounceTimer = undefined
+        const xOnly = lastSize != null && lastSize.height === height && lastSize.width !== width
+        lastSize = { width, height }
+        refreshLayout(xOnly)
+      }, RESIZE_DEBOUNCE_MS)
+    })
+    resizeObserver.observe(rootRef.value)
+  }
+})
+
+onBeforeUnmount(() => {
+  if (refreshRafId) cancelAnimationFrame(refreshRafId)
+  clearTimeout(resizeDebounceTimer)
+  resizeObserver?.disconnect()
+  resizeObserver = null
+  themeObserver?.disconnect()
+  themeObserver = null
+})
+
+// 数据被父级刷新后，行对象可能整体换新，编辑态需随 key 迁移
+watch(
+  () => props.dataSource,
+  (rows) => {
+    if (!activeEditingRow) return
+    if (rows.includes(activeEditingRow)) return
+    const previousKey = getRowKey(activeEditingRow)
+    const replacement = rows.find((row) => String(getRowKey(row)) === String(previousKey))
+    deactivateRowEditing(activeEditingRow)
+    activeEditingRow = null
+    editingActive.value = false
+    if (replacement) activateEditing(replacement, null)
+  },
+)
+
+watch(
+  () => props.editable,
+  (editable) => {
+    if (editable) return
+    clearActiveEditing()
+    clearSelectedArea()
+  },
+)
+
+// 行高是虚拟滚动计算的输入，变化后必须重算
+watch(
+  () => [props.rowHeight, props.headerRowHeight],
+  () => refreshLayout(),
+)
+
+defineExpose({
+  scrollToRow,
+  editRow,
+  initVirtualScroll,
+  refreshLayout: initVirtualScroll,
+  getSelectedArea,
+  clearSelectedArea,
+  setRowExpand,
+})
+</script>
+
+<template>
+  <div
+    ref="rootRef"
+    :class="[
+      b(),
+      bordered ? is('bordered') : '',
+      autoFitWidth ? is('auto-fit-width') : '',
+    ]"
+    data-slot="table"
+  >
+    <StkTable
+      ref="tableRef"
+      :class="e('inner')"
+      v-bind="$attrs"
+      :theme="tableTheme"
+      :row-height="rowHeight"
+      :header-row-height="headerRowHeight"
+      :virtual="effectiveVirtual"
+      :virtual-x="effectiveVirtualX"
+      :smooth-scroll="true"
+      :auto-resize="false"
+      :col-resizable="effectiveColResizable"
+      :header-drag="columnDragConfig"
+      :columns="displayColumns"
+      :data-source="dataSource"
+      :footer-data="footerData"
+      :footer-config="footerConfig"
+      :drag-row-config="{ mode: rowDraggable ? 'insert' : 'none' }"
+      :row-key="rowKey as never"
+      :no-data-full="noDataFull"
+      :show-overflow="showOverflow"
+      :empty-cell-text="''"
+      :area-selection="editable"
+      :bordered="bordered ? 'v' : false"
+      @update:columns="onColumnsUpdate"
+      @area-selection-change="handleAreaSelectionChange"
+      @row-order-change="handleRowOrderChange"
+    >
+      <template v-if="slots.expand" #expand="slotProps">
+        <slot name="expand" v-bind="slotProps" />
+      </template>
+      <template v-if="slots.empty" #empty>
+        <slot name="empty" />
+      </template>
+      <template v-else #empty>
+        <div :class="e('empty')" role="status">暂无数据</div>
+      </template>
+    </StkTable>
+  </div>
+</template>
+
+<style lang="scss">
+@use '@g3soft/tokens/scss' as *;
+@use './style/index';
+
+.#{b('table')} {
+  position: relative;
+  width: 100%;
+  height: 100%;
+  overflow: hidden;
+}
+
+/* 自绘外框：描边沿圆弧走、四角闭合。
+   库自身的边框恒为 false（我们传 bordered="v" 只取它的竖向分割线），
+   外框与圆角由这一层提供，避免库的方形渐变外框与圆角打架。 */
+.#{b('table')}.#{is('bordered')} {
+  border: 1px solid v('border-color', #d9d9d9);
+  border-radius: v('radius-lg', 8px);
+}
+
+.#{e('table', 'inner')} {
+  width: 100%;
+  height: 100%;
+
+  /* transform 虚拟滚动模式下把 tbody 提升为合成层：
+     translateY 走合成器，避免每帧重绘整表。 */
+  .stk-tbody-main {
+    will-change: transform;
+  }
+}
+
+/* 不自适应时按列配置宽度展示；自适应模式不启用列宽拖拽，使用库默认布局 */
+.#{b('table')}:not(.#{is('auto-fit-width')}) :deep(.stk-table-main) {
+  flex: none;
+}
+
+/* bordered="v" 仍会给根节点画方形外框与最后一列的右侧渐变线，
+   这些边缘该由外层圆角容器提供，去掉库的外边缘后只保留单元格之间的竖线。
+   注意只能抹掉最右一列的外侧右边线——整份清空会把库给右固定列补的
+   fixed-cell--border-left 也一并干掉（表现为操作列压住内容却没有分割线）。 */
+.#{e('table', 'inner')}.stk-table.bordered-v {
+  border-left: none;
+  background-image: none;
+
+  th:last-child,
+  td:last-child {
+    --bg-border-right: linear-gradient(transparent, transparent);
+  }
+}
+
+/* ---------- 行分隔线 ---------- */
+.#{e('table', 'inner')}.stk-table {
+  th,
+  td {
+    border-bottom: 1px solid v('border-color', #d9d9d9);
+  }
+}
+
+/* ---------- 行内编辑 ---------- */
+.#{e('table', 'cell-editor')} {
+  width: 100%;
+  height: 100%;
+  min-width: 0;
+  font-size: v('font-size', 14px);
+}
+
+/* 编辑器所在的 td 需要确定高度：非虚拟模式下（≤100 行，库不给 td 定高、只有 tr 有）
+   子元素 height:100% 无法解析，Input 会塌成内容高度。 */
+.#{e('table', 'inner')}.stk-table .stk-tbody-main td:has(> .#{e('table', 'cell-editor-root')}) {
+  height: var(--row-height);
+}
+
+.#{e('table', 'inner')} td:has(> .#{e('table', 'cell-editor-root')}) {
+  padding: 3px;
+}
+
+/* 编辑器根节点填满单元格 */
+.#{e('table', 'inner')}.stk-table {
+  .#{e('table', 'cell-editor-root')} {
+    &.g3-input,
+    &.g3-select {
+      width: 100%;
+      height: 100%;
+      min-height: 0;
+      box-sizing: border-box;
+    }
+  }
+}
+
+/* 展示态文本可选中；拖选期间由库禁用选中，故用 :not() 排除避免冲突 */
+.#{e('table', 'inner')}.stk-table:not(.is-area-selecting) .stk-tbody-main .table-cell-wrapper {
+  user-select: text;
+}
+
+.#{e('table', 'inner')}.text-overflow .#{e('table', 'cell-display')} {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.#{e('table', 'cell-display')} {
+  display: block;
+  min-width: 0;
+  user-select: text;
+}
+
+/* ---------- 选择列：原生 checkbox + 自绘方框，视觉对齐 G3Checkbox ---------- */
+.#{e('table', 'checkbox')} {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 100%;
+  height: 100%;
+  margin: 0;
+  cursor: pointer;
+  line-height: 1;
+  box-sizing: border-box;
+
+  &.#{is('disabled')} {
+    cursor: not-allowed;
+    opacity: 0.45;
+  }
+
+  /* 视觉隐藏但保留可访问性与可聚焦性 */
+  input {
+    position: absolute;
+    width: 1px;
+    height: 1px;
+    margin: 0;
+    opacity: 0;
+    pointer-events: none;
+  }
+
+  .#{e('table', 'checkbox-box')} {
+    position: relative;
+    display: block;
+    flex: none;
+    width: v('checkbox-size', 16px);
+    height: v('checkbox-size', 16px);
+    box-sizing: border-box;
+    border: 1px solid v('border-color', #d9d9d9);
+    border-radius: v('radius-sm', 4px);
+    background: v('bg-container', #fff);
+    /* 只过渡颜色：transition: all 会连带过渡定位/尺寸 */
+    transition:
+      background-color v('duration', 0.2s) v('ease', ease),
+      border-color v('duration', 0.2s) v('ease', ease);
+  }
+
+  &:hover:not(.#{is('disabled')}) .#{e('table', 'checkbox-box')} {
+    border-color: v('color-primary', #18181b);
+  }
+
+  &.#{is('checked')} .#{e('table', 'checkbox-box')},
+  &.#{is('indeterminate')} .#{e('table', 'checkbox-box')} {
+    border-color: v('color-primary', #18181b);
+    background: v('color-primary', #18181b);
+  }
+
+  /* 对勾：用边框拼，不引入图标组件（逐行渲染场景下要零开销） */
+  &.#{is('checked')} .#{e('table', 'checkbox-box')}::after {
+    content: '';
+    position: absolute;
+    inset-inline-start: 5px;
+    top: 2px;
+    width: 4px;
+    height: 8px;
+    border: solid v('color-primary-on', #fafafa);
+    border-width: 0 2px 2px 0;
+    transform: rotate(45deg);
+  }
+
+  &.#{is('indeterminate')} .#{e('table', 'checkbox-box')}::after {
+    content: '';
+    position: absolute;
+    inset-inline-start: 3px;
+    top: 7px;
+    width: 8px;
+    height: 2px;
+    border: none;
+    border-radius: 2px;
+    background: v('color-primary-on', #fafafa);
+  }
+
+  input:focus-visible + .#{e('table', 'checkbox-box')} {
+    @include focus-ring();
+  }
+}
+
+/* ---------- 操作列 ---------- */
+.#{e('table', 'actions-cell')} {
+  display: inline-flex;
+  align-items: center;
+  gap: v('space-1', 4px);
+}
+
+.#{e('table', 'action-btn')} {
+  display: inline-flex;
+  align-items: center;
+  gap: 3px;
+  padding: 2px 4px;
+  border: none;
+  background: transparent;
+  color: v('color-primary', #18181b);
+  font-size: v('font-size-sm', 12px);
+  line-height: 20px;
+  white-space: nowrap;
+  cursor: pointer;
+
+  &:hover {
+    opacity: 0.75;
+  }
+
+  &:disabled {
+    color: v('text-disabled', rgba(0, 0, 0, 0.25));
+    cursor: not-allowed;
+    opacity: 1;
+  }
+
+  &.#{e('table', 'action-btn-danger')} {
+    color: v('color-danger', #ec4246);
+  }
+}
+
+.#{e('table', 'action-more')} {
+  &.#{e('table', 'action-more-open')} {
+    opacity: 0.75;
+  }
+}
+
+.#{e('table', 'confirm-content')} {
+  color: v('text-2', rgba(0, 0, 0, 0.65));
+  font-size: v('font-size', 14px);
+  line-height: 22px;
+}
+
+/* ---------- 空态 ---------- */
+.#{e('table', 'empty')} {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: v('space-5', 24px);
+  color: v('text-3', rgba(0, 0, 0, 0.45));
+  font-size: v('font-size', 14px);
+}
+
+/* ---------- 表尾合计 ---------- */
+.#{b('table')} .stk-footer {
+  td {
+    border-top: 1px solid v('border-color', #d9d9d9);
+    background: v('fill', rgba(0, 0, 0, 0.02));
+    font-weight: 500;
+  }
+}
+</style>
diff --git a/code/g3soft-libs/packages/ui/src/table/index.ts b/code/g3soft-libs/packages/ui/src/table/index.ts
new file mode 100644
index 00000000..a2047fd3
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/table/index.ts
@@ -0,0 +1,19 @@
+export { default as G3Table } from './G3Table.vue'
+export { registerTableFeatures } from './G3Table.vue'
+export type {
+  G3TableColumn,
+  TableAction,
+  TableAreaRange,
+  TableColResizableConfig,
+  TableColumnDraggableConfig,
+  TableEditor,
+  TableEmits,
+  TableExpose,
+  TableFooterConfig,
+  TableProps,
+  TableRow,
+  TableRowKey,
+  TableRowSelection,
+  TableSelectOption,
+  TableSeqConfig,
+} from './types'
diff --git a/code/g3soft-libs/packages/ui/src/table/style/_overrides.scss b/code/g3soft-libs/packages/ui/src/table/style/_overrides.scss
new file mode 100644
index 00000000..79e8d661
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/table/style/_overrides.scss
@@ -0,0 +1,123 @@
+// G3Table 覆盖层：把 stk-table-vue 的主题变量映射到 @g3soft 令牌体系。
+//
+// 为什么改变量而不是改选择器：
+// 库把 41 个主题值全部做成了 `.stk-table` 作用域内的 CSS 变量（实测见 style.css）。
+// 覆盖变量既能一次改全套（边框、hover、斑马纹、排序箭头、滚动条…），
+// 又不会因为库内部 DOM 结构调整而失效。fms 的做法是逐个选择器覆写，
+// 结果同一个「边框颜色」散落在 3 处（自己画外框 + 清库的渐变 + 补行分隔线），
+// 库一升级就要重新验证每一条。这里改成一个入口。
+//
+// 所有令牌都带 fallback：未加载 @g3soft/tokens 时组件仍可正常渲染。
+@use '@g3soft/tokens/scss' as *;
+
+// 选择器说明：内层 `<StkTable class="g3-table__inner">` 渲染后自带库的 `.stk-table` 类，
+// 所以这里写 `.g3-table__inner.stk-table`（双类，权重 (0,2,0)）去压库默认的 `.stk-table`
+// （(0,1,0)）。注意 `.stk-table` 是库的固定类名，**不能**用 b('table') 生成——
+// 那会得到 `.g3-table`，而内层元素上并没有这个类，覆盖会静默失效。
+.#{b('table')} {
+  .#{e('table', 'inner')}.stk-table {
+    // ── 尺寸：行高由组件以行内 style 注入（唯一的真源），这里只兜底结构尺寸
+    --cell-padding-x: #{v('space-3', 12px)};
+    --cell-padding-y: 0;
+    --border-width: 1px;
+    --resize-handle-width: 4px;
+
+    // ── 边框与底色
+    // 库用 --border-color 派生 --bg-border-* 四条渐变（top/right/bottom/left）。
+    // 改这一个变量，四条边线一起跟随——不需要像 fms 那样在 body 上手写
+    // 三个 --bg-border-* 覆盖（那是在跟派生关系较劲，而且写到了全局作用域）。
+    --border-color: #{v('border-color', #d9d9d9)};
+    --td-bgc: #{v('bg-container', #fff)};
+    --th-bgc: #{v('fill', rgba(0, 0, 0, 0.02))};
+    --tf-bgc: #{v('fill', rgba(0, 0, 0, 0.02))};
+    --th-color: #{v('text-1', rgba(0, 0, 0, 0.88))};
+    --stripe-bgc: #{v('fill', rgba(0, 0, 0, 0.02))};
+
+    // ── hover / 选中：走令牌，不用库默认的蓝色系（hsl(207, ...)）
+    // 库默认 --td-hover-color 是 hsl(207,90%,70%)、--tr-hover-bgc 是 #e6f7ff，
+    // 那是另一套蓝色主题，与我们的主色（默认 zinc-900，可换肤）不一致。
+    --tr-hover-bgc: #{v('fill', rgba(0, 0, 0, 0.04))};
+    --tr-active-bgc: #{v('color-primary-soft', rgba(24, 24, 27, 0.12))};
+    --td-hover-color: #{v('fill-hover', rgba(0, 0, 0, 0.08))};
+    --td-active-color: #{v('color-primary-soft', rgba(24, 24, 27, 0.12))};
+
+    // ── 排序箭头
+    --sort-arrow-color: #{v('text-3', rgba(0, 0, 0, 0.45))};
+    --sort-arrow-hover-color: #{v('text-2', rgba(0, 0, 0, 0.65))};
+    --sort-arrow-active-color: #{v('color-primary', #18181b)};
+    --sort-arrow-active-sub-color: #{v('text-3', rgba(0, 0, 0, 0.45))};
+
+    // ── 展开箭头（树形 / 展开行）
+    --fold-icon-color: #{v('text-3', rgba(0, 0, 0, 0.45))};
+    --fold-icon-hover-color: #{v('text-1', rgba(0, 0, 0, 0.88))};
+
+    // ── 固定列阴影：用主色系中性阴影，与浮层阴影同一档
+    --fixed-col-shadow-color-from: rgba(0, 0, 0, 0.1);
+    --fixed-col-shadow-color-to: rgba(0, 0, 0, 0);
+
+    // ── 拖拽手柄 / 列宽指示器
+    --drag-handle-hover-color: #{v('fill-hover', rgba(0, 0, 0, 0.08))};
+    --col-resize-indicator-color: #{v('color-primary', #18181b)};
+
+    // ── 滚动条
+    --sb-thumb-color: #{v('text-3', rgba(0, 0, 0, 0.25))};
+    --sb-thumb-hover-color: #{v('text-2', rgba(0, 0, 0, 0.45))};
+
+    // ── 区域选择（行内编辑依赖）：主色淡底 + 主色描边
+    --cs-bgc: #{v('color-primary-soft', rgba(24, 24, 27, 0.12))};
+    --cs-bc: #{v('color-primary', #18181b)};
+    --rs-bgc: #{v('color-primary-soft', rgba(24, 24, 27, 0.12))};
+    --rs-bc: #{v('color-primary', #18181b)};
+
+    // ── 单元格高亮（程序化 highlight）
+    --highlight-color: #{v('color-primary', #18181b)};
+
+    // ── 字体：库用 inherit，这里显式跟随令牌
+    font-family: v('font-family', inherit);
+    font-size: v('font-size', 14px);
+    color: v('text-1', rgba(0, 0, 0, 0.88));
+  }
+}
+
+// ── 暗色主题：库自带 `.stk-table.dark` 的一套默认值，同样以变量覆盖
+// 组件会把 theme 透传给库（跟随 ConfigProvider / documentElement）。
+.#{b('table')} {
+  .#{e('table', 'inner')}.stk-table.dark {
+    --border-color: #{v('border-color', #424242)};
+    --td-bgc: #{v('bg-container', #141414)};
+    --th-bgc: #{v('fill', rgba(255, 255, 255, 0.04))};
+    --tf-bgc: #{v('fill', rgba(255, 255, 255, 0.04))};
+    --th-color: #{v('text-1', rgba(255, 255, 255, 0.88))};
+    --stripe-bgc: #{v('fill', rgba(255, 255, 255, 0.04))};
+
+    --tr-hover-bgc: #{v('fill', rgba(255, 255, 255, 0.06))};
+    --tr-active-bgc: #{v('color-primary-soft', rgba(255, 255, 255, 0.12))};
+    --td-hover-color: #{v('fill-hover', rgba(255, 255, 255, 0.12))};
+    --td-active-color: #{v('color-primary-soft', rgba(255, 255, 255, 0.12))};
+
+    --sort-arrow-color: #{v('text-3', rgba(255, 255, 255, 0.45))};
+    --sort-arrow-hover-color: #{v('text-2', rgba(255, 255, 255, 0.65))};
+    --sort-arrow-active-color: #{v('color-primary', #e5e5e5)};
+    --sort-arrow-active-sub-color: #{v('text-3', rgba(255, 255, 255, 0.45))};
+
+    --fold-icon-color: #{v('text-3', rgba(255, 255, 255, 0.45))};
+    --fold-icon-hover-color: #{v('text-1', rgba(255, 255, 255, 0.88))};
+
+    --fixed-col-shadow-color-from: rgba(0, 0, 0, 0.45);
+    --fixed-col-shadow-color-to: rgba(0, 0, 0, 0);
+
+    --drag-handle-hover-color: #{v('fill-hover', rgba(255, 255, 255, 0.12))};
+    --col-resize-indicator-color: #{v('color-primary', #e5e5e5)};
+
+    --sb-thumb-color: #{v('text-3', rgba(255, 255, 255, 0.25))};
+    --sb-thumb-hover-color: #{v('text-2', rgba(255, 255, 255, 0.45))};
+
+    --cs-bgc: #{v('color-primary-soft', rgba(255, 255, 255, 0.12))};
+    --cs-bc: #{v('color-primary', #e5e5e5)};
+    --rs-bgc: #{v('color-primary-soft', rgba(255, 255, 255, 0.12))};
+    --rs-bc: #{v('color-primary', #e5e5e5)};
+
+    --highlight-color: #{v('color-primary', #e5e5e5)};
+  }
+}
+
diff --git a/code/g3soft-libs/packages/ui/src/table/style/index.scss b/code/g3soft-libs/packages/ui/src/table/style/index.scss
new file mode 100644
index 00000000..4ba3750e
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/table/style/index.scss
@@ -0,0 +1,22 @@
+// G3Table 的底座样式层。
+//
+// stk-table-vue 的样式是**独立文件**（实测其 JS 里没有任何 .css import），
+// 组件库不能要求消费方额外引一次第三方样式，所以在这里 @import 进来，
+// 与我们的覆盖层一起由 vite 打进 dist/style.css。
+//
+// 覆盖策略：**优先覆盖库的 CSS 变量，而不是逐个选择器改样式**。
+// 库把 41 个主题值全做成了 .stk-table 作用域内的变量，改变量既省事，
+// 也不会因为库内部结构调整而失效（改选择器则会）。
+@use '@g3soft/tokens/scss' as *;
+
+// 库样式：light 主题的变量表 + 全部结构样式。
+//
+// ⚠️ 路径**不能带 `.css` 后缀**：Sass 对以 .css 结尾的 @import/@use 有特殊规则——
+// 它不会内联，只原样输出一条 CSS `@import 'stk-table-vue/lib/style.css'` 语句。
+// 那样产物里留下的是一条裸包路径，浏览器无法解析，线上直接掉样式。
+// 实测对比：带后缀产出 38 字符（仅一条 import 语句），不带后缀产出 19012 字符（真正内联）。
+// 同理用 @use 而非 @import：后者在 Dart Sass 3.0 会被移除。
+@use 'stk-table-vue/lib/style';
+
+// 我们的令牌映射与结构修正
+@use './overrides' as *;
diff --git a/code/g3soft-libs/packages/ui/src/table/types.ts b/code/g3soft-libs/packages/ui/src/table/types.ts
new file mode 100644
index 00000000..a59ca36b
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/table/types.ts
@@ -0,0 +1,200 @@
+import type { Component, VNode } from 'vue'
+import type { StkTableColumn } from 'stk-table-vue'
+
+/**
+ * G3Table 类型定义。
+ *
+ * 底座是 `stk-table-vue`：虚拟滚动 / 列宽拖拽 / 列序拖拽 / 区域选择 / 行拖拽排序
+ * 都由它提供。这里**不重写**它的列类型，而是 `Omit` 后扩展——重写会随库版本漂移。
+ */
+
+/** 行数据的约束：必须是对象，且键为字符串 */
+export type TableRow = Record<string, any>
+
+/** 行唯一键：字段名或取值函数 */
+export type TableRowKey<T extends TableRow> = keyof T & string | ((row: T) => string | number)
+
+/** 下拉选项（行内编辑 select 用） */
+export interface TableSelectOption {
+  label: string
+  value: string | number | boolean | null
+  disabled?: boolean
+}
+
+/** 行内编辑器配置 */
+export interface TableEditor<T extends TableRow = TableRow> {
+  type: 'text' | 'number' | 'password' | 'textarea' | 'select' | 'checkbox'
+  /**
+   * select 的选项。
+   * 传函数时接收当前行——列选项依赖同行其它列时用它（如「按目标模块列出目标字段」）。
+   */
+  options?: TableSelectOption[] | ((row: T) => TableSelectOption[])
+  /** 是否禁用该单元格编辑 */
+  disabled?: boolean | ((row: T) => boolean)
+  /** select 是否可清空，默认 true */
+  allowClear?: boolean
+  /** select 清空后落库的值，默认 null */
+  emptyValue?: unknown
+  /** 本列值变化时的回调（早于组件的 change 事件） */
+  onChange?: (value: unknown, row: T, col: G3TableColumn<T>) => void
+}
+
+/**
+ * 操作列按钮配置。
+ *
+ * `danger` / `type` 决定按钮色；带 `confirm` 时先弹确认框再执行 `onClick`。
+ */
+export interface TableAction<T extends TableRow = TableRow> {
+  /** 唯一键；`type: 'more'` 的子项用它做下拉菜单的 key，不传则回退到 type / 下标 */
+  key?: string | number
+  /** 文案 */
+  label?: string
+  /** 语义类型：danger / delete 走危险色 */
+  type?: 'default' | 'danger' | 'delete' | 'more'
+  /** 图标组件（lucide），渲染为 size=14 */
+  icon?: Component
+  title?: string
+  danger?: boolean
+  /** 是否显示该操作 */
+  visible?: boolean | ((row: T) => boolean)
+  disabled?: boolean | ((row: T) => boolean)
+  /** 二次确认：字符串=标题；对象=完整配置 */
+  confirm?:
+    | string
+    | {
+        title?: string
+        description?: string
+        content?: string
+        okText?: string
+        cancelText?: string
+        /** 默认 danger */
+        okType?: 'danger' | 'primary'
+        width?: number
+        maskClosable?: boolean
+      }
+  onClick?: (row: T) => void
+  /** type === 'more' 时的子项 */
+  items?: TableAction<T>[]
+}
+
+/**
+ * 列定义：底座 `StkTableColumn` 的**严格超集**。
+ *
+ * 刻意用 `&` 交叉而不是 `Omit` 重写字段：底座的 `sortField?: keyof T` 在
+ * `T extends Record<string, any>` 下会展开成 `string | number | symbol`，
+ * 一旦我们把它收窄成 `string`，`G3TableColumn` 就不再能赋值给
+ * `StkTableColumn<any>`，整棵列数组传不进库（会连锁报一串类型错误）。
+ * 交叉则只增不改，天然兼容。
+ *
+ * `dataIndex` 收紧为 `keyof T & string`：底座的 `keyof T & string` 本身就是这样，
+ * 这里显式写出仅为可读性，不产生新的不兼容。
+ */
+export type G3TableColumn<T extends TableRow = TableRow> = StkTableColumn<T> & {
+  /** 该列是否允许拖拽调宽。操作列 / 展开列必须显式设 false */
+  resizable?: boolean
+  /** 行内编辑器 */
+  editor?: TableEditor<T>
+  /** 操作列按钮 */
+  actions?: TableAction<T>[]
+}
+
+/** 行多选配置 */
+export interface TableRowSelection<T extends TableRow = TableRow> {
+  selectedRowKeys?: Array<string | number>
+  onChange?: (keys: Array<string | number>, rows: T[]) => void
+  /** 单行是否禁用勾选 */
+  getCheckboxProps?: (row: T) => { disabled?: boolean }
+}
+
+/** 序号列配置 */
+export interface TableSeqConfig {
+  title?: string
+  width?: number
+}
+
+/** 列宽拖拽配置 */
+export interface TableColResizableConfig<T extends TableRow = TableRow> {
+  disabled?: boolean | ((col: G3TableColumn<T>) => boolean)
+}
+
+/** 列序拖拽配置 */
+export interface TableColumnDraggableConfig<T extends TableRow = TableRow> {
+  mode?: 'insert' | 'swap'
+  disabled?: boolean | ((col: G3TableColumn<T>) => boolean)
+}
+
+/** 区域选择范围（透传底座） */
+export interface TableAreaRange {
+  index: { start: { row: number; col: number }; end: { row: number; col: number } }
+}
+
+/** 表尾合计列配置 */
+export interface TableFooterConfig {
+  [key: string]: unknown
+}
+
+/** 组件 props */
+export interface TableProps<T extends TableRow = TableRow> {
+  /** 列定义 */
+  columns?: G3TableColumn<T>[]
+  /** 数据源 */
+  dataSource?: T[]
+  /** 行唯一键 */
+  rowKey?: TableRowKey<T>
+  /** 纵向虚拟滚动总开关（实际是否开启受行数门控，见 G3Table.vue 注释） */
+  virtual?: boolean
+  /** 横向虚拟滚动总开关（实际是否开启受列数门控） */
+  virtualX?: boolean
+  /** 行高：唯一真源，同时驱动虚拟滚动计算与 CSS 变量 */
+  rowHeight?: number
+  /** 表头行高 */
+  headerRowHeight?: number
+  /** 边框：true=外框圆角描边+行分隔线；false=无外框仅行分隔线 */
+  bordered?: boolean | string
+  /** 列宽拖拽 */
+  colResizable?: boolean | TableColResizableConfig<T>
+  /** 列序拖拽 */
+  columnDraggable?: boolean | TableColumnDraggableConfig<T>
+  /** 行拖拽排序 */
+  rowDraggable?: boolean
+  /** 行多选 */
+  rowSelection?: TableRowSelection<T> | null
+  /** 序号列 */
+  seq?: boolean | TableSeqConfig
+  /** 当前高亮行 key */
+  activeRowKey?: string | number | null
+  /** 行内编辑总开关 */
+  editable?: boolean
+  /** 空态是否铺满容器 */
+  noDataFull?: boolean
+  /** 溢出省略 */
+  showOverflow?: boolean
+  /** 非横向虚拟时铺满容器 */
+  autoFitWidth?: boolean
+  /** 主题；不传则跟随全局主题（ConfigProvider / documentElement） */
+  theme?: 'light' | 'dark'
+  /** 表尾数据 */
+  footerData?: TableRow[]
+  /** 表尾配置 */
+  footerConfig?: TableFooterConfig
+}
+
+/** 组件事件 */
+export interface TableEmits<T extends TableRow = TableRow> {
+  (e: 'update:columns', columns: G3TableColumn<T>[]): void
+  (e: 'update:selectedRowKeys', keys: Array<string | number>): void
+  (e: 'change', row: T, col: G3TableColumn<T>, value: unknown): void
+  (e: 'row-order-change', rows: T[], sourceIndex: number, targetIndex: number): void
+  (e: 'area-selection-change', ranges: TableAreaRange[]): void
+}
+
+/** 组件实例方法 */
+export interface TableExpose {
+  scrollToRow(rowKey: string | number): Promise<void>
+  editRow(rowKey: string | number, focusCol?: string | null): Promise<void>
+  initVirtualScroll(): void
+  refreshLayout(): void
+  getSelectedArea(): unknown
+  clearSelectedArea(): void
+  setRowExpand(...args: unknown[]): unknown
+}
diff --git a/code/g3soft-libs/packages/ui/src/table/utils/actions.ts b/code/g3soft-libs/packages/ui/src/table/utils/actions.ts
new file mode 100644
index 00000000..33311ff0
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/table/utils/actions.ts
@@ -0,0 +1,248 @@
+import { h, ref } from 'vue'
+import { G3Button } from '../../button'
+import { G3Dropdown } from '../../dropdown'
+import { G3Modal } from '../../modal'
+import { useNamespace } from '../../_composables/useNamespace'
+import type { DropdownClickPayload, DropdownItemData } from '../../dropdown'
+import type { G3TableColumn, TableAction, TableRow } from '../types'
+
+/**
+ * 操作列。
+ *
+ * 两类按钮：内联的（直接渲染成小按钮）与「更多」下拉（`type: 'more'`）。
+ * 带 `confirm` 的操作先弹确认框——用**状态化**的 G3Modal 而不是命令式 `Modal.confirm()`，
+ * 后者依赖全局挂载容器，组件库不该有这种隐式依赖。
+ */
+
+const stop = (event: Event) => event.stopPropagation()
+
+function resolveActionState<T extends TableRow>(
+  state: boolean | ((row: T) => boolean) | undefined,
+  row: T,
+): boolean {
+  return typeof state === 'function' ? Boolean(state(row)) : Boolean(state)
+}
+
+function isActionVisible<T extends TableRow>(action: TableAction<T>, row: T): boolean {
+  return action.visible === undefined || resolveActionState(action.visible, row)
+}
+
+/** 单个内联操作按钮 */
+function actionButton<T extends TableRow>(
+  action: TableAction<T>,
+  row: T,
+  triggerAction: (action: TableAction<T>, row: T) => void,
+  e: (el: string) => string,
+) {
+  const disabled = resolveActionState(action.disabled, row)
+  const content: unknown[] = []
+  if (action.icon) content.push(h(action.icon, { size: 14 }))
+  if (action.label || action.type) content.push(action.label || action.type)
+
+  return h(
+    'button',
+    {
+      type: 'button',
+      class: [
+        e('action-btn'),
+        {
+          [e('action-btn-danger')]:
+            action.danger || action.type === 'danger' || action.type === 'delete',
+        },
+      ],
+      title: action.title || action.label,
+      disabled,
+      onMousedown: stop,
+      onClick: (event: MouseEvent) => {
+        event.stopPropagation()
+        triggerAction(action, row)
+      },
+    },
+    content as never,
+  )
+}
+
+/**
+ * 二次确认弹窗。
+ *
+ * 两个 prop/事件名极易写错（Vue 会静默吞掉未声明者，不报错、只是功能失效）：
+ * - 按钮文案是 `confirmText` / `cancelText`，**不是** antdv 的 `okText`；
+ * - 确认事件是 `onConfirm`，**不是** antdv 的 `onOk`。
+ */
+function createConfirmDialog<T extends TableRow>(
+  state: { value: { action: TableAction<T>; row: T } | null },
+  close: () => void,
+  e: (el: string) => string,
+) {
+  const current = state.value
+  if (!current) return null
+  const { action, row } = current
+  const config = typeof action.confirm === 'string' ? { title: action.confirm } : action.confirm || {}
+  const title = config.title || '确认操作'
+  const description = config.description ?? config.content ?? '确定要执行此操作吗？'
+  const confirmText = config.okText || '确定'
+  const cancelText = config.cancelText || '取消'
+  const danger = (config.okType ?? 'danger') === 'danger'
+
+  return h(
+    G3Modal,
+    {
+      open: true,
+      title,
+      width: config.width ?? 416,
+      centered: true,
+      closable: false,
+      fullscreen: false,
+      resizable: false,
+      maskClosable: Boolean(config.maskClosable ?? false),
+      confirmText,
+      cancelText,
+      'onUpdate:open': (open: boolean) => {
+        if (!open) close()
+      },
+      onCancel: close,
+      onConfirm: () => {
+        close()
+        action.onClick?.(row)
+      },
+    },
+    {
+      default: () => h('div', { class: e('confirm-content') }, description),
+      footer: danger
+        ? () => [
+            h(G3Button, { type: 'outline', onClick: close }, () => cancelText),
+            h(
+              G3Button,
+              {
+                type: 'danger',
+                onClick: () => {
+                  close()
+                  action.onClick?.(row)
+                },
+              },
+              () => confirmText,
+            ),
+          ]
+        : undefined,
+    },
+  )
+}
+
+/**
+ * 生成操作列的单元格渲染函数。
+ *
+ * `actions` 为空时返回 undefined（调用方据此决定是否注入 customCell）。
+ */
+export function createActionsCell<T extends TableRow>(actions: TableAction<T>[]) {
+  if (!actions?.length) return undefined
+
+  const { e } = useNamespace('table')
+
+  const inlineActions = actions.filter((action) => action.type !== 'more')
+  const moreAction = actions.find((action) => action.type === 'more')
+  const openRow = ref<T | null>(null)
+  const confirmState = ref<{ action: TableAction<T>; row: T } | null>(null) as {
+    value: { action: TableAction<T>; row: T } | null
+  }
+
+  function closeMenu() {
+    openRow.value = null
+  }
+
+  function closeConfirm() {
+    confirmState.value = null
+  }
+
+  function triggerAction(action: TableAction<T>, row: T) {
+    if (resolveActionState(action.disabled, row)) return
+    if (!action.confirm) {
+      action.onClick?.(row)
+      return
+    }
+    confirmState.value = { action, row }
+  }
+
+  return ({ row }: { row: T }) => {
+    const children: unknown[] = inlineActions
+      .filter((action) => isActionVisible(action, row))
+      .map((action) => actionButton(action, row, triggerAction, e))
+
+    // 确认弹窗必须先于「无更多项」的提前 return 渲染——否则只配内联操作（如删除）时，
+    // confirmState 已置位但弹窗永远不出现（表现为「删除按钮点了没反应」）。
+    const dialog = createConfirmDialog(confirmState, closeConfirm, e)
+    if (dialog) children.push(dialog)
+
+    const visibleMoreItems = (moreAction?.items || []).filter((item) => isActionVisible(item, row))
+    if (!visibleMoreItems.length) return h('span', { class: e('actions-cell') }, children as never)
+
+    const menuItems: DropdownItemData[] = visibleMoreItems.map((item, index) => ({
+      key: String(item.key ?? item.type ?? index),
+      label: item.label,
+      icon: item.icon ? h(item.icon, { size: 14 }) : undefined,
+      disabled: resolveActionState(item.disabled, row),
+      danger: item.danger || item.type === 'danger' || item.type === 'delete',
+    }))
+    const visibleItemByKey = new Map(
+      visibleMoreItems.map((item, index) => [String(item.key ?? item.type ?? index), item]),
+    )
+
+    if (openRow.value !== row) {
+      children.push(
+        h(
+          'button',
+          {
+            type: 'button',
+            class: [e('action-btn'), e('action-more')],
+            title: moreAction?.title || '更多操作',
+            'aria-label': moreAction?.title || '更多操作',
+            onMousedown: stop,
+            onClick: (event: MouseEvent) => {
+              event.stopPropagation()
+              openRow.value = row
+            },
+          },
+          moreAction?.label || '⋯',
+        ),
+      )
+    } else {
+      children.push(
+        h(
+          G3Dropdown,
+          {
+            open: true,
+            placement: 'bottom-end',
+            offset: 4,
+            items: menuItems,
+            'onUpdate:open': (open: boolean) => {
+              if (!open) closeMenu()
+            },
+            onClick: (payload: DropdownClickPayload) => {
+              const item =
+                visibleItemByKey.get(String(payload?.key)) ??
+                visibleMoreItems.find((it, index) => String(it.key ?? it.type ?? index) === String(payload?.key))
+              closeMenu()
+              if (item) triggerAction(item, row)
+            },
+          },
+          {
+            default: () =>
+              h(
+                'button',
+                {
+                  type: 'button',
+                  class: [e('action-btn'), e('action-more'), e('action-more-open')],
+                  title: moreAction?.title || '更多操作',
+                  'aria-label': moreAction?.title || '更多操作',
+                  onMousedown: stop,
+                  onClick: stop,
+                },
+                moreAction?.label || '⋯',
+              ),
+          },
+        ),
+      )
+    }
+
+    return h('span', { class: e('actions-cell') }, children as never)
+  }
+}
diff --git a/code/g3soft-libs/packages/ui/src/table/utils/column.test.ts b/code/g3soft-libs/packages/ui/src/table/utils/column.test.ts
new file mode 100644
index 00000000..397dc28a
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/table/utils/column.test.ts
@@ -0,0 +1,184 @@
+import { describe, expect, it } from 'vitest'
+import {
+  DRAG_ROW_COLUMN_TYPE,
+  SEQ_COLUMN_TYPE,
+  getHeaderAlign,
+  isInternalColumn,
+  readInternalWidths,
+  resolveSeqConfig,
+  stripInternalColumns,
+} from './column'
+import { createSelectionColumn, isSelectionColumn, SELECTION_COLUMN_KEY } from './selection'
+import type { G3TableColumn, TableRow } from '../types'
+
+/** 造一列的最小工具 */
+function col(dataIndex: string, extra: Partial<G3TableColumn<TableRow>> = {}) {
+  return { dataIndex, title: dataIndex, ...extra } as G3TableColumn<TableRow>
+}
+
+describe('resolveSeqConfig', () => {
+  it('seq 为假时不启用', () => {
+    expect(resolveSeqConfig(false).enabled).toBe(false)
+    expect(resolveSeqConfig(undefined).enabled).toBe(false)
+  })
+
+  it('seq 为 true 时用默认标题与宽度', () => {
+    const cfg = resolveSeqConfig(true)
+    expect(cfg).toEqual({ enabled: true, title: '序号', width: 50 })
+  })
+
+  it('传对象时接受自定义标题与宽度', () => {
+    expect(resolveSeqConfig({ title: 'No.', width: 80 })).toEqual({
+      enabled: true,
+      title: 'No.',
+      width: 80,
+    })
+  })
+
+  it('宽度转成数字（字符串也接受）', () => {
+    expect(resolveSeqConfig({ width: '64' as unknown as number }).width).toBe(64)
+  })
+
+  it('只给 title 时宽度回落默认值', () => {
+    expect(resolveSeqConfig({ title: '序号列' }).width).toBe(50)
+  })
+})
+
+describe('getHeaderAlign', () => {
+  it('显式声明优先于一切推断', () => {
+    expect(getHeaderAlign(col('a', { headerAlign: 'right' }))).toBe('right')
+  })
+
+  it('序号列居中', () => {
+    expect(getHeaderAlign(col('', { type: SEQ_COLUMN_TYPE }))).toBe('center')
+  })
+
+  it('选择列居中', () => {
+    const selection = { dataIndex: SELECTION_COLUMN_KEY, [SELECTION_COLUMN_KEY]: true } as unknown as G3TableColumn<TableRow>
+    expect(getHeaderAlign(selection)).toBe('center')
+  })
+
+  it('操作列居中（按 dataIndex 与 actions 两种写法都能识别）', () => {
+    expect(getHeaderAlign(col('actions'))).toBe('center')
+    expect(getHeaderAlign(col('op', { actions: [{ label: '删除' }] }))).toBe('center')
+  })
+
+  it('checkbox 编辑器列居中', () => {
+    expect(getHeaderAlign(col('flag', { editor: { type: 'checkbox' } }))).toBe('center')
+  })
+
+  it('普通列左对齐', () => {
+    expect(getHeaderAlign(col('name'))).toBe('left')
+  })
+})
+
+describe('isInternalColumn', () => {
+  it('识别选择列', () => {
+    const selection = { dataIndex: SELECTION_COLUMN_KEY, [SELECTION_COLUMN_KEY]: true } as unknown as G3TableColumn<TableRow>
+    expect(isInternalColumn(selection)).toBe(true)
+    expect(isSelectionColumn(selection)).toBe(true)
+  })
+
+  it('识别序号列与拖拽列', () => {
+    expect(isInternalColumn(col('', { type: SEQ_COLUMN_TYPE }))).toBe(true)
+    expect(isInternalColumn(col('__g3DragRow', { type: DRAG_ROW_COLUMN_TYPE }))).toBe(true)
+  })
+
+  it('业务列不算内部列', () => {
+    expect(isInternalColumn(col('name'))).toBe(false)
+    expect(isInternalColumn(col('amount'))).toBe(false)
+  })
+})
+
+describe('stripInternalColumns', () => {
+  const original = [col('name'), col('amount')]
+
+  it('剥离内部列，只回传业务列', () => {
+    const written = [
+      col(SELECTION_COLUMN_KEY, { [SELECTION_COLUMN_KEY]: true } as never),
+      col('', { type: SEQ_COLUMN_TYPE }),
+      col('name', { width: 120 }),
+      col('amount', { width: 90 }),
+    ] as G3TableColumn<TableRow>[]
+    const result = stripInternalColumns(written, original)
+    expect(result.map((c) => c.dataIndex)).toEqual(['name', 'amount'])
+  })
+
+  it('把新宽度回写到原始列（保留原始列的其它配置）', () => {
+    const withTitle = [{ dataIndex: 'name', title: '名称', width: 100 }] as G3TableColumn<TableRow>[]
+    const written = [col('name', { width: 260 })] as G3TableColumn<TableRow>[]
+    const result = stripInternalColumns(written, withTitle)
+    expect(result[0].width).toBe(260)
+    // 原始 title 必须保留：回写的列对象来自库，不带着我们的配置
+    expect(result[0].title).toBe('名称')
+  })
+
+  it('空数组安全', () => {
+    expect(stripInternalColumns([], original)).toEqual([])
+    expect(stripInternalColumns(undefined as never, original)).toEqual([])
+  })
+})
+
+describe('readInternalWidths', () => {
+  it('读回三个内部列的宽度', () => {
+    const written = [
+      col(SELECTION_COLUMN_KEY, { [SELECTION_COLUMN_KEY]: true, width: 60 } as never),
+      col('', { type: SEQ_COLUMN_TYPE, width: 70 }),
+      col('__g3DragRow', { type: DRAG_ROW_COLUMN_TYPE, width: 40 }),
+      col('name', { width: 200 }),
+    ] as G3TableColumn<TableRow>[]
+    expect(readInternalWidths(written)).toEqual({ selection: 60, seq: 70, dragRow: 40 })
+  })
+
+  it('业务列宽度不进入结果', () => {
+    expect(readInternalWidths([col('name', { width: 200 })] as G3TableColumn<TableRow>[])).toEqual({})
+  })
+
+  it('宽度为空或非数字时跳过', () => {
+    const written = [
+      col('', { type: SEQ_COLUMN_TYPE }),
+      col(SELECTION_COLUMN_KEY, { [SELECTION_COLUMN_KEY]: true, width: 'abc' } as never),
+    ] as G3TableColumn<TableRow>[]
+    expect(readInternalWidths(written)).toEqual({})
+  })
+})
+
+describe('createSelectionColumn', () => {
+  function setup(selectedRowKeys: Array<string | number> = [], disabledKeys: Array<string | number> = []) {
+    const data = [{ id: 1 }, { id: 2 }, { id: 3 }]
+    const changes: Array<{ keys: Array<string | number>; rows: TableRow[] }> = []
+    const column = createSelectionColumn<TableRow>({
+      getDataSource: () => data,
+      getRowKey: (row) => row.id as number,
+      getSelectedRowKeys: () => selectedRowKeys,
+      isRowDisabled: (row) => disabledKeys.includes(row.id as number),
+      onChange: (keys, rows) => changes.push({ keys, rows }),
+    })
+    return { column, changes, data }
+  }
+
+  it('返回的列带内部标识，且固定在左侧居中', () => {
+    const { column } = setup()
+    expect(isSelectionColumn(column)).toBe(true)
+    expect(column.fixed).toBe('left')
+    expect(column.align).toBe('center')
+    expect(column.headerAlign).toBe('center')
+    expect(column.width).toBe(44)
+  })
+
+  it('行单元格是函数（供库作 customCell 调用），且能渲染出原生 checkbox', () => {
+    const { column } = setup([1])
+    const render = column.customCell as unknown as (p: { row: TableRow }) => { children: unknown[] }
+    const vnode = render({ row: { id: 1 } })
+    // 第一个子节点是 <input type="checkbox">
+    const input = (vnode.children as Array<{ type: string; props: Record<string, unknown> }>)[0]
+    expect(input.type).toBe('input')
+    expect(input.props.type).toBe('checkbox')
+    expect(input.props.checked).toBe(true)
+  })
+
+  it('表头单元格存在且是函数', () => {
+    const { column } = setup()
+    expect(typeof column.customHeaderCell).toBe('function')
+  })
+})
diff --git a/code/g3soft-libs/packages/ui/src/table/utils/column.ts b/code/g3soft-libs/packages/ui/src/table/utils/column.ts
new file mode 100644
index 00000000..a2f4ae05
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/table/utils/column.ts
@@ -0,0 +1,144 @@
+import { createActionsCell } from './actions'
+import { createEditableCell, type EditableContext } from './editable'
+import { isSelectionColumn } from './selection'
+import type { G3TableColumn, TableRow } from '../types'
+
+/**
+ * 列处理的公共逻辑：内部列注入/剥离、对齐推断、customCell 注入。
+ *
+ * 独立成模块是因为 `resolveCustomCell` 同时依赖 editable 与 actions 两条链路，
+ * 塞进任何一边都会形成别扭的跨模块参数传递。
+ */
+
+/** 序号列的内部类型标识（库用它渲染行号） */
+export const SEQ_COLUMN_TYPE = 'seq'
+/** 行拖拽列的内部类型标识（库用它渲染拖拽手柄） */
+export const DRAG_ROW_COLUMN_TYPE = 'dragRow'
+
+/** 内部列（选择 / 序号 / 拖拽 / 操作）的 dataIndex，用于回写时识别并剥离 */
+const INTERNAL_DATA_INDEXES = new Set(['', '__g3Selection', '__g3DragRow', '__actions__'])
+
+export interface SeqConfig {
+  enabled: boolean
+  title: string
+  width: number
+}
+
+/** 由 seq prop 派生序号列配置 */
+export function resolveSeqConfig(
+  seq: boolean | { title?: string; width?: number } | undefined,
+): SeqConfig {
+  if (!seq) return { enabled: false, title: '序号', width: 50 }
+  const cfg: { title?: string; width?: number } = seq === true ? {} : seq
+  return {
+    enabled: true,
+    title: cfg.title ?? '序号',
+    width: Number(cfg.width ?? 50),
+  }
+}
+
+/**
+ * 表头对齐推断。
+ *
+ * 规则：显式声明优先；序号列 / 选择列 / 操作列 / checkbox 列一律居中——
+ * 这些列的内容是图标或短数字，左对齐会显得浮。
+ */
+export function getHeaderAlign<T extends TableRow>(
+  column: G3TableColumn<T>,
+): 'left' | 'center' | 'right' {
+  if (column.headerAlign) return column.headerAlign as 'left' | 'center' | 'right'
+  if (column.type === SEQ_COLUMN_TYPE) return 'center'
+  if (isSelectionColumn(column)) return 'center'
+  if (column.dataIndex === 'actions') return 'center'
+  if (column.actions && column.actions.length) return 'center'
+  if (column.editor && column.editor.type === 'checkbox') return 'center'
+  return 'left'
+}
+
+/**
+ * 给一列决定是否注入 `customCell`。
+ *
+ * **这是整个表格性能上最要紧的一处判断**：
+ * 纯展示列与非编辑态的可编辑列**不注入** customCell，让它们走库的原生 td 渲染路径。
+ * 每格少一个函数式组件实例；滚动时可见格数以百计，省下的是实打实的挂载/更新开销。
+ *
+ * `editingActive` 表示「全表是否有任意一行处于编辑态」：
+ * - false：可编辑列也走原生 td（非编辑态本来只展示文本）
+ * - true：可编辑列挂编辑器渲染（内部再按行判断是否真处于编辑态）
+ *
+ * checkbox 与 select 例外，始终注入：前者要能随时点，后者要把值解析成 label 展示。
+ */
+export function resolveCustomCell<T extends TableRow>(
+  col: G3TableColumn<T>,
+  editingContext: EditableContext<T>,
+  editingActive: boolean,
+): G3TableColumn<T> {
+  // 调用方显式给了渲染函数：尊重它，不再包装
+  if (col.customCell) return col
+
+  const editor = col.editor
+  if (editor && (editingActive || editor.type === 'checkbox' || editor.type === 'select')) {
+    return {
+      ...col,
+      customCell: createEditableCell(col, editingContext) as unknown as G3TableColumn<T>['customCell'],
+    }
+  }
+
+  if (col.actions?.length) {
+    const actionsCell = createActionsCell(col.actions)
+    if (actionsCell) {
+      return { ...col, customCell: actionsCell as unknown as G3TableColumn<T>['customCell'] }
+    }
+  }
+
+  return col
+}
+
+/** 判断是否为内部生成的列（不可被拖拽调宽 / 拖拽换序 / 回写给父级） */
+export function isInternalColumn<T extends TableRow>(column: G3TableColumn<T>): boolean {
+  return (
+    isSelectionColumn(column) ||
+    column.type === SEQ_COLUMN_TYPE ||
+    column.type === DRAG_ROW_COLUMN_TYPE ||
+    INTERNAL_DATA_INDEXES.has(String(column.dataIndex))
+  )
+}
+
+/**
+ * 从库回写的 columns 里剥离内部列，只回传业务列。
+ *
+ * 库在拖拽列宽/列序后会回写**全部**列（含我们注入的选择列、序号列），
+ * 直接把它 emit 给父级会污染父组件的 columns（表现为父级数据里多出几列，
+ * 下次渲染重复注入、列越滚越多）。这里按 key 找回原始列，只更新 width。
+ */
+export function stripInternalColumns<T extends TableRow>(
+  columns: G3TableColumn<T>[],
+  originalColumns: G3TableColumn<T>[],
+): G3TableColumn<T>[] {
+  const originalByKey = new Map(
+    originalColumns.map((col) => [String(col.key ?? col.dataIndex ?? ''), col]),
+  )
+  return (columns || [])
+    .filter((col) => !isInternalColumn(col))
+    .map((col) => {
+      const original = originalByKey.get(String(col.key ?? col.dataIndex ?? ''))
+      return original ? { ...original, width: col.width ?? original.width } : col
+    })
+}
+
+/**
+ * 从回写的列里同步内部列（选择列 / 序号列 / 拖拽列）的宽度。
+ * 用户可能拖宽这几列，宽度要留在组件内部状态里，而不是回传给父级。
+ */
+export function readInternalWidths<T extends TableRow>(columns: G3TableColumn<T>[]) {
+  const result: { selection?: number; seq?: number; dragRow?: number } = {}
+  for (const column of columns || []) {
+    if (column.width == null) continue
+    const width = Number.parseInt(String(column.width), 10)
+    if (!Number.isFinite(width)) continue
+    if (isSelectionColumn(column)) result.selection = width
+    else if (column.type === SEQ_COLUMN_TYPE) result.seq = width
+    else if (column.type === DRAG_ROW_COLUMN_TYPE) result.dragRow = width
+  }
+  return result
+}
diff --git a/code/g3soft-libs/packages/ui/src/table/utils/editable.test.ts b/code/g3soft-libs/packages/ui/src/table/utils/editable.test.ts
new file mode 100644
index 00000000..19e7bd3b
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/table/utils/editable.test.ts
@@ -0,0 +1,406 @@
+import { describe, expect, it, vi } from 'vitest'
+import { createEditableCell, type EditableContext } from './editable'
+import type { G3TableColumn, TableRow } from '../types'
+
+interface Row extends TableRow {
+  id: number
+  name: string
+  status: number
+}
+
+function makeColumn(extra: Partial<G3TableColumn<Row>> = {}): G3TableColumn<Row> {
+  return { dataIndex: 'name', title: '名称', ...extra } as G3TableColumn<Row>
+}
+
+/**
+ * 造一个可控的编辑上下文桩。
+ * 默认：该行处于编辑态、当前编辑列就是目标列、用户刚激活（需要聚焦）。
+ */
+function makeCtx(overrides: Partial<EditableContext<Row>> = {}): {
+  ctx: EditableContext<Row>
+  changes: Array<{ row: Row; value: unknown }>
+  focused: boolean[]
+  blurred: boolean[]
+  notified: number
+} {
+  const changes: Array<{ row: Row; value: unknown }> = []
+  const focused: number[] = []
+  const blurred: number[] = []
+  let notified = 0
+  const ctx: EditableContext<Row> = {
+    isEditing: () => true,
+    shouldFocus: () => true,
+    wasFocused: () => false,
+    consumePendingFocus: () => true,
+    onEditorFocus: (row) => focused.push(row.id),
+    onEditorBlur: (row) => blurred.push(row.id),
+    shouldNotify: () => {
+      notified += 1
+      return true
+    },
+    onChange: (row, _col, value) => changes.push({ row, value }),
+    ...overrides,
+  }
+  return {
+    ctx,
+    changes,
+    focused,
+    blurred,
+    // 用 getter 读实时值
+    get notified() {
+      return notified
+    },
+  } as never
+}
+
+/** 取出渲染函数返回的 vnode */
+function render(col: G3TableColumn<Row>, ctx: EditableContext<Row>, row: Row) {
+  const cell = createEditableCell(col, ctx) as unknown as (p: { row: Row }) => {
+    type: unknown
+    props: Record<string, unknown>
+    children?: unknown
+  }
+  return cell({ row })
+}
+
+describe('非编辑态：走纯展示路径', () => {
+  it('渲染成 span，不挂任何编辑器组件', () => {
+    const col = makeColumn({ editor: { type: 'text' } } as never)
+    const { ctx } = makeCtx({ isEditing: () => false })
+    const vnode = render(col, ctx, { id: 1, name: '合同.pdf', status: 1 })
+    expect(vnode.type).toBe('span')
+    expect(vnode.children).toBe('合同.pdf')
+  })
+
+  it('展示态也带 title，便于悬停看全名', () => {
+    const col = makeColumn({ editor: { type: 'text' } } as never)
+    const { ctx } = makeCtx({ isEditing: () => false })
+    const vnode = render(col, ctx, { id: 1, name: '很长的文件名.pdf', status: 1 })
+    expect(vnode.props.title).toBe('很长的文件名.pdf')
+  })
+
+  it('select 展示态把值解析成 label（不是原始 value）', () => {
+    const col = makeColumn({
+      editor: {
+        type: 'select',
+        options: [
+          { label: '启用', value: 1 },
+          { label: '停用', value: 0 },
+        ],
+      },
+    } as never)
+    const { ctx } = makeCtx({ isEditing: () => false })
+    const vnode = render(col, ctx, { id: 1, name: 'x', status: 1 })
+    // 这里用 status 列演示：直接构造一列绑到 status
+    const statusCol = { dataIndex: 'status', title: '状态', editor: col.editor } as G3TableColumn<Row>
+    const vnode2 = render(statusCol, ctx, { id: 1, name: 'x', status: 1 })
+    expect(vnode2.children).toBe('启用')
+    void vnode
+  })
+
+  it('select 值找不到对应选项时回落显示原值', () => {
+    const col = {
+      dataIndex: 'status',
+      title: '状态',
+      editor: { type: 'select', options: [{ label: '启用', value: 1 }] },
+    } as G3TableColumn<Row>
+    const { ctx } = makeCtx({ isEditing: () => false })
+    const vnode = render(col, ctx, { id: 1, name: 'x', status: 99 })
+    // 展示层统一转字符串（同一个值还要供 title 属性用），故这里是 '99' 而非 99
+    expect(vnode.children).toBe('99')
+  })
+
+  it('值为 null/undefined 时展示空字符串而不是 "null"', () => {
+    const col = makeColumn({ editor: { type: 'text' } } as never)
+    const { ctx } = makeCtx({ isEditing: () => false })
+    const vnode = render(col, ctx, { id: 1, name: null as never, status: 1 })
+    expect(vnode.children).toBe('')
+  })
+})
+
+describe('编辑态：input 编辑器', () => {
+  it('挂的是 G3Input 组件（不是原生 input）', () => {
+    const col = makeColumn({ editor: { type: 'text' } } as never)
+    const { ctx } = makeCtx()
+    const vnode = render(col, ctx, { id: 1, name: 'abc', status: 1 })
+    // 组件 vnode 的 type 是对象（组件定义）
+    expect(typeof vnode.type).toBe('object')
+  })
+
+  it('初始值取自行数据', () => {
+    const col = makeColumn({ editor: { type: 'text' } } as never)
+    const { ctx } = makeCtx()
+    const vnode = render(col, ctx, { id: 1, name: 'abc', status: 1 })
+    expect(vnode.props.modelValue).toBe('abc')
+  })
+
+  it('text 类型映射到 G3Input 的 default（不是原生 text）', () => {
+    const col = makeColumn({ editor: { type: 'text' } } as never)
+    const { ctx } = makeCtx()
+    const vnode = render(col, ctx, { id: 1, name: 'abc', status: 1 })
+    expect(vnode.props.type).toBe('default')
+  })
+
+  it('number 类型正确映射', () => {
+    const col = { dataIndex: 'status', title: '状态', editor: { type: 'number' } } as G3TableColumn<Row>
+    const { ctx } = makeCtx()
+    const vnode = render(col, ctx, { id: 1, name: 'x', status: 5 })
+    expect(vnode.props.type).toBe('number')
+  })
+
+  it('textarea 类型正确映射', () => {
+    const col = makeColumn({ editor: { type: 'textarea' } } as never)
+    const { ctx } = makeCtx()
+    const vnode = render(col, ctx, { id: 1, name: 'x', status: 1 })
+    expect(vnode.props.type).toBe('textarea')
+  })
+})
+
+describe('草稿机制：输入过程中不落库', () => {
+  it('onUpdate:modelValue 只写草稿，不改行数据、不通知父级', () => {
+    const col = makeColumn({ editor: { type: 'text' } } as never)
+    const row = { id: 1, name: '原始', status: 1 }
+    const { ctx, changes } = makeCtx()
+    const vnode = render(col, ctx, row)
+
+    const update = vnode.props['onUpdate:modelValue'] as (v: string) => void
+    update('输入中')
+    update('输入中更多')
+
+    // 行数据未被改动——这是草稿机制的核心保证
+    expect(row.name).toBe('原始')
+    expect(changes).toHaveLength(0)
+  })
+
+  it('重渲染时回显草稿值（而不是行数据里的旧值）', () => {
+    const col = makeColumn({ editor: { type: 'text' } } as never)
+    const row = { id: 1, name: '原始', status: 1 }
+    const { ctx } = makeCtx()
+
+    const first = render(col, ctx, row)
+    ;(first.props['onUpdate:modelValue'] as (v: string) => void)('草稿值')
+
+    // 同一行再次渲染（模拟父级触发重渲染）
+    const second = render(col, ctx, row)
+    expect(second.props.modelValue).toBe('草稿值')
+  })
+
+  it('失焦才落库并通知父级', () => {
+    const col = makeColumn({ editor: { type: 'text' } } as never)
+    const row = { id: 1, name: '原始', status: 1 }
+    const { ctx, changes, blurred } = makeCtx()
+    const vnode = render(col, ctx, row)
+
+    const update = vnode.props['onUpdate:modelValue'] as (v: string) => void
+    update('提交值')
+    const blur = vnode.props.onBlur as (e: unknown) => void
+    blur({ target: { value: '提交值' } })
+
+    expect(row.name).toBe('提交值')
+    expect(changes).toHaveLength(1)
+    expect(changes[0].value).toBe('提交值')
+    expect(blurred).toEqual([1])
+  })
+
+  it('blur 后草稿被清掉，再渲染回到行数据的值', () => {
+    const col = makeColumn({ editor: { type: 'text' } } as never)
+    const row = { id: 1, name: '原始', status: 1 }
+    const { ctx } = makeCtx()
+    const vnode = render(col, ctx, row)
+
+    ;(vnode.props['onUpdate:modelValue'] as (v: string) => void)('提交值')
+    ;(vnode.props.onBlur as (e: unknown) => void)({ target: { value: '提交值' } })
+
+    const again = render(col, ctx, row)
+    expect(again.props.modelValue).toBe('提交值')
+  })
+
+  it('编辑器卸载时把草稿写回行数据（避免输入凭空丢失）', () => {
+    const col = makeColumn({ editor: { type: 'text' } } as never)
+    const row = { id: 1, name: '原始', status: 1 }
+    const { ctx, changes } = makeCtx()
+    const vnode = render(col, ctx, row)
+
+    ;(vnode.props['onUpdate:modelValue'] as (v: string) => void)('未提交的值')
+    ;(vnode.props.onVnodeBeforeUnmount as () => void)()
+
+    // 兜底写回：值保住了，但**不触发通知**（那是 blur 的职责）
+    expect(row.name).toBe('未提交的值')
+    expect(changes).toHaveLength(0)
+  })
+})
+
+describe('checkbox 编辑器', () => {
+  const col = {
+    dataIndex: 'status',
+    title: '启用',
+    editor: { type: 'checkbox' },
+  } as G3TableColumn<Row>
+
+  it('渲染成 label + 原生 checkbox（零组件开销）', () => {
+    const { ctx } = makeCtx()
+    const vnode = render(col, ctx, { id: 1, name: 'x', status: 1 })
+    expect(vnode.type).toBe('label')
+    const children = vnode.children as Array<{ type: string; props: Record<string, unknown> }>
+    expect(children[0].props.type).toBe('checkbox')
+  })
+
+  it('约定 1 = 选中', () => {
+    const { ctx } = makeCtx()
+    const vnode = render(col, ctx, { id: 1, name: 'x', status: 1 })
+    const input = (vnode.children as Array<{ props: Record<string, unknown> }>)[0]
+    expect(input.props.checked).toBe(true)
+  })
+
+  it('约定 0 = 未选中', () => {
+    const { ctx } = makeCtx()
+    const vnode = render(col, ctx, { id: 1, name: 'x', status: 0 })
+    const input = (vnode.children as Array<{ props: Record<string, unknown> }>)[0]
+    expect(input.props.checked).toBe(false)
+  })
+
+  it('勾选直接改行数据并通知（不需要先激活整行编辑）', () => {
+    const row = { id: 1, name: 'x', status: 0 }
+    const { ctx, changes } = makeCtx()
+    const vnode = render(col, ctx, row)
+    const input = (vnode.children as Array<{ props: Record<string, unknown> }>)[0]
+
+    ;(input.props.onChange as (e: unknown) => void)({ target: { checked: true } })
+    expect(row.status).toBe(1)
+    expect(changes[0].value).toBe(1)
+  })
+
+  it('取消勾选写回 0', () => {
+    const row = { id: 1, name: 'x', status: 1 }
+    const { ctx, changes } = makeCtx()
+    const vnode = render(col, ctx, row)
+    const input = (vnode.children as Array<{ props: Record<string, unknown> }>)[0]
+
+    ;(input.props.onChange as (e: unknown) => void)({ target: { checked: false } })
+    expect(row.status).toBe(0)
+    expect(changes[0].value).toBe(0)
+  })
+})
+
+describe('禁用与字段级开关', () => {
+  it('editor.disabled 为 true 时走展示态', () => {
+    const col = makeColumn({ editor: { type: 'text', disabled: true } } as never)
+    const { ctx } = makeCtx()
+    const vnode = render(col, ctx, { id: 1, name: 'abc', status: 1 })
+    expect(vnode.type).toBe('span')
+  })
+
+  it('editor.disabled 传函数时按行判断', () => {
+    const col = makeColumn({
+      editor: { type: 'text', disabled: (row: Row) => row.id === 1 },
+    } as never)
+    const { ctx } = makeCtx()
+
+    expect(render(col, ctx, { id: 1, name: 'a', status: 1 }).type).toBe('span')
+    expect(typeof render(col, ctx, { id: 2, name: 'b', status: 1 }).type).toBe('object')
+  })
+
+  it('editor.onChange 先于上下文的 onChange 触发', () => {
+    const order: string[] = []
+    const col = makeColumn({
+      editor: {
+        type: 'text',
+        onChange: () => order.push('editor'),
+      },
+    } as never)
+    const row = { id: 1, name: 'x', status: 1 }
+    const { ctx } = makeCtx({
+      onChange: () => order.push('ctx'),
+    })
+    const vnode = render(col, ctx, row)
+    ;(vnode.props.onBlur as (e: unknown) => void)({ target: { value: 'v' } })
+
+    expect(order).toEqual(['editor', 'ctx'])
+  })
+
+  it('shouldNotify 返回 false 时两者都不触发（值没变就不通知）', () => {
+    const editorOnChange = vi.fn()
+    const ctxOnChange = vi.fn()
+    const col = makeColumn({ editor: { type: 'text', onChange: editorOnChange } } as never)
+    const { ctx } = makeCtx({ shouldNotify: () => false, onChange: ctxOnChange })
+    const vnode = render(col, ctx, { id: 1, name: 'x', status: 1 })
+    ;(vnode.props.onBlur as (e: unknown) => void)({ target: { value: 'x' } })
+
+    expect(editorOnChange).not.toHaveBeenCalled()
+    expect(ctxOnChange).not.toHaveBeenCalled()
+  })
+})
+
+describe('select 编辑器', () => {
+  it('挂 G3Select，且显式关掉 filterable', () => {
+    const col = {
+      dataIndex: 'status',
+      title: '状态',
+      editor: { type: 'select', options: [{ label: '启用', value: 1 }] },
+    } as G3TableColumn<Row>
+    const { ctx } = makeCtx()
+    const vnode = render(col, ctx, { id: 1, name: 'x', status: 1 })
+    expect(typeof vnode.type).toBe('object')
+    expect(vnode.props.filterable).toBe(false)
+  })
+
+  it('选择后直接改行数据并通知', () => {
+    const col = {
+      dataIndex: 'status',
+      title: '状态',
+      editor: { type: 'select', options: [{ label: '启用', value: 1 }] },
+    } as G3TableColumn<Row>
+    const row = { id: 1, name: 'x', status: 0 }
+    const { ctx, changes } = makeCtx()
+    const vnode = render(col, ctx, row)
+    ;(vnode.props['onUpdate:modelValue'] as (v: unknown) => void)(1)
+
+    expect(row.status).toBe(1)
+    expect(changes[0].value).toBe(1)
+  })
+
+  it('清空时落到 editor.emptyValue', () => {
+    const col = {
+      dataIndex: 'status',
+      title: '状态',
+      editor: { type: 'select', options: [{ label: '启用', value: 1 }], emptyValue: -1 },
+    } as G3TableColumn<Row>
+    const row = { id: 1, name: 'x', status: 1 }
+    const { ctx, changes } = makeCtx()
+    const vnode = render(col, ctx, row)
+    ;(vnode.props['onUpdate:modelValue'] as (v: unknown) => void)(undefined)
+
+    expect(row.status).toBe(-1)
+    expect(changes[0].value).toBe(-1)
+  })
+
+  it('清空且未配 emptyValue 时落 null', () => {
+    const col = {
+      dataIndex: 'status',
+      title: '状态',
+      editor: { type: 'select', options: [{ label: '启用', value: 1 }] },
+    } as G3TableColumn<Row>
+    const row = { id: 1, name: 'x', status: 1 }
+    const { ctx, changes } = makeCtx()
+    const vnode = render(col, ctx, row)
+    ;(vnode.props['onUpdate:modelValue'] as (v: unknown) => void)(undefined)
+
+    expect(row.status).toBe(null)
+    expect(changes[0].value).toBe(null)
+  })
+
+  it('options 可传函数并按当前行求值', () => {
+    const col = {
+      dataIndex: 'status',
+      title: '状态',
+      editor: {
+        type: 'select',
+        options: (row: Row) => [{ label: `行${row.id}`, value: row.id }],
+      },
+    } as G3TableColumn<Row>
+    const { ctx } = makeCtx()
+    const vnode = render(col, ctx, { id: 7, name: 'x', status: 7 })
+    const options = vnode.props.options as Array<{ label: string }>
+    expect(options[0].label).toBe('行7')
+  })
+})
diff --git a/code/g3soft-libs/packages/ui/src/table/utils/editable.ts b/code/g3soft-libs/packages/ui/src/table/utils/editable.ts
new file mode 100644
index 00000000..1ac995cb
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/table/utils/editable.ts
@@ -0,0 +1,312 @@
+import { h, toRaw } from 'vue'
+import { G3Input } from '../../input'
+import { G3Select } from '../../select'
+import { useNamespace } from '../../_composables/useNamespace'
+import type { G3TableColumn, TableEditor, TableRow, TableSelectOption } from '../types'
+
+/**
+ * 行内编辑单元格。
+ *
+ * 三条关键设计（都来自 fms 的实战结论，此处照搬）：
+ *
+ * 1. **草稿机制**：Input 受控值先写进 `inputDrafts`（WeakMap，按 row 分组），
+ *    失焦才落库并通知父级。不这么做的话，每敲一个字符都会改到行数据、触发父级重渲染，
+ *    光标会丢、输入法会断。
+ * 2. **焦点恢复靠三态判定**：`consumePendingFocus`（用户刚激活该格，一次性）/
+ *    `wasFocused`（重渲染前本来就持有焦点）。两者都不满足时**不聚焦**——
+ *    否则「数据回灌 → 重挂载 → 抢焦点 → 失焦 → 再重渲染」会自我驱动，
+ *    表现为「离开单元格时高亮一闪而过」。
+ * 3. **事件隔离**：库在 mousedown 阶段处理单元格选区与行编辑激活，
+ *    编辑器内部的点击必须 stop，否则第一次点击只激活编辑态、第二次才生效。
+ */
+
+const stop = (event: Event) => event.stopPropagation()
+
+/** Input 受控值草稿：row -> (dataIndex -> value) */
+const inputDrafts = new WeakMap<object, Map<string, unknown>>()
+
+/** 编辑器对外的上下文（由 G3Table 提供） */
+export interface EditableContext<T extends TableRow> {
+  /** 该行是否处于编辑态 */
+  isEditing: (row: T) => boolean
+  /** 该行的当前编辑列是否为该列 */
+  shouldFocus: (row: T, col: G3TableColumn<T>) => boolean
+  /** 重渲染前该行编辑器是否持有焦点 */
+  wasFocused: (row: T) => boolean
+  /** 消费一次「待聚焦」标记（用户激活时置位） */
+  consumePendingFocus: (row: T) => boolean
+  onEditorFocus: (row: T) => void
+  onEditorBlur: (row: T) => void
+  /** 值真正变化时才返回 true（用于去重通知） */
+  shouldNotify: (row: T, col: G3TableColumn<T>, value: unknown) => boolean
+  /** 通知父级 */
+  onChange: (row: T, col: G3TableColumn<T>, value: unknown) => void
+}
+
+/* ---------- 草稿 ---------- */
+
+function getInputDraft<T extends TableRow>(row: T, dataIndex: string): unknown {
+  const drafts = inputDrafts.get(row)
+  return drafts?.has(dataIndex) ? drafts.get(dataIndex) : row[dataIndex]
+}
+
+function setInputDraft<T extends TableRow>(row: T, dataIndex: string, value: unknown) {
+  let drafts = inputDrafts.get(row)
+  if (!drafts) {
+    drafts = new Map()
+    inputDrafts.set(row, drafts)
+  }
+  drafts.set(dataIndex, value)
+}
+
+function clearInputDraft<T extends TableRow>(row: T, dataIndex: string) {
+  const drafts = inputDrafts.get(row)
+  if (!drafts) return
+  drafts.delete(dataIndex)
+  if (!drafts.size) inputDrafts.delete(row)
+}
+
+function commitInputDraft<T extends TableRow>(row: T, dataIndex: string, value: unknown) {
+  clearInputDraft(row, dataIndex)
+  // 泛型 T 只能按已知键读取，写入需退到 TableRow（索引签名为 string）
+  ;(row as TableRow)[dataIndex] = value
+}
+
+/**
+ * 卸载兜底：把草稿写回 raw 对象但**不触发响应式更新**。
+ * 正常路径会在 blur 中响应式提交并通知父级；这里只在「拖拽/切数据导致强制卸载」
+ * 时避免用户输入凭空丢失。
+ */
+function preserveInputDraft<T extends TableRow>(row: T, dataIndex: string) {
+  const drafts = inputDrafts.get(row)
+  if (!drafts?.has(dataIndex)) return
+  // toRaw 同样是泛型，写入前退到 TableRow；这里刻意绕过响应式，故不走 row 本身
+  ;(toRaw(row) as TableRow)[dataIndex] = drafts.get(dataIndex)
+  clearInputDraft(row, dataIndex)
+}
+
+/* ---------- 值处理 ---------- */
+
+/** options 允许传函数并接收当前行：列选项依赖同行其它列时用它 */
+function resolveOptions<T extends TableRow>(
+  editor: TableEditor<T>,
+  row: T,
+): TableSelectOption[] {
+  return typeof editor.options === 'function' ? editor.options(row) : (editor.options ?? [])
+}
+
+function isEditorDisabled<T extends TableRow>(editor: TableEditor<T>, row: T): boolean {
+  return typeof editor.disabled === 'function'
+    ? Boolean(editor.disabled(row))
+    : Boolean(editor.disabled)
+}
+
+function notifyChange<T extends TableRow>(
+  ctx: EditableContext<T>,
+  editor: TableEditor<T>,
+  row: T,
+  col: G3TableColumn<T>,
+  value: unknown,
+) {
+  if (!ctx.shouldNotify(row, col, value)) return
+  editor.onChange?.(value, row, col)
+  ctx.onChange(row, col, value)
+}
+
+/** 非编辑态的展示内容：select 需要把值解析成 label */
+function displayValue<T extends TableRow>(
+  row: T,
+  col: G3TableColumn<T>,
+  editor: TableEditor<T>,
+) {
+  const { e } = useNamespace('table')
+  const value = row[col.dataIndex]
+  const text =
+    editor.type === 'select'
+      ? (resolveOptions(editor, row).find((item) => String(item.value) === String(value))
+          ?.label ?? value)
+      : value
+  const content = text ?? ''
+  return h(
+    'span',
+    { class: e('cell-display'), title: String(content) },
+    content as string,
+  )
+}
+
+/* ---------- 焦点 ---------- */
+
+function createFocusHandler<T extends TableRow>(
+  ctx: EditableContext<T>,
+  row: T,
+  col: G3TableColumn<T>,
+  selectText = false,
+) {
+  return ({ component, el }: { component?: any; el?: any }) => {
+    if (!ctx.shouldFocus(row, col)) return
+    // 仅在两种场景聚焦：用户刚激活该格（一次性），或重渲染前本就持有焦点
+    const pending = ctx.consumePendingFocus?.(row)
+    const wasFocused = Boolean(ctx.wasFocused?.(row))
+    if (!pending && !wasFocused) return
+
+    const input = el?.matches?.('input') ? el : el?.querySelector?.('input')
+    if (document.activeElement === input) return
+
+    const instance = component?.exposed || component?.proxy
+    const shouldSelect = selectText && (pending || wasFocused)
+    const opts = shouldSelect ? { cursor: 'all', preventScroll: true } : { preventScroll: true }
+    if (instance?.focus) {
+      instance.focus(opts)
+      return
+    }
+    input?.focus(opts)
+    if (shouldSelect) input?.select()
+  }
+}
+
+/* ---------- 编辑器 ---------- */
+
+/** 编辑器到 G3Input 的 type 映射：fms 用 antdv 的 inputType，我们用自己的枚举 */
+const INPUT_TYPE_MAP: Record<string, 'default' | 'password' | 'number' | 'textarea'> = {
+  text: 'default',
+  default: 'default',
+  password: 'password',
+  number: 'number',
+  textarea: 'textarea',
+}
+
+function createInput<T extends TableRow>(
+  row: T,
+  col: G3TableColumn<T>,
+  editor: TableEditor<T>,
+  ctx: EditableContext<T>,
+) {
+  const { e } = useNamespace('table')
+  const focus = createFocusHandler(ctx, row, col, true)
+  return h(G3Input, {
+    type: INPUT_TYPE_MAP[editor.type] ?? 'default',
+    modelValue: (getInputDraft(row, col.dataIndex) ?? '') as string,
+    class: [e('cell-editor'), e('cell-editor-root')],
+    'aria-label': col.title || col.dataIndex,
+    'onUpdate:modelValue': (value: string | number) => {
+      setInputDraft(row, col.dataIndex, value)
+    },
+    onFocus: () => ctx.onEditorFocus?.(row),
+    onBlur: (event: FocusEvent) => {
+      ctx.onEditorBlur?.(row)
+      const value = (event.target as HTMLInputElement).value
+      commitInputDraft(row, col.dataIndex, value)
+      notifyChange(ctx, editor, row, col, value)
+    },
+    onKeydown: (event: KeyboardEvent) => {
+      // G3Input 根节点是包装 div，currentTarget 不是原生 input，需用 event.target
+      if (event.key === 'Enter') {
+        event.preventDefault()
+        event.stopPropagation()
+        ;(event.target as HTMLInputElement).select()
+      } else if (event.key === 'Escape') {
+        ;(event.target as HTMLInputElement).blur()
+      }
+    },
+    onClick: stop,
+    onVnodeMounted: focus,
+    onVnodeUpdated: focus,
+    onVnodeBeforeUnmount: () => preserveInputDraft(row, col.dataIndex),
+  })
+}
+
+function createSelect<T extends TableRow>(
+  row: T,
+  col: G3TableColumn<T>,
+  editor: TableEditor<T>,
+  ctx: EditableContext<T>,
+) {
+  const { e } = useNamespace('table')
+  const options = resolveOptions(editor, row)
+  const focus = createFocusHandler(ctx, row, col)
+  return h(G3Select, {
+    modelValue: (row[col.dataIndex] ?? undefined) as any,
+    options: options as any,
+    clearable: editor.allowClear ?? true,
+    filterable: false,
+    class: [e('cell-editor'), e('cell-editor-root')],
+    'aria-label': col.title || col.dataIndex,
+    'onUpdate:modelValue': (value: unknown) => {
+      const resolved = value ?? editor.emptyValue ?? null
+      row[col.dataIndex] = resolved as T[keyof T & string]
+      notifyChange(ctx, editor, row, col, resolved)
+    },
+    onClick: stop,
+    onVnodeMounted: focus,
+    onVnodeUpdated: focus,
+  })
+}
+
+function createCheckbox<T extends TableRow>(
+  row: T,
+  col: G3TableColumn<T>,
+  editor: TableEditor<T>,
+  ctx: EditableContext<T>,
+) {
+  const { e, is } = useNamespace('table')
+  // 约定：1 = 选中，0 = 未选中（与后端 tinyint 对齐，fms 同此约定）
+  const checked = row[col.dataIndex] === 1
+  const focus = ctx.isEditing(row) ? createFocusHandler(ctx, row, col) : undefined
+  const update = (value: number) => {
+    row[col.dataIndex] = value as T[keyof T & string]
+    notifyChange(ctx, editor, row, col, value)
+  }
+  return h(
+    'label',
+    {
+      class: [e('checkbox'), e('cell-editor-root'), { [is('checked')]: checked }],
+      onClick: stop,
+      // 库在 mousedown 阶段处理选区与行编辑激活；checkbox 是始终可直接操作的控件，
+      // 必须在此阶段隔离，否则第一次点击只激活编辑态、第二次才真正切换。
+      onMousedown: stop,
+    },
+    [
+      h('input', {
+        type: 'checkbox',
+        checked,
+        'aria-label': col.title || col.dataIndex,
+        onChange: (event: Event) => {
+          update((event.target as HTMLInputElement).checked ? 1 : 0)
+        },
+        onKeydown: (event: KeyboardEvent) => {
+          if (event.key !== 'Enter') return
+          event.preventDefault()
+          event.stopPropagation()
+          const value = row[col.dataIndex] === 1 ? 0 : 1
+          ;(event.currentTarget as HTMLInputElement).checked = value === 1
+          update(value)
+        },
+        onClick: stop,
+        onMousedown: stop,
+        onVnodeMounted: focus,
+        onVnodeUpdated: focus,
+      }),
+      h('span', { class: e('checkbox-box') }),
+    ],
+  )
+}
+
+/**
+ * 生成某列的单元格渲染函数。
+ *
+ * 注意返回值有三档：禁用 → 纯展示；checkbox → 始终可交互（无需先激活整行编辑）；
+ * 其余 → 非编辑态走展示、编辑态挂编辑器。
+ */
+export function createEditableCell<T extends TableRow>(
+  col: G3TableColumn<T>,
+  ctx: EditableContext<T>,
+) {
+  const editor = col.editor as TableEditor<T>
+  return ({ row }: { row: T }) => {
+    if (isEditorDisabled(editor, row)) return displayValue(row, col, editor)
+    if (editor.type === 'checkbox') return createCheckbox(row, col, editor, ctx)
+    if (!ctx.isEditing(row)) return displayValue(row, col, editor)
+    if (editor.type === 'select') return createSelect(row, col, editor, ctx)
+    return createInput(row, col, editor, ctx)
+  }
+}
diff --git a/code/g3soft-libs/packages/ui/src/table/utils/selection.test.ts b/code/g3soft-libs/packages/ui/src/table/utils/selection.test.ts
new file mode 100644
index 00000000..104bc9f8
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/table/utils/selection.test.ts
@@ -0,0 +1,237 @@
+import { describe, expect, it } from 'vitest'
+import { createSelectionColumn, isSelectionColumn } from './selection'
+import type { TableRow } from '../types'
+
+interface Row extends TableRow {
+  id: number
+  name: string
+}
+
+/**
+ * 选择列的测试。
+ *
+ * 造的是「函数式组件」返回的 vnode，所以直接读 vnode 结构断言，
+ * 不挂载组件——完全确定性，也不依赖 happy-dom 的布局。
+ */
+
+function setup(options: {
+  data?: Row[]
+  selected?: Array<string | number>
+  disabled?: number[]
+  multiple?: boolean
+} = {}) {
+  const data = options.data ?? [
+    { id: 1, name: 'a' },
+    { id: 2, name: 'b' },
+    { id: 3, name: 'c' },
+  ]
+  const changes: Array<{ keys: Array<string | number>; rows: Row[] }> = []
+  const column = createSelectionColumn<Row>({
+    getDataSource: () => data,
+    getRowKey: (row) => row.id,
+    getSelectedRowKeys: () => options.selected ?? [],
+    isRowDisabled: (row) => (options.disabled ?? []).includes(row.id),
+    onChange: (keys, rows) => changes.push({ keys, rows: rows as Row[] }),
+  })
+  return { column, changes, data }
+}
+
+type VNodeLike = {
+  type: string
+  props: Record<string, unknown>
+  children?: unknown
+}
+
+/**
+ * 把 vnode 的 class 读成扁平字符串。
+ *
+ * 组件里 class 是 `[字符串, { 条件类: 布尔 }]` 这种「数组 + 对象」混合形式
+ * （Vue 的标准写法），不能直接 join——第二个元素是对象。
+ */
+function classOf(vnode: VNodeLike): string {
+  const raw = vnode.props.class
+  const out: string[] = []
+  const walk = (value: unknown) => {
+    if (!value) return
+    if (typeof value === 'string') {
+      out.push(value)
+      return
+    }
+    if (Array.isArray(value)) {
+      value.forEach(walk)
+      return
+    }
+    if (typeof value === 'object') {
+      for (const [key, enabled] of Object.entries(value as Record<string, unknown>)) {
+        if (enabled) out.push(key)
+      }
+    }
+  }
+  walk(raw)
+  return out.join(' ')
+}
+
+/** 行单元格渲染函数 */
+function rowRender(column: ReturnType<typeof setup>['column']) {
+  return column.customCell as unknown as (p: { row: Row }) => VNodeLike
+}
+
+/** 表头单元格渲染函数 */
+function headerRender(column: ReturnType<typeof setup>['column']) {
+  return column.customHeaderCell as unknown as () => VNodeLike
+}
+
+function checkboxOf(vnode: VNodeLike) {
+  const children = vnode.children as VNodeLike[]
+  return children[0]
+}
+
+function boxOf(vnode: VNodeLike) {
+  const children = vnode.children as VNodeLike[]
+  return children[1]
+}
+
+/** 触发 input 的 change（模拟用户点击） */
+function fireChange(input: VNodeLike, checked: boolean) {
+  const handler = input.props.onChange as (e: unknown) => void
+  handler({ target: { checked }, stopPropagation: () => undefined })
+}
+
+describe('createSelectionColumn', () => {
+  it('列定义：内部标识 + 固定左侧 + 居中 + 默认宽度', () => {
+    const { column } = setup()
+    expect(isSelectionColumn(column)).toBe(true)
+    expect(column.fixed).toBe('left')
+    expect(column.align).toBe('center')
+    expect(column.headerAlign).toBe('center')
+    expect(column.width).toBe(44)
+  })
+
+  it('行复选框用原生 input，不引入 Checkbox 组件（零组件开销）', () => {
+    const { column } = setup()
+    const vnode = rowRender(column)({ row: { id: 1, name: 'a' } })
+    // 根是 label，子节点第一个是原生 input
+    expect(vnode.type).toBe('label')
+    const input = checkboxOf(vnode)
+    expect(input.type).toBe('input')
+    expect(input.props.type).toBe('checkbox')
+  })
+
+  it('选中态：input.checked 与 is-checked 类同时反映', () => {
+    const { column } = setup({ selected: [2] })
+    const render = rowRender(column)
+
+    const checkedOne = render({ row: { id: 2, name: 'b' } })
+    expect(checkboxOf(checkedOne).props.checked).toBe(true)
+    expect(classOf(checkedOne)).toContain('is-checked')
+
+    const uncheckedOne = render({ row: { id: 1, name: 'a' } })
+    expect(checkboxOf(uncheckedOne).props.checked).toBe(false)
+    expect(classOf(uncheckedOne)).not.toContain('is-checked')
+  })
+
+  it('勾选一行：把该 key 加入并回调（带行对象）', () => {
+    const { column, changes } = setup({ selected: [] })
+    fireChange(checkboxOf(rowRender(column)({ row: { id: 2, name: 'b' } })), true)
+    expect(changes).toHaveLength(1)
+    expect(changes[0].keys).toEqual([2])
+    expect(changes[0].rows.map((r) => r.id)).toEqual([2])
+  })
+
+  it('取消勾选：从已选里移除', () => {
+    const { column, changes } = setup({ selected: [1, 2] })
+    fireChange(checkboxOf(rowRender(column)({ row: { id: 1, name: 'a' } })), false)
+    expect(changes[0].keys).toEqual([2])
+  })
+
+  it('禁用行：点击不触发回调', () => {
+    const { column, changes } = setup({ disabled: [2] })
+    const vnode = rowRender(column)({ row: { id: 2, name: 'b' } })
+    expect(checkboxOf(vnode).props.disabled).toBe(true)
+    fireChange(checkboxOf(vnode), true)
+    expect(changes).toHaveLength(0)
+  })
+
+  it('禁用行：类名带 is-disabled', () => {
+    const { column } = setup({ disabled: [2] })
+    const vnode = rowRender(column)({ row: { id: 2, name: 'b' } })
+    expect(classOf(vnode)).toContain('is-disabled')
+  })
+
+  it('表格根节点是 label，子节点为 input + 自绘方框', () => {
+    const { column } = setup()
+    const vnode = rowRender(column)({ row: { id: 1, name: 'a' } })
+    expect(boxOf(vnode).type).toBe('span')
+  })
+})
+
+describe('表头复选框：全选 / 半选判定', () => {
+  it('全选：所有行都在已选里', () => {
+    const { column } = setup({ selected: [1, 2, 3] })
+    const header = headerRender(column)()
+    expect(checkboxOf(header).props.checked).toBe(true)
+    const cls = classOf(header)
+    expect(cls).toContain('is-checked')
+    expect(cls).not.toContain('is-indeterminate')
+  })
+
+  it('半选：部分选中', () => {
+    const { column } = setup({ selected: [1] })
+    const header = headerRender(column)()
+    expect(checkboxOf(header).props.checked).toBe(false)
+    const cls = classOf(header)
+    expect(cls).toContain('is-indeterminate')
+    expect(cls).not.toContain('is-checked')
+  })
+
+  it('全不选：勾选框为空', () => {
+    const { column } = setup({ selected: [] })
+    const header = headerRender(column)()
+    expect(checkboxOf(header).props.checked).toBe(false)
+    const cls = classOf(header)
+    expect(cls).not.toContain('is-checked')
+    expect(cls).not.toContain('is-indeterminate')
+  })
+
+  it('禁用行不算进「全选」分母：3 行里 1 行禁用、2 行选中即为全选', () => {
+    const { column } = setup({ selected: [1, 2], disabled: [3] })
+    const header = headerRender(column)()
+    expect(checkboxOf(header).props.checked).toBe(true)
+    expect(classOf(header)).toContain('is-checked')
+  })
+
+  it('筛选后隐藏的 key 不干扰判定：数据里只剩 1 行时，选中它即为全选', () => {
+    // 已选里有 id=9（不在当前数据里，模拟翻页/筛选后残留）
+    const { column } = setup({
+      data: [{ id: 1, name: 'a' }],
+      selected: [1, 9],
+    })
+    const header = headerRender(column)()
+    expect(checkboxOf(header).props.checked).toBe(true)
+    expect(classOf(header)).not.toContain('is-indeterminate')
+  })
+
+  it('全选：把所有行 key 加进去', () => {
+    const { column, changes } = setup({ selected: [] })
+    fireChange(checkboxOf(headerRender(column)()), true)
+    expect(changes[0].keys.sort()).toEqual([1, 2, 3])
+  })
+
+  it('全选不包含禁用行', () => {
+    const { column, changes } = setup({ selected: [], disabled: [2] })
+    fireChange(checkboxOf(headerRender(column)()), true)
+    expect(changes[0].keys.sort()).toEqual([1, 3])
+  })
+
+  it('取消全选：清空', () => {
+    const { column, changes } = setup({ selected: [1, 2, 3] })
+    fireChange(checkboxOf(headerRender(column)()), false)
+    expect(changes[0].keys).toEqual([])
+  })
+
+  it('空数据：表头不显示为全选', () => {
+    const { column } = setup({ data: [], selected: [] })
+    const header = headerRender(column)()
+    expect(checkboxOf(header).props.checked).toBe(false)
+  })
+})
diff --git a/code/g3soft-libs/packages/ui/src/table/utils/selection.ts b/code/g3soft-libs/packages/ui/src/table/utils/selection.ts
new file mode 100644
index 00000000..27eb8c33
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/table/utils/selection.ts
@@ -0,0 +1,174 @@
+import { computed, h } from 'vue'
+import { useNamespace } from '../../_composables/useNamespace'
+import type { G3TableColumn, TableRow } from '../types'
+
+/**
+ * 多选列。
+ *
+ * **为什么不用 `G3Checkbox` 组件**：表格是逐行渲染的，一个 Checkbox 组件实例
+ * = 一次 setup + 响应式 + vnode 树。滚动时这些实例不断挂载/卸载，是纯粹的浪费。
+ * 这里用原生 `<input type="checkbox">` + 自绘方框，零组件开销；
+ * 视觉规格（16px、radius-sm、主色描边/填充、focus-ring）与 G3Checkbox 一致，
+ * 由 CSS 层模拟，不引入组件依赖。
+ */
+
+/** 单例事件处理器：避免每行渲染时创建新闭包 */
+const stop = (event: Event) => event.stopPropagation()
+
+export interface SelectionColumnOptions<T extends TableRow> {
+  /** 取当前数据源（响应式） */
+  getDataSource: () => T[]
+  /** 从行数据提取 key */
+  getRowKey: (row: T) => string | number
+  /** 取已选 key 数组（响应式） */
+  getSelectedRowKeys: () => Array<string | number>
+  /** 单行是否禁用 */
+  isRowDisabled?: (row: T) => boolean
+  /** 选中变化回调 */
+  onChange?: (keys: Array<string | number>, rows: T[]) => void
+}
+
+/** 选择列的内部标识：用于从回写的 columns 里识别并剥离内部列 */
+export const SELECTION_COLUMN_KEY = '__g3Selection'
+
+/** 判断某列是否为选择列 */
+export function isSelectionColumn(col: unknown): boolean {
+  return (col as Record<string, unknown> | null)?.[SELECTION_COLUMN_KEY] === true
+}
+
+/**
+ * 创建选择列定义，返回可直接插入 columns 的列对象。
+ */
+export function createSelectionColumn<T extends TableRow>(
+  options: SelectionColumnOptions<T>,
+): G3TableColumn<T> {
+  const { getDataSource, getRowKey, getSelectedRowKeys, isRowDisabled = () => false, onChange } =
+    options
+
+  const { e, b, is } = useNamespace('table')
+
+  /** 已选 key 集合 */
+  const selectedRowKeySet = computed(() => new Set(getSelectedRowKeys()))
+  /** key -> row 映射，用于把 key 数组还原成行对象回调出去 */
+  const rowByKey = computed(() => {
+    const map = new Map<string | number, T>()
+    for (const row of getDataSource()) map.set(getRowKey(row), row)
+    return map
+  })
+
+  function updateSelection(nextKeys: Array<string | number>) {
+    const rows = nextKeys.map((key) => rowByKey.value.get(key)).filter(Boolean) as T[]
+    onChange?.(nextKeys, rows)
+  }
+
+  function changeRow(row: T, checked: boolean) {
+    if (isRowDisabled(row)) return
+    const nextKeys = new Set(selectedRowKeySet.value)
+    const key = getRowKey(row)
+    if (checked) nextKeys.add(key)
+    else nextKeys.delete(key)
+    updateSelection(Array.from(nextKeys))
+  }
+
+  function changeAll(checked: boolean) {
+    const nextKeys = new Set(selectedRowKeySet.value)
+    for (const row of getDataSource()) {
+      if (isRowDisabled(row)) continue
+      const key = getRowKey(row)
+      if (checked) nextKeys.add(key)
+      else nextKeys.delete(key)
+    }
+    updateSelection(Array.from(nextKeys))
+  }
+
+  /** 行复选框 */
+  const SelectionCell = ({ row }: { row: T }) => {
+    const key = getRowKey(row)
+    const disabled = isRowDisabled(row)
+    const checked = selectedRowKeySet.value.has(key)
+    return h(
+      'label',
+      {
+        class: [
+          e('checkbox'),
+          {
+            [is('checked')]: checked,
+            [is('disabled')]: disabled,
+          },
+        ],
+        onClick: stop,
+        onMousedown: stop,
+      },
+      [
+        h('input', {
+          type: 'checkbox',
+          class: e('checkbox-input'),
+          checked,
+          disabled,
+          onChange: (event: Event) => {
+            event.stopPropagation()
+            changeRow(row, (event.target as HTMLInputElement).checked)
+          },
+          onClick: stop,
+          onMousedown: stop,
+        }),
+        h('span', { class: e('checkbox-box') }),
+      ],
+    )
+  }
+
+  /**
+   * 表头复选框。
+   * 只统计**当前数据源里**的选中项：否则筛选/翻页后被隐藏的 key 会干扰
+   * 「全选」与「半选」的判定（表现为明明只选了一行，表头却是全选态）。
+   */
+  const SelectionHeaderCell = () => {
+    const rows = getDataSource().filter((row) => !isRowDisabled(row))
+    let selectedCount = 0
+    for (const key of selectedRowKeySet.value) {
+      if (rowByKey.value.has(key)) selectedCount += 1
+    }
+    const allChecked = rows.length > 0 && selectedCount === rows.length
+    const indeterminate = selectedCount > 0 && selectedCount < rows.length
+
+    return h(
+      'label',
+      {
+        class: [
+          e('checkbox'),
+          {
+            [is('checked')]: allChecked,
+            [is('indeterminate')]: indeterminate,
+          },
+        ],
+        onClick: stop,
+      },
+      [
+        h('input', {
+          type: 'checkbox',
+          class: e('checkbox-input'),
+          checked: allChecked,
+          onChange: (event: Event) => {
+            event.stopPropagation()
+            changeAll((event.target as HTMLInputElement).checked)
+          },
+          onClick: stop,
+        }),
+        h('span', { class: e('checkbox-box') }),
+      ],
+    )
+  }
+
+  return {
+    [SELECTION_COLUMN_KEY]: true,
+    key: SELECTION_COLUMN_KEY,
+    dataIndex: SELECTION_COLUMN_KEY as keyof T & string,
+    title: '',
+    width: 44,
+    fixed: 'left',
+    align: 'center',
+    headerAlign: 'center',
+    customCell: SelectionCell as unknown as G3TableColumn<T>['customCell'],
+    customHeaderCell: SelectionHeaderCell as unknown as G3TableColumn<T>['customHeaderCell'],
+  } as G3TableColumn<T>
+}
diff --git a/code/g3soft-libs/packages/ui/vite.config.ts b/code/g3soft-libs/packages/ui/vite.config.ts
index abc3af23..2627d174 100644
--- a/code/g3soft-libs/packages/ui/vite.config.ts
+++ b/code/g3soft-libs/packages/ui/vite.config.ts
@@ -37,6 +37,13 @@ export default defineConfig({
     dts({
       // 只产出声明文件，JS 交给 vite 本体
       include: ['src'],
+      /**
+       * 排除测试文件：`include: ['src']` 会连 `*.test.ts` 一起扫进来，
+       * 而单测里可能 import Node 内置模块（`node:fs` / `node:path`）——
+       * 声明构建跑在浏览器侧的类型环境里，解析不到会报 TS2307。
+       * 测试文件也不该出现在发布产物的 d.ts 里。
+       */
+      exclude: ['src/**/*.test.ts', 'src/**/__tests__/**'],
       // 选项名是 outDirs（复数）。旧写法 outDir 会被**静默忽略** —— vue-tsc 就是从这条报错里抓出来的。
       outDirs: 'dist',
       // 刻意不打包成单个 d.ts：那需要 bundleTypes（旧名 rollupTypes，v5 已不存在）
diff --git a/code/g3soft-libs/pnpm-lock.yaml b/code/g3soft-libs/pnpm-lock.yaml
index 31b50c0d..4b4ce1d2 100644
--- a/code/g3soft-libs/pnpm-lock.yaml
+++ b/code/g3soft-libs/pnpm-lock.yaml
@@ -75,6 +75,9 @@ importers:
       '@tiptap/extension-link':
         specifier: ^3.31.4
         version: 3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))(@tiptap/pm@3.31.4)
+      '@tiptap/extension-list':
+        specifier: ^3.31.4
+        version: 3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))(@tiptap/pm@3.31.4)
       '@tiptap/extension-placeholder':
         specifier: ^3.31.4
         version: 3.31.4(@tiptap/extensions@3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))(@tiptap/pm@3.31.4))
@@ -105,6 +108,9 @@ importers:
       '@tiptap/starter-kit':
         specifier: ^3.31.4
         version: 3.31.4
+      stk-table-vue:
+        specifier: 1.1.0
+        version: 1.1.0
     devDependencies:
       '@playwright/test':
         specifier: ^1.63.0
@@ -2251,6 +2257,9 @@ packages:
   std-env@4.3.0:
     resolution: {integrity: sha512-OtU/EgQ1kIm5KwqQpBC6ZEMXrZRui11w8zgfTWp8cdO9B8OaPsbA8bTHO2P+HNo1VlUTGMVBwPhydu6poeXiag==}
 
+  stk-table-vue@1.1.0:
+    resolution: {integrity: sha512-lPVBGZNuVGxSWq0k+XBGY00xStjplm4ckRIm/Zl83SAnxfMYUKQB0v/dEovAl/oARf9gq3/QvgZnTj93Bze66g==}
+
   string-width@4.2.3:
     resolution: {integrity: sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g==}
     engines: {node: '>=8'}
@@ -4795,6 +4804,8 @@ snapshots:
 
   std-env@4.3.0: {}
 
+  stk-table-vue@1.1.0: {}
+
   string-width@4.2.3:
     dependencies:
       emoji-regex: 8.0.0