Wyg Plus Components

Appearance

Upload 上传 ​

⚠️ 版本警告

注意： 本文档适用于版本低于 2.x.x（不包括 2.0.0 和 1.0.0 版本）。如果您使用的是 2.0.0 或 1.0.0 或更高版本，请参考对应版本的最新文档。

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

引入 ​

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 开启照片墙列表上传。

上传前校验 ​

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-propsarco Upload 组件 PropsUploadProps-
file-list (v-model)文件列表FileItem[]-
show-remove-button是否显示删除按钮booleantrue
show-retry-button是否显示重试按钮booleantrue
show-preview-button是否显示预览按钮booleantrue
show-attachment-preview-button是否在照片墙列表中显示附件列表的预览按钮booleantrue
show-downLoad是否显示下载按钮booleantrue
show-upload-button是否显示上传按钮boolean | { showOnExceedLimit: boolean }true
tip提示文字string-
show-avatar-upload是否开启用户头像上传模式booleanfalse
is-picture-card-list是否开启照片墙列表booleanfalse
customIcon自定义图标WCustomIcon-
is-upload-to-ali-oss是否上传至阿里oss，默认不开启booleanfalse
is-multiple-upload是否开启分片上传，默认开启。如果为 false，始终使用 put 上传booleantrue
multipart-file-options分片配置，默认：{ parallel: 5, partSize: 1024 * 1024 * 5 }MultipartFileOptions-
file-max-size-limt文件最大大小限制，文件大小超过该限制将开启分片上传，默认 104857600 (100MB)FileLimit-
ali-oss-configOSS 客户端上传配置AliOssConfig-
ali-oss-sts-configSTS 临时授权配置AliOssSTSConfig-
is-oss-sign-upload是否使用 Sign 签名URL进行临时授权上传，需要配置 STSbooleanfalse
dir-path阿里云 OSS 中，指定上传的目录，除 Sign 上传外string-
is-oss-delete-file是否当上传完成并成功时，从 oss 上删除文件，默认 truebooleantrue
file-preview-propsfile preview 组件的 propsFilePreviewProps-
is-file-preview是否使用 file 文件数据进行预览（本地预览）booleanfalse
is-file-preview-url是否使用文件的 oss 网络地址进行预览，你可以配置 ali-oss-config 或 ali-oss-sts-config 或 signbooleanfalse
show-modal预览是否使用 Modal 模式预览，图片除外，默认 Modalboolean-
show-drawer预览是否使用抽屉 Drawer 模式预览，图片除外boolean-
typescript
interface Props {
    /** arco Upload 组件 Props */
    uploadProps?: UploadProps;
    /** 文件列表 */
    fileList?: FileItem[];
    /** 是否显示删除按钮 */
    showRemoveButton?: boolean;
    /** 是否显示重试按钮 */
    showRetryButton?: boolean;
    /** 是否显示预览按钮 */
    showPreviewButton?: boolean;
    /** 是否在照片墙列表中显示附件列表的预览按钮 */
    showAttachmentPreviewButton?: boolean;
    /** 是否显示下载按钮 */
    showDownLoad?: boolean;
    /** 是否显示上传按钮 */
    showUploadButton: boolean;
    /** 提示文字 */
    tip?: string;
    /** 是否开启用户头像上传模式 */
    showAvatarUpload?: boolean;
    /** 是否开启照片墙列表 */
    isPictureCardList?: boolean;
    /** 自定义图标 */
    customIcon?: WCustomIcon;
    /** 是否上传至阿里oss，默认不开启 */
    isUploadToAliOss?: boolean;
    /** 是否开启分片上传，默认开启。如果为 false，始终使用 put 上传 */
    isMultipleUpload?: boolean;
    /** 分片配置，默认：{ parallel: 5,partSize: 1024 * 1024 * 5 } */
    multipartFileOptions?: MultipartFileOptions;
    /** 文件最大大小限制，文件大小超过该限制将开启分片上传，默认 104857600 (100MB) */
    fileMaxSizeLimt?: FileLimit;
    /** OSS 客户端上传配置 */
    aliOssConfig?: AliOssConfig;
    /** STS 临时授权配置 */
    aliOssStsConfig?: AliOssSTSConfig;
    /** 是否使用 Sign 签名URL进行临时授权上传，需要配置 STS */
    isOssSignUpload?: boolean;
    /** 阿里云 OSS 中，指定上传的目录，除 Sign 上传外 */
    dirPath?: string;
    /** 是否当上传完成并成功时，从 oss 上删除文件，默认 true */
    isOssDeleteFile?: boolean;
    /** file preview 组件的 props */
    filePreviewProps?: FilePreviewProps;
    /** 是否使用 file 文件数据进行预览（本地预览）。默认使用 file 数据。内部以实现 */
    isFilePreview?: boolean;
    /** 是否使用文件的网络地址进行预览，内部以实现，你可以配置 aliOssConfig */
    isFilePreviewUrl?: boolean;
    /** 预览是否使用 Modal 模式预览，图片除外, 默认 Modal */
    showModal?: boolean;
    /** 预览是否使用抽屉 Drawer 模式预览，图片除外 */
    showDrawer?: boolean;
}

/** 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 {
    /** 重试图标 */
    retryIcon?: RenderFunction;
    /** 成功图标 */
    successIcon?: RenderFunction;
    /** 删除图标 */
    removeIcon?: RenderFunction;
    /** 预览图标 */
    previewIcon?: RenderFunction;
    /** 上传中图标 */
    uploading?: RenderFunction;
    /** 下载图标 */
    downLoad?: RenderFunction;
    /** 文件图标 */
    fileIcon?: (fileItem: FileItem) => VNode;
    /** 文件名 */
    fileName?: (fileItem: FileItem) => string;
}

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

/** 文件最大大小限制配置 */
export interface FileLimit {
    /** 文件最大大小限制 */
    fileMaxSizeLimt: number;
}

/** OSS 客户端上传配置 */
export interface AliOssConfig {
    /** 访问密钥 ID */
    accessKeyId: string;
    /** 访问密钥 Secret */
    accessKeySecret: string;
    /** 访问的默认存储桶 */
    bucket?: string | undefined;
    /** Bucket 数据区域位置，默认为 oss-cn-hangzhou */
    region?: string | undefined;
    /** 是否使用 HTTPS 连接 */
    secure?: boolean | undefined;
    /** 超时时间，默认为 60 秒 */
    timeout?: string | number | undefined;
}

/** 使用STS进行临时授权 */
export interface AliOssSTSConfig {
    /** 接口访问地址 */
    baseURL: string;
    /** token */
    token: string;
    /** 是否https上传 */
    isHttps: boolean;
    /** 获取签名信息接口参数 */
    params: IStsParams | null;
}

/** 获取 Sign 签名信息接口参数 */
export interface IStsParams {
    /** 文件存储路径 */
    path?: string;
    /** 超时时间，单位秒 */
    expireTime?: number | string;
    bucket?: string;
    region?: string;
    callbackUrl?: string;
    userAndTenantInfo?: string;
}

/** file preview 组件的 props, 除(fileConfig, showModal, showDrawer) */
export interface FilePreviewProps {
    /** arco Modal 组件 Props */
    modalProps?: ModalProps;
    /** arco Drawer 组件 Props */
    drawerProps?: DrawerProps;
    /** arco imagePreview 组件 Props */
    imagePreviewProps?: ImagePreviewProps;
    /** 文件预览配置，只能传入一个 file 或 url */
    // fileConfig?: {
    //   /** file 文件数据，内部通过 FileReader 读取该文件的 ArrayBuffer */
    //   file?: File;
    //   /** 文件的网络地址 */
    //   fileURL?: string;
    // };
    /** 是否使用 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;
}

<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

<upload> Methods： ​

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

<upload> Slots： ​

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

Released under the MIT License.

Copyright (c) 2024-PRESENT Wyg Plus contributors