Empty 空状态
列表、表格、搜索结果没有数据时,用一张图和一句话告诉用户“这里是空的”,下面还可以放操作按钮。
引入
ts
import { NsEmpty } from '@ns/ui'
基础用法
不传任何属性时,显示内置的空状态图和“暂无数据”。
vue
<script setup lang="ts">
import { NsEmpty } from '@ns/ui'
</script>
<template>
<NsEmpty />
</template>
自定义描述
description 改描述文字;传空字符串时不显示描述,图片下面不留空白。
vue
<script setup lang="ts">
import { NsEmpty } from '@ns/ui'
</script>
<template>
<div class="grid">
<NsEmpty description="没有找到相关内容" />
<NsEmpty description="" />
<NsEmpty description="当前筛选条件下没有记录,试试放宽时间范围或者清空关键词" />
</div>
</template>
<style scoped>
.grid {
display: grid;
grid-template-columns: repeat(auto-fill, minmax(220px, 1fr));
gap: var(--ns-spacing-4);
}
</style>
图片尺寸
图片区域默认是 160×100 像素。image-size 传数字时宽高相等,传对象 { width, height } 时分别指定宽高(单位都是像素)。内置图和 image 传的图片都按比例缩放到这个区域里。
vue
<script setup lang="ts">
import { NsEmpty } from '@ns/ui'
</script>
<template>
<div class="grid">
<NsEmpty :image-size="60" description="小尺寸(60)" />
<NsEmpty description="默认(160×100)" />
<NsEmpty :image-size="{ width: 240, height: 80 }" description="指定宽高(240×80)" />
<NsEmpty image="/images/empty.png" :image-size="80" description="自定义图片也生效" />
</div>
</template>
<style scoped>
.grid {
display: grid;
grid-template-columns: repeat(auto-fill, minmax(260px, 1fr));
gap: var(--ns-spacing-4);
}
</style>
自定义图片
image 传图片地址,替换内置的空状态图。
vue
<script setup lang="ts">
import { NsEmpty } from '@ns/ui'
</script>
<template>
<NsEmpty image="/images/empty.png" description="使用自定义图片" />
</template>
图片插槽
需要放图标或自定义内容时用 #image 插槽,它会替换整个图片区域里的内容,写了插槽时 image 不再生效。
vue
<script setup lang="ts">
import { NsEmpty, NsIcon } from '@ns/ui'
</script>
<template>
<NsEmpty description="没有搜索结果">
<template #image>
<NsIcon name="search" style="font-size: 64px" />
</template>
</NsEmpty>
</template>
不同场景换不同的图标和颜色:
vue
<script setup lang="ts">
import { NsEmpty, NsIcon } from '@ns/ui'
</script>
<template>
<div class="grid">
<NsEmpty description="文件夹是空的">
<template #image>
<NsIcon name="folder" style="font-size: 56px; color: var(--ns-color-warning)" />
</template>
</NsEmpty>
<NsEmpty description="没有新消息">
<template #image>
<NsIcon name="mail" style="font-size: 56px; color: var(--ns-color-primary)" />
</template>
</NsEmpty>
<NsEmpty description="没有待办通知">
<template #image>
<NsIcon name="bell" style="font-size: 56px; color: var(--ns-text-color-placeholder)" />
</template>
</NsEmpty>
<NsEmpty description="全部处理完了">
<template #image>
<NsIcon name="success" style="font-size: 56px; color: var(--ns-color-success)" />
</template>
</NsEmpty>
</div>
</template>
<style scoped>
.grid {
display: grid;
grid-template-columns: repeat(auto-fill, minmax(180px, 1fr));
gap: var(--ns-spacing-4);
}
</style>
底部操作
默认插槽的内容显示在描述下面,通常放一两个按钮。
vue
<script setup lang="ts">
import { NsEmpty, NsButton, NsSpace } from '@ns/ui'
</script>
<template>
<div class="grid">
<NsEmpty description="暂无数据">
<NsButton type="primary">添加数据</NsButton>
</NsEmpty>
<NsEmpty description="还没有创建项目">
<NsSpace>
<NsButton type="primary" icon="plus">新建项目</NsButton>
<NsButton icon="upload">导入</NsButton>
</NsSpace>
</NsEmpty>
<NsEmpty description="网络不太好,没有加载出来">
<NsButton variant="link" type="primary" icon="refresh">重新加载</NsButton>
</NsEmpty>
</div>
</template>
<style scoped>
.grid {
display: grid;
grid-template-columns: repeat(auto-fill, minmax(240px, 1fr));
gap: var(--ns-spacing-4);
}
</style>
列表为空时显示
常见用法是数据为空时用 NsEmpty 代替列表。点“清空”把列表清掉,再点空状态里的按钮恢复:
vue
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsCard, NsEmpty } from '@ns/ui'
const all = ['需求评审', '接口联调', '发布上线']
const todos = ref([...all])
</script>
<template>
<NsCard title="待办事项" style="max-width: 360px">
<template #header-extra>
<NsButton size="small" :disabled="!todos.length" @click="todos = []">清空</NsButton>
</template>
<ul v-if="todos.length" style="margin: 0; padding-left: 20px">
<li v-for="item in todos" :key="item">{{ item }}</li>
</ul>
<NsEmpty v-else :image-size="60" description="没有待办事项">
<NsButton size="small" type="primary" @click="todos = [...all]">恢复示例数据</NsButton>
</NsEmpty>
</NsCard>
</template>
Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| image | string | — | 自定义图片地址。不传时显示内置的空状态图 |
| imageSize | number | { width: number; height: number } | — | 图片区域尺寸(像素)。数字时宽高相等,对象时分别指定;不传时是 160×100 |
| description | string | '暂无数据' | 描述文字。传空字符串时不显示 |
Slots
| 插槽 | 说明 |
|---|---|
| image | 自定义图片区域的内容,替换 image 和内置的空状态图 |
| default | 底部内容,显示在描述下面,通常放操作按钮 |
类型
ts
import type { EmptyImageSize, EmptyProps, EmptySlots } from '@ns/ui'
type EmptyImageSize = number | { width: number; height: number }
interface EmptyProps {
image?: string
imageSize?: EmptyImageSize
description?: string
}
interface EmptySlots {
image?: () => unknown
default?: () => unknown
}
注意事项
- 默认图片区域是 160×100 像素,图片和内置图在里面按比例缩放、居中显示,不会超出这个区域。传了
imageSize后,区域和图片都按imageSize的大小显示。 - 内置的空状态图颜色跟随主题的占位文字色(
--ns-text-color-placeholder),暗色主题下会自动变化;用image传的图片不会跟着变。 description为空字符串时不渲染描述段落,图片和底部内容之间不会多出空白。- 组件没有事件,也没有暴露方法。
优化点
- [ ] 支持更多内置空状态图片样式
- [ ] 支持空状态类型(如简单、详细)
- [ ] 支持全局配置默认描述和图片