企业官网建设流程全解析

naive-ui Empty 空状态组件完全指南：Props、Slots、尺寸与主题定制

【免费下载链接】naive-uiA Vue 3 Component Library. Fairly Complete. Theme Customizable. Uses TypeScript. Fast.项目地址: https://gitcode.com/gh_mirrors/na/naive-ui

导读

naive-ui 的NEmpty组件用于在列表、表格、筛选结果等无数据场景中展示占位内容，帮助用户理解"当前没有数据"并引导下一步操作。本指南以官方文档 Empty 组件文档 为核心骨架，结合组件源码、主题样式与单元测试，完整讲解其 Props、Slots、五种尺寸、国际化默认文案及主题变量定制，读完即可在项目中直接落地使用。

组件概览

NEmpty的布局结构非常直观：默认渲染为一个纵向 flex 容器，自上而下依次排列图标（icon）→ 描述（description）→ 附加内容（extra）。从 Empty.tsx 的渲染逻辑与 样式定义 可以看出：

.n-empty（flex 纵向居中） ├── .n-empty__icon 图标区，宽高与字号均为 var(--n-icon-size) ├── .n-empty__description 描述区，与图标间隔 8px └── .n-empty__extra 附加操作区，与描述间隔 12px

组件在源码中以defineComponent方式声明，组件名为Empty，对外导出名为NEmpty（见 组件入口）。它默认展示一个内置的"空数据"图标与一行描述文字，三个区域均可通过插槽整体替换。

Props 完整说明

官方文档中 Empty Props 的完整参数如下：

对应源码中 emptyProps 的声明，逐一说明如下：

• description：自定义描述文案。注意源码中的取值优先级为props.description ?? 全局 config-provider 中配置的 Empty.description ?? 当前语言环境下的默认文案（见 Empty.tsx）。其中"当前语言环境下的默认文案"由 locale 决定，例如 enUS 中为'No Data'（见 enUS locale），zhCN 中为"暂无数据"；同时组件渲染时还有一层兜底逻辑mergedDescriptionRef.value || localeRef.value.description（见 Empty.tsx）。
• show-description：设为false时完全不渲染.n-empty__description节点。
• show-icon：设为false时完全不渲染.n-empty__icon节点。
• size：控制整体尺寸，从 2.40.0 版本开始支持。它通过主题变量动态换算为图标尺寸与文字字号（详见下文"尺寸机制"）。

此外，源码中还额外声明了一个未在文档表格列出的render-icon（() => VNodeChild）函数式 prop：当传入时，它会作为默认图标渲染（优先级低于icon插槽），用于在不写插槽的情况下通过函数返回自定义图标节点（见 Empty.tsx）。

Slots 完整说明

官方文档中 Empty Slots 的参数如下：

三个插槽均无参数，分别对应渲染逻辑中的三个分支（见 Empty.tsx）：

• default：替换描述文字区域。提供后，descriptionprop 与本地化默认文案均不再生效。
• extra：在描述下方追加自定义操作区，典型用法是放置"重新加载""去创建""查看全部"等引导按钮。只有当该插槽存在时.n-empty__extra节点才会渲染。
• icon：替换默认图标。提供后，render-iconprop 与内置图标均不生效；show-icon仍可控制整个图标区是否显示。

渲染逻辑与插槽优先级可以总结为：

图标区：show-icon=false 则不渲染 ├── 有 icon 插槽 → 渲染插槽内容 └── 否则 → render-icon prop 或内置 EmptyIcon 描述区：show-description=false 则不渲染 ├── 有 default 插槽 → 渲染插槽内容 └── 否则 → description prop → locale 默认文案（如 'No Data'） 附加区：有 extra 插槽才渲染

三个官方 Demo 实战解读

组件文档页展示了三个可运行示例（basic.vue、icon.vue、size.demo.vue），分别覆盖最常用场景。

1. 基础用法：描述 + 操作按钮

<template> <n-empty description="You can't find anything"> <template #extra> <n-button size="small"> Find Something New </n-button> </template> </n-empty> </template>

这是最典型的空状态页面：通过description说明"没有找到内容"，再用extra插槽放一个引导按钮让用户继续操作。由于两个插槽（default/extra）与description互不冲突，可以自由组合。

2. 自定义图标

<script lang="ts" setup> import { IosAirplane } from '@vicons/ionicons4' </script> <template> <n-empty description="Custom your icon"> <template #icon> <n-icon> <IosAirplane /> </n-icon> </template> <template #extra> <n-button size="small"> Find Something New </n-button> </template> </n-empty> </template>

通过icon插槽可以完全替换默认空数据图标，示例中搭配@vicons/ionicons4图标库与n-icon组件使用，让空状态与业务主题更契合。

3. 尺寸切换

<template> <n-empty size="large" description="can be large"> <template #extra> <n-button size="small"> Find Something New </n-button> </template> </n-empty> </template>

size支持tiny、small、medium、large、huge五种取值，适合在页面不同视觉层级（如抽屉、弹窗、整页）中匹配不同大小的空状态。

尺寸机制与图标规格

size属性最终作用于两组 CSS 变量：图标尺寸--n-icon-size与描述文字字号--n-font-size。在 Empty.tsx 中，组件会根据size从主题的self部分动态取用iconSize<Size>与fontSize<Size>并映射为 CSS 变量。

五种尺寸对应的图标规格定义在 样式通用变量 中：

而描述文字字号则来自全局主题的fontSizeTiny/fontSizeSmall/fontSizeMedium/fontSizeLarge/fontSizeHuge（见 light.ts）。从样式源码 index.cssr.ts 可以看到，图标区将--n-icon-size同时用于宽、高、字号与行高，因此尺寸切换时图标会整体等比缩放。

国际化与默认文案

NEmpty接入 naive-ui 的 locale 体系：当未提供description且未在 config-provider 中配置时，组件会读取当前 locale 的Empty.description作为默认文案。例如英文环境默认显示'No Data'（见 enUS locale），切换为中文环境后会自动显示对应翻译。这一机制也体现在 locale-debug.demo.vue 中——不传任何参数直接渲染<n-empty />即可看到当前语言环境的默认效果。

若希望全局统一自定义空状态文案与图标，可以在 config-provider 的componentProps.Empty中配置description与render-icon，源码中已显式支持这一读取路径（见 Empty.tsx）。

主题定制：CSS 变量与暗色模式

Empty 组件暴露了 5 个可定制的 CSS 变量（由 cssVarsRef 生成，注释亦见 index.cssr.ts）：

此外还有--n-bezier（动画缓动曲线），用于图标与描述文字的 0.3s 颜色过渡。

主题的self部分定义在 light.ts 中，暗色主题 dark.ts 直接复用同一份self并仅替换commonDark，因此所有颜色变量会自动适配暗色模式。如需自定义，可通过theme-overrides覆盖Empty主题变量，例如：

import { NConfigProvider, NEmpty, darkTheme } from 'naive-ui' const themeOverrides = { Empty: { iconColor: '#2080f0', iconSizeLarge: '60px' } }

源码与测试验证

组件的单元测试位于 Empty.spec.ts，可作为使用行为的权威参考，其中值得注意的验证点包括：

• 插槽优先级：同时传入default/icon/extra三个插槽时，分别渲染到.n-empty__description、.n-empty__icon、.n-empty__extra三个节点；
• 开关类 Props：show-icon: false时不渲染.n-empty__icon；show-description: false时不渲染.n-empty__description；
• 文案优先级：descriptionprop 优先于 locale 默认文案（"should prioritize description prop over locale"）；
• 空文案兼容：传入空字符串description: ''时描述区仍正常渲染，不会崩溃；
• 尺寸快照：tiny/small/medium/large/huge五档尺寸均生成对应的 style 快照，验证 CSS 变量随尺寸正确切换。

快速上手小结

一个完整的 Empty 使用范式可以概括为三步：

1. 最简用法：<n-empty />，自动使用当前语言环境的默认图标与文案（如 "No Data"）；
2. 补充语境：通过description说明"空的原因"，如description="You can't find anything"；
3. 引导操作：用extra插槽放入行动按钮，用icon插槽（或render-icon）替换业务图标，用size匹配所在容器视觉层级。

如需在列表、数据表格等组件中集成空状态，可组合show-icon、show-description与自定义插槽实现从"纯图标"到"图标+文案+按钮"的任意形态。

【免费下载链接】naive-uiA Vue 3 Component Library. Fairly Complete. Theme Customizable. Uses TypeScript. Fast.项目地址: https://gitcode.com/gh_mirrors/na/naive-ui