# Uploader 上傳
### 介紹
用於將本地的圖片或文件上傳至服務器。
### 安裝
``` ts
import { Uploader } from '@nutui/nutui-react';
```
### 基本用法
:::demo
``` tsx
import React, { useState } from "react";
import { Uploader } from '@nutui/nutui-react';
const App = () => {
const uploadUrl = 'https://my-json-server.typicode.com/linrufeng/demo/posts'
const onStart = () => {
console.log('start 觸發')
}
return (
<>
基本用法
)
}
export default App;
```
:::
### 上传状态
:::demo
``` tsx
import React, { useState } from "react";
import { Uploader } from '@nutui/nutui-react';
const App = () => {
const uploadUrl = 'https://my-json-server.typicode.com/linrufeng/demo/posts'
const defaultFileList: FileType[] = [
{
name: '檔1.png',
url: 'https://m.360buyimg.com/babel/jfs/t1/164410/22/25162/93384/616eac6cE6c711350/0cac53c1b82e1b05.gif',
status: 'success',
message: '上傳成功',
type: 'image',
uid: '123',
},
{
name: '檔2.png',
url: 'https://m.360buyimg.com/babel/jfs/t1/164410/22/25162/93384/616eac6cE6c711350/0cac53c1b82e1b05.gif',
status: 'error',
message: '上傳失敗',
type: 'image',
uid: '124',
},
{
name: '檔3.png',
url: 'https://m.360buyimg.com/babel/jfs/t1/164410/22/25162/93384/616eac6cE6c711350/0cac53c1b82e1b05.gif',
status: 'uploading',
message: '上傳中...',
type: 'image',
uid: '125',
},
]
const onDelete = (file: FileItem, fileList: FileItem[]) => {
console.log(translated.ca3903f3, file, fileList)
}
return (
<>
上傳狀態
)
}
export default App;
```
:::
### 自定義上傳樣式
:::demo
``` tsx
import React, { useState } from "react";
import { Uploader, Button } from '@nutui/nutui-react';
const App = () => {
const uploadUrl = 'https://my-json-server.typicode.com/linrufeng/demo/posts'
return (
<>
自定義上傳樣式
)
}
export default App;
```
:::
### 自定義上傳使用默認進度條
:::demo
``` tsx
import React, { useState } from "react";
import { Uploader, Button, Progress } from '@nutui/nutui-react';
const App = () => {
const uploadUrl = 'https://my-json-server.typicode.com/linrufeng/demo/posts'
const [progressPercent, setProgressPercent] = useState(0)
const onProgress = ({ event, options, percentage }: any) => {
setProgressPercent(percentage)
}
return (
<>
自定義上傳使用默認進度條
)
}
export default App;
```
:::
### 直接調起攝像頭（移動端生效）
:::demo
``` tsx
import React, { useState } from "react";
import { Uploader, Button } from '@nutui/nutui-react';
const App = () => {
const uploadUrl = 'https://my-json-server.typicode.com/linrufeng/demo/posts'
return (
<>
直接調起攝像頭（移動端生效）
)
}
export default App;
```
:::
### 限制上傳數量5個
:::demo
``` tsx
import React, { useState } from "react";
import { Uploader, Button } from '@nutui/nutui-react';
const App = () => {
const uploadUrl = 'https://my-json-server.typicode.com/linrufeng/demo/posts'
return (
<>
限制上傳數量5個
)
}
export default App;
```
:::
### 限制上傳大小（每個文件最大不超過 50kb）
:::demo
``` tsx
import React, { useState } from "react";
import { Uploader, Button } from '@nutui/nutui-react';
const App = () => {
const uploadUrl = 'https://my-json-server.typicode.com/linrufeng/demo/posts'
const onOversize = (files: File[]) => {
console.log('oversize 觸發 文件大小不能超過 50kb', files)
}
return (
<>
限制上傳大小（每個文件最大不超過 50kb）
)
}
export default App;
```
:::
### 自定義 FormData headers
:::demo
``` tsx
import React, { useState } from "react";
import { Uploader, Button } from '@nutui/nutui-react';
const App = () => {
const uploadUrl = 'https://my-json-server.typicode.com/linrufeng/demo/posts'
const formData = {
custom: 'test',
}
return (
<>
自定義 FormData headers
)
}
export default App;
```
:::
### 自定義 xhr 上傳方式(before-xhr-upload)
:::demo
``` tsx
import React, { useState } from "react";
import { Uploader, Button } from '@nutui/nutui-react';
const App = () => {
const uploadUrl = 'https://my-json-server.typicode.com/linrufeng/demo/posts'
const beforeXhrUpload = (xhr: XMLHttpRequest, options: any) => {
if (options.method.toLowerCase() == 'put') {
xhr.send(options.sourceFile);
} else {
xhr.send(options.formData);
}
};
return (
<>
自定義 xhr 上傳方式(before-xhr-upload)
)
}
export default App;
```
:::
### 手動上傳
:::demo
``` tsx
import React, { useState, useRef } from "react";
import { Uploader, Button } from '@nutui/nutui-react';
const App = () => {
const uploadUrl = 'https://my-json-server.typicode.com/linrufeng/demo/posts'
const uploadRef = useRef(null)
const submitUpload = () => {
uploadRef.current.submit()
}
return (
<>
手動上傳
)
}
export default App;
```
:::
### 禁用狀態
:::demo
``` tsx
import React, { useState } from "react";
import { Uploader, Button } from '@nutui/nutui-react';
const App = () => {
return (
<>
禁用狀態
)
}
export default App;
```
:::
### Prop
| 字段 | 說明 | 類型 | 默認值 |
|-------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------|------------------|
| autoUpload | 是否在選取文件後立即進行上傳，false 時需要手動執行 ref submit 方法進行上傳 | Boolean | true |
| name | `input` 標籤 `name` 的名稱，發到後台的文件參數名 | String | "file" |
| url | 上傳服務器的接口地址 | String | - |
| defaultFileList | 默認已經上傳的文件列表 | FileItem[] | [] |
| isPreview | 是否上傳成功後展示預覽圖 | Boolean | true |
| defaultImg | 當上傳非圖片('image')格式的默認圖片地址 | String | '' |
| isDeletable | 是否展示刪除按鈕 | Boolean | true |
| method | 上傳請求的 http method | String | "post" |
| listType | 上傳列表的內建樣式，支持兩種基本樣式 picture、list | String | "picture" |
| capture | 圖片[選取模式](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Element/input#htmlattrdefcapture)，直接調起攝像頭 | String | false |
| maximize | 可以設定最大上傳文件的大小（字節） | Number丨String | Number.MAX_VALUE |
| maximum | 文件上傳數量限制 | Number丨String | 1 |
| clearInput | 是否需要清空`input`內容，設為`true`支持重複選擇上傳同一個文件 | Boolean | false |
| accept | 允許上傳的文件類型，[詳細說明](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Element/Input/file#%E9%99%90%E5%88%B6%E5%85%81%E8%AE%B8%E7%9A%84%E6%96%87%E4%BB%B6%E7%B1%BB%E5%9E%8B) | String | * |
| headers | 設置上傳的請求頭部 | Object | {} |
| data | 附加上傳的信息 formData | Object | {} |
| uploadIcon | 上傳區域[圖標名稱](#/zh-CN/icon)或圖片鏈接 | String | "photograph" |
| uploadIconSize | 上傳區域[圖標尺寸](#/icon)大小，如 `20px` `2em` `2rem` | String or Number | - |
| xhrState | 接口響應的成功狀態（status）值 | Number | 200 |
| withCredentials | 支持發送 cookie 憑證信息 | Boolean | fasle |
| multiple | 是否支持文件多選 | Boolean | fasle |
| disabled | 是否禁用文件上傳 | Boolean | fasle |
| timeout | 超時時間，單位為毫秒 | Number丨String | 1000 * 30 |
| onBeforeUpload | 上傳前的函數需要返回一個`Promise`對象 | Function | null |
| onBeforeXhrUpload | 執行 XHR 上傳時，自定義方式 | Function(xhr，option) | null |
| onBeforeDelete | 除文件時的回調，返回值為 false 時不移除。支持返回一個 `Promise` 對象，`Promise` 對象 resolve(false) 或 reject 時不移除 | Function(file): boolean 丨Promise | - |
### FileItem
| 名稱 | 說明 | 默認值 |
|----------|---------------------------------------------------------|---------------------------------|
| status | 文件狀態值，可選'ready,uploading,success,error,removed' | "ready" |
| uid | 文件的唯一標識 | new Date().getTime().toString() |
| name | 文件名稱 | "" |
| url | 文件路徑 | "" |
| type | 文件類型 | "image/jpeg" |
| formData | 上傳所需的data | new FormData() |
### Event
| 名稱 | 說明 | 回調參數 |
|----------|------------------------|----------------------|
| onStart | 文件上傳開始 | options |
| onProgress | 文件上傳的進度 | event,options,percentage |
| onOversize | 文件大小超過限制時觸發 | files |
| onSuccess | 上傳成功 | responseText,options |
| onFailure | 上傳失敗 | responseText,options |
| onChange | 上傳文件改變時的狀態 | fileList,event |
| onRemove | 文件刪除之前的狀態 | files,fileList |
| onFileItemClick | 文件上傳成功後點擊觸發 | fileItem |