x-next 1.12.0 → 1.14.0

package/AI_USAGE/components/upload-api.md

@@ -0,0 +1,200 @@
+<!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
+# Upload 完整公开 API
+
+适用版本：x-next@1.14.0；来源指纹：`014984639d816a2c7e25eb22690c586b0b2e8efba6846bec8a4e424db41a09e9`。
+
+从同版本构建的公开声明、运行时 props/emits 和显式 expose 生成。运行时导入始终使用 `x-next`，声明路径仅作定位。插槽类型未细化时，具体槽名与作用域见本地用法示例。
+
+## Upload API
+
+公开声明：`dist/components/upload/index.d.ts`。 类型中的 undefined 表示可省略；原始 prop 默认值不等于继承配置或服务默认值。
+
+### Props
+
+| 名称 | 用途 | 公开类型 | 必填 | 声明默认值 |
+| --- | --- | --- | --- | --- |
+| fileList | 文件列表，支持 v-model:file-list | undefined &#124; UploadFile<unknown>[] | 否 | undefined |
+| defaultFileList | 非受控模式下的初始文件列表 | undefined &#124; UploadFile<unknown>[] | 否 | [] |
+| action | 上传地址，传函数时按文件动态解析并支持异步 | undefined &#124; string &#124; (file: File) => string &#124; Promise<string> | 否 | undefined |
+| method | 请求方法 | undefined &#124; "post" &#124; "put" &#124; "patch" | 否 | "post" |
+| headers | 请求头 | undefined &#124; { [x: string]: string; } | 否 | undefined |
+| data | 附加表单字段，可传函数按文件解析 | undefined &#124; { [x: string]: unknown; } &#124; (file: UploadFile) => Record<string, unknown> &#124; Promise<Record<string, unknown>> | 否 | undefined |
+| name | FormData 文件字段名 | undefined &#124; string &#124; (file: UploadFile) => string | 否 | "file" |
+| withCredentials | 是否携带 Cookie | undefined &#124; false &#124; true | 否 | false |
+| timeout | 请求超时毫秒数，0 表示不超时 | undefined &#124; number | 否 | 0 |
+| customRequest | 自定义上传请求；返回 Promise 时自动接管状态与结果，返回 { abort } 时手动回调 | undefined &#124; (option: UploadRequestOption) => UploadRequest &#124; Promise<unknown> &#124; void | 否 | undefined |
+| accept | 接受的文件类型，同原生 accept | undefined &#124; string | 否 | undefined |
+| multiple | 是否允许选择多个文件 | undefined &#124; false &#124; true | 否 | false |
+| directory | 是否支持选择文件夹（含拖拽递归） | undefined &#124; false &#124; true | 否 | false |
+| capture | 移动端捕获来源，透传原生 input | undefined &#124; false &#124; true &#124; "user" &#124; "environment" | 否 | undefined |
+| paste | 是否支持聚焦后粘贴文件 | undefined &#124; false &#124; true | 否 | false |
+| draggable | 是否渲染为拖拽上传区域 | undefined &#124; false &#124; true | 否 | false |
+| disabled | 是否禁用 | undefined &#124; false &#124; true | 否 | undefined |
+| autoUpload | 是否选择后立即上传 | undefined &#124; false &#124; true | 否 | true |
+| limit | 最大文件数量，0 表示不限 | undefined &#124; number | 否 | 0 |
+| beforeUpload | 上传前钩子，可拦截或替换文件 | undefined &#124; (file: File, fileList: File[]) => UploadBeforeUploadResult &#124; Promise<UploadBeforeUploadResult> | 否 | undefined |
+| beforeRemove | 移除前钩子，返回 false 阻止移除 | undefined &#124; (file: UploadFile) => boolean &#124; void &#124; Promise<boolean &#124; void> | 否 | undefined |
+| listType | 列表展示形态 | undefined &#124; "text" &#124; "picture" &#124; "picture-card" | 否 | "text" |
+| tip | 提示文案，拖拽区与图片卡入口显示 | undefined &#124; string | 否 | undefined |
+| showFileList | 是否展示文件列表 | undefined &#124; false &#124; true | 否 | true |
+| showUploadButton | 是否展示上传入口，对象形式可配置达 limit 后仍显示 | undefined &#124; false &#124; true &#124; UploadShowUploadButton | 否 | true |
+| showRemoveButton | 是否展示移除按钮 | undefined &#124; false &#124; true | 否 | true |
+| showRetryButton | 是否展示重试 / 开始上传按钮 | undefined &#124; false &#124; true | 否 | true |
+| showCancelButton | 是否展示取消上传按钮 | undefined &#124; false &#124; true | 否 | true |
+| showPreviewButton | 是否展示预览按钮 | undefined &#124; false &#124; true | 否 | true |
+| showDownloadButton | 是否展示下载按钮 | undefined &#124; false &#124; true | 否 | false |
+| download | 链接是否带 download 属性，点击直接下载 | undefined &#124; false &#124; true | 否 | false |
+| showLink | 有地址时是否渲染为链接 | undefined &#124; false &#124; true | 否 | true |
+| imagePreview | 是否用 ImagePreview 打开图片 | undefined &#124; false &#124; true | 否 | false |
+| imageLoading | 缩略图原生 loading 策略 | undefined &#124; "eager" &#124; "lazy" | 否 | undefined |
+| responseUrlKey | 从响应中提取 url 的字段名（支持 data.url 嵌套路径）或解析函数 | undefined &#124; string &#124; (file: UploadFile, response?: unknown) => string &#124; undefined | 否 | undefined |
+| ariaLabel | 上传入口的无障碍名称 | undefined &#124; string | 否 | undefined |
+
+### Events
+
+| 事件 | 用途 | 监听器签名（即事件参数） |
+| --- | --- | --- |
+| update:fileList | 文件列表变化，配合 v-model:file-list 使用 | undefined &#124; (_files: UploadFile<unknown>[]) => any |
+| change | 文件加入、进度、成功、失败、移除时触发 | undefined &#124; (_info: UploadChangeInfo) => any |
+| progress | 上传进度变化时触发，percent 为 0 ~ 1 | undefined &#124; (_info: UploadProgressInfo) => any |
+| success | 单个文件上传成功 | undefined &#124; (_file: UploadFile<unknown>) => any |
+| error | 单个文件上传失败 | undefined &#124; (_file: UploadFile<unknown>) => any |
+| remove | 文件被移除 | undefined &#124; (_file: UploadFile<unknown>) => any |
+| exceed | 文件数量超出 limit，超出部分不进入列表 | undefined &#124; (_info: UploadExceedInfo) => any |
+| reject | 文件被拒绝，reason 为 accept / limit / beforeUpload / read | undefined &#124; (_info: UploadRejectInfo) => any |
+| preview | 点击文件名或预览按钮 | undefined &#124; (_file: UploadFile<unknown>) => any |
+| download | 点击下载按钮 | undefined &#124; (_file: UploadFile<unknown>) => any |
+
+### Slots
+
+| 名称 | 用途 | 公开类型 |
+| --- | --- | --- |
+| default | 上传入口内容 | undefined &#124; () => any |
+| upload-button | 替换入口内容，保留组件交互 | undefined &#124; () => any |
+| upload-item | 替换整行列表项渲染 | undefined &#124; (scope: { file: UploadFile; index: number; }) => any |
+| file-icon | 自定义文本列表的文件图标 | undefined &#124; (scope: { file: UploadFile; }) => any |
+| file-name | 自定义文件名内容 | undefined &#124; (scope: { file: UploadFile; }) => any |
+| extra-button | 在操作区追加自定义操作 | undefined &#124; (scope: { file: UploadFile; }) => any |
+| image | 自定义图片 / 图片卡的缩略图 | undefined &#124; (scope: { file: UploadFile; }) => any |
+
+### 实例方法 / 暴露值
+
+| 名称 | 公开类型 |
+| --- | --- |
+| submit | 公开声明未细化（用法和实现已显式暴露） |
+| abort | 公开声明未细化（用法和实现已显式暴露） |
+| retry | 公开声明未细化（用法和实现已显式暴露） |
+| upload | 公开声明未细化（用法和实现已显式暴露） |
+| updateFile | 公开声明未细化（用法和实现已显式暴露） |
+| fileList | UploadFile<unknown>[] |
+
+### 关联类型定义
+
+以下摘自本组件族声明，供查阅嵌套配置；运行时和值类型均以根入口可导出项为准。
+
+```typescript-reference
+type UploadStatus = 'init' | 'uploading' | 'done' | 'error';
+
+type UploadListType = 'text' | 'picture' | 'picture-card';
+
+type UploadRequestMethod = 'post' | 'put' | 'patch';
+
+type UploadRejectReason = 'accept' | 'limit' | 'beforeUpload' | 'read';
+
+interface UploadFile<T = unknown> {
+    /** 文件唯一标识；外部列表未提供时组件会自动生成并保持稳定 */
+    uid: string;
+    name: string;
+    size?: number;
+    type?: string;
+    lastModified?: number;
+    /** 默认 done；上传中 uploading；失败 error；待上传 init */
+    status?: UploadStatus;
+    /** 上传进度，0 ~ 1（与 x-next Progress 组件一致） */
+    percent?: number;
+    /** 文件地址；上传成功后可由 responseUrlKey 从响应中提取 */
+    url?: string;
+    /** 缩略图地址；图片文件加入列表时自动生成本地预览地址 */
+    thumbUrl?: string;
+    /** 上传接口响应体 */
+    response?: T;
+    /** 上传失败的错误对象 */
+    error?: unknown;
+    /** 原始 File 对象；外部历史文件通常没有 */
+    file?: File;
+}
+
+type UploadBeforeUploadResult = void | boolean | File | Blob | string;
+
+type UploadBeforeUpload = (file: File, fileList: File[]) => UploadBeforeUploadResult | Promise<UploadBeforeUploadResult>;
+
+type UploadBeforeRemove = (file: UploadFile) => boolean | void | Promise<boolean | void>;
+
+type UploadAction = string | ((file: File) => string | Promise<string>);
+
+type UploadData = Record<string, unknown> | ((file: UploadFile) => Record<string, unknown> | Promise<Record<string, unknown>>);
+
+type UploadName = string | ((file: UploadFile) => string);
+
+type UploadResponseUrlKey = string | ((file: UploadFile, response?: unknown) => string | undefined);
+
+interface UploadRequestOption {
+    action: string;
+    method: UploadRequestMethod;
+    /** 文件字段名 */
+    name: string;
+    /** 原始文件对象 */
+    file: File;
+    /** 列表项，可读取 uid / 业务附加字段 */
+    fileItem: UploadFile;
+    data?: Record<string, unknown>;
+    headers?: Record<string, string>;
+    withCredentials: boolean;
+    /** 超时毫秒数，0 表示不超时 */
+    timeout: number;
+    /**
+     * 每次尝试独立的中止信号；取消上传、移除文件或组件卸载时触发 abort。
+     * 可直接透传给 fetch / axios 的 signal；环境不支持 AbortController 时为 undefined。
+     */
+    signal?: AbortSignal;
+    /** 进度回调，percent 为 0 ~ 1 */
+    onProgress: (percent: number, event?: ProgressEvent) => void;
+    onSuccess: (response?: unknown) => void;
+    onError: (error?: unknown) => void;
+}
+
+interface UploadRequest {
+    abort?: () => void;
+}
+
+type UploadCustomRequest = (option: UploadRequestOption) => UploadRequest | Promise<unknown> | void;
+
+interface UploadChangeInfo {
+    file: UploadFile;
+    fileList: UploadFile[];
+}
+
+interface UploadProgressInfo extends UploadChangeInfo {
+    percent: number;
+    event?: ProgressEvent;
+}
+
+interface UploadExceedInfo {
+    /** 因超出 limit 被拒绝的文件 */
+    files: File[];
+    fileList: UploadFile[];
+}
+
+interface UploadRejectInfo {
+    files: File[];
+    reason: UploadRejectReason;
+}
+
+interface UploadShowUploadButton {
+    /** 已达 limit 时仍显示上传入口，选中文件后触发 exceed 事件 */
+    showOnExceedLimit?: boolean;
+}
+```
+
+
+返回 [Upload 用法](./upload.md)。