oneao/workspace
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

u

Browse Source
This commit is contained in:
oneao committed 2026-10-12 17:32:50 +08:00
1 parent 78eb811ff7
commit 97fe2ff306
83 files changed
+10083 -3662
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

code/g3soft-libs/docs/content/ui/data/attachment.md
-234
View File
@@ -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` 处理。
code/g3soft-libs/docs/content/ui/data/table.md
+183
View File
@@ -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` 处理。
code/g3soft-libs/docs/content/ui/form/input.md
+5 -1
View File
@@ -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` 规则。
code/g3soft-libs/docs/content/ui/form/rich-text.md
+239 -13
View File
@@ -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`）**，否则使用方装包后会报模块缺失。
code/g3soft-libs/docs/content/ui/overlay/dropdown.md
+17
View File
@@ -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>
```
## 键盘操作
菜单打开后焦点会进入菜单容器，因此可以直接用键盘：