# nie-rss

> NIE-RSS

Latest version **0.1.5** (published 2023-10-24) · MIT license · 0 weekly downloads

## Install

```sh
npm install nie-rss
pnpm add nie-rss
yarn add nie-rss
bun add nie-rss
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities.

Warnings: low downloads; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.1.5 |
| Published | 2023-10-24 |
| First published | 2023-09-14 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 4 |
| Unpacked size | 477.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | niejunhao |
| Maintainers | niejunhao |
| Keywords | NIE-RSS |

## Links

- npm: https://www.npmjs.com/package/nie-rss
- npm.io page: https://npm.io/package/nie-rss

## Dependencies (4)

- [vue](https://npm.io/package/vue.md) ^3.3.4
- [pica](https://npm.io/package/pica.md) ^9.0.1
- [spark-md5](https://npm.io/package/spark-md5.md) ^3.0.2
- [sortablejs](https://npm.io/package/sortablejs.md) ^1.15.0

## Recent versions

- 0.1.5 (latest) — 2023-10-24
- 0.1.4 — 2023-10-20
- 0.1.3 — 2023-10-18
- 0.1.2 — 2023-10-17
- 0.1.1 — 2023-10-17
- 0.1.0 — 2023-10-07
- 0.0.9 — 2023-10-07
- 0.0.8 — 2023-09-28
- 0.0.7 — 2023-09-28
- 0.0.6 — 2023-09-22
- 0.0.5 — 2023-09-21
- 0.0.4 — 2023-09-18
- 0.0.3 — 2023-09-15
- 0.0.2 — 2023-09-14

## 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){
        // 添加文件，必须返回一个true
        return Promise.resolve(true);
    }
    // 拒绝文件
    return Promise.reject('文件类型不符合');
}

</script>

<template>
    <div>
        <NieRss :file-add-before = "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/>

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

    返回值：void

<br/>

- **fileProcessing(fileId, sourceIndex)**  
    开始处理文件，例如文件编辑等操作  
    参数：
    - fileId 文件ID
    - sourceIndex 需要处理的文件sourceUpdates数组下标，如果需要处理原始文件传-1，默认-1

    返回值：void

<br/>


- **fileProcessed(fileId, file)**  
    文件处理完成
    参数：
    - fileId 文件ID
    - file 处理完成的文件

    返回值：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/>

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

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

---
_Source: https://npm.io/package/nie-rss · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._