展示类

标签

标签是图形化标记界面上的元素的组件,达到快速识别、分组的目的。

代码演示

如何引入

<script lang="ts">
    import { Tag, TagGroup, SplitTagGroup } from '@fibrae/semi-ui-svelte';
</script>

基本用法

基本标签用法,将内容使用 <Tag> 标签包裹即可。
可以通过添加 closable 属性将其变为可关闭标签。

此时点击 x 关闭会调用 onClose(event, tagKey),在 onClose 中对事件调用 preventDefault 可以使其点击后依然显示不隐藏。标签内容写在 Tag 标签内,即 children snippet。

default tag
Closable Tag
Closable Tag, Prevent Default
代码
<script lang="ts">
    import { Space, Tag, type TagCloseEvent } from '@fibrae/semi-ui-svelte';

    const preventClose = (event: TagCloseEvent) => event.preventDefault();
</script>

<div>
    <Space>
        <Tag>default tag</Tag>
        <Tag closable>Closable Tag</Tag>
        <Tag closable onClose={preventClose}>Closable Tag, Prevent Default</Tag>
    </Space>
</div>

尺寸

默认定义了两种尺寸:大、小(默认)。

small tag
large tag
代码
<script lang="ts">
    import { Space, Tag } from '@fibrae/semi-ui-svelte';
</script>

<Space>
    <Tag color="light-blue" size="small">small tag</Tag>
    <Tag color="cyan" size="large">large tag</Tag>
</Space>

形状

默认定义了两种形状:square(默认)、circle。

small circle tag
large circle tag
代码
<script lang="ts">
    import { Space, Tag } from '@fibrae/semi-ui-svelte';
</script>

<Space>
    <Tag color="amber" shape="circle" size="small">small circle tag</Tag>
    <Tag color="violet" shape="circle" size="large">large circle tag</Tag>
</Space>

配置图标

通过 prefixIcon、suffixIcon snippet,可以在内容前后添加 Icon 图标:用 {#snippet prefixIcon()}...{/snippet} 写在 Tag 标签内,或定义后作为属性传入。

Semi Design
D2C: figma to code in one click
代码
<script lang="ts">
    import { IconGithubLogo, IconSemiLogo } from '@fibrae/semi-icons-svelte';
    import { Space, Tag } from '@fibrae/semi-ui-svelte';
</script>

<Space>
    <Tag color="light-blue" shape="circle" size="large">
        {#snippet prefixIcon()}
            <IconGithubLogo />
        {/snippet}
        Semi Design
    </Tag>
    <Tag color="cyan" shape="circle" size="large">
        D2C: figma to code in one click
        {#snippet suffixIcon()}
            <IconSemiLogo />
        {/snippet}
    </Tag>
</Space>

颜色

标签支持默认色板的 16 种颜色和白色,包括:amber、 blue、 cyan、 green、 grey、 indigo、 light-blue、 light-green、 lime、 orange、 pink、 purple、 red、 teal、 violet、 yellow、 white,也可以通过 style 来自定义颜色样式。

amber
blue
cyan
green
grey
indigo
light-blue
light-green
lime
orange
pink
purple
red
teal
violet
yellow
white
代码
<script lang="ts">
    import { Space, Tag, type TagColor } from '@fibrae/semi-ui-svelte';

    const colors: TagColor[] = ['amber', 'blue', 'cyan', 'green', 'grey', 'indigo', 'light-blue', 'light-green', 'lime', 'orange', 'pink', 'purple', 'red', 'teal', 'violet', 'yellow', 'white'];
</script>

<Space wrap>
    {#each colors as color (color)}
        <Tag {color}>{color}</Tag>
    {/each}
</Space>

AI 风格 - 多彩标签

设置 colorful 为 true 即可获得多彩的标签。注意: 多彩标签的字重和非多彩标签字重不同。

多彩标签可通过 gradient 区分是否为渐变色。

AI
AI
AI
AI
AI
AI
AI
AI
AI
AI
AI
AI
代码
<script lang="ts">
    import { IconAIFilledLevel1, IconAIFilledLevel3 } from '@fibrae/semi-icons-svelte';
    import { Tag } from '@fibrae/semi-ui-svelte';

    const grid = 'display: grid; grid-template-columns: repeat(3, 1fr); grid-gap: 10px; width: fit-content';
</script>

{#snippet level1()}
    <IconAIFilledLevel1 size="small" />
{/snippet}
{#snippet level3()}
    <IconAIFilledLevel3 size="small" />
{/snippet}

<div style="display: flex; flex-direction: column; row-gap: 30px">
    <div style={grid}>
        <Tag colorful gradient prefixIcon={level1} shape="circle" type="solid">AI</Tag>
        <Tag colorful gradient prefixIcon={level3} shape="circle" type="light">AI</Tag>
        <Tag colorful gradient prefixIcon={level3} shape="circle" type="ghost">AI</Tag>
        <Tag colorful prefixIcon={level1} shape="circle" type="solid">AI</Tag>
        <Tag colorful prefixIcon={level1} shape="circle" type="light">AI</Tag>
        <Tag colorful prefixIcon={level1} shape="circle" type="ghost">AI</Tag>
    </div>
    <div style={grid}>
        <Tag colorful gradient prefixIcon={level1} type="solid">AI</Tag>
        <Tag colorful gradient prefixIcon={level3} type="light">AI</Tag>
        <Tag colorful gradient prefixIcon={level3} type="ghost">AI</Tag>
        <Tag colorful prefixIcon={level1} type="solid">AI</Tag>
        <Tag colorful prefixIcon={level1} type="light">AI</Tag>
        <Tag colorful prefixIcon={level1} type="ghost">AI</Tag>
    </div>
</div>

样式类型

标签支持三种样式类型,包括浅色底色 light,白色底色 ghost,深色底色 solid;默认值为 light。通过 type 配置

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
代码
<script lang="ts">
    import { IconGithubLogo, IconSemiLogo } from '@fibrae/semi-icons-svelte';
    import { Space, Tag, type TagType } from '@fibrae/semi-ui-svelte';

    const types: [TagType, string][] = [
        ['light', 'Light'],
        ['ghost', 'Ghost'],
        ['solid', 'Solid'],
    ];
</script>

<Space wrap>
    {#each types as [type, label] (type)}
        <Tag color="light-blue" shape="circle" size="large" {type}>
            {#snippet prefixIcon()}
                <IconGithubLogo />
            {/snippet}
            Semi Design {label} Tag
        </Tag>
        <Tag color="cyan" shape="circle" size="large" {type}>
            D2C: figma to code in one click
            {#snippet suffixIcon()}
                <IconSemiLogo />
            {/snippet}
        </Tag>
    {/each}
</Space>

头像标签

设置 avatarSrc 可以生成头像标签。结合 avatarShape 可以调整头像标签的形状,支持 square 和 circle。

焦锐志
焦锐志
焦锐志
焦锐志
焦锐志
焦锐志
代码
<script lang="ts">
    import { Space, Tag } from '@fibrae/semi-ui-svelte';

    const src = '/assets/placeholder/avatar-a.svg';
</script>

<Space align="start" vertical>
    <Tag avatarSrc={src}>焦锐志</Tag>
    <Tag avatarSrc={src} size="large">焦锐志</Tag>
    <Tag avatarSrc={src} closable size="large">焦锐志</Tag>
    <Tag avatarShape="circle" avatarSrc={src}>焦锐志</Tag>
    <Tag avatarShape="circle" avatarSrc={src} size="large">焦锐志</Tag>
    <Tag avatarShape="circle" avatarSrc={src} closable size="large">焦锐志</Tag>
</Space>

不可见的

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

Invisible tag
代码
<script lang="ts">
    import { Radio, RadioGroup, Tag, type RadioValue } from '@fibrae/semi-ui-svelte';

    let value = $state<RadioValue | undefined>(0);
</script>

<div>
    <RadioGroup aria-label="标签可见性" bind:value name="demo-tag-visible" type="button">
        <Radio value={1}>Show</Radio>
        <Radio value={0}>Hide</Radio>
    </RadioGroup>
    <div style="margin-top: 10px">
        <Tag color="light-blue" size="large" visible={value === 1}>Invisible tag</Tag>
    </div>
</div>

TagGroup 使用

在 TagGroup 内通过 tagList 传入 tags 配置,并且设置 maxTagCount 属性, 超出数量限制后,会显示为 +N
通过设置 showPopover 属性,来控制 hover 到 +N Tag 时,是否通过 Popover 显示剩余内容

抖音
火山
剪映
+1
Douyin
Hotsoon
+2
代码
<script lang="ts">
    import { TagGroup, type TagGroupItem } from '@fibrae/semi-ui-svelte';

    const src = '/assets/placeholder/avatar-a.svg';
    const tagList: TagGroupItem[] = [
        { color: 'light-blue', children: '抖音' },
        { color: 'cyan', children: '火山' },
        { color: 'violet', children: '剪映' },
        { color: 'white', children: '醒图' },
    ];
    const tagList2: TagGroupItem[] = [
        { color: 'white', children: 'Douyin', avatarSrc: src },
        { color: 'white', children: 'Hotsoon', avatarSrc: src },
        { color: 'white', children: 'Capcut', avatarSrc: src },
        { color: 'white', children: 'Xingtu', avatarSrc: src },
    ];
    const divStyle = 'background-color: var(--semi-color-fill-0); height: 35px; width: 300px; display: flex; align-items: center; padding: 0 10px; margin-bottom: 30px';
    const tagGroupStyle = 'display: flex; align-items: center; width: 350px';
</script>

<div style={divStyle}>
    <TagGroup maxTagCount={3} size="large" style={tagGroupStyle} {tagList} />
</div>
<div style={divStyle}>
    <TagGroup avatarShape="circle" maxTagCount={2} showPopover size="large" style={tagGroupStyle} tagList={tagList2} />
</div>

如果 TagGroup 中的标签可删除,用户需要在 onTagClose 中更新传给 TagGroup 的 tagList。从列表移除标签时请为每项提供 tagKey,否则文字相同的标签移除前一个后会错位。tagList 每项的 children 为 string | number,需要完全自定义每个标签的节点时使用 tag snippet,参数为 { tag, index }。tagList 里数据项自己的 onClose 与分组的 onTagClose 都会调用。

抖音
剪映
醒图
+2
代码
<script lang="ts">
    import { TagGroup, type TagCloseEvent, type TagGroupItem } from '@fibrae/semi-ui-svelte';

    let tagList = $state<TagGroupItem[]>([
        { tagKey: '1', color: 'light-blue', children: '抖音', closable: true },
        { tagKey: '3', color: 'cyan', children: '剪映', closable: true },
        { tagKey: '2', color: 'violet', children: '醒图', closable: true },
        { tagKey: '4', color: 'teal', children: '轻颜相机', closable: true },
        { tagKey: '5', color: 'white', children: '飞书', closable: true },
    ]);

    const closeTag = (_event: TagCloseEvent, tagKey: string | number | undefined) => {
        tagList = tagList.filter((tag) => tag.tagKey !== tagKey);
    };
</script>

<div style="background-color: var(--semi-color-fill-0); height: 35px; width: 300px; display: flex; align-items: center; padding: 0 10px; margin-bottom: 30px">
    <TagGroup maxTagCount={3} onTagClose={closeTag} showPopover size="large" style="display: flex; align-items: center; width: 350px" {tagList} />
</div>

SplitTagGroup 组合标签

使用 SplitTagGroup 可以将多个标签组合成一个整体,首尾标签会有圆角,中间标签圆角为 0,形成连续的视觉效果。

标签一
标签二
标签三
组合
标签
示例
效果
浅色
组合
标签
镂空
样式
组合
代码
<script lang="ts">
    import { Space, SplitTagGroup, Tag } from '@fibrae/semi-ui-svelte';
</script>

<Space align="start" vertical>
    <SplitTagGroup>
        <Tag color="blue" type="solid">标签一</Tag>
        <Tag color="cyan" type="solid">标签二</Tag>
        <Tag color="teal" type="solid">标签三</Tag>
    </SplitTagGroup>

    <SplitTagGroup>
        <Tag color="violet" shape="circle">组合</Tag>
        <Tag color="purple" shape="circle">标签</Tag>
        <Tag color="pink" shape="circle">示例</Tag>
        <Tag color="red" shape="circle">效果</Tag>
    </SplitTagGroup>

    <SplitTagGroup>
        <Tag color="amber" type="light">浅色</Tag>
        <Tag color="orange" type="light">组合</Tag>
        <Tag color="yellow" type="light">标签</Tag>
    </SplitTagGroup>

    <SplitTagGroup>
        <Tag color="green" type="ghost">镂空</Tag>
        <Tag color="light-green" type="ghost">样式</Tag>
        <Tag color="lime" type="ghost">组合</Tag>
    </SplitTagGroup>
</Space>

API参考

Tag

Props

属性说明类型默认值
avatarShape头像标签中头像的形状,可选 square 或 circle。AvatarShape"square"
avatarSrc头像资源地址,设置后生成头像标签。string-
children标签内容的 snippet。Snippet-
closable标签是否可以关闭。booleanfalse
color标签颜色,可选色板中的 16 种颜色和 white。TagColor"grey"
colorful是否为多彩标签。booleanfalse
gradient多彩标签是否为渐变色,需 colorful 为 true。booleanfalse
onClose关闭标签时调用,参数为关闭事件与 tagKey;点击关闭图标时为 click 事件,按 Backspace 或 Delete 关闭时为 keydown 事件。对事件调用 preventDefault 可保持标签显示。Type(event: TagCloseEvent, tagKey?: string | number) => void-
onkeydown标签上按下按键时调用。TypeKeyboardEventHandler<T> | null-
prefixIcon内容前的图标的 snippet。Snippet-
shape标签形状,可选 square 或 circle。TagShape"square"
size标签尺寸,可选 small、default 或 large。TagSize"default"
suffixIcon内容后的图标的 snippet。Snippet-
tabindex标签的 tabindex;可交互的标签缺省为 0。number | null-
tagKey标签的唯一标识,作为 onClose 的第二个参数。string | number-
type样式类型,可选 light、ghost 或 solid。TagType"light"
visible标签是否可见,可用 bind:visible 绑定;函数绑定的 setter 可以拒绝关闭。不传时标签自行关闭,之前一直显示。boolean-

class、style 与原生属性经展开落在根元素(div)上,原生事件用小写名(onclick、onmouseenter)。声明 onclick 或 closable 后标签可交互。

TagGroup

Props

属性说明类型默认值
avatarShape组内头像标签的头像形状。AvatarShape"square"
maxTagCount最多显示的标签数,超出的部分显示为 +N。number-
onPlusNMouseEnter指针移入 +N 标签时调用。Type(event: MouseEvent) => void-
onTagClose组内标签被关闭时调用,参数为关闭事件与该标签的 tagKey;数据项自己的 onClose 同样会调用。需在回调中更新 tagList。Type(event: TagCloseEvent, tagKey?: string | number) => void-
popoverProps传给 Popover 的属性,可设置 position、trigger 等;child 与 content 由 TagGroup 固定。PopoverProps-
restCount+N 中显示的数量,缺省为超出 maxTagCount 的标签数。number-
showPopover悬停在 +N 上时,是否通过 Popover 显示剩余标签。boolean-
size组内标签的尺寸。TagSize"default"
tag自定义每个标签渲染的 snippet,参数为 { tag, index }:标签配置与序号,序号在可见标签与 +N 弹层中连续计数。TypeSnippet<[scope: { tag: TagGroupItem; index: number }]>-
tagList标签配置数组,每项为 Tag 的属性,children 为 string 或 number 的标签文字。TagGroupItem[]-

class、style 与原生属性经展开落在 TagGroup 的根元素(div)上。+N 的 Tag 自己是 Popover 的触发器,不额外包 span。

SplitTagGroup

Props

属性说明类型默认值
children组合在一起的 Tag 的 snippet。Snippet-

class、style、aria-label 等原生属性经展开落在根元素(div)上,根元素的 role 固定为 group。

Accessibility

ARIA

  • aria-label 用于表示 Tag 的作用,对于可删除或者可点击的 Tag ,我们推荐使用此属性

键盘和焦点

  • 如果当前 Tag 可交互,那么这个 Tag 可被聚焦到。如:
    • 使用了 onClick 属性(Vue 为 @click,Svelte 为 onclick)时,键盘用户可以通过 Enter 或空格键激活此 Tag
    • closable 属性为 true 时,键盘用户可以通过 Delete 或 Backspace 键删除此 Tag,焦点会移到相邻的可聚焦 Tag

文案规范

  • 由于空间有限,标签文本应尽可能简短
  • 避免换行
  • 使用句子大小写;

设计变量

下表是组件内部的 Sass 变量,不能覆写。定制样式请覆写 --semi-* CSS 变量(见 Design Token 页),或写不分层的 CSS 规则。
Sass 变量值用法
$color-tag_avatar-bg-defaultvar(--semi-color-bg-4)头像标签背景颜色 - 默认
$color-tag_avatar-border-defaultvar(--semi-color-border)头像标签描边颜色 - 默认
$color-tag_avatar-text-defaultvar(--semi-color-text-0)头像标签文字颜色 - 默认
$color-tag_white-bg-defaultvar(--semi-color-bg-4)白色标签背景颜色 - 默认
$color-tag_white-border-defaultrgb(from var(--semi-grey-2) r g b / 0.7)白色标签描边颜色 - 默认
$color-tag_white-text-defaultvar(--semi-color-text-0)白色标签文字颜色 - 默认
$color-tag_white-icon-defaultvar(--semi-color-text-2)白色标签图标颜色 - 默认
$color-tag-outline-focus$color-focus-ring标签轮廓 - 聚焦
$color-tag_colorful_solid-bgvar(--semi-color-ai-purple)AI Tag深色底色类型背景色
$color-tag_colorful_solid-textvar(--semi-color-white)AI Tag 深色底色类型字体颜色
$color-tag_colorful_solid_gradient-bgvar(--semi-color-ai-general)AI Tag深色底色类型渐变背景色
$color-tag_colorful_light-bgvar(--semi-ai-purple-0)AI Tag 浅色底色类型背景色
$color-tag_colorful_light-textvar(--semi-color-ai-purple)AI Tag 浅色底色类型字体颜色
$color-tag_colorful_light_gradient-bgvar(--semi-ai-general-0)AI Tag浅色底色类型背景色-渐变
$color-tag_colorful_light_gradient-textvar(--semi-color-ai-general)AI Tag浅色底色类型字体色-渐变
$color-tag_colorful_light_gradient-1var(--semi-ai-general-5-0)AI Tag 浅色底色icon渐变色1
$color-tag_colorful_light_gradient-2var(--semi-ai-general-5-1)AI Tag 浅色底色icon渐变色2
$color-tag_colorful_light_gradient-3var(--semi-ai-general-5-2)AI Tag 浅色底色icon渐变色3
$color-tag_colorful_light_gradient-4var(--semi-ai-general-5-3)AI Tag 浅色底色icon渐变色4
$color-tag_colorful_ghost-bgvar(--semi-color-white)AI Tag 白色底色类型背景色
$color-tag_colorful_ghost-textvar(--semi-color-ai-purple)AI Tag 白色底色类型字体颜色
$color-tag_colorful_ghost-bordervar(--semi-color-ai-general)AI Tag 白色底色类型描边颜色
$color-tag_colorful_ghost_gradient-textvar(--semi-color-ai-general)AI Tag 白色底色类型字体色-渐变
$color-tag_colorful_ghost_gradient-1var(--semi-ai-general-5-0)AI Tag 白色底色icon渐变色1
$color-tag_colorful_ghost_gradient-2var(--semi-ai-general-5-1)AI Tag 白色底色icon渐变色2
$color-tag_colorful_ghost_gradient-3var(--semi-ai-general-5-2)AI Tag 白色底色icon渐变色3
$color-tag_colorful_ghost_gradient-4var(--semi-ai-general-5-3)AI Tag 白色底色icon渐变色4
$width-tag_avatar_circle_small16px头像标签圆角 - 小尺寸
$width-tag_avatar_circle_large20px头像标签圆角 - 大尺寸
$width-tag-border1px标签描边宽度
$width-tag_avatar-border$width-tag-border头像标签描边宽度
$width-tag-outline$width-focus-ring标签轮廓宽度
$height-tag_small20px小尺寸标签高度
$height-tag_large24px大尺寸标签高度
$radius-tagvar(--semi-border-radius-small)标签圆角大小
$radius-tag_circlevar(--semi-border-radius-full)胶囊标签圆角大小
$spacing-tag_small-paddingY2px小尺寸标签垂直方向内边距
$spacing-tag_small-paddingX$spacing-tight小尺寸标签水平方向内边距
$spacing-tag_prefix_icon_paddingRight$spacing-extra-tight后缀图标右侧边距
$spacing-tag_suffix_icon_paddingLeft$spacing-extra-tight后缀图标左侧边距
$spacing-tag_large-paddingY4px大尺寸标签垂直方向内边距
$spacing-tag_large-paddingX$spacing-tight大尺寸标签水平方向内边距
$color-tag_close-icon-defaultvar(--semi-color-text-2)可删除的标签删除按钮颜色
$color-tag_close-icon-hovervar(--semi-color-text-1)可删除的标签删除按钮颜色 - 悬浮
$color-tag_close-icon-activevar(--semi-color-text-0)可删除的标签删除按钮颜色 - 按下
$spacing-tag_close-paddingLeft$spacing-extra-tight可删除的标签删除按钮左侧内边距
$spacing-tag_closable-paddingTop$spacing-extra-tight可删除的标签删除按钮顶部内边距
$spacing-tag_closable-paddingRight$spacing-extra-tight可删除的标签删除按钮右侧内边距
$spacing-tag_closable-paddingBottom$spacing-extra-tight可删除的标签删除按钮底部内边距
$spacing-tag_closable-paddingLeft$spacing-tight可删除的标签删除按钮左侧内边距
$spacing-tag_avatar-marginRight$spacing-extra-tight头像标签头像右侧外边距
$spacing-tag_avatar_square-paddingTop0方形头像标签头像顶部内边距
$spacing-tag_avatar_square-paddingRight$spacing-extra-tight方形头像标签头像右侧内边距
$spacing-tag_avatar_square-paddingBottom0方形头像标签头像底部内边距
$spacing-tag_avatar_square-paddingLeft0方形头像标签头像左侧内边距
$spacing-tag_avatar_circle-paddingTop$spacing-super-tight圆型头像标签头像顶部内边距
$spacing-tag_avatar_circle-paddingRight$spacing-extra-tight圆型头像标签头像右侧内边距
$spacing-tag_avatar_circle-paddingBottom$spacing-super-tight圆型头像标签头像底部内边距
$spacing-tag_avatar_circle-paddingLeft$spacing-super-tight圆型头像标签头像左侧内边距
$color-tag_avatar_square_img-bg-defaultvar(--semi-color-default)方形头像标签头像背景色 - 默认
$spacing-tag_group-marginBottom0标签组底部外边距
$spacing-tag_group-marginRight$spacing-tight标签组右侧外边距
$font-tag_colorful-fontWeight$font-weight-boldAI tag的字重