Upload 上传

⚠️ 版本警告

注意：本文档适用于版本 3.x.x 或更高版本，请参考对应版本的最新文档。

请确保您正在查看的文档版本与您所使用的版本相符，以避免可能的功能差异和不兼容问题。

引入

javascript

import { WUpload } from '@wyg/file-upload'

import '@wyg/file-upload/dist/style.css'

基本使用

上传组件的基本用法。

已上传的文件列表

可以指定默认的已上传文件列表，以便于观察。

注意

如果是默认或通过上传并回显的数据列表，格式应该是：

{
    status: 'done',
    uid: '当前文件的唯一标识',
    name: '您的文件名',
    url: '您的 url 文件地址',
    description: 'image' | 'file', // 如果是在照片墙模式下，需标明当前类型（图片 或 附件）
}

必须包含 uid、name、url 和 status 四个字段。其中，status 值为 done 时，才会显示预览和下载按钮。

照片墙

通过设置 list-type="picture-card" 开启照片墙模式。

图标列表

通过设置 list-type="picture" 开启图片列表样式。

拖拽上传

通过设置 draggable 开启对拖拽的支持。

用户头像上传

通过设置 show-avatar-upload 开启用户头像上传。

照片墙列表

通过设置 is-picture-card-list 开启照片墙列表上传。

网盘文件选择

通过设置 show-netdisk-file-picker 属性在照片墙列表开启网盘文件选择功能。

注意

要启用网盘文件选择功能，需先配置 is-picture-card-list 照片墙列表，并且提供 netdisk-file-api-origin 和 netdisk-file-token-value 属性。

注意

通过网盘选中文件后，不会重新发起上传流程，因此不会触发 Upload 组件的 change、success 等事件。

TIP

支持自定义设置网盘提示浮层及各类弹窗的 z-index，以确保在复杂 UI 中正确显示层级关系。

netdiskZIndex?: {
  /** 列表弹窗（默认：1100） */
  selectorZIndex?: number;
  /** 搜索弹窗（默认：1200） */
  searchModalZIndex?: number;
  /** 已选文件弹窗（默认：1200） */
  selectedFilesModalZIndex?: number;
  /** 路径提示浮层（默认：1300） */
  tooltipZIndex?: number;
};

上传前校验

onBeforeUpload 会在每一个文件上传之前执行。如果返回 false 或者 Promise.reject，那么将会取消当前文件的上传。

移除前校验

onBeforeRemove 会在每一个文件移除之前执行。如果返回 false 或者 Promise.reject，那么将会取消当前文件的操作。

限制上传数量

通过 limit 限制上传的最大数量。超出后上传按钮会隐藏。同时您可以配置 show-upload-button 中的 showOnExceedLimit 属性为 true，来显示超出后的上传按钮。

自定义图标

文件夹上传

可以通过 directory 开启文件夹上传，(需要浏览器支持)。

阿里 OSS 上传

通过 is-upload-to-ali-oss 开启 oss 上传。请确保正确配置相关的 OSS 参数。

`<upload>` Props：

属性名	说明	类型	默认值
upload-props	arco Upload 组件 Props	`UploadProps`	`-`
file-list (v-model)	文件列表	`FileItem[]`	`-`
show-remove-button	是否显示删除按钮	`boolean`	`true`
show-retry-button	是否显示重试按钮	`boolean`	`true`
show-preview-button	是否显示预览按钮	`boolean`	`true`
show-attachment-preview-button	是否在照片墙列表中显示附件列表的预览按钮	`boolean`	`true`
show-netdisk-file-picker	是否在照片墙列表中展示网盘文件选择功能	`booleean`	`false`
netdisk-file-api-origin	开启网盘功能后，需要传入当前接口地址	`string`	`-`
netdisk-file-source-system	开启网盘功能后，需要传入的源系统名称	`string`	`wygtech-storage-platform`
netdisk-file-token-value	开启网盘功能后，需要传入 `token` 值	`string`	`-`
netdisk-suffix	网盘文件筛选后缀，用于模糊匹配文件类型	`string`	`-`
netdisk-z-index	支持自定义设置网盘提示浮层和各弹窗的 z-index 层级	`{ selectorZIndex?: number; searchModalZIndex?: number; selectedFilesModalZIndex?: number; tooltipZIndex?: number; }`	`-`
show-downLoad	是否显示下载按钮	`boolean`	`true`
show-upload-button	是否显示点击上传按钮	`boolean \| { showOnExceedLimit: boolean }`	`true`
show-picture-card-upload-button	照片墙模式下是否显示卡片上传按钮	`boolean`	`true`
tip	提示文字	`string`	`-`
show-avatar-upload	是否开启用户头像上传模式	`boolean`	`false`
is-picture-card-list	是否开启照片墙列表	`boolean`	`false`
customIcon	自定义图标	`WCustomIcon`	`-`
is-upload-to-ali-oss	是否上传至阿里oss，默认不开启	`boolean`	`false`
is-multiple-upload	是否开启分片上传	`boolean`	`true`
multipart-file-options	分片配置，默认：`{ parallel: 5, partSize: 5 }`	`MultipartFileOptions`	`-`
ali-oss-sts-config	STS 临时授权配置	`AliOssSTSConfig`	`-`
file-preview-props	file preview 组件的 props	`FilePreviewProps`	`-`
show-modal	预览是否使用 Modal 模式预览，图片除外，默认 Modal	`boolean`	`-`
show-drawer	预览是否使用抽屉 Drawer 模式预览，图片除外	`boolean`	`-`
handle-upload-filename	上传时是否对 filename 参数进行处理	`(name: string) => string`	`-`

typescript

interface Props {
  /** arco Upload 组件 Props */
  uploadProps?: UploadProps;
  /** 文件列表 */
  fileList?: FileItem[];
  /** 是否显示删除按钮 */
  showRemoveButton?: boolean;
  /** 是否显示重试按钮 */
  showRetryButton?: boolean;
  /** 是否显示预览按钮 */
  showPreviewButton?: boolean;
  /** 是否在照片墙列表中显示附件列表的预览按钮 */
  showAttachmentPreviewButton?: boolean;
  /**
   * 是否在照片墙列表中展示网盘文件选择功能。
   * 如果为 true，则必须提供 netdiskFileApiOrigin 和 netdiskFileTokenValue 属性
   */
  showNetdiskFilePicker?: boolean;
  /** 开启网盘功能后，需要传入当前的环境信息 */
  // netdiskFileMode?: 'test' | 'prod';
  /** 开启网盘功能后，需要传入当前接口地址 */
  netdiskFileApiOrigin?: string;
  /** 开启网盘功能后，需要传入的源系统名称（默认：wygtech-storage-platform） */
  netdiskFileSourceSystem?: string;
  /** 开启网盘功能后，需要传入 token 值 */
  netdiskFileTokenValue?: string;
  /**  
   * 网盘文件筛选后缀，用于模糊匹配文件类型
   * 支持多个后缀名，使用英文逗号分隔，例如：'png,docx'
   * 模糊匹配规则：传入 'doc' 可匹配 'doc' 与 'docx'
   */
  netdiskSuffix?: string;
  /** 是否显示下载按钮 */
  showDownLoad?: boolean;
  /** 是否显示 点击上传 按钮 */
  showUploadButton?: boolean | { showOnExceedLimit: boolean };
  /** 照片墙模式下是否显示 卡片上传 按钮 */
  showPictureCardUploadButton?: boolean;
  /** 提示文字 */
  tip?: string;
  /** 是否开启用户头像上传模式 */
  showAvatarUpload?: boolean;
  /** 是否开启照片墙列表 */
  isPictureCardList?: boolean;
  /** 自定义图标 */
  customIcon?: WCustomIcon;
  /** 是否上传至阿里oss，默认不开启 */
  isUploadToAliOss?: boolean;
  /** 是否开启分片上传，默认 true */
  isMultipleUpload?: boolean;
  /** 分片配置，默认：{ parallel: 5,partSize: 5 } */
  multipartFileOptions?: MultipartFileOptions;
  /** STS 临时授权配置 */
  aliOssStsConfig?: AliOssSTSConfig;
  /** file preview 组件的 props */
  filePreviewProps?: FilePreviewProps;
  /** 预览是否使用 Modal 模式预览，图片除外, 默认 Modal */
  showModal?: boolean;
  /** 预览是否使用抽屉 Drawer 模式预览，图片除外 */
  showDrawer?: boolean;
  /** 上传时是否对 filename 参数进行处理 */
  handleUploadFilename?: (name: string) => string;
}

/** arco Upload 组件 Props, 
 (除 
    fileList, defaultFileList, tip, showRemoveButton, showRetryButton, showCancelButton, 
    showUploadButton, showPreviewButton, download, showLink, responseUrlKey, customIcon
    imagePreview, onButtonClick
 ) 
*/
export interface UploadProps {
    /** 上传的 URL */
    action: string;
    /** 文件列表 */
    // fileList?: FileItem[];
    /** 默认的文件列表（非受控状态） */
    // defaultFileList?: FileItem[];
    /** 接收的上传文件类型 */
    accept?: string;
    /** 是否禁用 */
    disabled?: boolean;
    /** 是否支持多文件上传 */
    multiple?: boolean;
    /** 是否支持文件夹上传（需要浏览器支持） */
    directory?: boolean;
    /** 是否支持拖拽上传 */
    draggable?: boolean;
    /** 提示文字 */
    // tip?: string;
    /** 上传请求附加的头信息 */
    headers?: Record<string, string>;
    /** 上传请求附加的数据 */
    data?: Record<string, string | Blob>| ((fileItem: FileItem) => Record<string, string | Blob>);
    /** 上传的文件名 */
    name?: string | ((fileItem: FileItem) => string);
    /** 上传请求是否携带 cookie */
    withCredentials?: boolean;
    /** 自定义上传行为 */
    customRequest?: (option: RequestOption) => UploadRequest;
    /** 限制上传文件的数量。0 表示不限制 */
    limit?: number;
    /** 是否自动上传文件 */
    autoUpload?: boolean;
    /** 是否显示文件列表 */
    showFileList?: boolean;
    /** 是否显示删除按钮 */
    // showRemoveButton?: boolean;
    // /** 是否显示重试按钮 */
    // showRetryButton?: boolean;
    /** 是否显示取消按钮 */
    // showCancelButton?: boolean;
    /** 是否显示上传按钮 */
    // showUploadButton?: boolean | { showOnExceedLimit: boolean };
    /** 照片墙是否显示预览按钮 */
    // showPreviewButton?: boolean;
    /** 是否在 <a> 链接上添加 download 属性 */
    // download?: boolean;
    /** 在列表模式下，如果上传的文件存在 URL 则展示链接。如果关闭仅展示文字并且点击可以触发 preview 事件 */
    // showLink?: boolean;
    /** <img> 的原生 HTML 属性，需要浏览器支持 */
    imageLoading?: 'eager' | 'lazy';
    /** 图片列表类型 */
    listType?: 'text' | 'picture' | 'picture-card';
    /** Response中获取图片URL的key，开启后会用上传的图片替换预加载的图片 */
    // responseUrlKey?: string | ((fileItem: FileItem) => string);
    /** 自定义图标 */
    // customIcon?: WCustomIcon;
    /** 是否使用 ImagePreview 组件进行预览 */
    // imagePreview?: boolean;
    /** 上传文件前触发 */
    onBeforeUpload?: (file: File) => boolean | Promise<boolean | File>;
    /** 移除文件前触发 */
    onBeforeRemove?: (fileItem: FileItem) => Promise<boolean>;
    /** 点击上传按钮触发（如果返回 Promise 则会关闭默认 input 上传） */
    // onButtonClick?: (event: Event) => Promise<FileList> | void;
}

/** 自定义图标 */
export interface WCustomIcon {
    /** 暂停图标 */
    pauseIcon?: RenderFunction;
    /** 重试图标 */
    retryIcon?: RenderFunction;
    /** 成功图标 */
    successIcon?: RenderFunction;
    /** 删除图标 */
    removeIcon?: RenderFunction;
    /** 预览图标 */
    previewIcon?: RenderFunction;
    /** 上传中图标 */
    uploading?: RenderFunction;
    /** 下载图标 */
    downLoad?: RenderFunction;
    /** 文件图标 */
    fileIcon?: (fileItem: FileItem) => VNode;
    /** 文件名 */
    fileName?: (fileItem: FileItem) => string;
}

/** 使用STS进行临时授权 */
export interface AliOssSTSConfig {
    /** 网关接口访问地址 必传, 如：https://gatewaytest.wygsy.com */
    baseURL: string;
    /** 系统标识 */
    sourceSystem:
        | string
        | 'base-platform'
        | 'wygtech-oa'
        | 'wygtech-hr-platform'
        | 'wygca-admin'
        | 'wygtech-signature'
        | 'wygtech-boss'
        | 'wygtech-crm';
    /** token 必传 */
    token: string;
    /** 是否https上传，默认true */
    isHttps?: boolean;
    /** 超时时间，单位秒 */
    expireTime?: number | string;
    /** 域和桶，可用值：BEIJING_SF_GCSJ, CHENGDU_TECH_CENTER, CHENGDU_TECH_CENTER_PRIVATE, CHENGDU_TECH_CENTER_TEST, CHENGDU_TECH_CENTER_TEST_PRIVATE, HANGZHOU_SHANGYUN, HANGZHOU_SHANGYUN_TES */
    ossBucket?: TYPE_OSS_BUCKET;
    /** 文件授权接口，默认使用 tool-center 的接口 */
    authUrl?: string;
}

/** 域和桶, 可用值; */
export type TYPE_OSS_BUCKET = "BEIJING_SF_GCSJ" | "CHENGDU_TECH_CENTER" | "CHENGDU_TECH_CENTER_PRIVATE" | "CHENGDU_TECH_CENTER_TEST" | "CHENGDU_TECH_CENTER_TEST_PRIVATE" | "HANGZHOU_SHANGYUN" | "HANGZHOU_SHANGYUN_TEST";

/** 分片配置 */
export interface MultipartFileOptions {
    /** 并发上传的分片数 */
    parallel: number | undefined;
    /** 每个分片大小 */
    partSize: number | undefined;
}

/** file preview 组件的 props, 除(fileConfig, imagePreviewCarousel, current, showModal, showDrawer) */
export interface FilePreviewProps {
  /** arco Modal 组件 Props */
  modalProps?: ModalProps;
  /** arco Modal 组件 container 元素的自定义样式 (style) 属性 */
  modalContainerStyle?: CSSProperties;
  /** arco Drawer 组件 Props */
  drawerProps?: DrawerProps;
  /** arco Drawer 组件 container 元素的自定义样式 (style) 属性 */
  drawerContainerStyle?: CSSProperties;
  /** 文件预览配置，只能传入一个 file 或 url（只支持 office 文件预览） */
  // fileConfig?: FileConfig;
  /** arco imagePreviewGroup 组件 Props（多个图片预览组件）  */
  imagePreviewGroupProps?: ImagePreviewGroupProps;
  /** 图片预览的url数组，支持左右翻页查看其它图片（多个图片预览） */
  // imagePreviewCarousel?: string[];
  /** 多图预览时当前展示的图片下标 */
  // current?: number;
  /** 是否使用 modal 模式预览，图片除外 */
  // showModal?: boolean;
  /** 是否显示下载按钮。如果为 false, 则显示确认按钮 */
  showDownLoad?: boolean;
  /** 抽屉 Drawer 是否开启全屏 */
  drawerFullscreen?: boolean;
  /** 是否使用抽屉 Drawer 模式预览，图片除外 */
  // showDrawer?: boolean;
}

/** arco Upload 组件，类型 FileItem */
interface FileItem {
    /** 当前上传文件的唯一标示 */
    uid: string;
    /** 当前上传文件的状态 */
    status?: FileStatus;
    /** 文件对象 */
    file?: File;
    /** 上传进度百分比 */
    percent?: number;
    /** 当前文件上传请求返回的响应 */
    response?: any;
    /** 文件地址 */
    url?: string;
    /** 文件名 */
    name?: string;
    /** 照片墙列表上传来源（图片 或 附件） */
    description?: PictureCardListUploadSource;
    /** 开启 oss 上传，并上传成功后返回 oss 的 url 文件地址 */
    ossUrl?: string;
    /** 开启 oss 上传，并上传成功后返回的结果 */
    ossResult?: any;
}

/** 确定照片墙列表上传来源 */
type PictureCardListUploadSource = 'image' | 'file' | '';

类型 FileItem 数据格式参考如下：

`<upload>` Events：

事件名	说明	参数
exceed-limit	上传的文件超出限制后触发	fileList: `FileItem[]` files: `File[]`
change	上传的文件状态发生改变时触发	fileList: `FileItem[]` fileItem: `FileItem`
progress	上传中的文件进度改变时触发	fileItem: `FileItem` ev: `ProgressEvent`
preview	点击预览时的触发	fileItem: `FileItem`
success	上传成功时触发	fileItem: `FileItem`
error	上传失败时触发	fileItem: `FileItem`
remove-file	移除文件时触发	fileItem: `FileItem`

`<upload>` Methods：

方法名	说明	参数	返回值
methods	arco Upload 组件的 Methods，点击这里	`-`	`-`

`<upload>` Slots：

插槽名	说明	参数
upload-item	`text` 和 `picture` 上传列表的项目	fileItem: `FileItem` index: `number`
picture-card-upload-item	`picture-card` 上传列表的项目	fileItem: `FileItem` index: `number`
picture-card-list	照片墙列表	`-`
draggable-upload	拖拽上传	`-`
avatar-upload	用户头像上传	`-`
upload-button	`text`, `picture`, `picture-card` 的上传按钮	`-`

Upload 上传 ​

引入 ​

基本使用 ​

已上传的文件列表 ​

照片墙 ​

图标列表 ​

拖拽上传 ​

用户头像上传 ​

照片墙列表 ​

网盘文件选择 ​

上传前校验 ​

移除前校验 ​

限制上传数量 ​

自定义图标 ​

文件夹上传 ​

阿里 OSS 上传 ​

<upload> Props： ​

<upload> Events： ​

<upload> Methods： ​

<upload> Slots： ​

Upload 上传

引入

基本使用

已上传的文件列表

照片墙

图标列表

拖拽上传

用户头像上传

照片墙列表

网盘文件选择

上传前校验

移除前校验

限制上传数量

自定义图标

文件夹上传

阿里 OSS 上传

`<upload>` Props：

`<upload>` Events：

`<upload>` Methods：

`<upload>` Slots：