Vant Badge 徽标组件完全指南从基础用法到源码级定位原理【免费下载链接】vantA lightweight, customizable Vue UI library for mobile web apps.项目地址: https://gitcode.com/GitHub_Trending/va/vant导读Vant 的Badge徽标组件用于在子元素右上角展示一个小徽标或红点是电商、社交类移动端应用中未读消息数购物车数量上新提醒等场景的标准视觉元素。本文以 packages/vant/src/badge/README.md 为核心结合 Badge.tsx 实现、index.spec.ts 测试用例与 index.less 样式源码带你完整掌握 Badge 的全部 Props、插槽、类型导出与主题定制能力并深入理解offset偏移与show-zero隐藏规则的底层实现原理。安装与组件注册Vant 组件统一支持按需注册。通过app.use全局注册 Badge 组件import { createApp } from vue; import { Badge } from vant; const app createApp(); app.use(Badge);除了app.use(Badge)全局注册外还可参考 advanced-usage 文档 中介绍的按需引入、全量引入等其他注册方式。注册后即可在模板中使用van-badge标签。从源码看index.ts 通过 Vant 统一的withInstall工具将组件挂载为可安装插件同时声明了VanBadge的全局组件类型declare module vue的GlobalComponents因此在 TypeScript 项目中无需额外类型声明即可获得完整的模板类型提示。基础用法Badge 最常见的用法是包裹一个子元素将徽标定位在其右上角。content属性用于设置徽标内容可以是数字或字符串设置dot属性则仅展示一个红点van-badge :content5 div classchild / /van-badge van-badge :content10 div classchild / /van-badge van-badge contentHot div classchild / /van-badge van-badge dot div classchild / /van-badge style .child { width: 40px; height: 40px; background: #f2f3f5; border-radius: 4px; } /style说明content支持number | string演示中的Hot即为字符串内容适合展示促销文字等场景dot为true时渲染纯色圆点此时content不生效官方演示代码见 demo/index.vue其中.child只是一个 40×40 的占位方块实际使用中可替换为任意图片、图标或 DOM 元素。隐藏规则show-zero值得注意的是当content为0时默认仍然会展示徽标show-zero默认值为true。如果你希望数字归零时自动隐藏徽标这是消息类业务的常见需求将show-zero设为false即可van-badge :content0 :show-zerofalse div classchild / /van-badge该行为有明确的测试用例佐证见 index.spec.ts默认渲染content: 0时.van-badge存在设置showZero: false后该节点消失。最大值截断max当content为数字且超过max时徽标内容自动显示为{max}。典型场景是未读消息数超过 99 条时展示 99van-badge :content20 max9 div classchild / /van-badge van-badge :content50 max20 div classchild / /van-badge van-badge :content200 max99 div classchild / /van-badge以上三个示例分别渲染为9、20、99。max的类型为number | string且仅在content为数字或纯数字字符串时生效。在 Badge.tsx 中该逻辑通过isNumeric(content!) content max判断后返回${max}注意这里使用的是数值比较因此content200与content{200}的行为一致。自定义颜色通过color属性可以设置徽标背景色默认值为#ee0a24Vant 危险色van-badge :content5 color#1989fa div classchild / /van-badge van-badge :content10 color#1989fa div classchild / /van-badge van-badge dot color#1989fa div classchild / /van-badge源码实现中color直接作为内联background样式应用见 Badge.tsx因此优先级高于 CSS 变量--van-badge-background适合按业务场景单独定制颜色。自定义徽标内容content 插槽content插槽用于完全自定义徽标内部内容最常见的用法是嵌入图标。插槽内容会替换content属性的展示逻辑源码中hasContent()优先判断是否存在slots.contentvan-badge div classchild / template #content van-icon namesuccess classbadge-icon / /template /van-badge van-badge div classchild / template #content van-icon namecross classbadge-icon / /template /van-badge van-badge div classchild / template #content van-icon namedown classbadge-icon / /template /van-badge配合以下样式让图标在徽标内居中.badge-icon { display: block; font-size: 10px; line-height: 16px; }对应测试见 index.spec.tscontent插槽传入Custom Content时会按插槽内容渲染。自定义位置position默认情况下徽标位于子元素右上角top-right。position属性支持在四个角之间切换van-badge :content10 positiontop-left div classchild / /van-badge van-badge :content10 positionbottom-left div classchild / /van-badge van-badge :content10 positionbottom-right div classchild / /van-badgeposition可取值top-left、top-right默认、bottom-left、bottom-right。从源码看该属性对应的 BEM 修饰类由 index.less 实现四个位置分别通过top/right/bottom/left: 0结合translate平移将徽标钉在对应角上例如top-right为transform: translate(50%, -50%)且--fixed类只在存在默认插槽包裹子元素时生效保证徽标相对子元素绝对定位。独立展示StandaloneBadge 并不强制要求包裹子元素。不传默认插槽时徽标会作为独立元素渲染适合直接在页面任意位置摆放van-badge :content20 / van-badge :content200 max99 /渲染逻辑在 Badge.tsx存在slots.default时返回van-badge__wrapper包裹结构position: relative的容器见 index.less否则直接返回徽标本身。这也解释了为何独立展示时无法使用position的四角定位没有相对容器此时offset会退化为以margin方式生效。偏移微调offsetoffset属性接收一个二元数组[x, y]分别对应水平与垂直偏移量用于对徽标位置进行精细微调van-badge :content5 :offset[4, 4] div classchild / /van-badge其行为细节值得展开数组中元素类型为number | string数字会自动追加px通过工具函数addUnit见 format.ts字符串则按原样使用可传入2rem、4em等任意 CSS 单位包裹子元素时偏移量转换为对应方向的top/bottom/right/left内联样式且正负号会根据position自动取反——例如默认top-right下offset[2, 4]实际渲染为top: 4px; right: -2px向容器外侧移动独立展示无子元素时偏移退化为margin-top与margin-left生效。这些行为均有测试覆盖index.spec.ts覆盖了数字偏移、带单位的字符串偏移、负值、以及top-left/bottom-left/bottom-right三种位置下的偏移方向换算。完整 APIProps属性说明类型默认值content徽标内容当dot为false时生效number | string-color背景颜色string#ee0a24dot是否展示为圆点booleanfalsemax最大值超过后展示{max}仅在 content 为数字时生效number | string-offset徽标偏移量数组两项分别对应水平与垂直偏移[number | string, number | string]-show-zerocontent 为 0 时是否展示徽标booleantrueposition徽标位置可选top-leftbottom-leftbottom-rightstringtop-right补充说明源码 Badge.tsx 中还存在一个未在文档 Props 表中列出的tag属性默认div用于自定义包裹子元素的 HTML 标签如span、li等需要更多语义化标签时可利用该属性。content的 Prop 声明使用 Vant 工具集中的numericProp即[Number, String]因此模板中content5与:content5均可。Slots名称说明default默认插槽即徽标包裹的子元素content自定义徽标内部内容类型定义组件导出了完整的 TypeScript 类型可按需引入import type { BadgeProps, BadgePosition } from vant;其中BadgeProps由ExtractPropTypestypeof badgeProps推导而来BadgePosition为top-left | top-right | bottom-left | bottom-right联合类型见 Badge.tsx。此外 index.ts 还导出了BadgeThemeVars用于配合主题定制时的类型约束。主题定制CSS 变量Badge 的所有样式均通过 CSS 变量驱动可在ConfigProvider组件中按需覆盖。完整的变量清单如下名称默认值说明--van-badge-size16px徽标最小宽度--van-badge-colorvar(--van-white)徽标文字颜色--van-badge-padding0 3px徽标内边距--van-badge-font-sizevar(--van-font-size-sm)徽标字号--van-badge-font-weightvar(--van-font-bold)徽标字重--van-badge-border-widthvar(--van-border-width)徽标边框宽度--van-badge-backgroundvar(--van-danger-color)徽标背景色--van-badge-dot-colorvar(--van-danger-color)圆点背景色--van-badge-dot-size8px圆点直径--van-badge-font-apple-system-font, Helvetica Neue, Arial, sans-serif徽标字体族以上默认值声明于 index.less其中引用的--van-danger-color红色#ee0a24、--van-font-size-sm12px、--van-font-bold600、--van-radius-max999px用于徽标圆角等基础变量定义在 css-variables.less。!-- 通过 ConfigProvider 全局覆盖示例 -- van-config-provider :theme-vars{ badgeSize: 20px, badgeBackground: #07c160 } van-badge :content5 div classchild / /van-badge /van-config-provider主题定制的详细用法可参考 ConfigProvider 组件文档。同时types.ts 中定义的BadgeThemeVars提供了这些变量的 TypeScript 类型提示。源码实现速览三个核心渲染函数理解 Badge 的渲染逻辑只需抓住 Badge.tsx 中的三个函数hasContent()第 46-56 行决定徽标是否显示。优先看是否存在content插槽否则要求content有值且非空字符串并叠加show-zero规则showZero || (content ! 0 content ! 0)renderContent()第 58-72 行决定徽标显示什么。dot模式下返回空存在插槽时渲染插槽否则在超过max时返回${max}其余情况原样返回contentstyle计算属性第 77-111 行将color、offset结合position换算为具体的内联样式。包裹子元素时按方向写入top/right/bottom/left并自动处理符号取反独立展示时退化为margin。Badge 组件以 Vant 标准的createNamespace(badge)生成van-badge类名体系DOM 结构为van-badge__wrapper (child van-badge[--position][--dot][--fixed])与 index.less 的 BEM 选择器一一对应方便你按需覆写样式。整组行为均由 index.spec.ts 的 10 余个用例锁定涉及空内容、零值、偏移、位置、插槽等边界场景可作为你接入 Badge 时的行为参考基准。【免费下载链接】vantA lightweight, customizable Vue UI library for mobile web apps.项目地址: https://gitcode.com/GitHub_Trending/va/vant创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考