Element Plus Badge 徽标组件完全指南从基础用法到源码级原理【免费下载链接】element-plus A Vue.js 3 UI Library made by Element team项目地址: https://gitcode.com/GitHub_Trending/el/element-plusBadge徽标是 Element PlusVue 3 UI 组件库中用于在按钮、图标等元素右上角展示数字、状态标记的轻量级组件典型场景包括未读消息数购物车数量版本更新提示等。本文以官方文档 docs/en-US/component/badge.md 为核心结合组件源码、主题样式与单元测试系统讲解 Badge 的全部 API、使用技巧与底层渲染机制读完即可在生产项目中熟练驾驭数字徽标、自定义内容、红点与偏移定位等能力。基础用法用 value 展示数字或文本Badge 最核心的能力是通过value属性展示徽标内容value同时接受number与string两种类型传入数字时显示数值传入字符串时原样渲染文本。当组件包裹了默认插槽内容如按钮时徽标会自动定位在右上角。template el-badge :value12 classitem el-buttoncomments/el-button /el-badge el-badge :value3 classitem el-buttonreplies/el-button /el-badge el-badge :value1 classitem typeprimary el-buttoncomments/el-button /el-badge el-badge :value2 classitem typewarning el-buttonreplies/el-button /el-badge el-badge :value1 classitem colorgreen el-buttoncustom background/el-button /el-badge /template该示例对应官方演示 docs/examples/badge/basic.vue展示了三种典型形态独立数字徽标、通过type切换语义色、通过color自定义背景色。从源码看value的声明位于 packages/components/badge/src/badge.ts其类型为[String, Number]默认值为value: { type: [String, Number], default: , },而徽标最终显示内容由 packages/components/badge/src/badge.vue 中的content计算属性决定const content computedstring(() { if (props.isDot) return if (isNumber(props.value) isNumber(props.max)) { return props.max props.value ? ${props.max} : ${props.value} } return ${props.value} })值得注意的细节当value与max均为数字时走封顶分支只要二者之一不是数字例如字符串就直接用字符串模板输出value这正是字符串值可显示自定义文本的原理。单元测试 packages/components/badge/tests/badge.test.tsx 验证了value{80}时渲染文本为80。最大值封顶max 的显示规则当消息数量过大如 200 条未读时UI 上通常需要压缩为99的形式。通过max属性可以自定义封顶阈值当value超过max时徽标显示为{max}。template el-badge :value200 :max99 classitem el-buttoncomments/el-button /el-badge el-badge :value100 :max10 classitem el-buttonreplies/el-button /el-badge /template该示例对应官方演示 docs/examples/badge/max.vue200 99显示99100 10显示10。必须注意max 仅对数字生效max的默认值是99见 badge.ts且只在value是数字时生效。这是由content计算属性中的isNumber(props.value) isNumber(props.max)双重判断保证的——如果value传的是字符串如newmax会被完全忽略。测试用例 badge.test.tsx 对max的动态变化做了覆盖value从 200 变为 80 时显示内容从100变为80证明该计算是响应式的。自定义内容字符串 value 与 content 插槽除了数字Badge 还支持完全自定义的展示内容有两种途径1. 直接传入字符串value传字符串时徽标直接显示该文本适合newhot等场景el-badge valuenew classitem el-buttoncomments/el-button /el-badge el-badge valuehot classitem el-buttonreplies/el-button /el-badge2. 使用 content 插槽2.9.1从 2.9.1 版本起官方提供content具名插槽插槽作用域暴露{ value: string }即最终计算出的徽标文本让你能自由组合图标、文字甚至任意模板结构el-badge value99 classitem el-buttonshare/el-button template #content{ value } div classcustom-content el-icon Message / /el-icon span{{ value }}/span /div /template /el-badge上述示例来自官方演示 docs/examples/badge/customize.vue在徽标内渲染了图标 数字的组合。对应的渲染实现见 badge.vueslot namecontent :valuecontent {{ content }} /slot即提供content插槽时优先渲染插槽内容否则回退到{{ content }}文本输出。测试用例 badge.test.tsx 验证了 content 插槽可渲染自定义节点。提示default插槽用于包裹宿主元素如按钮content插槽用于定制徽标本身二者分工不同。红点模式is-dot当只需有更新的弱提示、不需要具体数字时可使用红点模式。设置is-dot属性后徽标渲染为一个 8×8 像素的圆点数字内容被忽略el-badge is-dot classitemquery/el-badge el-badge is-dot classitem el-button classshare-button :iconShare typeprimary / /el-badge该示例来自官方演示 docs/examples/badge/dot.vue。红点的视觉定义位于 packages/theme-chalk/src/badge.scssinclude when(dot) { height: 8px; width: 8px; padding: 0; right: 0; border-radius: 50%; }is-dot的声明为Boolean类型见 badge.ts默认false。源码中content计算属性对isDot有短路处理——为true时直接返回空字符串确保红点模式下不渲染任何文本。偏移定位offset2.7.0从 2.7.0 版本开始Badge 支持通过offset属性微调徽标相对默认位置的偏移量。其格式为[left, top]的二元数组分别表示相对默认位置向右left和向下top的偏移el-badge classitem :value1 :offset[10, 5] el-buttonoffset/el-button /el-badge示例来自官方演示 docs/examples/badge/offset.vue。offset默认值为[0, 0]见 badge.ts。偏移的底层实现原理从源码 badge.vue 可以看出offset并不是直接移动元素而是通过负margin-right与正margin-top实现const style computedStyleValue(() { return [ { backgroundColor: props.color, marginRight: addUnit(-props.offset[0]), marginTop: addUnit(props.offset[1]), }, props.badgeStyle ?? {}, ] })addUnit来自element-plus/utils负责为数值自动追加单位。由于徽标默认固定在右上角见下方固定定位分析向右移动对应减小margin-right因此取负值向下移动对应增加margin-top。测试 badge.test.tsx 精确断言了offset{[10, 10]}时生成的样式为margin-right: -10px与margin-top: 10px。隐藏、零值控制与自定义颜色除官方演示覆盖的能力外badge.md的 API 表还列出了三个高频属性这里结合源码补充说明。hidden完全隐藏徽标hidden为Boolean默认false。它并非通过 CSS 隐藏而是直接从 DOM 树中移除sup元素——见 badge.vue 的v-if!hidden (content || isDot || $slots.content)条件。测试用例 badge.test.tsx 验证了hidden切换时元素的存在与消失。show-zero是否显示零值2.6.0show-zero默认true即value为 0 时仍显示0。设为false后零值徽标会被添加is-hide-zero类由样式 badge.scss 的display: none隐藏include when(hide-zero) { display: none; }注意一个边界行为见 badge.test.tsx若同时设置了负数max如max{-1}且value为 0由于max value显示内容会变成-1而非 0此时show-zero不再生效——因为显示的文本本身已非 0。color自定义背景色2.6.3color为String类型直接作为内联background-color注入见 badge.vue优先级高于type决定的主题色。测试 badge.test.tsx 验证了colorblue会生成background-color: blue样式。API 参考Attributes名称说明类型默认值value显示值string/numbermax最大值超出后显示{max}仅在 value 为数字时生效number99is-dot是否显示为小圆点booleanfalsehidden是否隐藏徽标booleanfalsetype徽标类型primary \| success \| warning \| danger \| infodangershow-zero ^(2.6.0)value 为 0 时是否显示徽标booleantruecolor ^(2.6.3)圆点背景色string—offset ^(2.7.0)徽标偏移量[number, number][0, 0]badge-style ^(2.7.1)徽标自定义样式CSSProperties—badge-class ^(2.7.1)徽标自定义类名string—以上参数均可在 packages/components/badge/src/badge.ts 的badgeProps中找到完整声明与默认值定义。Slots名称说明类型default自定义默认内容宿主元素—content ^(2.9.1)自定义徽标内容{ value: string }通过 ref 访问实例Badge 通过defineExpose暴露了content计算属性见 badge.vue对应的实例类型BadgeInstance定义在 packages/components/badge/src/instance.ts可在需要程序化读取当前徽标文本时使用。渲染机制与样式体系解析组件结构与 BEM 命名Badge 的模板结构非常精简badge.vue外层div.el-badge包裹默认插槽内层sup渲染徽标并整体包在el-zoom-in-center过渡动画中。命名空间由useNamespace(badge)生成。transition :name${ns.namespace.value}-zoom-in-center sup v-if!hidden (content || isDot || $slots.content) :class[ ns.e(content), ns.em(content, type), ns.is(fixed, !!$slots.default), ns.is(dot, isDot), ns.is(hide-zero, !showZero value 0), badgeClass, ] :stylestyle slot namecontent :valuecontent {{ content }} /slot /sup /transition固定定位is-fixed从类名生成逻辑可以看出只要提供了默认插槽宿主元素徽标就会获得is-fixed类从而采用绝对定位固定在右上角。对应样式见 badge.scssinclude when(fixed) { position: absolute; top: 0; right: calc(1px #{getCssVar(badge, size)} / 2); transform: translateY(-50%) translateX(100%); z-index: getCssVar(index, normal); }反之若 Badge 单独使用无默认插槽则退化为普通内联元素不会绝对定位。测试 badge.test.tsx 专门断言了带默认插槽时is-fixed类的存在。类型色与 CSS 变量type的五个取值primary / success / warning / danger / info通过 SCSS 循环生成对应背景色badge.scss颜色值取自$badge主题变量并支持通过--el-badge-*CSS 变量进行主题定制。默认danger即红色系这也是红点模式的默认底色来源。注册与使用在完整引入 Element Plus 时ElBadge已随插件自动注册。若按需引入可以从element-plus导入组件及其样式import { ElBadge } from element-plus import element-plus/es/components/badge/style/css组件的安装封装位于 packages/components/badge/index.ts通过withInstall(Badge)提供全局注册能力样式入口为 packages/components/badge/style/index.ts引入后即可在模板中使用el-badge。小结Badge 是 Element Plus 中 API 面小但细节丰富的组件value双类型决定了数字/文本两种形态max封顶只在数字场景生效content插槽2.9.1提供了最大限度的自定义空间offset2.7.0通过负 margin 实现精确偏移is-fixed/is-hide-zero/el-zoom-in-center等类名则展示了 BEM 命名与主题变量的典型实践。结合 badge.vue、badge.ts 与 badge.test.tsx 阅读源码即可对徽标组件的渲染链路建立完整认知。【免费下载链接】element-plus A Vue.js 3 UI Library made by Element team项目地址: https://gitcode.com/GitHub_Trending/el/element-plus创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Element Plus Badge 徽标组件完全指南：从基础用法到源码级原理
Element Plus Badge 徽标组件完全指南从基础用法到源码级原理【免费下载链接】element-plus A Vue.js 3 UI Library made by Element team项目地址: https://gitcode.com/GitHub_Trending/el/element-plusBadge徽标是 Element PlusVue 3 UI 组件库中用于在按钮、图标等元素右上角展示数字、状态标记的轻量级组件典型场景包括未读消息数购物车数量版本更新提示等。本文以官方文档 docs/en-US/component/badge.md 为核心结合组件源码、主题样式与单元测试系统讲解 Badge 的全部 API、使用技巧与底层渲染机制读完即可在生产项目中熟练驾驭数字徽标、自定义内容、红点与偏移定位等能力。基础用法用 value 展示数字或文本Badge 最核心的能力是通过value属性展示徽标内容value同时接受number与string两种类型传入数字时显示数值传入字符串时原样渲染文本。当组件包裹了默认插槽内容如按钮时徽标会自动定位在右上角。template el-badge :value12 classitem el-buttoncomments/el-button /el-badge el-badge :value3 classitem el-buttonreplies/el-button /el-badge el-badge :value1 classitem typeprimary el-buttoncomments/el-button /el-badge el-badge :value2 classitem typewarning el-buttonreplies/el-button /el-badge el-badge :value1 classitem colorgreen el-buttoncustom background/el-button /el-badge /template该示例对应官方演示 docs/examples/badge/basic.vue展示了三种典型形态独立数字徽标、通过type切换语义色、通过color自定义背景色。从源码看value的声明位于 packages/components/badge/src/badge.ts其类型为[String, Number]默认值为value: { type: [String, Number], default: , },而徽标最终显示内容由 packages/components/badge/src/badge.vue 中的content计算属性决定const content computedstring(() { if (props.isDot) return if (isNumber(props.value) isNumber(props.max)) { return props.max props.value ? ${props.max} : ${props.value} } return ${props.value} })值得注意的细节当value与max均为数字时走封顶分支只要二者之一不是数字例如字符串就直接用字符串模板输出value这正是字符串值可显示自定义文本的原理。单元测试 packages/components/badge/tests/badge.test.tsx 验证了value{80}时渲染文本为80。最大值封顶max 的显示规则当消息数量过大如 200 条未读时UI 上通常需要压缩为99的形式。通过max属性可以自定义封顶阈值当value超过max时徽标显示为{max}。template el-badge :value200 :max99 classitem el-buttoncomments/el-button /el-badge el-badge :value100 :max10 classitem el-buttonreplies/el-button /el-badge /template该示例对应官方演示 docs/examples/badge/max.vue200 99显示99100 10显示10。必须注意max 仅对数字生效max的默认值是99见 badge.ts且只在value是数字时生效。这是由content计算属性中的isNumber(props.value) isNumber(props.max)双重判断保证的——如果value传的是字符串如newmax会被完全忽略。测试用例 badge.test.tsx 对max的动态变化做了覆盖value从 200 变为 80 时显示内容从100变为80证明该计算是响应式的。自定义内容字符串 value 与 content 插槽除了数字Badge 还支持完全自定义的展示内容有两种途径1. 直接传入字符串value传字符串时徽标直接显示该文本适合newhot等场景el-badge valuenew classitem el-buttoncomments/el-button /el-badge el-badge valuehot classitem el-buttonreplies/el-button /el-badge2. 使用 content 插槽2.9.1从 2.9.1 版本起官方提供content具名插槽插槽作用域暴露{ value: string }即最终计算出的徽标文本让你能自由组合图标、文字甚至任意模板结构el-badge value99 classitem el-buttonshare/el-button template #content{ value } div classcustom-content el-icon Message / /el-icon span{{ value }}/span /div /template /el-badge上述示例来自官方演示 docs/examples/badge/customize.vue在徽标内渲染了图标 数字的组合。对应的渲染实现见 badge.vueslot namecontent :valuecontent {{ content }} /slot即提供content插槽时优先渲染插槽内容否则回退到{{ content }}文本输出。测试用例 badge.test.tsx 验证了 content 插槽可渲染自定义节点。提示default插槽用于包裹宿主元素如按钮content插槽用于定制徽标本身二者分工不同。红点模式is-dot当只需有更新的弱提示、不需要具体数字时可使用红点模式。设置is-dot属性后徽标渲染为一个 8×8 像素的圆点数字内容被忽略el-badge is-dot classitemquery/el-badge el-badge is-dot classitem el-button classshare-button :iconShare typeprimary / /el-badge该示例来自官方演示 docs/examples/badge/dot.vue。红点的视觉定义位于 packages/theme-chalk/src/badge.scssinclude when(dot) { height: 8px; width: 8px; padding: 0; right: 0; border-radius: 50%; }is-dot的声明为Boolean类型见 badge.ts默认false。源码中content计算属性对isDot有短路处理——为true时直接返回空字符串确保红点模式下不渲染任何文本。偏移定位offset2.7.0从 2.7.0 版本开始Badge 支持通过offset属性微调徽标相对默认位置的偏移量。其格式为[left, top]的二元数组分别表示相对默认位置向右left和向下top的偏移el-badge classitem :value1 :offset[10, 5] el-buttonoffset/el-button /el-badge示例来自官方演示 docs/examples/badge/offset.vue。offset默认值为[0, 0]见 badge.ts。偏移的底层实现原理从源码 badge.vue 可以看出offset并不是直接移动元素而是通过负margin-right与正margin-top实现const style computedStyleValue(() { return [ { backgroundColor: props.color, marginRight: addUnit(-props.offset[0]), marginTop: addUnit(props.offset[1]), }, props.badgeStyle ?? {}, ] })addUnit来自element-plus/utils负责为数值自动追加单位。由于徽标默认固定在右上角见下方固定定位分析向右移动对应减小margin-right因此取负值向下移动对应增加margin-top。测试 badge.test.tsx 精确断言了offset{[10, 10]}时生成的样式为margin-right: -10px与margin-top: 10px。隐藏、零值控制与自定义颜色除官方演示覆盖的能力外badge.md的 API 表还列出了三个高频属性这里结合源码补充说明。hidden完全隐藏徽标hidden为Boolean默认false。它并非通过 CSS 隐藏而是直接从 DOM 树中移除sup元素——见 badge.vue 的v-if!hidden (content || isDot || $slots.content)条件。测试用例 badge.test.tsx 验证了hidden切换时元素的存在与消失。show-zero是否显示零值2.6.0show-zero默认true即value为 0 时仍显示0。设为false后零值徽标会被添加is-hide-zero类由样式 badge.scss 的display: none隐藏include when(hide-zero) { display: none; }注意一个边界行为见 badge.test.tsx若同时设置了负数max如max{-1}且value为 0由于max value显示内容会变成-1而非 0此时show-zero不再生效——因为显示的文本本身已非 0。color自定义背景色2.6.3color为String类型直接作为内联background-color注入见 badge.vue优先级高于type决定的主题色。测试 badge.test.tsx 验证了colorblue会生成background-color: blue样式。API 参考Attributes名称说明类型默认值value显示值string/numbermax最大值超出后显示{max}仅在 value 为数字时生效number99is-dot是否显示为小圆点booleanfalsehidden是否隐藏徽标booleanfalsetype徽标类型primary \| success \| warning \| danger \| infodangershow-zero ^(2.6.0)value 为 0 时是否显示徽标booleantruecolor ^(2.6.3)圆点背景色string—offset ^(2.7.0)徽标偏移量[number, number][0, 0]badge-style ^(2.7.1)徽标自定义样式CSSProperties—badge-class ^(2.7.1)徽标自定义类名string—以上参数均可在 packages/components/badge/src/badge.ts 的badgeProps中找到完整声明与默认值定义。Slots名称说明类型default自定义默认内容宿主元素—content ^(2.9.1)自定义徽标内容{ value: string }通过 ref 访问实例Badge 通过defineExpose暴露了content计算属性见 badge.vue对应的实例类型BadgeInstance定义在 packages/components/badge/src/instance.ts可在需要程序化读取当前徽标文本时使用。渲染机制与样式体系解析组件结构与 BEM 命名Badge 的模板结构非常精简badge.vue外层div.el-badge包裹默认插槽内层sup渲染徽标并整体包在el-zoom-in-center过渡动画中。命名空间由useNamespace(badge)生成。transition :name${ns.namespace.value}-zoom-in-center sup v-if!hidden (content || isDot || $slots.content) :class[ ns.e(content), ns.em(content, type), ns.is(fixed, !!$slots.default), ns.is(dot, isDot), ns.is(hide-zero, !showZero value 0), badgeClass, ] :stylestyle slot namecontent :valuecontent {{ content }} /slot /sup /transition固定定位is-fixed从类名生成逻辑可以看出只要提供了默认插槽宿主元素徽标就会获得is-fixed类从而采用绝对定位固定在右上角。对应样式见 badge.scssinclude when(fixed) { position: absolute; top: 0; right: calc(1px #{getCssVar(badge, size)} / 2); transform: translateY(-50%) translateX(100%); z-index: getCssVar(index, normal); }反之若 Badge 单独使用无默认插槽则退化为普通内联元素不会绝对定位。测试 badge.test.tsx 专门断言了带默认插槽时is-fixed类的存在。类型色与 CSS 变量type的五个取值primary / success / warning / danger / info通过 SCSS 循环生成对应背景色badge.scss颜色值取自$badge主题变量并支持通过--el-badge-*CSS 变量进行主题定制。默认danger即红色系这也是红点模式的默认底色来源。注册与使用在完整引入 Element Plus 时ElBadge已随插件自动注册。若按需引入可以从element-plus导入组件及其样式import { ElBadge } from element-plus import element-plus/es/components/badge/style/css组件的安装封装位于 packages/components/badge/index.ts通过withInstall(Badge)提供全局注册能力样式入口为 packages/components/badge/style/index.ts引入后即可在模板中使用el-badge。小结Badge 是 Element Plus 中 API 面小但细节丰富的组件value双类型决定了数字/文本两种形态max封顶只在数字场景生效content插槽2.9.1提供了最大限度的自定义空间offset2.7.0通过负 margin 实现精确偏移is-fixed/is-hide-zero/el-zoom-in-center等类名则展示了 BEM 命名与主题变量的典型实践。结合 badge.vue、badge.ts 与 badge.test.tsx 阅读源码即可对徽标组件的渲染链路建立完整认知。【免费下载链接】element-plus A Vue.js 3 UI Library made by Element team项目地址: https://gitcode.com/GitHub_Trending/el/element-plus创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考