Translation in progress
This page hasn't been translated into English yet, so the content below is in Chinese. The code examples work the same way.
Upload 上传
点击或拖拽选择文件,上传到服务器,并显示文件列表和上传进度。
引入
import { NsUpload } from '@ns/ui'
基础用法
action 是上传地址。选中文件后立即用 POST 上传,文件字段名是 name(默认 file)。真实项目里写成 <NsUpload action="/api/upload" /> 就行,完整的写法见最后的“对接真实接口”。
页面上没有真实的上传接口,所以这里的示例都传了 http-request,用定时器模拟上传:进度每 200 毫秒加 20%,到 100% 算上传成功,文件不会发出去。
<script setup lang="ts">
import { NsUpload } from '@ns/ui'
import type { UploadHttpRequest } from '@ns/ui'
// 用定时器模拟上传,不发真实请求
const mockUpload: UploadHttpRequest = ({ onProgress, onSuccess }) => {
let percent = 0
const timer = setInterval(() => {
percent += 20
onProgress({ percent })
if (percent === 100) {
clearInterval(timer)
onSuccess({ code: 0 })
}
}, 200)
return { abort: () => clearInterval(timer) }
}
</script>
<template>
<NsUpload :http-request="mockUpload" />
</template>
不传 file-list 时组件自己维护文件列表。
受控的文件列表
用 v-model:file-list 绑定列表,可以回显已有文件,也能拿到每个文件的状态(ready、uploading、success、error)。下面列出了绑定值里每个文件的状态和进度,选几个文件看它们的变化:
<script setup lang="ts">
import { ref } from 'vue'
import { NsUpload } from '@ns/ui'
import type { UploadFile, UploadHttpRequest } from '@ns/ui'
const fileList = ref<UploadFile[]>([
{ uid: 1, name: 'report.pdf', status: 'success', url: '/files/report.pdf' }
])
// 用定时器模拟上传,不发真实请求
const mockUpload: UploadHttpRequest = ({ onProgress, onSuccess }) => {
let percent = 0
const timer = setInterval(() => {
percent += 20
onProgress({ percent })
if (percent === 100) {
clearInterval(timer)
onSuccess({ code: 0 })
}
}, 200)
return { abort: () => clearInterval(timer) }
}
</script>
<template>
<NsUpload v-model:file-list="fileList" :http-request="mockUpload" multiple />
<div class="file-state">
<div v-for="file in fileList" :key="file.uid">
{{ file.name }}:{{ file.status
}}{{ file.status === 'uploading' ? ` ${file.progress}%` : '' }}
</div>
</div>
</template>
<style scoped>
.file-state {
margin-top: 12px;
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
line-height: 1.8;
}
</style>
拖拽上传
drag 开启后显示拖拽区,默认是上传图标加“将文件拖到此处,或点击上传”。拖进来的文件和点击选择的文件一样按 accept、max-size 检查,没开 multiple 时只取第一个合格的文件。拖拽区可以用 Tab 聚焦,按回车或空格打开文件选择。
<script setup lang="ts">
import { NsUpload } from '@ns/ui'
import type { UploadHttpRequest } from '@ns/ui'
// 用定时器模拟上传,不发真实请求
const mockUpload: UploadHttpRequest = ({ onProgress, onSuccess }) => {
let percent = 0
const timer = setInterval(() => {
percent += 20
onProgress({ percent })
if (percent === 100) {
clearInterval(timer)
onSuccess({ code: 0 })
}
}, 200)
return { abort: () => clearInterval(timer) }
}
</script>
<template>
<NsUpload :http-request="mockUpload" drag accept="image/*" />
</template>
trigger 插槽替换拖拽区里的图标和文字,默认插槽的内容显示在文件列表后面,适合放提示:
<script setup lang="ts">
import { NsIcon, NsUpload } from '@ns/ui'
import type { UploadHttpRequest } from '@ns/ui'
// 用定时器模拟上传,不发真实请求
const mockUpload: UploadHttpRequest = ({ onProgress, onSuccess }) => {
let percent = 0
const timer = setInterval(() => {
percent += 20
onProgress({ percent })
if (percent === 100) {
clearInterval(timer)
onSuccess({ code: 0 })
}
}, 200)
return { abort: () => clearInterval(timer) }
}
</script>
<template>
<NsUpload :http-request="mockUpload" drag multiple>
<template #trigger>
<NsIcon name="folder" size="lg" />
<div>把合同扫描件拖到这里,可以一次拖多个</div>
</template>
<p class="tip">支持 pdf、jpg、png,单个文件不超过 10MB</p>
</NsUpload>
</template>
<style scoped>
.tip {
margin-top: 8px;
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
</style>
限制文件类型、数量和大小
accept和原生 input 的写法一样:扩展名要带点(.jpg,.png,不分大小写),或者写 MIME(image/*、application/pdf),逗号分隔。原生的accept只是选择框里默认的筛选,用户切到“所有文件”就能选别的格式,所以组件会再检查一遍,点击选择和拖拽进来的文件都查。max-size是单个文件的大小上限,单位是字节,例如 5MB 写5 * 1024 * 1024。- 类型不符或者超过大小的文件不加入列表、不上传,每个文件触发一次
reject,第二个参数是原因:'type'或'size'。组件自己不弹提示,在reject里按需提示。 limit限制文件总数,超出时整批都不加入,并触发exceed。被拒收的文件不算在里面。
<script setup lang="ts">
import { NsMessage, NsUpload } from '@ns/ui'
import type { UploadHttpRequest, UploadRejectReason } from '@ns/ui'
const maxSize = 5 * 1024 * 1024
const onReject = (file: File, reason: UploadRejectReason) => {
if (reason === 'type') NsMessage.warning(`${file.name} 的格式不对,只能上传 jpg、png`)
else NsMessage.warning(`${file.name} 超过 5MB`)
}
const onExceed = () => NsMessage.warning('最多上传 3 个文件')
// 用定时器模拟上传,不发真实请求
const mockUpload: UploadHttpRequest = ({ onProgress, onSuccess }) => {
let percent = 0
const timer = setInterval(() => {
percent += 20
onProgress({ percent })
if (percent === 100) {
clearInterval(timer)
onSuccess({ code: 0 })
}
}, 200)
return { abort: () => clearInterval(timer) }
}
</script>
<template>
<NsUpload
:http-request="mockUpload"
accept=".jpg,.png"
:max-size="maxSize"
:limit="3"
multiple
@reject="onReject"
@exceed="onExceed"
>
<p>只能上传 jpg、png,单个不超过 5MB,最多 3 个</p>
</NsUpload>
</template>
选中的文件按这个顺序检查:类型(accept)→ 大小(max-size)→ 数量(limit)→ before-upload。一个文件类型和大小都不对时只触发一次 reject,原因是 'type'。
更复杂的检查(例如图片的宽高)放在 before-upload 里,返回 false 时跳过这个文件。before-upload 也可以返回 Promise:resolve 为 false 或 reject 时跳过这个文件,resolve 为 File 时上传返回的文件(例如压缩后的图片),其余文件照常处理。
下面的 before-upload 跳过文件名里有空格的文件;其余文件先“检查” 300 毫秒,再换成文件名前面加了“已检查-”的新文件上传:
<script setup lang="ts">
import { NsMessage, NsUpload } from '@ns/ui'
import type { UploadHttpRequest } from '@ns/ui'
const beforeUpload = async (file: File) => {
if (/\s/.test(file.name)) {
NsMessage.warning(`${file.name} 的文件名里有空格,跳过`)
return false
}
// 模拟异步检查(例如读取图片宽高),300 毫秒后通过
await new Promise((resolve) => setTimeout(resolve, 300))
// 返回新的 File:上传、显示的都是它
return new File([file], `已检查-${file.name}`, { type: file.type })
}
// 用定时器模拟上传,不发真实请求
const mockUpload: UploadHttpRequest = ({ onProgress, onSuccess }) => {
let percent = 0
const timer = setInterval(() => {
percent += 20
onProgress({ percent })
if (percent === 100) {
clearInterval(timer)
onSuccess({ code: 0 })
}
}, 200)
return { abort: () => clearInterval(timer) }
}
</script>
<template>
<NsUpload :http-request="mockUpload" :before-upload="beforeUpload" multiple />
</template>
手动上传
auto-upload 设为 false 时只加入列表,调用 submit() 才上传。abort() 取消正在上传的文件,它们回到 ready,可以再次 submit();clearFiles() 清空列表,传状态数组时只清掉这些状态的文件。
这个示例的模拟上传放慢到 5 秒,来得及点“取消上传”:
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsSpace, NsUpload } from '@ns/ui'
import type { UploadHttpRequest, UploadInstance } from '@ns/ui'
const uploadRef = ref<UploadInstance>()
// 用定时器模拟上传:每 500 毫秒进度加 10%,不发真实请求
const mockUpload: UploadHttpRequest = ({ onProgress, onSuccess }) => {
let percent = 0
const timer = setInterval(() => {
percent += 10
onProgress({ percent })
if (percent === 100) {
clearInterval(timer)
onSuccess({ code: 0 })
}
}, 500)
return { abort: () => clearInterval(timer) }
}
</script>
<template>
<NsUpload ref="uploadRef" :http-request="mockUpload" :auto-upload="false" multiple />
<div style="margin-top: 12px">
<NsSpace wrap>
<NsButton type="primary" @click="uploadRef?.submit()">开始上传</NsButton>
<NsButton @click="uploadRef?.abort()">取消上传</NsButton>
<NsButton @click="uploadRef?.clearFiles(['success'])">清掉已上传的</NsButton>
<NsButton @click="uploadRef?.clearFiles()">清空</NsButton>
</NsSpace>
</div>
</template>
自定义上传请求
http-request 替换默认的 XHR 上传。可以返回 Promise(完成即成功、reject 即失败),也可以返回带 abort 方法的对象,自己调用参数里的 onProgress、onSuccess、onError。
import type { UploadHttpRequest } from '@ns/ui'
// 返回 Promise
const httpRequest: UploadHttpRequest = ({ file }) => api.upload(file)
// 返回 { abort },可以汇报进度
const httpRequestWithProgress: UploadHttpRequest = ({ file, onProgress, onSuccess, onError }) => {
const controller = new AbortController()
api
.upload(file, { signal: controller.signal, onProgress: (percent) => onProgress({ percent }) })
.then(onSuccess, onError)
return { abort: () => controller.abort() }
}
两种写法都可以直接试。左边返回 Promise,1 秒后完成,没有进度;右边返回 { abort },汇报进度,勾选“模拟失败”后传到 60% 时调用 onError,文件变成失败状态并触发 error 事件:
<script setup lang="ts">
import { ref } from 'vue'
import { NsCheckbox, NsMessage, NsSpace, NsUpload } from '@ns/ui'
import type { UploadFile, UploadHttpRequest } from '@ns/ui'
const shouldFail = ref(false)
// 返回 Promise:resolve 的值就是 success 事件里的 response
const promiseUpload: UploadHttpRequest = ({ file }) =>
new Promise((resolve) => setTimeout(() => resolve({ name: file.name }), 1000))
// 返回 { abort }:自己汇报进度、成功和失败
const progressUpload: UploadHttpRequest = ({ onProgress, onSuccess, onError }) => {
let percent = 0
const timer = setInterval(() => {
percent += 20
if (shouldFail.value && percent === 60) {
clearInterval(timer)
onError(new Error('网络中断,上传失败'))
return
}
onProgress({ percent })
if (percent === 100) {
clearInterval(timer)
onSuccess({ code: 0 })
}
}, 300)
return { abort: () => clearInterval(timer) }
}
const onError = (error: Error, file: UploadFile) => {
NsMessage.error(`${file.name}:${error.message}`)
}
</script>
<template>
<NsSpace wrap align="start" size="large">
<NsUpload :http-request="promiseUpload">
<p>返回 Promise</p>
</NsUpload>
<NsUpload :http-request="progressUpload" @error="onError">
<NsCheckbox v-model="shouldFail">模拟失败</NsCheckbox>
</NsUpload>
</NsSpace>
</template>
http-request 的参数里还有 action、name、headers、data、withCredentials,就是组件上对应属性的值,自己发请求时按需使用。下面的模拟上传把收到的参数显示出来:
<script setup lang="ts">
import { ref } from 'vue'
import { NsUpload } from '@ns/ui'
import type { UploadHttpRequest, UploadRequestOptions } from '@ns/ui'
const received = ref('')
const mockUpload: UploadHttpRequest = (options: UploadRequestOptions) => {
const { file, action, name, headers, data, withCredentials } = options
received.value = JSON.stringify(
{ file: file.name, action, name, headers, data, withCredentials },
null,
2
)
return new Promise((resolve) => setTimeout(resolve, 500))
}
</script>
<template>
<NsUpload
action="/api/attachments"
name="attachment"
:headers="{ 'X-Tenant': 'demo' }"
:data="{ bizType: 'contract', bizId: 42 }"
with-credentials
:http-request="mockUpload"
/>
<pre class="received">{{ received || '选一个文件,这里显示 http-request 收到的参数' }}</pre>
</template>
<style scoped>
.received {
margin-top: 12px;
padding: var(--ns-spacing-3);
border-radius: var(--ns-border-radius);
background-color: var(--ns-fill-color-light);
color: var(--ns-text-color-secondary);
font-family: var(--ns-font-family-mono);
font-size: var(--ns-font-size-sm);
white-space: pre-wrap;
}
</style>
图片列表和照片墙
list-type 为 picture 时每个文件带一张缩略图,picture-card 时显示成 148px 的卡片。图片文件没有 url 时用本地文件生成预览。
照片墙模式的上传入口是排在卡片后面、同样 148px 的虚线“+”方块(没有文件时也显示),不再是“点击上传”按钮。trigger 插槽的内容会放进这个方块里,替换“+”图标。同时开了 drag 时还是拖拽区。
<script setup lang="ts">
import { NsUpload } from '@ns/ui'
import type { UploadHttpRequest } from '@ns/ui'
// 用定时器模拟上传,不发真实请求
const mockUpload: UploadHttpRequest = ({ onProgress, onSuccess }) => {
let percent = 0
const timer = setInterval(() => {
percent += 20
onProgress({ percent })
if (percent === 100) {
clearInterval(timer)
onSuccess({ code: 0 })
}
}, 200)
return { abort: () => clearInterval(timer) }
}
</script>
<template>
<NsUpload :http-request="mockUpload" list-type="picture-card" accept="image/*" />
</template>
三种 list-type 放在一起对比,每种都回显了两个已有的图片,可以再选几张看上传中的样子(文字列表显示百分比,另外两种显示进度条):
<script setup lang="ts">
import { ref } from 'vue'
import { NsSpace, NsUpload } from '@ns/ui'
import type { UploadFile, UploadHttpRequest } from '@ns/ui'
const createList = (): UploadFile[] => [
{ uid: 1, name: 'cat.jpg', status: 'success', url: '/images/cat.jpg' },
{ uid: 2, name: 'cover.png', status: 'success', url: '/images/cover.png' }
]
const textList = ref(createList())
const pictureList = ref(createList())
const cardList = ref(createList())
// 用定时器模拟上传,不发真实请求
const mockUpload: UploadHttpRequest = ({ onProgress, onSuccess }) => {
let percent = 0
const timer = setInterval(() => {
percent += 20
onProgress({ percent })
if (percent === 100) {
clearInterval(timer)
onSuccess({ code: 0 })
}
}, 300)
return { abort: () => clearInterval(timer) }
}
</script>
<template>
<NsSpace direction="vertical" fill size="large">
<div>
<div class="row-label">text(默认)</div>
<NsUpload v-model:file-list="textList" :http-request="mockUpload" accept="image/*" multiple />
</div>
<div>
<div class="row-label">picture</div>
<NsUpload
v-model:file-list="pictureList"
:http-request="mockUpload"
list-type="picture"
accept="image/*"
multiple
/>
</div>
<div>
<div class="row-label">picture-card</div>
<NsUpload
v-model:file-list="cardList"
:http-request="mockUpload"
list-type="picture-card"
accept="image/*"
multiple
/>
</div>
</NsSpace>
</template>
<style scoped>
.row-label {
margin-bottom: 8px;
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
</style>
照片墙的 trigger 插槽替换“+”图标;照片墙同时开了 drag 时,入口变成拖拽区:
<script setup lang="ts">
import { NsIcon, NsSpace, NsUpload } from '@ns/ui'
import type { UploadHttpRequest } from '@ns/ui'
// 用定时器模拟上传,不发真实请求
const mockUpload: UploadHttpRequest = ({ onProgress, onSuccess }) => {
let percent = 0
const timer = setInterval(() => {
percent += 20
onProgress({ percent })
if (percent === 100) {
clearInterval(timer)
onSuccess({ code: 0 })
}
}, 200)
return { abort: () => clearInterval(timer) }
}
</script>
<template>
<NsSpace direction="vertical" fill size="large">
<NsUpload :http-request="mockUpload" list-type="picture-card" accept="image/*" multiple>
<template #trigger>
<div class="card-trigger">
<NsIcon name="image" size="lg" />
<span>上传照片</span>
</div>
</template>
</NsUpload>
<NsUpload :http-request="mockUpload" list-type="picture-card" accept="image/*" drag multiple />
</NsSpace>
</template>
<style scoped>
.card-trigger {
display: flex;
flex-direction: column;
align-items: center;
gap: var(--ns-spacing-2);
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
</style>
单张图片
头像这类只能有一张图的场景:limit 设成 1,有图以后用 CSS 把“+”方块藏起来(组件不会自动隐藏),删掉图片后又会出现。
<script setup lang="ts">
import { ref } from 'vue'
import { NsUpload } from '@ns/ui'
import type { UploadFile, UploadHttpRequest } from '@ns/ui'
const fileList = ref<UploadFile[]>([
{ uid: 1, name: 'avatar.jpg', status: 'success', url: '/images/avatar.jpg' }
])
// 用定时器模拟上传,不发真实请求
const mockUpload: UploadHttpRequest = ({ onProgress, onSuccess }) => {
let percent = 0
const timer = setInterval(() => {
percent += 20
onProgress({ percent })
if (percent === 100) {
clearInterval(timer)
onSuccess({ code: 0 })
}
}, 200)
return { abort: () => clearInterval(timer) }
}
</script>
<template>
<NsUpload
v-model:file-list="fileList"
:class="{ 'avatar-upload--full': fileList.length >= 1 }"
:http-request="mockUpload"
:limit="1"
list-type="picture-card"
accept="image/*"
/>
</template>
<style scoped>
.avatar-upload--full :deep(.ns-upload__trigger--picture-card) {
display: none;
}
</style>
自定义触发按钮
trigger 插槽替换默认的“点击上传”按钮,可以放任意按钮;默认插槽显示在文件列表后面。
<script setup lang="ts">
import { NsButton, NsUpload } from '@ns/ui'
import type { UploadHttpRequest } from '@ns/ui'
// 用定时器模拟上传,不发真实请求
const mockUpload: UploadHttpRequest = ({ onProgress, onSuccess }) => {
let percent = 0
const timer = setInterval(() => {
percent += 20
onProgress({ percent })
if (percent === 100) {
clearInterval(timer)
onSuccess({ code: 0 })
}
}, 200)
return { abort: () => clearInterval(timer) }
}
</script>
<template>
<NsUpload :http-request="mockUpload" multiple>
<template #trigger>
<NsButton type="primary" icon="upload">选择附件</NsButton>
</template>
<p class="tip">可以一次选多个文件</p>
</NsUpload>
</template>
<style scoped>
.tip {
margin-top: 8px;
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
</style>
禁用
disabled 后不能选择文件,拖拽区和照片墙的入口变灰,列表里的删除按钮也不能点。
<script setup lang="ts">
import { ref } from 'vue'
import { NsSpace, NsUpload } from '@ns/ui'
import type { UploadFile } from '@ns/ui'
const fileList = ref<UploadFile[]>([
{ uid: 1, name: 'report.pdf', status: 'success', url: '/files/report.pdf' }
])
const pictures = ref<UploadFile[]>([
{ uid: 2, name: 'cat.jpg', status: 'success', url: '/images/cat.jpg' }
])
</script>
<template>
<NsSpace direction="vertical" fill size="large">
<NsUpload v-model:file-list="fileList" disabled />
<NsUpload drag disabled />
<NsUpload v-model:file-list="pictures" list-type="picture-card" disabled />
</NsSpace>
</template>
事件
选文件、上传、删除时触发的事件按时间倒序列在下面。这个上传只收图片、单个不超过 1MB、最多 3 个,选不合格的文件可以看到 reject、exceed:
<script setup lang="ts">
import { ref } from 'vue'
import { NsUpload } from '@ns/ui'
import type {
UploadFile,
UploadHttpRequest,
UploadProgressEvent,
UploadRejectReason
} from '@ns/ui'
const logs = ref<string[]>([])
const log = (text: string) => {
logs.value = [text, ...logs.value].slice(0, 8)
}
const onChange = (file: UploadFile) => log(`change:${file.name}`)
const onProgress = (event: UploadProgressEvent, file: UploadFile) => {
log(`progress:${file.name} ${event.percent}%`)
}
const onSuccess = (_response: unknown, file: UploadFile) => log(`success:${file.name}`)
const onRemove = (file: UploadFile) => log(`remove:${file.name}`)
const onExceed = (files: File[]) => log(`exceed:这次选了 ${files.length} 个,超过 3 个`)
const onReject = (file: File, reason: UploadRejectReason) => {
log(`reject:${file.name},原因 ${reason}`)
}
// 用定时器模拟上传,不发真实请求
const mockUpload: UploadHttpRequest = ({ onProgress, onSuccess }) => {
let percent = 0
const timer = setInterval(() => {
percent += 50
onProgress({ percent })
if (percent === 100) {
clearInterval(timer)
onSuccess({ code: 0 })
}
}, 300)
return { abort: () => clearInterval(timer) }
}
</script>
<template>
<NsUpload
:http-request="mockUpload"
accept="image/*"
:max-size="1024 * 1024"
:limit="3"
multiple
@change="onChange"
@progress="onProgress"
@success="onSuccess"
@remove="onRemove"
@exceed="onExceed"
@reject="onReject"
/>
<div class="event-log">
<div v-for="(item, index) in logs" :key="index">{{ item }}</div>
<div v-if="!logs.length">还没有触发事件</div>
</div>
</template>
<style scoped>
.event-log {
margin-top: 12px;
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
line-height: 1.8;
}
</style>
上传失败时触发 error,见上面“自定义上传请求”里勾选“模拟失败”的例子。
在表单里使用
放在 NsFormItem 里时,添加、删除、清空文件后触发 change 规则;表单禁用时不能选择和删除文件。不需要校验时设 :validate-event="false"。
<script setup lang="ts">
import { reactive, ref } from 'vue'
import { NsButton, NsForm, NsFormItem, NsMessage, NsUpload } from '@ns/ui'
import type { UploadFile, UploadHttpRequest } from '@ns/ui'
const formRef = ref<InstanceType<typeof NsForm>>()
const form = reactive<{ files: UploadFile[] }>({ files: [] })
// 用定时器模拟上传,不发真实请求
const mockUpload: UploadHttpRequest = ({ onProgress, onSuccess }) => {
let percent = 0
const timer = setInterval(() => {
percent += 20
onProgress({ percent })
if (percent === 100) {
clearInterval(timer)
onSuccess({ code: 0 })
}
}, 200)
return { abort: () => clearInterval(timer) }
}
const submit = async () => {
const { valid } = await formRef.value!.validate()
if (valid) NsMessage.success(`提交了 ${form.files.length} 个附件`)
}
</script>
<template>
<NsForm
ref="formRef"
:model="form"
:rules="{
files: [{ type: 'array', required: true, message: '请上传附件', trigger: 'change' }]
}"
>
<NsFormItem label="附件" prop="files">
<NsUpload v-model:file-list="form.files" :http-request="mockUpload" />
</NsFormItem>
<NsFormItem>
<NsButton type="primary" @click="submit">提交</NsButton>
</NsFormItem>
</NsForm>
</template>
对接真实接口
真实项目里传 action,组件用 XHR 以 multipart/form-data 发 POST 请求:文件放在 name 字段(默认 file),data 里的字段一起发送,headers 加在请求头上,with-credentials 时带上 cookie。接口返回的内容按 JSON 解析后作为 success 事件的 response,HTTP 状态不是 2xx 时触发 error。下面是一个常见的写法(@/utils/auth 换成项目里取登录凭证的方法):
<script setup lang="ts">
import { ref } from 'vue'
import { NsMessage, NsUpload } from '@ns/ui'
import type { UploadFile } from '@ns/ui'
import { getToken } from '@/utils/auth'
const fileList = ref<UploadFile[]>([])
const headers = { Authorization: `Bearer ${getToken()}` }
// 假设接口返回 { code: 0, data: { url } }:把文件地址记在列表里,提交表单时用
const onSuccess = (response: unknown, file: UploadFile) => {
const res = response as { code: number; msg?: string; data?: { url: string } }
if (res.code !== 0) {
NsMessage.error(res.msg ?? `${file.name} 上传失败`)
return
}
file.url = res.data?.url
}
const onError = (error: Error, file: UploadFile) => {
NsMessage.error(`${file.name}:${error.message}`)
}
</script>
<template>
<NsUpload
v-model:file-list="fileList"
action="/api/upload"
name="file"
:headers="headers"
:data="{ bizType: 'contract' }"
with-credentials
multiple
@success="onSuccess"
@error="onError"
/>
</template>
Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| action | string | '' | 上传地址 |
| headers | Record<string, string> | - | 请求头 |
| multiple | boolean | false | 是否可以多选 |
| data | Record<string, unknown> | - | 额外的表单字段。Blob、File 按文件发送,其余转成字符串 |
| name | string | 'file' | 文件字段名 |
| withCredentials | boolean | false | 是否携带 cookie |
| accept | string | '' | 接受的文件类型,点击选择和拖拽的文件都会检查,不符合的触发 reject |
| maxSize | number | - | 单个文件的大小上限,单位字节。超过的触发 reject;不传时不限制 |
| limit | number | - | 最多几个文件 |
| autoUpload | boolean | true | 选中后是否立即上传 |
| fileList | UploadFile[] | - | 文件列表,支持 v-model:file-list。不传时组件自己维护 |
| disabled | boolean | false | 是否禁用 |
| drag | boolean | false | 是否显示拖拽区 |
| listType | 'text' | 'picture' | 'picture-card' | 'text' | 文件列表的样式 |
| httpRequest | UploadHttpRequest | - | 自定义上传请求 |
| beforeUpload | (file: File) => boolean | Promise<File | boolean | void> | - | 上传前的钩子,返回 false 或 reject 时跳过这个文件 |
| validateEvent | boolean | true | 文件列表变化时是否触发所在表单项的校验 |
Events
| 事件 | 回调参数 | 说明 |
|---|---|---|
| update:fileList | (fileList: UploadFile[]) | 文件列表变化时触发 |
| change | (file: UploadFile, fileList: UploadFile[]) | 新文件加入列表时触发 |
| progress | (event: UploadProgressEvent, file: UploadFile, fileList: UploadFile[]) | 上传进度变化时触发 |
| success | (response: unknown, file: UploadFile, fileList: UploadFile[]) | 上传成功时触发 |
| error | (error: Error, file: UploadFile, fileList: UploadFile[]) | 上传失败时触发 |
| remove | (file: UploadFile, fileList: UploadFile[]) | 点删除按钮移除文件时触发 |
| exceed | (files: File[], fileList: UploadFile[]) | 选中的文件超过 limit 时触发 |
| reject | (file: File, reason: UploadRejectReason) | 文件类型不符合 accept('type')或超过 maxSize('size')时触发,每个文件一次 |
Slots
| 插槽 | 说明 |
|---|---|
| trigger | 替换默认的“点击上传”按钮、照片墙的“+”图标,或拖拽区里的上传图标和文字 |
| default | 显示在文件列表后面的内容,例如提示文字 |
方法
| 名称 | 类型 | 说明 |
|---|---|---|
| submit | () => void | 上传所有 ready 状态的文件 |
| abort | (file?: UploadFile) => void | 取消上传。被取消的文件回到 ready,可以再 submit();不传时取消全部 |
| clearFiles | (statuses?: UploadFile['status'][]) => void | 清空列表;传了状态时只清掉这些状态的文件 |
类型
import type {
UploadFile,
UploadStatus,
UploadListType,
UploadRejectReason,
UploadRequestOptions,
UploadHttpRequest,
UploadInstance
} from '@ns/ui'
type UploadStatus = 'ready' | 'uploading' | 'success' | 'error'
/** type:不符合 accept;size:超过 maxSize */
type UploadRejectReason = 'size' | 'type'
interface UploadFile {
uid: number | string
name: string
size?: number
status?: UploadStatus
progress?: number
url?: string
response?: unknown
raw?: File
}
interface UploadRequestOptions {
file: File
name: string
action: string
headers?: Record<string, string>
data?: Record<string, unknown>
withCredentials?: boolean
onProgress: (event: { percent: number }) => void
onSuccess: (response: unknown) => void
onError: (error: Error) => void
}
type UploadHttpRequest = (
options: UploadRequestOptions
) => { abort: () => void } | Promise<unknown> | void
注意事项
- 只传
:file-list、不处理update:fileList时,组件内部的列表照样会变化,直到父组件传入新的数组为止。 - 默认请求把响应按 JSON 解析,解析失败时原样返回文本;HTTP 状态不是 2xx 时算失败。
- 文件被移除后,它那次上传的回调不再生效;默认请求会被取消。
- 组件卸载时不会取消进行中的上传,只释放缩略图占用的内存。
- 照片墙的“+”方块达到
limit后不会自动隐藏,再点会触发exceed;只允许一张图时(例如头像),可以按fileList.length自己用 CSS 或v-if处理。 accept里写错的项(既不是.开头的扩展名,也不是 MIME)和浏览器一样被忽略,一项有效的都没有时不限制类型。例如jpg,png不限制任何类型,要写成.jpg,.png。- 按 MIME 检查时看的是浏览器给的
file.type。有些格式浏览器认不出来(例如 Windows 上的.heic),type是空的,写image/*时会被拒收;需要收这类文件时加上扩展名,例如image/*,.heic。 maxSize检查的是用户选中的原文件。要先压缩再判断大小时不要用maxSize,在before-upload里压缩并自己判断。maxSize为0或负数时不限制大小。
优化点
- [x] 照片墙模式的“+”上传卡片
- [x] 文件大小上限(
maxSize),选文件时也按accept检查,不合格的触发reject - [ ] 支持文件预览
- [ ] 支持图片裁剪
- [ ] 支持断点续传
- [ ] 支持文件夹上传