Vant Empty 空状态组件实战指南占位提示、内置图片类型与主题定制【免费下载链接】vantA lightweight, customizable Vue UI library for mobile web apps.项目地址: https://gitcode.com/GitHub_Trending/va/vantVant 的Empty组件用于在列表为空、数据加载失败、搜索无结果等场景下展示占位提示帮助用户理解当前页面状态。本文以 Empty 官方文档 为主体结合组件源码、样式变量与测试用例系统讲解其安装注册、内置图片类型、尺寸控制、插槽扩展以及基于 CSS 变量的主题定制让你在移动端业务中快速落地优雅的空状态 UI。组件介绍Empty空状态是 Vant 内置的轻量占位组件核心能力包括内置default默认、error通用错误、network网络错误、search搜索提示四类预设占位图均由组件内部以 SVG 内联渲染无需额外请求图片资源支持传入任意图片 URL或通过插槽完全自定义图片与描述区域提供默认插槽可在空状态下方追加操作按钮如重新加载去逛逛全部样式通过 CSS 变量开放可与 ConfigProvider 组件 配合实现全局主题定制。安装与引入通过以下方式来全局注册组件更多注册方式请参考组件注册import { createApp } from vue; import { Empty } from vant; const app createApp(); app.use(Empty);注册后即可在模板中使用van-empty标签。从源码结构看index.ts 通过withInstall将组件包装为可app.use()安装的插件形式并额外导出了emptyProps、EmptyProps、EmptyThemeVars类型便于按需引用。同时 index.ts 声明了GlobalComponents中的VanEmpty类型因此在 Vue 3 TypeScript 项目中无需额外类型声明即可获得完整的模板类型提示。代码演示基础用法最简单的用法是只传入description描述文字van-empty description描述文字 /此时组件会渲染内置的默认占位图灰白配色的 SVG 插画并在图片下方展示描述文字。图片类型Empty组件内置了多种占位图片类型可以在不同业务场景下使用!-- 通用错误 -- van-empty imageerror description描述文字 / !-- 网络错误 -- van-empty imagenetwork description描述文字 / !-- 搜索提示 -- van-empty imagesearch description描述文字 /从 Empty.tsx 的渲染逻辑可以印证组件内部维护了一张预设图片映射表const PRESET_IMAGES: Recordstring, () JSX.Element { error: renderError, search: renderSearch, network: renderNetwork, default: renderMaterial, }; return PRESET_IMAGES[props.image]?.() || img src{props.image} /;也就是说image属性先与内置类型匹配匹配成功则渲染对应的 SVG 图形renderError、renderSearch、renderNetwork、renderMaterial四个渲染函数否则将image值当作普通图片 URL渲染为img标签。因此image属性既支持枚举值也支持任意图片地址。这些 SVG 并非静态资源而是由 TSX 内联生成——例如renderNetwork用svg viewBox0 0 160 160绘制信号塔与波纹renderError绘制带叉号的占位图形renderSearch绘制放大镜renderMaterial绘制手机卡片插画。同时通过useId生成唯一渐变 ID并使用data-allow-mismatch标记避免 SSR 场景下的 hydration 不匹配问题对应测试文件 demo-ssr.spec.ts 覆盖了该场景。自定义大小通过image-size属性自定义图片的大小!-- 不指定单位默认为 px -- van-empty image-size100 description描述文字 / !-- 指定单位支持 rem, vh, vw -- van-empty image-size10rem description描述文字 /将image-size设置为数组格式可以分别设置宽高。数组第一项对应宽度数组第二项对应高度van-empty :image-size[60, 40] description描述文字 /其底层实现位于 format.ts 的getSizeStyle纯数字值会通过addUnit自动拼接px单位见 format.tsisNumeric判断为数字时返回${value}px否则保留原字符串因此rem、vw、vh等合法 CSS 单位可直接透传数组形式则分别映射为width与height。该尺寸样式最终应用到.van-empty__image容器上见 Empty.tsx。对应测试 index.spec.ts 验证了image-size50时容器宽高均为50px切换为1vw后宽高均变为1vw数组[20, 10]则分别得到20px宽与10px高。自定义图片需要自定义图片时可以在image属性中传入任意图片 URLvan-empty imagehttps://fastly.jsdelivr.net/npm/vant/assets/custom-empty-image.png image-size80 description描述文字 /传入 URL 后组件渲染img标签并默认铺满.van-empty__image容器样式见 index.lessimg宽高均为100%。在实际业务中更推荐使用相对路径或 CDN 地址图片尺寸建议按设计稿配合image-size一并控制。底部内容通过默认插槽可以在Empty组件的下方插入内容常用于放置引导性操作按钮van-empty description描述文字 van-button round typeprimary classbottom-button按钮/van-button /van-empty style .bottom-button { width: 160px; height: 40px; } /style底部内容容器.van-empty__bottom通过margin-top: var(--van-empty-bottom-margin-top)默认24px与描述文字区隔。在 demo/index.vue 中可以看到该用法的完整演示按钮宽度可通过 CSS 自由控制。APIProps参数说明类型默认值image图片类型可选值为errornetworksearch支持传入图片 URLstringdefaultimage-size图片大小默认单位为px支持rem/vh/vw等 CSS 单位传数组时第一项为宽、第二项为高number | string | Array-description图片下方的描述文字string-对应源码中的 props 声明见 Empty.tsximage使用makeStringProp(default)声明默认值default对应内置默认插画imageSize的类型为Numeric | [Numeric, Numeric]。Slots名称说明default自定义底部内容image自定义图片description自定义描述文字插槽优先级从 Empty.tsx 可以看出描述区域优先渲染description插槽未提供插槽时才使用descriptionprop图片区域优先渲染image插槽见 Empty.tsx未提供时再走内置预设或 URL 逻辑default插槽渲染在.van-empty__bottom容器内。对应测试 index.spec.ts 分别验证了三个插槽的渲染行为。类型定义组件导出以下类型定义便于在 TSX 或脚本中强类型引用import type { EmptyProps } from vant;此外还导出了EmptyThemeVars见 types.ts可用于主题变量的类型约束。主题定制样式变量组件提供了下列 CSS 变量可用于自定义样式使用方法请参考 ConfigProvider 组件。名称默认值描述--van-empty-paddingvar(--van-padding-xl) 0组件内边距--van-empty-image-size160px图片容器尺寸--van-empty-description-margin-topvar(--van-padding-md)描述文字上边距--van-empty-description-padding0 60px描述文字内边距--van-empty-description-colorvar(--van-text-color-2)描述文字颜色--van-empty-description-font-sizevar(--van-font-size-md)描述文字字号--van-empty-description-line-heightvar(--van-line-height-md)描述文字行高--van-empty-bottom-margin-top24px底部内容上边距这些变量的默认值定义在 index.less 的:root/:host中并由.van-empty、__image、__description、__bottom等 BEM 类逐一消费。由于整个空状态区域使用flex-direction: columnalign-items: center布局见 index.less调整描述文字宽度时只需覆盖--van-empty-description-padding即可。说明CSS 变量名与EmptyThemeVars中emptyDescriptionLineHeight等小驼峰键一一对应参考 types.ts。另外在深色模式下组件会自动应用.van-theme-dark .van-empty { opacity: 0.5; }见 index.less降低整块插画的视觉亮度以适配暗色背景。通过 ConfigProvider 全局配置结合 Vant 的 ConfigProvider 组件可以按主题统一覆盖空状态样式例如van-config-provider :theme-vars{ emptyDescriptionColor: #969799, emptyImageSize: 140px, } van-empty description暂无数据 / /van-config-provider这样无需逐个页面改动即可在全局或局部作用域内统一空状态的图片尺寸与描述颜色与组件文档中使用 CSS 变量定制样式的思路完全一致。使用场景小结结合本文内容Empty组件在实战中的典型组合如下列表无数据van-empty description暂无数据 /接口报错imageerror 底部插槽放置重新加载按钮搜索无结果imagesearch 引导用户更换关键词的文案断网提示imagenetwork并可配合image-size控制插画在页面中的视觉占比品牌定制通过image传入品牌插画 URL或使用image插槽完全替换内置 SVG。组件全部样式与结构均围绕图片 → 描述 → 底部操作三段式布局组织见 index.less内置插画零网络开销配合本文的 Props、Slots 与 CSS 变量说明即可快速构建与业务视觉一致的移动端空状态方案。【免费下载链接】vantA lightweight, customizable Vue UI library for mobile web apps.项目地址: https://gitcode.com/GitHub_Trending/va/vant创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Vant Empty 空状态组件实战指南：占位提示、内置图片类型与主题定制
Vant Empty 空状态组件实战指南占位提示、内置图片类型与主题定制【免费下载链接】vantA lightweight, customizable Vue UI library for mobile web apps.项目地址: https://gitcode.com/GitHub_Trending/va/vantVant 的Empty组件用于在列表为空、数据加载失败、搜索无结果等场景下展示占位提示帮助用户理解当前页面状态。本文以 Empty 官方文档 为主体结合组件源码、样式变量与测试用例系统讲解其安装注册、内置图片类型、尺寸控制、插槽扩展以及基于 CSS 变量的主题定制让你在移动端业务中快速落地优雅的空状态 UI。组件介绍Empty空状态是 Vant 内置的轻量占位组件核心能力包括内置default默认、error通用错误、network网络错误、search搜索提示四类预设占位图均由组件内部以 SVG 内联渲染无需额外请求图片资源支持传入任意图片 URL或通过插槽完全自定义图片与描述区域提供默认插槽可在空状态下方追加操作按钮如重新加载去逛逛全部样式通过 CSS 变量开放可与 ConfigProvider 组件 配合实现全局主题定制。安装与引入通过以下方式来全局注册组件更多注册方式请参考组件注册import { createApp } from vue; import { Empty } from vant; const app createApp(); app.use(Empty);注册后即可在模板中使用van-empty标签。从源码结构看index.ts 通过withInstall将组件包装为可app.use()安装的插件形式并额外导出了emptyProps、EmptyProps、EmptyThemeVars类型便于按需引用。同时 index.ts 声明了GlobalComponents中的VanEmpty类型因此在 Vue 3 TypeScript 项目中无需额外类型声明即可获得完整的模板类型提示。代码演示基础用法最简单的用法是只传入description描述文字van-empty description描述文字 /此时组件会渲染内置的默认占位图灰白配色的 SVG 插画并在图片下方展示描述文字。图片类型Empty组件内置了多种占位图片类型可以在不同业务场景下使用!-- 通用错误 -- van-empty imageerror description描述文字 / !-- 网络错误 -- van-empty imagenetwork description描述文字 / !-- 搜索提示 -- van-empty imagesearch description描述文字 /从 Empty.tsx 的渲染逻辑可以印证组件内部维护了一张预设图片映射表const PRESET_IMAGES: Recordstring, () JSX.Element { error: renderError, search: renderSearch, network: renderNetwork, default: renderMaterial, }; return PRESET_IMAGES[props.image]?.() || img src{props.image} /;也就是说image属性先与内置类型匹配匹配成功则渲染对应的 SVG 图形renderError、renderSearch、renderNetwork、renderMaterial四个渲染函数否则将image值当作普通图片 URL渲染为img标签。因此image属性既支持枚举值也支持任意图片地址。这些 SVG 并非静态资源而是由 TSX 内联生成——例如renderNetwork用svg viewBox0 0 160 160绘制信号塔与波纹renderError绘制带叉号的占位图形renderSearch绘制放大镜renderMaterial绘制手机卡片插画。同时通过useId生成唯一渐变 ID并使用data-allow-mismatch标记避免 SSR 场景下的 hydration 不匹配问题对应测试文件 demo-ssr.spec.ts 覆盖了该场景。自定义大小通过image-size属性自定义图片的大小!-- 不指定单位默认为 px -- van-empty image-size100 description描述文字 / !-- 指定单位支持 rem, vh, vw -- van-empty image-size10rem description描述文字 /将image-size设置为数组格式可以分别设置宽高。数组第一项对应宽度数组第二项对应高度van-empty :image-size[60, 40] description描述文字 /其底层实现位于 format.ts 的getSizeStyle纯数字值会通过addUnit自动拼接px单位见 format.tsisNumeric判断为数字时返回${value}px否则保留原字符串因此rem、vw、vh等合法 CSS 单位可直接透传数组形式则分别映射为width与height。该尺寸样式最终应用到.van-empty__image容器上见 Empty.tsx。对应测试 index.spec.ts 验证了image-size50时容器宽高均为50px切换为1vw后宽高均变为1vw数组[20, 10]则分别得到20px宽与10px高。自定义图片需要自定义图片时可以在image属性中传入任意图片 URLvan-empty imagehttps://fastly.jsdelivr.net/npm/vant/assets/custom-empty-image.png image-size80 description描述文字 /传入 URL 后组件渲染img标签并默认铺满.van-empty__image容器样式见 index.lessimg宽高均为100%。在实际业务中更推荐使用相对路径或 CDN 地址图片尺寸建议按设计稿配合image-size一并控制。底部内容通过默认插槽可以在Empty组件的下方插入内容常用于放置引导性操作按钮van-empty description描述文字 van-button round typeprimary classbottom-button按钮/van-button /van-empty style .bottom-button { width: 160px; height: 40px; } /style底部内容容器.van-empty__bottom通过margin-top: var(--van-empty-bottom-margin-top)默认24px与描述文字区隔。在 demo/index.vue 中可以看到该用法的完整演示按钮宽度可通过 CSS 自由控制。APIProps参数说明类型默认值image图片类型可选值为errornetworksearch支持传入图片 URLstringdefaultimage-size图片大小默认单位为px支持rem/vh/vw等 CSS 单位传数组时第一项为宽、第二项为高number | string | Array-description图片下方的描述文字string-对应源码中的 props 声明见 Empty.tsximage使用makeStringProp(default)声明默认值default对应内置默认插画imageSize的类型为Numeric | [Numeric, Numeric]。Slots名称说明default自定义底部内容image自定义图片description自定义描述文字插槽优先级从 Empty.tsx 可以看出描述区域优先渲染description插槽未提供插槽时才使用descriptionprop图片区域优先渲染image插槽见 Empty.tsx未提供时再走内置预设或 URL 逻辑default插槽渲染在.van-empty__bottom容器内。对应测试 index.spec.ts 分别验证了三个插槽的渲染行为。类型定义组件导出以下类型定义便于在 TSX 或脚本中强类型引用import type { EmptyProps } from vant;此外还导出了EmptyThemeVars见 types.ts可用于主题变量的类型约束。主题定制样式变量组件提供了下列 CSS 变量可用于自定义样式使用方法请参考 ConfigProvider 组件。名称默认值描述--van-empty-paddingvar(--van-padding-xl) 0组件内边距--van-empty-image-size160px图片容器尺寸--van-empty-description-margin-topvar(--van-padding-md)描述文字上边距--van-empty-description-padding0 60px描述文字内边距--van-empty-description-colorvar(--van-text-color-2)描述文字颜色--van-empty-description-font-sizevar(--van-font-size-md)描述文字字号--van-empty-description-line-heightvar(--van-line-height-md)描述文字行高--van-empty-bottom-margin-top24px底部内容上边距这些变量的默认值定义在 index.less 的:root/:host中并由.van-empty、__image、__description、__bottom等 BEM 类逐一消费。由于整个空状态区域使用flex-direction: columnalign-items: center布局见 index.less调整描述文字宽度时只需覆盖--van-empty-description-padding即可。说明CSS 变量名与EmptyThemeVars中emptyDescriptionLineHeight等小驼峰键一一对应参考 types.ts。另外在深色模式下组件会自动应用.van-theme-dark .van-empty { opacity: 0.5; }见 index.less降低整块插画的视觉亮度以适配暗色背景。通过 ConfigProvider 全局配置结合 Vant 的 ConfigProvider 组件可以按主题统一覆盖空状态样式例如van-config-provider :theme-vars{ emptyDescriptionColor: #969799, emptyImageSize: 140px, } van-empty description暂无数据 / /van-config-provider这样无需逐个页面改动即可在全局或局部作用域内统一空状态的图片尺寸与描述颜色与组件文档中使用 CSS 变量定制样式的思路完全一致。使用场景小结结合本文内容Empty组件在实战中的典型组合如下列表无数据van-empty description暂无数据 /接口报错imageerror 底部插槽放置重新加载按钮搜索无结果imagesearch 引导用户更换关键词的文案断网提示imagenetwork并可配合image-size控制插画在页面中的视觉占比品牌定制通过image传入品牌插画 URL或使用image插槽完全替换内置 SVG。组件全部样式与结构均围绕图片 → 描述 → 底部操作三段式布局组织见 index.less内置插画零网络开销配合本文的 Props、Slots 与 CSS 变量说明即可快速构建与业务视觉一致的移动端空状态方案。【免费下载链接】vantA lightweight, customizable Vue UI library for mobile web apps.项目地址: https://gitcode.com/GitHub_Trending/va/vant创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考