Tag

标签：light/solid/ghost 三态，16 色板 + white，可关闭(closable)、可交互(onClick/keydown)、头像(avatarSrc)、AI 多彩(colorful/gradient)、前后缀图标。受控 visible 不回写，仅通过 onClose 通知。配套 TagGroup（折叠 +N）与 SplitTagGroup（连接式组合），对齐 Semi 同页三组件。

设计文档

如何引入

import { Tag, TagGroup, SplitTagGroup } from '@chenzy-design/svelte';

基本用法

内容用 Tag 包裹即可；closable 变为可关闭标签，点击 x 触发 onClose，在 onClose 内 preventDefault 可阻止默认隐藏。

default tag

Closable Tag

Closable Tag, Prevent Default

尺寸

默认定义大、小（默认）两种尺寸。

small tag

large tag

形状

支持 square（默认）与 circle 两种形状。

small circle tag

large circle tag

配置图标

通过 prefixIcon / suffixIcon 在内容前后添加图标。

Semi Design

D2C: figma to code in one click

颜色

支持默认色板的 16 种颜色和 white，也可通过 style 自定义颜色。

amber

blue

cyan

green

grey

indigo

light-blue

light-green

lime

orange

pink

purple

red

teal

violet

yellow

white

AI 风格 - 多彩标签

设置 colorful 获得多彩标签（字重与非多彩不同）；gradient 区分渐变色与单色，与 type 组合。

样式类型

三种样式类型：light 浅色底、ghost 白色底、solid 深色底。默认 light。

Semi Design Light Tag

D2C: figma to code in one click

Semi Design Ghost Tag

D2C: figma to code in one click

Semi Design Solid Tag

D2C: figma to code in one click

头像标签

设置 avatarSrc 生成头像标签，avatarShape 调整头像形状（square / circle）。

焦锐志

不可见的

通过 visible 属性控制标签是否可见。

Show

Hide

Invisible tag

TagGroup 使用

在 TagGroup 内通过 tagList 传入配置并设置 maxTagCount，超出显示为 +N；showPopover 控制 hover +N 时是否 Popover 弹层展示剩余。

TagGroup 可删除

TagGroup 中标签可删除时，在 onTagClose 中依据回传的 tagKey 处理 tagList（对齐 Semi onTagClose(tagChildren, e, tagKey)）。

SplitTagGroup 组合标签

使用 SplitTagGroup 将多个标签组合成整体：首尾标签圆角、中间圆角为 0，形成连续视觉效果。

标签一

标签二

标签三

组合

标签

示例

效果

SplitTagGroup 样式组合

子 Tag 保留自身颜色 / 类型，连接外观纯视觉不影响语义（light / ghost）。

浅色

组合

标签

镂空

样式

组合

API 参考

Tag

Props

属性	说明	类型	默认值
`type`	视觉风格	`'light'\|'solid'\|'ghost'`	'light'
`color`	语义色，对齐 Semi 16 色板 + white	`'amber'\|'blue'\|'cyan'\|'green'\|'grey'\|'indigo'\|'light-blue'\|'light-green'\|'lime'\|'orange'\|'pink'\|'purple'\|'red'\|'teal'\|'violet'\|'yellow'\|'white'`	'grey'
`size`	default 与 small 同高	`'small'\|'default'\|'large'`	'default'
`shape`	circle 用胶囊圆角	`'square'\|'circle'`	'square'
`closable`	尾部关闭按钮	`boolean`	false
`visible`	受控显隐；受控时不回写，仅 onClose 通知	`boolean`	undefined
`colorful`	AI 多彩标签：蓝→紫渐变，字重更重	`boolean`	false
`gradient`	渐变色，仅 colorful=true 时生效	`boolean`	false
`avatarSrc`	头像型 Tag 的图片地址	`string`	undefined
`avatarShape`	头像形状	`'square'\|'circle'`	'square'
`tagKey`	在 TagGroup 中的稳定标识	`string\|number`	undefined
`prefixIcon`	前置图标	`Snippet`	undefined
`suffixIcon`	后置图标（关闭图标始终最右）	`Snippet`	undefined
`children`	标签内容	`Snippet`	undefined
`onClose`	关闭回调；在回调内 e.preventDefault() 阻止默认隐藏	`(tagChildren, e, tagKey) => void`	undefined
`onClick`	单击回调；传入后标签变可交互(role=button/可聚焦/Enter 激活)	`(e) => void`	undefined
`onMouseEnter`	鼠标进入回调	`(e) => void`	undefined
`onKeyDown`	键盘事件回调（内部处理后触发）	`(e) => void`	undefined
`tabIndex`	可交互 Tag 的 tabIndex（TagInput 内用 -1）	`number`	undefined
`ariaLabel`	透传根元素可访问名（aria-label）	`string`	undefined
`class`	透传根类名	`string`	undefined
`style`	透传根内联样式	`string`	undefined

Events

事件	载荷	说明
`onClose`	`—`	关闭按钮点击（tagChildren, e, tagKey）
`onClick`	`—`	标签点击（clickable 时）
`onMouseEnter`	`—`	鼠标进入
`onKeyDown`	`—`	键盘按下

Slots

名称	说明
`children`	标签文本/内容
`prefixIcon`	前置图标
`suffixIcon`	后置图标

TagGroup

一组 Tag 成组渲染，超过 maxTagCount 折叠剩余为「+N」标签，showPopover 时 hover 在 Popover(showArrow/top) 弹层展示被折叠项。tagList 数据驱动。复用 Tag/Popover，严格对齐 Semi TagGroup。

Props

属性	说明	类型	默认值
`tagList`	数据驱动的标签数据	`TagItem[]`	[]
`maxTagCount`	最大数量限制，超出折叠为 +N	`number`	undefined
`restCount`	直接指定折叠数量（覆盖自动计算）	`number`	undefined
`size`	标签尺寸（透传各 Tag）	`'small'\|'default'\|'large'`	'default'
`avatarShape`	标签内头像形状（透传）	`'circle'\|'square'`	undefined
`showPopover`	hover +N 时是否 Popover 弹层展示剩余	`boolean`	false
`popoverProps`	弹层透传（复用本库 Popover）	`PopoverProps`	undefined
`onTagClose`	删除某标签回调（对齐 Semi）	`(tagChildren, e, tagKey) => void`	undefined
`onPlusNMouseEnter`	鼠标进入 +N 回调	`(e) => void`	undefined
`class`	透传根类名	`string`	undefined
`style`	透传根内联样式	`string`	undefined

SplitTagGroup

连接式标签组：多个 Tag 组合成整体（首子前缘圆角、末子后缘圆角、中间圆角为 0，相邻 1px 间隙），视觉上是一个分段控件。纯 CSS 装饰，无折叠；circle 子标签首末用胶囊圆角。严格对齐 Semi SplitTagGroup。

Props

属性	说明	类型	默认值
`ariaLabel`	组的可访问名（aria-label）	`string`	undefined
`class`	透传根类名	`string`	undefined
`style`	透传根内联样式	`string`	undefined
`children`	子 Tag（首尾自动加圆角、相邻合并边）	`Snippet`	undefined

设计变量

变量	默认值	用法
`--cd-tag-avatar-bg`	`var(--cd-color-bg-4)`	头像标签背景色（Semi $color-tag_avatar-bg-default）
`--cd-tag-avatar-border`	`var(--cd-color-border)`	头像标签描边色（Semi $color-tag_avatar-border-default）
`--cd-tag-avatar-square-img-bg`	`var(--cd-color-fill-1)`	方形头像图片背景色（Semi $color-tag_avatar_square_img-bg-default，近似 color-default）
`--cd-tag-avatar-text`	`var(--cd-color-text-0)`	头像标签文字色（Semi $color-tag_avatar-text-default）
`--cd-tag-close-icon-active`	`var(--cd-color-text-0)`	关闭按钮按下颜色（Semi $color-tag_close-icon-active）
`--cd-tag-close-icon-default`	`var(--cd-color-text-2)`	可删除标签删除按钮颜色（Semi $color-tag_close-icon-default）
`--cd-tag-close-icon-hover`	`var(--cd-color-text-1)`	关闭按钮悬浮颜色（Semi $color-tag_close-icon-hover）
`--cd-tag-colorful-from`	`#4d6bff`	colorful（AI 多彩）蓝→紫渐变起始色
`--cd-tag-colorful-to`	`#a64dff`	colorful（AI 多彩）蓝→紫渐变结束色
`--cd-tag-colorful-via`	`#7b5cff`	colorful（AI 多彩）蓝→紫渐变中间色

Tag

如何引入

基本用法

尺寸

形状

配置图标

颜色

AI 风格 - 多彩标签

样式类型

头像标签

不可见的

TagGroup 使用

TagGroup 可删除

SplitTagGroup 组合标签

SplitTagGroup 样式组合

API 参考

Tag

Props

Events

Slots

TagGroup

Props

SplitTagGroup

Props

Accessibility

设计变量