u
This commit is contained in:
oneao committed
1 parent
32d423b759
commit
78eb811ff7
102 files changed
+12067
-209
No files matched your search
@@ -0,0 +1,234 @@
|
||||
---
|
||||
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` 处理。
|
||||
Reference in new issue
Block a user