# nie-rss

**Repository Path**: niejunhao/nie-rss

## Basic Information

- **Project Name**: nie-rss
- **Description**: Vue3.x 大文件上传组件
- **Primary Language**: TypeScript
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 7
- **Forks**: 0
- **Created**: 2023-09-22
- **Last Updated**: 2023-10-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: 大文件上传组件, 分片上传, 秒传

## README

# `NIE-RSS` 文件上传组件

## 简介

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

## 仓库

[码云Gitee](https://gitee.com/niejunhao/nie-rss.git "码云仓库") 

## 基础

1. ### 安装
``` js
// 安装组件
npm install nie-rss
```

2. ### 导入

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

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

```

3. ### 使用
``` html
<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**  
    文件上传地址  
    完整文件和分片上传文件都会使用这个地址  

<br/>

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

<br/>

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

<br/>

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

<br/>

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

<br/>

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

<br/>

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

<br/>

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

<br/>

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

<br/>

- **retryRequestNumber**  
    重试请求次数  
    默认：6

<br/>

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

``` js

<script lang="js" setup>

const fileAddBefore = (rssFile) => {
    // 是否添加文件
    const addFile = rssFile.extension === 'png';
    if(addFile){
        // 添加文件
        return Promise.resolve();
    }
    // 拒绝文件
    return Promise.reject();
}

</script>

<template>
    <div>
        <NieRss :fileAddBefore = "fileAddBefore"></NieRss>
    </div>
</template>

```


<br/>

## 方法

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

<br/>

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

<br/>

- **pause(fileId)**  
    暂停单个文件上传  
    参数： 
    - fileId 文件ID   

    返回值：void

<br/>

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

<br/>

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

<br/>

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

<br/>


- **addFile(file)**  
    添加文件  
    参数： 
    - file 需要添加的文件 JS File对象  

    返回值：void

<br/>

- **addFiles(files)**  
    批量添加文件  
    参数：
    - files 要添加的文件列表 JS File对象数组  

    返回值：void

<br/>

- **removeFile(fileId)**  
    删除文件  
    参数：
    - fileId 文件ID

    返回值：void

<br/>

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

<br/>

- **on(event, callback)**  
    注册监听事件  
    参数：
    - event 事件名称  
    - callback：事件回调函数  

    返回值：void

``` js

<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>

```

<br/>


- **off(event, callback)**  
    移除监听事件  
    注意这里的callback必须是注册时的callback函数  
    参数：
    - event 事件名称  
    - callback：事件回调函数  

    返回值：void


``` js

<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>

```

<br/>


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

    返回值：void

<br/>

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

    返回值：void

<br/>

``` js

<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>

```

<br/>

## 事件

<br/>

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

<br/>

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

<br/>

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

<br/>


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

<br/>


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

<br/>

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

<br/>

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

<br/>

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

<br/>

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

## 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            | 文件上传完成后服务器返回的信息                           |
|               |

> ### 方法

<br/>

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

<br/>

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

<br/>

- **setProgress(progress)**  
    设置当前文件上传进度， 会触发进度更新事件
    参数：
    - progress 进度百分比 1-100

    返回值：void

<br/>

- **setStatus(rssFileStatus)**  
    修改文件状态，会触发文件状态变更事件  
    参数：
    - rssFileStatus 文件上传状态值  

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

    返回值：void

<br/>

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

<br/>