Badge 使用手册

许可阅读：首次阅读组件文档、源码或 npm 使用流程，先读完整 LICENSE；同任务同版本去重。公开 API 配置与内部实现修改分别按许可处理；全部组件使用统一运行包，源码权益以许可为准。

组件介绍

用紧凑的数字、文字或圆点提示未读数量与状态，可搭配按钮、头像和导航项使用。

使用选择

用于简短状态或数量提示。需要用户点击执行动作时使用 Button；输入中的可操作标签按 Chip 或 Tag 的交互选择。

• children 优先于 count；显式 dot 只显示圆点，不显示内容。

• 数量默认最大显示 99，零默认隐藏；使用 max / showZero 修改。Avatar 或 Icon 上的角标用 as="badge"。

快速开始

以下示例展示推荐的基本组合。更多场景与组合限制见后文。

<script lang="ts">	import { Avatar, Badge } from '@snowui-design-system/components';	import { AvatarAbstract03 } from '@snowui-design-system/resource-svelte';</script> <div style="display: flex; align-items: center; flex-wrap: wrap; gap: var(--gap-4) var(--gap-3);">	<Avatar fallbackColor="orange" aria-label="Release notifications" size={48}><Badge as="badge" count={5} /></Avatar>	<Avatar fallbackColor="cyan" aria-label="Documentation inbox" size={48} badgePosition="bottom"><Badge as="badge" count={120} max={99} color="Orange" /></Avatar>	<Avatar src={AvatarAbstract03} aria-label="New components" size={48}><Badge as="badge" count="New" color="Red" /></Avatar>	<Avatar fallbackColor="red" aria-label="Maintainer online" size={48} badgePosition="bottom"><Badge as="badge" dot color="Green" /></Avatar></div>

API

未重新声明的继承能力请查所属基础组件文档；本表只列本组件源码具名公开属性。

使用边界与详细说明

关键字 (Keyword)

布局模型

主布局模型：内联外壳布局。定义见 ../../../specs/maintainers/LayoutProtocol.md §12.4（源码参考：specs/maintainers/LayoutProtocol.md）。

Badge 的根节点是 inline-level 定位外壳，内容整体 Hug：

• 根节点保持 inline-flex，负责宿主定位、尺寸测量和 Frame 位移动效；默认 flex-shrink: 0，在窄横向容器内保留文字与内边距，不被相邻内容挤瘦。

• 内层 .snowui-badge-surface 负责 background / padding / radius / min-width / font-size / line-height，并作为完整视觉 Badge 承担 scale / opacity / blur 动效。

• 内部 snowui-morph-container 使用 Grid Stacking 保持数字变化时的布局稳定性；内容层以容器 50% 为锚点并回移自身 50%，固定尺寸小于文字最小宽度时仍以 Badge 中心为原点对称溢出，不依赖 Grid 的安全溢出回退。文字和数字均保持严格几何居中。这是 Badge 私有结构，不改变主布局模型。

• dot 模式仍属于内联外壳布局的特化：外壳收敛为固定点尺寸，padding 清零。

• as="badge" 只表示 Badge 作为 Icon / Avatar 的外层挂件角色，不改变 Badge 内部布局模型。

布局变量链：

variant="border" 复用 Kbd 默认描边视觉的同一组 Token 值，但仍保持 Badge 的状态标签语义与 <span>/Frame 外壳：

border 只作用于文本内容模式；dot 继续使用 Dot 视觉。作为 Button、SidebarItem 等宿主的后代时，border 保持文本 Hug，不继承宿主的固定方形尺寸上下文。 border 的内部 morph 文字层继承 var(--leading-12)，不使用 filled Badge 的紧凑 line-height: 1；因此可见高度与 Kbd 默认 border 一致。

color 使用 SnowUI 公共语意色协议，严格区分大小写：

<Badge count={1} color="Blue" /><Badge count={2} color="Red" /><Badge dot color="Green" /><Badge count="New" variant="border" />

角色化组合

 <Icon size={24}>    {#snippet badge()}        <Badge as="badge" count={5} />    {/snippet}    <Bell /></Icon>  <Badge count={99} max={99} /><Badge dot />

智能行为

1. 自动隐藏: count 模式默认仅在数值大于等于 1 时出现；数值为 0 且 showZero=false 时自动隐藏，退场期间保留最后一次可见值（例如从 1 退场，不显示 0）

2. 溢出格式化: 超过 max 自动显示为 max+

3. 自动内容: 无 count 时尝试从父元素获取文本

4. 角色感知尺寸继承:

   • 独立使用: 自动读取父级 Frame (如列表项容器) 的尺寸上下文完成自适应缩放。

   • 作为徽标 (as="badge"): 忽略负级 Group 的尺寸上下文，优先保持徽标比例并由宿主（Avatar/Icon）驱动定位。

默认动效

Badge 的显示 / 隐藏使用两条并行动效，与 transitions.dev Notification badge 的结构一致：

• Frame currentState="Appear/Disappear" 与 whileAppear / whileDisappear 负责定位外壳：出现时从左下偏移滑到锚点，退场时不反向位移。

• 内层 .snowui-badge-surface 是完整视觉外壳，负责 scale / opacity / blur：出现时整体从 scale(0)、opacity: 0、blur(2px) 回弹至正常状态；退场时以中心点将包括背景、padding 和数字在内的整个 Badge 缩小至 0。

• 内部 .snowui-morph-container 只负责 Grid Stacking 和内容居中，不承担出退场动效。

隐藏时 Badge 会短暂保留节点 180ms，再从 DOM 中移除。默认退场不做反向位移，只让 Badge 整体以中心点缩小、渐隐并增加模糊。whileAppear / whileDisappear={true} 使用 Badge 完整默认 Frame 动效；显式对象是完整视觉通道声明，只执行对象中声明的通道并继承 Badge 默认时序；传 false 可关闭对应 Frame 动效。prefers-reduced-motion: reduce 会关闭 slide / pop / blur 过渡。

私有动效变量：