---
'@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`。