Semi Design 上传组件(Upload)深度解析与实战指南-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00725/article/details/148419138

Semi Design 上传组件(Upload)深度解析与实战指南

semi-design 🚀A modern, comprehensive, flexible design system and React UI library. 🎨 Provide more than 2800+ Design Tokens, easy to build your design system. Make Semi Design to Any Design. 🧑🏻‍💻 Design to Code in one click 项目地址: https://gitcode.com/gh_mirrors/se/semi-design

组件概述

Semi Design 的 Upload 上传组件是一个功能强大的文件上传解决方案，它提供了丰富的功能和灵活的配置选项，能够满足各种文件上传场景的需求。该组件支持单文件上传、多文件上传、文件夹上传等多种模式，并提供了文件类型限制、大小限制、数量限制等实用功能。

基础使用

基本用法

最简单的上传组件使用方式是在 Upload 组件内部放置一个触发元素（通常是 Button），点击后会激活文件选择框：

import { Upload, Button } from '@douyinfe/semi-ui';
import { IconUpload } from '@douyinfe/semi-icons';

function BasicUpload() {
    return (
        <Upload action="https://api.semi.design/upload">
            <Button icon={<IconUpload />} theme="light">
                点击上传
            </Button>
        </Upload>
    );
}

自定义上传属性

上传时可以通过 data 和 headers 属性添加额外的请求参数和请求头：

function CustomUpload() {
    const data = {
        role: 'ies',
        time: new Date().getTime(),
    };
    const headers = {
        'x-tt-semi': 'semi-upload',
    };
    
    return (
        <Upload 
            action="https://api.semi.design/upload" 
            data={data} 
            headers={headers}
        >
            <Button icon={<IconUpload />} theme="light">
                点击上传
            </Button>
        </Upload>
    );
}

高级功能

文件类型限制

通过 accept 属性可以限制上传的文件类型，支持文件后缀名或 MIME 类型：

function TypeLimitUpload() {
    return (
        <>
            <Upload action="..." accept="image/*">
                <Button>上传图片</Button>
            </Upload>
            <Upload action="..." accept="video/*">
                <Button>上传视频</Button>
            </Upload>
            <Upload action="..." accept=".pdf,.png,.jpeg">
                <Button>上传PDF/PNG/JPEG</Button>
            </Upload>
        </>
    );
}

文件大小限制

通过 maxSize 和 minSize 可以限制上传文件的大小（单位为KB），并可通过 onSizeError 处理大小不符合要求的文件：

function SizeLimitUpload() {
    return (
        <Upload
            action="..."
            maxSize={1024}
            minSize={200}
            onSizeError={(file) => Toast.error(`${file.name} 大小不符合要求`)}
        >
            <Button>点击上传(200KB-1MB)</Button>
        </Upload>
    );
}

文件数量限制

通过 limit 属性可以限制上传文件的数量，当达到限制时会触发 onExceed 回调：

function CountLimitUpload() {
    return (
        <Upload
            action="..."
            limit={3}
            onExceed={() => Toast.warning('最多上传3个文件')}
        >
            <Button>点击上传(最多3个)</Button>
        </Upload>
    );
}

特殊场景应用

头像上传

Upload 组件非常适合头像上传场景，可以结合 Avatar 组件实现美观的头像上传功能：

function AvatarUpload() {
    const [url, setUrl] = useState(defaultAvatarUrl);
    const onSuccess = () => {
        Toast.success('头像更新成功');
        setUrl(newAvatarUrl);
    };

    return (
        <Upload
            action="..."
            onSuccess={onSuccess}
            accept="image/*"
            showUploadList={false}
        >
            <Avatar src={url} hoverMask={<CameraIcon />} />
        </Upload>
    );
}

文件夹上传

通过设置 directory 属性可以实现整个文件夹的上传：

function DirectoryUpload() {
    return (
        <Upload action="..." directory>
            <Button>上传文件夹</Button>
        </Upload>
    );
}

自定义与扩展

自定义文件列表操作

可以通过 renderFileOperation 自定义文件列表的操作区域：

function CustomOperationUpload() {
    const renderFileOperation = (fileItem) => (
        <div style={{ display: 'flex', gap: 8 }}>
            <Button icon={<EyeIcon />} size="small" />
            <Button icon={<DownloadIcon />} size="small" />
            <Button icon={<DeleteIcon />} size="small" onClick={fileItem.onRemove} />
        </div>
    );
    
    return (
        <Upload action="..." renderFileOperation={renderFileOperation}>
            <Button>点击上传</Button>
        </Upload>
    );
}

自定义预览逻辑

通过 previewFile 可以自定义文件的预览方式：

function CustomPreviewUpload() {
    const previewFile = (file) => {
        if (file.type === 'application/pdf') {
            return <PdfIcon />;
        }
        return <Image src={file.url} />;
    };
    
    return (
        <Upload action="..." previewFile={previewFile}>
            <Button>点击上传</Button>
        </Upload>
    );
}