定价

Chip 使用手册

v1.2.0 · @snowui-design-system/components

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

组件介绍

以紧凑的行内标签展示分类、状态或简短信息，可与文字、图标和列表内容自然组合。

使用选择

用于紧凑的内容标识与组合。选择、移除或点击行为应按公开 API 声明；不要把纯展示 Chip 自动视为按钮或复选框。

  • 默认变体内置圆点，background 变体默认不显示圆点；showDot 可显式改变。

  • as="leading" 可替换圆点，as="trailing" 添加尾部内容；动态改变尺寸时显式传 size。

快速开始

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

<script lang="ts">	import { Chip } from '@snowui-design-system/components';</script> <div style="display: flex; flex-direction: column; gap: var(--gap-4) var(--gap-3); align-items: center; width: min(100%, 40rem);">    <div style="display: flex; align-items: center; flex-wrap: wrap; gap: var(--gap-4) var(--gap-3); justify-content: center;">            <Chip variant="default" style="color: var(--secondary-purple);">Featured</Chip><Chip variant="default" style="color: var(--secondary-indigo);">Planned</Chip><Chip variant="default" style="color: var(--secondary-blue);">In progress</Chip><Chip variant="default" style="color: var(--secondary-green);">Ready</Chip><Chip variant="default" style="color: var(--secondary-orange);">In review</Chip><Chip variant="default" style="color: var(--secondary-red);">Needs fixes</Chip><Chip variant="default" style="color: var(--black-40);">Draft</Chip><Chip variant="default" style="color: var(--black-100);">Archived</Chip>        </div><div style="display: flex; align-items: center; flex-wrap: wrap; gap: var(--gap-4) var(--gap-3); justify-content: center;">            <Chip variant="background" style="color: var(--secondary-purple);">Featured</Chip><Chip variant="background" style="color: var(--secondary-indigo);">Planned</Chip><Chip variant="background" style="color: var(--secondary-blue);">In progress</Chip><Chip variant="background" style="color: var(--secondary-green);">Ready</Chip><Chip variant="background" style="color: var(--secondary-orange);">In review</Chip><Chip variant="background" style="color: var(--secondary-red);">Needs fixes</Chip><Chip variant="background" style="color: var(--black-40);">Draft</Chip><Chip variant="background" style="color: var(--black-100);">Archived</Chip>        </div></div>

API

关键字 类型 默认值 描述
variant "default" | "background" "default" 视觉变体。default 默认显示内置 Dot；background 增加色块背景与 0.5px 边框，默认不显示 Dot
size "sm" | "lg" — 显式值优先；未传时在组件创建时读取父级数值尺寸 Context 快照，≤12 使用 sm，>12 使用 lg；无数值 Context 时回退 sm。不跟随后续父级尺寸变化；动态切换请显式传入 size。sm 文字 12/16，lg 文字 14/20
showDot boolean — 未传时随 variant 解析：default 显示、background 隐藏。显式 true / false 开启或关闭内置 Dot；存在外置 leading 时始终隐藏内置 Dot
children Snippet — 无参数内容片段，渲染标签正文和可选 leading / trailing 子项。SnowUI 组件通过 as="leading" / as="trailing" 声明角色；外置 leading 替换内置 Dot

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

使用边界与详细说明

布局模型

主布局模型：槽位宿主布局（三槽位：leading / content / trailing）。 通过 <Frame singleLine> 输出 data-auto-layout，复用 auto-layout.css（源码参考：components/src/styles/auto-layout.css） 的三槽位 grid 模板，子元素以 data-as="leading" | "trailing" 声明角色。

默认 Leading 图标 (Built-in)

default 默认带前置 Dot，background 默认不显示；可通过 showDot 显式控制：

  • 形状：内联 SVG，viewBox 0 0 32 32，圆心 (16, 16)，半径 6，fill="currentColor"

  • 大小：sm 12 × 12px；lg 16 × 16px（由 --snowui-chip-icon-size 变量驱动）

  • 颜色：currentColor，跟随父级字色

内置图标替换规则（强制）

遵循 ComponentGuidelines.md §2.7.1（源码参考：specs/maintainers/ComponentGuidelines.md）。当外部传入 data-as="leading"（原生 HTML）或 as="leading"（SnowUI 大写组件）的子元素时，组件自动隐藏内置 Dot：

 <Chip>Label</Chip>  <Chip>    <Icon as="leading"><CheckCircle /></Icon>    Label</Chip>  <Chip>    Label    <Icon as="trailing"><X /></Icon></Chip>

颜色规则

  • 默认颜色：color: inherit，即继承父容器文字颜色（currentColor）。组件内部不内置任何颜色变体。

  • 多色实现：通过外部传入工具类（如 text-purple、text-red）或内联 style="color: ..." 改变 color。

  • 背景与边框联动：background 变体下，背景与边框基于 currentColor + 透明度自动派生：

    • 背景：color-mix(in srgb, currentColor 10%, transparent)

    • 边框：inset 0 0 0 0.5px color-mix(in srgb, currentColor 20%, transparent)（使用 inset box-shadow，避免占用布局空间）

修改文字颜色 → 背景与边框同步变化，无需额外 prop / 变量。

布局变量链

变量 默认来源 用途
--snowui-chip-font-size var(--text-12)（lg：var(--text-14)) 文字字号
--snowui-chip-line-height var(--leading-12)（lg：var(--leading-14)) 文字行高
--snowui-chip-gap var(--gap-1) 单行图文间距；实际至少4 CSS px，保留更大首选间距。Tag内部例外不适用于Chip。
--snowui-chip-icon-size 12px（sm）/ 16px（lg） 默认 Dot 尺寸
--snowui-chip-padding 0（default）/ 2px 8px（sm+bg）/ 4px 12px（lg+bg） 内边距
--snowui-chip-radius 0（default）/ 9999px（background） 圆角
--snowui-chip-bg transparent / color-mix(... 10%) 背景
--snowui-chip-shadow none / inset 0 0 0 0.5px color-mix(... 20%) 描边

用法示例

 <Chip>Label</Chip>  <Chip size="lg">Label</Chip>  <Chip variant="background">Label</Chip>  <Chip variant="background" showDot>Label</Chip>  <Chip variant="background" size="lg">Label</Chip>  <Chip variant="background" class="text-purple">Purple</Chip><Chip variant="background" class="text-red">Red</Chip>  <Chip>    <Icon as="leading"><Star /></Icon>    Featured</Chip>  <Chip variant="background">    Filter    <Icon as="trailing"><X /></Icon></Chip>

Chip 样式覆盖

先阅读 完整 LICENSE；同任务、同版本、同范围去重。

优先用组件公开 Props 匹配合适样式，尽可能保留原有视觉。确需改写时按 样式选择与改写顺序 使用自己的 class（含项目已有 Tailwind）或实例 style。以下名称来自源码实际消费的公开 override；先核对目标作用域，不修改私有 DOM。采用 SnowUI Token 时选择正确类别，外部应用不被要求安装一方 utilities。

变量 用途与默认参考
--snowui-chip-background-override 背景色（默认 color-mix(currentColor 10%, transparent)）
--snowui-chip-font-size-override font-size（默认 sm=var(--text-12) lg=var(--text-14)）
--snowui-chip-gap-override gap（默认 0）
--snowui-chip-line-height-override line-height（默认 sm=var(--leading-12) lg=var(--leading-14)）
--snowui-chip-padding-override background：sm=2px 8px，lg=4px 12px；图标侧 sm=4px、lg=8px
--snowui-chip-radius-override border-radius（仅 background 生效，默认 9999px）
--snowui-chip-shadow-override 描边 inset box-shadow（默认 0 0 0 0.5px color-mix(currentColor 20%, transparent)）

设计指南 · Token · 组合边界

Chip 类型与状态

必填属性：无具名必填属性。

可双向绑定：本组件未声明具名双向绑定属性；状态更新通过公开回调或所属宿主处理。

继承声明：Omit<FrameProps, "size">。继承能力以基类公开文档为准；Omit 中的字段已排除，不能按基类原样使用。

共享 Frame API · 返回 API

以下为公开属性实际引用的类型声明，来自源码；Svelte Snippet 表示内容片段，ComponentProps 表示对应组件的 Props。