@rainbow-oh/yee-c 0.9.2 → 0.11.0

package/src/Upload/demo/pictureWall.tsx

@@ -1,38 +1,39 @@
-import { Upload } from '@rainbow-oh/yee-c';
+import { Upload, type UploadFile, type UploadProps } from '@rainbow-oh/yee-c';
 import React, { useState } from 'react';
-import type { UploadFile } from '../interface';
+
+const imageUrl =
+  'https://zos.alipayobjects.com/rmsportal/jkjgkEfvpUPVyRjUImniVslZfWPnJuuZ.png';
 
 export default () => {
   const [fileList, setFileList] = useState<UploadFile[]>([
     {
       uid: '-1',
-      name: 'image.png',
-      status: 'done',
-      url: 'https://zos.alipayobjects.com/rmsportal/jkjgkEfvpUPVyRjUImniVslZfWPnJuuZ.png',
-    } as unknown as UploadFile,
+      name: 'image-1.png',
+      status: 'success',
+      type: 'image/png',
+      url: imageUrl,
+    },
     {
       uid: '-2',
-      name: 'image.png',
-      status: 'done',
-      url: 'https://zos.alipayobjects.com/rmsportal/jkjgkEfvpUPVyRjUImniVslZfWPnJuuZ.png',
-    } as unknown as UploadFile,
+      name: 'image-2.png',
+      status: 'success',
+      type: 'image/png',
+      url: imageUrl,
+    },
     {
       uid: '-3',
-      name: 'image.png',
-      status: 'done',
-      url: 'https://zos.alipayobjects.com/rmsportal/jkjgkEfvpUPVyRjUImniVslZfWPnJuuZ.png',
-    } as unknown as UploadFile,
+      name: 'image-3.png',
+      status: 'success',
+      type: 'image/png',
+      url: imageUrl,
+    },
   ]);
 
-  const handleChange = ({ fileList }: { fileList: UploadFile[] }) => {
-    setFileList(fileList);
-  };
-
-  const props = {
+  const props: UploadProps = {
     action: 'https://www.mocky.io/v2/5cc8019d300000980a055e76',
-    listType: 'picture-wall' as const,
+    listType: 'picture-wall',
     fileList,
-    onChange: handleChange,
+    onChange: ({ fileList: nextFileList }) => setFileList(nextFileList),
   };
 
   return <Upload {...props} />;

package/src/Upload/dragger.tsx

@@ -2,45 +2,58 @@ import clsx from 'clsx';
 import { Upload as UploadIcon } from 'lucide-react';
 import React from 'react';
 import { useLocale } from '../locale';
+import type { UploadDraggerProps, UploadInstance } from './interface';
 import Upload from './upload';
 
-const Dragger = React.forwardRef((props: any, ref) => {
-  const { prefixCls = 'yee-upload-dragger', children, disabled, hint } = props;
-  const { t } = useLocale();
+const Dragger = React.forwardRef<UploadInstance, UploadDraggerProps>(
+  (props, ref) => {
+    const {
+      prefixCls = 'yee-upload-dragger',
+      children,
+      disabled,
+      hint,
+    } = props;
+    const { t } = useLocale();
+
+    const renderChildren = () => {
+      return (
+        children ?? (
+          <>
+            <span className={`${prefixCls}-icon`} aria-hidden="true">
+              <UploadIcon size={22} />
+            </span>
+            <span className={`${prefixCls}-hint`}>
+              {hint ?? t('upload.draggerHint')}
+            </span>
+          </>
+        )
+      );
+    };
 
-  const renderChildren = () => {
     return (
-      children ?? (
-        <>
-          <span className={`${prefixCls}-icon`}>
-            <UploadIcon size={22} />
-          </span>
-          <span className={`${prefixCls}-hint`}>
-            {hint ?? t('upload.draggerHint')}
-          </span>
-        </>
-      )
+      <Upload {...props} type="drag" ref={ref}>
+        <div
+          className={clsx(prefixCls, {
+            [`${prefixCls}-disabled`]: disabled,
+          })}
+          role="button"
+          aria-disabled={disabled}
+          tabIndex={disabled ? -1 : 0}
+          onKeyDown={(event) => {
+            if (event.key === 'Enter' || event.key === ' ') {
+              event.preventDefault();
+              event.currentTarget.parentElement
+                ?.querySelector<HTMLInputElement>('input[type="file"]')
+                ?.click();
+            }
+          }}
+        >
+          {renderChildren()}
+        </div>
+      </Upload>
     );
-  };
-
-  return (
-    <Upload {...props} type="drag" ref={ref}>
-      <div
-        className={clsx(`${prefixCls}`, {
-          [`${prefixCls}-disabled`]: disabled,
-        })}
-        tabIndex={disabled ? -1 : 0}
-        onKeyDown={function (e) {
-          if (e.key === 'Enter') {
-            (e.target as HTMLDivElement).click();
-          }
-        }}
-      >
-        {renderChildren()}
-      </div>
-    </Upload>
-  );
-});
+  },
+);
 
 Dragger.displayName = 'Dragger';
 

package/src/Upload/index.en-US.md

@@ -10,7 +10,7 @@ toc: 'content'
 
 # Upload <span class="yee-mobile-badge" />
 
-Upload file by selecting or dragging.
+Upload files by selecting or dragging them.
 
 ## Code Demo
 
@@ -20,56 +20,76 @@ Upload file by selecting or dragging.
 <code src="./demo/directory.tsx" title="Directory" description="Upload directory"></code>
 <code src="./demo/multiple.tsx" title="Multiple" description="Multiple files upload"></code>
 <code src="./demo/controlled.tsx" title="Controlled" description="Controlled upload"></code>
+<code src="./demo/auto-upload.tsx" title="Manual Upload" description="Collect files with autoUpload=false and trigger batch upload from an external button via the instance method upload()"></code>
 
 ## API
 
 ### UploadProps
 
-| Property | Type | Description | Default |
-| --- | --- | --- | --- |
-| name | `string` | File name passed to backend | `'file'` |
-| children | `React.ReactNode` | Children elements | - |
-| type | `'drag' \| 'select'` | Upload type | - |
-| prefixCls | `string` | Custom class name prefix | - |
-| className | `string` | Custom class name | - |
-| style | `React.CSSProperties` | Custom style | - |
-| progress | `boolean` | Show upload progress | `true` |
-| withCredentials | `boolean` | Whether to carry cookies when uploading | - |
-| accept | `string` | Accepted file types | - |
-| action | `string \| (() => string)` | Upload URL | - |
-| data | `Record<string, any> \| ((file: File) => Record<string, any>)` | Additional parameters for upload | - |
-| directory | `boolean` | Support uploading folders | - |
-| multiple | `boolean` | Support multiple file selection | - |
-| disabled | `boolean` | Disabled | - |
-| headers | `Record<string, any>` | Set request headers | - |
-| maxFileSize | `number` | Max file size limit | - |
-| maxCount | `number` | Max file count limit | - |
-| listType | `'text' \| 'picture-list' \| 'picture-wall'` | Upload list type | - |
-| showUploadList | `boolean \| { showTooltip?: boolean; showRemoveIcon?: boolean; showReload?: boolean; showPreviewIcon?: boolean; removeIcon?: React.ReactNode; reloadIcon?: React.ReactNode; previewIcon?: React.ReactNode; }` | Show upload file list | `true` |
-| itemRender | `(file: UploadFile, fileList: UploadFile[]) => React.ReactNode` | Custom upload list item | - |
-| defaultFileList | `Array<UploadFile>` | Default upload files | - |
-| fileList | `Array<UploadFile>` | Controlled upload files | - |
-| beforeUpload | `(file: File, fileList: Array<File>) => boolean \| Promise<File \| boolean>` | Callback before upload | - |
-| customRequest | `(options: UploadRequestOptions) => void` | Custom upload implementation | - |
-| onChange | `(params: { file: UploadFile; fileList: Array<UploadFile>; event?: any }) => void` | Callback when upload status changes | - |
-| onPreview | `(file: UploadFile) => void` | File preview callback | - |
-| onRemove | `(file: UploadFile) => boolean \| Promise<boolean>` | Callback when file is removed | - |
-| data-* | `string` | - | Supports all data-* attributes, forwarded to root DOM element |
+| Property        | Type                                                                                                                                                                                                          | Description                                                                                                                                      | Default                                                               |
+| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------- |
+| name            | `string`                                                                                                                                                                                                      | File field name sent to the server                                                                                                               | `'file'`                                                              |
+| children        | `React.ReactNode`                                                                                                                                                                                             | Child nodes                                                                                                                                      | -                                                                     |
+| type            | `'drag' \| 'select'`                                                                                                                                                                                          | Upload type                                                                                                                                      | -                                                                     |
+| prefixCls       | `string`                                                                                                                                                                                                      | Custom class name prefix                                                                                                                         | -                                                                     |
+| className       | `string`                                                                                                                                                                                                      | Custom class name                                                                                                                                | -                                                                     |
+| style           | `React.CSSProperties`                                                                                                                                                                                         | Custom inline style                                                                                                                              | -                                                                     |
+| progress        | `boolean`                                                                                                                                                                                                     | Show upload progress                                                                                                                             | `true`                                                                |
+| withCredentials | `boolean`                                                                                                                                                                                                     | Send cookies with the upload                                                                                                                     | -                                                                     |
+| accept          | `string`                                                                                                                                                                                                      | Accepted file types; enforced for selection and drop                                                                                             | -                                                                     |
+| action          | `string \| (() => string)`                                                                                                                                                                                    | Upload URL; required without `customRequest`                                                                                                     | -                                                                     |
+| data            | `Record<string, any> \| ((file: File) => Record<string, any>)`                                                                                                                                                | Additional upload parameters                                                                                                                     | -                                                                     |
+| directory       | `boolean`                                                                                                                                                                                                     | Support directory upload                                                                                                                         | -                                                                     |
+| multiple        | `boolean`                                                                                                                                                                                                     | Support multiple files                                                                                                                           | -                                                                     |
+| disabled        | `boolean`                                                                                                                                                                                                     | Disable upload                                                                                                                                   | -                                                                     |
+| headers         | `Record<string, any>`                                                                                                                                                                                         | Request headers                                                                                                                                  | -                                                                     |
+| maxFileSize     | `number`                                                                                                                                                                                                      | Maximum file size in bytes                                                                                                                       | -                                                                     |
+| maxCount        | `number`                                                                                                                                                                                                      | Maximum file count                                                                                                                               | -                                                                     |
+| listType        | `'text' \| 'picture-list' \| 'picture-wall'`                                                                                                                                                                  | Upload list type                                                                                                                                 | `'text'`                                                              |
+| showUploadList  | `boolean \| { showTooltip?: boolean; showRemoveIcon?: boolean; showReload?: boolean; showPreviewIcon?: boolean; removeIcon?: React.ReactNode; reloadIcon?: React.ReactNode; previewIcon?: React.ReactNode; }` | Show upload file list                                                                                                                            | `true`                                                                |
+| itemRender      | `(file: UploadFile, fileList: UploadFile[]) => React.ReactNode`                                                                                                                                               | Custom action content for a list item                                                                                                            | -                                                                     |
+| defaultFileList | `UploadFile[]`                                                                                                                                                                                                | Default uploaded files                                                                                                                           | -                                                                     |
+| fileList        | `UploadFile[]`                                                                                                                                                                                                | Uploaded files in controlled mode                                                                                                                | -                                                                     |
+| autoUpload      | `boolean`                                                                                                                                                                                                     | Whether to upload automatically after selection; when `false` files only join the list and are uploaded later via the instance method `upload()` | `true`                                                                |
+| beforeUpload    | `(file: File, fileList: File[]) => boolean \| File \| PromiseLike<File \| boolean>`                                                                                                                           | Callback before upload                                                                                                                           | -                                                                     |
+| customRequest   | `(options: UploadRequestOptions) => void \| (() => void) \| { abort: () => void }`                                                                                                                            | Custom upload implementation; return an abort handle to cancel on remove, retry, and unmount                                                     | -                                                                     |
+| onChange        | `(params: { file: UploadFile; fileList: UploadFile[]; event?: any }) => void`                                                                                                                                 | Upload state callback; `fileList` is the updated list                                                                                            | -                                                                     |
+| onPreview       | `(file: UploadFile) => void`                                                                                                                                                                                  | File preview callback                                                                                                                            | -                                                                     |
+| onRemove        | `(file: UploadFile) => boolean \| PromiseLike<boolean>`                                                                                                                                                       | File removal callback                                                                                                                            | -                                                                     |
+| data-\*         | `string`                                                                                                                                                                                                      | -                                                                                                                                                | Supports all data-\* attributes and forwards them to the root element |
 
 ### UploadFile
 
-| Property | Type | Description | Default |
-| --- | --- | --- | --- |
-| status | `'uploading' \| 'error' \| 'success' \| 'ready'` | File upload status | - |
-| uid | `string` | File unique id | - |
-| name | `string` | File name | - |
-| size | `number` | File size | - |
-| percent | `number` | Upload progress | - |
-| raw | `File` | Raw file | - |
-| type | `string` | File type | - |
-| response | `any` | Upload response data | - |
-| error | `Error` | Upload error info | - |
+| Property | Type                                             | Description                                                 | Default |
+| -------- | ------------------------------------------------ | ----------------------------------------------------------- | ------- |
+| status   | `'uploading' \| 'error' \| 'success' \| 'ready'` | File upload status                                          | -       |
+| uid      | `string`                                         | Unique file ID; generated for files selected through Upload | -       |
+| name     | `string`                                         | File name                                                   | -       |
+| size     | `number`                                         | File size; optional for remote files                        | -       |
+| percent  | `number`                                         | Upload progress                                             | -       |
+| raw      | `File`                                           | Source file; optional for remote files                      | -       |
+| type     | `string`                                         | MIME type or file extension                                 | -       |
+| url      | `string`                                         | Preview URL for a remote file                               | -       |
+| response | `any`                                            | Upload response data                                        | -       |
+| error    | `Error`                                          | Upload error                                                | -       |
+
+### UploadRequestOptions
+
+| Property   | Type                        | Description                   |
+| ---------- | --------------------------- | ----------------------------- |
+| file       | `File`                      | Source file to upload         |
+| onProgress | `(percent: number) => void` | Update upload progress        |
+| onError    | `(error: Error) => void`    | Mark the upload as failed     |
+| onSuccess  | `(response: any) => void`   | Mark the upload as successful |
+
+### Instance Methods (Ref)
+
+Access via `ref` as `UploadInstance` (root DOM element plus the methods below):
+
+| Method | Type                                          | Description                                                                                                                                                                                   |
+| ------ | --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| upload | `(file?: UploadFile \| UploadFile[]) => void` | Upload files waiting in the list (`status` of `ready`); without arguments uploads all of them, or pass a single file or a list. Combine with `autoUpload={false}` to trigger uploads manually |
 
 ## Notes
 
-- Adapted for mobile (reduced Dragger padding, picture-wall actions always visible, list item touch targets 44px)
+- Adapted for mobile with reduced Dragger padding, always-visible picture-wall actions, and 44px list-item touch targets.

package/src/Upload/index.ts

@@ -9,6 +9,13 @@ const Upload = InternalUpload as UploadType;
 
 Upload.Dragger = Dragger;
 
-export type { UploadProps } from './interface';
+export type {
+  UploadDraggerProps,
+  UploadFile,
+  UploadInstance,
+  UploadProps,
+  UploadRequestAbort,
+  UploadRequestOptions,
+} from './interface';
 
 export default Upload;

package/src/Upload/index.zh-CN.md

@@ -20,56 +20,76 @@ toc: 'content'
 <code src="./demo/directory.tsx" title="文件夹上传" description="上传文件夹"></code>
 <code src="./demo/multiple.tsx" title="多文件上传" description="上传多个文件"></code>
 <code src="./demo/controlled.tsx" title="受控" description="受控的上传"></code>
+<code src="./demo/auto-upload.tsx" title="手动上传" description="autoUpload=false 先收集文件，通过实例方法 upload() 在外部按钮触发批量上传"></code>
 
 ## API
 
 ### UploadProps
 
-| 属性名 | 类型 | 描述 | 默认值 |
-| --- | --- | --- | --- |
-| name | `string` | 传递到后台的文件名 | `'file'` |
-| children | `React.ReactNode` | 子节点 | - |
-| type | `'drag' \| 'select'` | 上传类型 | - |
-| prefixCls | `string` | 自定义类名前缀 | - |
-| className | `string` | 自定义类名 | - |
-| style | `React.CSSProperties` | 自定义行内样式 | - |
-| progress | `boolean` | 是否显示上传进度 | `true` |
-| withCredentials | `boolean` | 上传是否携带cookie | - |
-| accept | `string` | 接受上传的文件类型 | - |
-| action | `string \| (() => string)` | 上传的地址 | - |
-| data | `Record<string, any> \| ((file: File) => Record<string, any>)` | 上传额外需要的参数 | - |
-| directory | `boolean` | 是否支持上传文件夹 | - |
-| multiple | `boolean` | 是否支持多选文件 | - |
-| disabled | `boolean` | 是否被禁用 | - |
-| headers | `Record<string, any>` | 设置上传的请求头 | - |
-| maxFileSize | `number` | 文件最大大小限制 | - |
-| maxCount | `number` | 最大文件数量限制 | - |
-| listType | `'text' \| 'picture-list' \| 'picture-wall'` | 设置上传列表类型 | - |
-| showUploadList | `boolean \| { showTooltip?: boolean; showRemoveIcon?: boolean; showReload?: boolean; showPreviewIcon?: boolean; removeIcon?: React.ReactNode; reloadIcon?: React.ReactNode; previewIcon?: React.ReactNode; }` | 是否显示上传文件列表 | `true` |
-| itemRender | `(file: UploadFile, fileList: UploadFile[]) => React.ReactNode` | 自定义上传列表项 | - |
-| defaultFileList | `Array<UploadFile>` | 默认上传文件 | - |
-| fileList | `Array<UploadFile>` | 受控状态的上传文件 | - |
-| beforeUpload | `(file: File, fileList: Array<File>) => boolean \| Promise<File \| boolean>` | 上传文件之前的回调函数 | - |
-| customRequest | `(options: UploadRequestOptions) => void` | 自定义上传实现 | - |
-| onChange | `(params: { file: UploadFile; fileList: Array<UploadFile>; event?: any }) => void` | 上传状态变化的回调 | - |
-| onPreview | `(file: UploadFile) => void` | 文件预览回调 | - |
-| onRemove | `(file: UploadFile) => boolean \| Promise<boolean>` | 删除文件的回调 | - |
-| data-* | `string` | - | 支持所有 data-* 属性，透传到组件根 DOM 元素 |
+| 属性名          | 类型                                                                                                                                                                                                          | 描述                                                                                      | 默认值                                       |
+| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | -------------------------------------------- |
+| name            | `string`                                                                                                                                                                                                      | 传递到后台的文件名                                                                        | `'file'`                                     |
+| children        | `React.ReactNode`                                                                                                                                                                                             | 子节点                                                                                    | -                                            |
+| type            | `'drag' \| 'select'`                                                                                                                                                                                          | 上传类型                                                                                  | -                                            |
+| prefixCls       | `string`                                                                                                                                                                                                      | 自定义类名前缀                                                                            | -                                            |
+| className       | `string`                                                                                                                                                                                                      | 自定义类名                                                                                | -                                            |
+| style           | `React.CSSProperties`                                                                                                                                                                                         | 自定义行内样式                                                                            | -                                            |
+| progress        | `boolean`                                                                                                                                                                                                     | 是否显示上传进度                                                                          | `true`                                       |
+| withCredentials | `boolean`                                                                                                                                                                                                     | 上传是否携带 cookie                                                                       | -                                            |
+| accept          | `string`                                                                                                                                                                                                      | 接受上传的文件类型；选择和拖放均会校验                                                    | -                                            |
+| action          | `string \| (() => string)`                                                                                                                                                                                    | 上传地址；未设置 `customRequest` 时必填                                                   | -                                            |
+| data            | `Record<string, any> \| ((file: File) => Record<string, any>)`                                                                                                                                                | 上传额外需要的参数                                                                        | -                                            |
+| directory       | `boolean`                                                                                                                                                                                                     | 是否支持上传文件夹                                                                        | -                                            |
+| multiple        | `boolean`                                                                                                                                                                                                     | 是否支持多选文件                                                                          | -                                            |
+| disabled        | `boolean`                                                                                                                                                                                                     | 是否被禁用                                                                                | -                                            |
+| headers         | `Record<string, any>`                                                                                                                                                                                         | 设置上传请求头                                                                            | -                                            |
+| maxFileSize     | `number`                                                                                                                                                                                                      | 文件最大大小限制，单位字节                                                                | -                                            |
+| maxCount        | `number`                                                                                                                                                                                                      | 最大文件数量限制                                                                          | -                                            |
+| listType        | `'text' \| 'picture-list' \| 'picture-wall'`                                                                                                                                                                  | 设置上传列表类型                                                                          | `'text'`                                     |
+| showUploadList  | `boolean \| { showTooltip?: boolean; showRemoveIcon?: boolean; showReload?: boolean; showPreviewIcon?: boolean; removeIcon?: React.ReactNode; reloadIcon?: React.ReactNode; previewIcon?: React.ReactNode; }` | 是否显示上传文件列表                                                                      | `true`                                       |
+| itemRender      | `(file: UploadFile, fileList: UploadFile[]) => React.ReactNode`                                                                                                                                               | 自定义上传列表项操作内容                                                                  | -                                            |
+| defaultFileList | `UploadFile[]`                                                                                                                                                                                                | 默认上传文件                                                                              | -                                            |
+| fileList        | `UploadFile[]`                                                                                                                                                                                                | 受控状态的上传文件                                                                        | -                                            |
+| autoUpload      | `boolean`                                                                                                                                                                                                     | 选择文件后是否自动上传；为 `false` 时文件仅进入列表，稍后通过实例方法 `upload()` 触发上传 | `true`                                       |
+| beforeUpload    | `(file: File, fileList: File[]) => boolean \| File \| PromiseLike<File \| boolean>`                                                                                                                           | 上传文件之前的回调                                                                        | -                                            |
+| customRequest   | `(options: UploadRequestOptions) => void \| (() => void) \| { abort: () => void }`                                                                                                                            | 自定义上传实现；返回取消句柄后，删除、重试和卸载会取消请求                                | -                                            |
+| onChange        | `(params: { file: UploadFile; fileList: UploadFile[]; event?: any }) => void`                                                                                                                                 | 上传状态变化回调，`fileList` 为变化后的列表                                               | -                                            |
+| onPreview       | `(file: UploadFile) => void`                                                                                                                                                                                  | 文件预览回调                                                                              | -                                            |
+| onRemove        | `(file: UploadFile) => boolean \| PromiseLike<boolean>`                                                                                                                                                       | 删除文件的回调                                                                            | -                                            |
+| data-\*         | `string`                                                                                                                                                                                                      | -                                                                                         | 支持所有 data-\* 属性，透传到组件根 DOM 元素 |
 
 ### UploadFile
 
-| 属性名 | 类型 | 描述 | 默认值 |
-| --- | --- | --- | --- |
-| status | `'uploading' \| 'error' \| 'success' \| 'ready'` | 文件上传状态 | - |
-| uid | `string` | 文件唯一id，未设置会自动生成 | - |
-| name | `string` | 文件名 | - |
-| size | `number` | 文件大小 | - |
-| percent | `number` | 上传进度 | - |
-| raw | `File` | 源文件 | - |
-| type | `string` | 文件类型，根据文件后缀名判断 | - |
-| response | `any` | 上传响应数据 | - |
-| error | `Error` | 上传错误信息 | - |
+| 属性名   | 类型                                             | 描述                                  | 默认值 |
+| -------- | ------------------------------------------------ | ------------------------------------- | ------ |
+| status   | `'uploading' \| 'error' \| 'success' \| 'ready'` | 文件上传状态                          | -      |
+| uid      | `string`                                         | 文件唯一 ID；组件选择的文件会自动生成 | -      |
+| name     | `string`                                         | 文件名                                | -      |
+| size     | `number`                                         | 文件大小；服务端文件可省略            | -      |
+| percent  | `number`                                         | 上传进度                              | -      |
+| raw      | `File`                                           | 源文件；服务端文件可省略              | -      |
+| type     | `string`                                         | MIME 类型或文件扩展名                 | -      |
+| url      | `string`                                         | 服务端文件的预览地址                  | -      |
+| response | `any`                                            | 上传响应数据                          | -      |
+| error    | `Error`                                          | 上传错误信息                          | -      |
+
+### UploadRequestOptions
+
+| 属性名     | 类型                        | 描述         |
+| ---------- | --------------------------- | ------------ |
+| file       | `File`                      | 待上传源文件 |
+| onProgress | `(percent: number) => void` | 更新上传进度 |
+| onError    | `(error: Error) => void`    | 标记上传失败 |
+| onSuccess  | `(response: any) => void`   | 标记上传成功 |
+
+### 实例方法（Ref）
+
+通过 `ref` 获取 `UploadInstance`（根 DOM 元素 + 以下方法）：
+
+| 方法   | 类型                                          | 描述                                                                                                                      |
+| ------ | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| upload | `(file?: UploadFile \| UploadFile[]) => void` | 上传列表中等待的文件（`status` 为 `ready`）；不传参数上传全部，也可指定单个或多个。配合 `autoUpload={false}` 手动触发上传 |
 
 ## 注意事项
 
-- 已适配移动端（减小 Dragger 内边距、图片墙操作按钮常显、列表项触控区域 44px）
+- 已适配移动端（减小 Dragger 内边距、图片墙操作按钮常显、列表项触控区域 44px）