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.
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为空字符串时不渲染描述段落,图片和底部内容之间不会多出空白。- 组件没有事件,也没有暴露方法。
优化点
- [ ] 支持更多内置空状态图片样式
- [ ] 支持空状态类型(如简单、详细)
- [ ] 支持全局配置默认描述和图片