NIE-RSS 文件上传组件

简介

• 拖拽选择
• 单文件上传
• 大文件分片上传
• 秒传
• 文件夹
• 并发上传限制
• 拖拽排序
• 文件编辑
• 列表视图
• 宫格视图

仓库

码云Gitee

基础

1. 安装

// 安装组件
npm install nie-rss

2. 导入

import NieRss from 'nie-rss';
import 'nie-rss/dist/style.css';

createApp(App).use(NieRss).mount('#app')

3. 使用

<script setup lang="ts">
import { ref } from 'vue';

const nieRss = ref();

// 配置
const options = {

    url: 'http://localhost:8091/rss/management',
    chunkUpload: true,
    singleFileParallelRequest: false
}

// 事件
const anyEvent = (event: any, ...args: any[]) => {
    console.log('anyEvent 1 >>> ', event, args);
}

// 文件添加事件
const fileAdded = (rssFile: RssFile) => {
    console.log('fileAdded 1 >>> ', rssFile);
}


// 调用组件方法
const getAllFiles = () => {
    const allFiles = nieRss.value.getAllFiles();
    console.log(allFiles);
}

const getFile = (fileId:string) => {
    const file = nieRss.value.getFile(fileId);
    console.log(file);
}

</script>

<template>
    <div>
        <Nie-Rss ref="nieRss" :options="options" @file-added="fileAdded" @anyEvent="anyEvent" />
        <button @click="getAllFiles">获取全部文件</button>
        <button @click="getFile('文件ID')">获取单个文件</button>
    </div>
</template>

配置

• url
  文件上传地址
  完整文件和分片上传文件都会使用这个地址

• chunkUpload
  是否开启分片上传
  默认：false

• initAtSplitFile
  添加文件时就切分分片
  如果为false，则会在文件上传开始之前切分分片
  默认：false

• chunkSize 文件分片大小
  单位：字节
  默认：2MB

• singleFileParallelRequest
  单个文件是否开启并发上传
  当为false时，同一时间只会上传文件的一个分片
  默认：true

• parallelFileUploadNumber
  同时上传的文件数量
  默认：3

• autoUpload
  添加文件之后立即执行上传
  默认：false

• parallelRequestNumber
  当前组件实例并发请求数量
  singleFileParallelRequest 为 true 时有效
  默认：10

• timeout
  请求超时时间
  单位：毫秒
  默认：60000

• retryRequestNumber
  重试请求次数
  默认：6

• fileAddBefore
  文件添加之前钩子
  参数：rssFile: 即将添加的文件信息
  返回一个Promise对象，如果返回reject将不会添加文件

<script lang="js" setup>

const fileAddBefore = (rssFile) => {
    // 是否添加文件
    const addFile = rssFile.extension === 'png';
    if(addFile){
        // 添加文件，必须返回一个true
        return Promise.resolve(true);
    }
    // 拒绝文件
    return Promise.reject('文件类型不符合');
}

</script>

<template>
    <div>
        <NieRss :file-add-before = "fileAddBefore"></NieRss>
    </div>
</template>

方法

• upload(fileId)
  上传单个文件
  参数：
  • fileId 文件ID
  返回值：void

• uploadAll
  上传所有文件
  返回值：void

• pause(fileId)
  暂停单个文件上传
  参数：

  • fileId 文件ID

  返回值：void

• pauseAll()
  暂停所有文件上传
  返回值：void

• getFile(fileId)
  获取单个文件
  参数：
  • fileId 文件ID
  返回值：RssFile | null | undefined

• getAllFiles()
  获取所有文件
  返回值：RssFile[]

• addFile(file)
  添加文件
  参数：

  • file 需要添加的文件 JS File对象

  返回值：void

• addFiles(files)
  批量添加文件
  参数：

  • files 要添加的文件列表 JS File对象数组

  返回值：void

• removeFile(fileId)
  删除文件
  参数：

  • fileId 文件ID

  返回值：void

• clearFiles()
  清空文件
  返回值：void

• useFileProcessPlugin(plugin)
  添加文件处理插件
  参数：

  • plugin 插件

  返回值：void

• fileProcessing(fileId, sourceIndex)
  开始处理文件，例如文件编辑等操作
  参数：

  • fileId 文件ID
  • sourceIndex 需要处理的文件sourceUpdates数组下标，如果需要处理原始文件传-1，默认-1

  返回值：void

• fileProcessed(fileId, file)
  文件处理完成 参数：

  • fileId 文件ID
  • file 处理完成的文件

  返回值：void

• on(event, callback)
  注册监听事件
  参数：

  • event 事件名称
  • callback：事件回调函数

  返回值：void

<script lang="js" setup>
import { ref, onMounted } from 'vue';

const nieRss = ref();

const callback = (rssFile) => {
    // 文件添加事件
    const filename = rssFile.filename;
}

onMounted(() => {

    nieRss.value.on('fileAdded', callback);

})

</script>

<template>
    <div>
        <NieRss ref="nieRss"></NieRss>
    </div>
</template>

• off(event, callback)
  移除监听事件
  注意这里的callback必须是注册时的callback函数
  参数：

  • event 事件名称
  • callback：事件回调函数

  返回值：void

<script lang="js" setup>
import { ref, onMounted } from 'vue';

const nieRss = ref();

const callback = (rssFile) => {
    // 文件添加事件
    const filename = rssFile.filename;
}

onMounted(() => {

    nieRss.value.on('fileAdded', callback);

    setTimeout(() => {
        nieRss.value.off('fileAdded', callback);
    }, 3000);

})

</script>

<template>
    <div>
        <NieRss ref="nieRss"></NieRss>
    </div>
</template>

• once(event, callback)
  监听事件
  和 on 注册作用相同，不同点在于once只会执行一次，执行一次后会自动移除监听 参数：

  • event 事件名称
  • callback：事件回调函数

  返回值：void

• emit(event, ...args)
  触发事件
  一般情况下，组件中的事件不需要我们触发，在组件内部会自动触发， 提供这个方法是为了方便我们注册和监听自定义的事件
  参数：

  • event 事件名称
  • args 发送给回调函数的参数

  返回值：void

<script lang="js" setup>
import { ref, onMounted } from 'vue';

const nieRss = ref();


onMounted(() => {

    setTimeout(() => {
        // 当调用了emit方法后，所有通过on或者once注册的监听回调都会被执行
        // 回调函数中的参数就是此处发送的参数
        const rssFile = 需要发给送的参数;
        nieRss.value.emit('fileAdded', rssFile);

    }, 3000);

})

</script>

<template>
    <div>
        <NieRss ref="nieRss"></NieRss>
    </div>
</template>

事件

• fileAdded: (rssFile) => void;
  文件添加成功事件
  参数：
  • rssFile 添加成功的文件信息

• filesAdded: (rssFiles) => void;
  批量添加文件成功事件
  参数：
  • rssFiles 批量添加成功的文件信息列表

• fileRemove: (rssFileId) => void;
  文件删除事件
  参数：
  • rssFileId 文件ID

• fileEmptyed: () => void;
  文件清空事件

• progress: (rssFile, progress) => void;
  文件上传进度更新事件
  参数：
  • rssFile 正在上传的文件
  • progress 进度

• complete: (rssFile) => void;
  文件上传完成事件
  参数：
  • rssFile 上传完成的文件信息

• statusChange: (rssFile, rssFileStatus) => void;
  文件状态变更事件
  参数：
  • rssFile 文件信息
  • rssFileStatus 变更后的状态

• failed: (rssFile: RssFile) => void;
  文件上传失败
  参数：
  • rssFile 文件信息

• anyEvent: (event, ...args) => void; 任意事件
  任何一个事件触发的同时也会触发这个事件
  参数：
  • event 事件名称
  • args 参数

• sorted: (oldRssFiles: RssFile[], newRssFiles: RssFile[]) => void; 排序完成事件 参数：
  • oldRssFiles 排序前的列表
  • newRssFiles 排序后的列表

RssFile

属性

| 属性名称 | 属性类型 | 属性描述 | | :------------ | :------------- | :------------------------------------------------------- | | id | string | 文件ID，当前Rss实例中唯一ID | | filename | number | 文件名称 | | fileSize | string | 文件大小 单位：字节 | | source | NativeFile | 源文件信息，JS中的File\Blob对象 | | extension | string | 文件扩展名，例如，filename = abc.png, 则 extension = png | | identity | string | 文件指纹，文件唯一标识 | | status | RssFileStatus | 文件状态 | | progress | number | 文件上传进度 | | sourceUpdates | NativeFile[] | 源文件更新记录，比如多次文件编辑 | | chunkFiles | RssChunkFile[] | 文件分片信息度 | | response | any | 文件上传完成后服务器返回的信息 | | |

方法

• upload()
  上传当前文件 返回值：void

• pause()
  暂停当前文件上传 返回值：void

• setProgress(progress)
  设置当前文件上传进度， 会触发进度更新事件 参数：

  • progress 进度百分比 1-100

  返回值：void

• setStatus(rssFileStatus)
  修改文件状态，会触发文件状态变更事件
  参数：

  • rssFileStatus 文件上传状态值

  状态值说明： | 状态值 | 状态值描述 | | :-------- | :----------------------------------------------------------- | | INIT | 文件初始化成功，在添加文件后还未操作文件时 | | AWAIT | 当文件上传数量超出最大上传数量时，文件在文件上传池中等待上传 | | UPLOADING | 文件正在上传中 | | PAUSE | 文件上传被暂停时 | | COMPLETE | 文件上传成功 | | FAILED | 文件上传失败 |

  返回值：void

• getRssOptions()
  获取整个Rss实例配置 返回值：Rss实例配置信息