展示类

标签

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

代码演示

如何引入

import { Tag, TagGroup, SplitTagGroup } from '@fibrous/semi-ui-solid';

基本用法

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

此时点击 x 关闭会触发 onClose 事件,在 onClose 中对事件调用 preventDefault 可以使其点击后依然显示不隐藏

default tag
Closable Tag
Closable Tag, Prevent Default
代码
import { Space, Tag } from '@fibrous/semi-ui-solid';

export default function TagDemo() {
    return (
        <div>
            <Space>
                <Tag>default tag</Tag>
                <Tag closable>Closable Tag</Tag>
                <Tag closable onClose={(_, e) => e.preventDefault()}>
                    Closable Tag, Prevent Default
                </Tag>
            </Space>
        </div>
    );
}

尺寸

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

small tag
large tag
代码
import { Space, Tag } from '@fibrous/semi-ui-solid';

export default function TagDemo() {
    return (
        <Space>
            <Tag size="small" color="light-blue">
                small tag
            </Tag>
            <Tag size="large" color="cyan">
                large tag
            </Tag>
        </Space>
    );
}

形状

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

small circle tag
large circle tag
代码
import { Space, Tag } from '@fibrous/semi-ui-solid';

export default function TagDemo() {
    return (
        <Space>
            <Tag size="small" shape="circle" color="amber">
                small circle tag
            </Tag>
            <Tag size="large" shape="circle" color="violet">
                large circle tag
            </Tag>
        </Space>
    );
}

配置图标

通过 prefixIcon、suffixIcon 属性传入 JSX 元素,可以在内容前后添加 Icon 图标。

Semi Design
D2C: figma to code in one click
代码
import { IconGithubLogo, IconSemiLogo } from '@fibrous/semi-icons-solid';
import { Space, Tag } from '@fibrous/semi-ui-solid';

export default function TagDemo() {
    return (
        <Space>
            <Tag color="light-blue" prefixIcon={<IconGithubLogo />} size="large" shape="circle">
                Semi Design
            </Tag>
            <Tag color="cyan" size="large" shape="circle" suffixIcon={<IconSemiLogo />}>
                D2C: figma to code in one click
            </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
代码
import { For } from 'solid-js';
import { Space, Tag, type TagColor } from '@fibrous/semi-ui-solid';

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

export default function TagDemo() {
    return (
        <Space wrap>
            <For each={colors}>{(color) => <Tag color={color}>{color}</Tag>}</For>
        </Space>
    );
}

AI 风格 - 多彩标签

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

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

AI
AI
AI
AI
AI
AI
AI
AI
AI
AI
AI
AI
代码
import { IconAIFilledLevel1, IconAIFilledLevel3 } from '@fibrous/semi-icons-solid';
import { Tag } from '@fibrous/semi-ui-solid';

export default function TagDemo() {
    return (
        <div style={{ display: 'flex', 'flex-direction': 'column', 'row-gap': '30px' }}>
            <div style={{ display: 'grid', 'grid-template-columns': 'repeat(3,1fr)', gap: '10px', width: 'fit-content' }}>
                <Tag colorful prefixIcon={<IconAIFilledLevel1 size="small" />} type="solid" shape="circle" gradient>
                    AI
                </Tag>
                <Tag colorful prefixIcon={<IconAIFilledLevel3 size="small" />} type="light" shape="circle" gradient>
                    AI
                </Tag>
                <Tag colorful prefixIcon={<IconAIFilledLevel3 size="small" />} type="ghost" shape="circle" gradient>
                    AI
                </Tag>
                <Tag colorful prefixIcon={<IconAIFilledLevel1 size="small" />} type="solid" shape="circle">
                    AI
                </Tag>
                <Tag colorful prefixIcon={<IconAIFilledLevel1 size="small" />} type="light" shape="circle">
                    AI
                </Tag>
                <Tag colorful prefixIcon={<IconAIFilledLevel1 size="small" />} type="ghost" shape="circle">
                    AI
                </Tag>
            </div>
            <div style={{ display: 'grid', 'grid-template-columns': 'repeat(3,1fr)', gap: '10px', width: 'fit-content' }}>
                <Tag colorful prefixIcon={<IconAIFilledLevel1 size="small" />} type="solid" gradient>
                    AI
                </Tag>
                <Tag colorful prefixIcon={<IconAIFilledLevel3 size="small" />} type="light" gradient>
                    AI
                </Tag>
                <Tag colorful prefixIcon={<IconAIFilledLevel3 size="small" />} type="ghost" gradient>
                    AI
                </Tag>
                <Tag colorful prefixIcon={<IconAIFilledLevel1 size="small" />} type="solid">
                    AI
                </Tag>
                <Tag colorful prefixIcon={<IconAIFilledLevel1 size="small" />} type="light">
                    AI
                </Tag>
                <Tag colorful prefixIcon={<IconAIFilledLevel1 size="small" />} 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
代码
import { IconGithubLogo, IconSemiLogo } from '@fibrous/semi-icons-solid';
import { Space, Tag } from '@fibrous/semi-ui-solid';

export default function TagDemo() {
    return (
        <Space wrap>
            <Tag color="light-blue" prefixIcon={<IconGithubLogo />} size="large" shape="circle" type="light">
                Semi Design Light Tag
            </Tag>
            <Tag color="cyan" size="large" shape="circle" suffixIcon={<IconSemiLogo />} type="light">
                D2C: figma to code in one click
            </Tag>
            <Tag color="light-blue" prefixIcon={<IconGithubLogo />} size="large" shape="circle" type="ghost">
                Semi Design Ghost Tag
            </Tag>
            <Tag color="cyan" size="large" shape="circle" type="ghost" suffixIcon={<IconSemiLogo />}>
                D2C: figma to code in one click
            </Tag>
            <Tag color="light-blue" prefixIcon={<IconGithubLogo />} size="large" shape="circle" type="solid">
                Semi Design Solid Tag
            </Tag>
            <Tag color="cyan" size="large" shape="circle" type="solid" suffixIcon={<IconSemiLogo />}>
                D2C: figma to code in one click
            </Tag>
        </Space>
    );
}

头像标签

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

焦锐志
焦锐志
焦锐志
焦锐志
焦锐志
焦锐志
代码
import { Space, Tag } from '@fibrous/semi-ui-solid';

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

export default function TagDemo() {
    return (
        <Space vertical align="start">
            <Tag avatarSrc={src}>焦锐志</Tag>
            <Tag avatarSrc={src} size="large">
                焦锐志
            </Tag>
            <Tag avatarSrc={src} size="large" closable>
                焦锐志
            </Tag>
            <Tag avatarSrc={src} avatarShape="circle">
                焦锐志
            </Tag>
            <Tag avatarSrc={src} avatarShape="circle" size="large">
                焦锐志
            </Tag>
            <Tag avatarSrc={src} avatarShape="circle" size="large" closable>
                焦锐志
            </Tag>
        </Space>
    );
}

不可见的

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

Invisible tag
代码
import { createSignal } from 'solid-js';
import { Radio, RadioGroup, Tag } from '@fibrous/semi-ui-solid';

export default function TagDemo() {
    const [visible, setVisible] = createSignal(false);
    const toggleVisible = () => {
        setVisible(!visible());
    };
    return (
        <div>
            <RadioGroup type="button" defaultValue={0} onChange={toggleVisible}>
                <Radio value={1}>Show</Radio>
                <Radio value={0}>Hide</Radio>
            </RadioGroup>
            <div style={{ 'margin-top': '10px' }}>
                <Tag visible={visible()} size="large" color="light-blue">
                    Invisible tag
                </Tag>
            </div>
        </div>
    );
}

TagGroup 使用

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

抖音
火山
剪映
+1
Douyin
Hotsoon
+2
代码
import { TagGroup, type TagGroupItem } from '@fibrous/semi-ui-solid';

const tagList: TagGroupItem[] = [
    { color: 'light-blue', children: '抖音' },
    { color: 'cyan', children: '火山' },
    { color: 'violet', children: '剪映' },
    { color: 'white', children: '醒图' },
];
const src = '/assets/placeholder/avatar-a.svg';
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',
};

export default function TagDemo() {
    return (
        <>
            <div style={divStyle}>
                <TagGroup maxTagCount={3} style={tagGroupStyle} tagList={tagList} size="large" />
            </div>
            <div style={divStyle}>
                <TagGroup maxTagCount={2} style={tagGroupStyle} tagList={tagList2} size="large" avatarShape="circle" showPopover />
            </div>
        </>
    );
}

如果 TagGroup 中的标签可删除,用户需要在 onTagClose 中更新传给 TagGroup 的 tagList。从列表移除标签时请为每项提供 tagKey,否则文字相同的标签移除前一个后会错位。tagList 每项的 children 为 string | number,需要完全自定义每个标签的节点时使用 renderTag={(tag, index) => ...}。

抖音
剪映
醒图
+2
代码
import { createSignal } from 'solid-js';
import { TagGroup, type TagGroupItem, type TagGroupProps } from '@fibrous/semi-ui-solid';

const defaultList: 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 },
];

export default function TagDemo() {
    const [tagList, setTagList] = createSignal(defaultList);

    const tagListClick: TagGroupProps['onTagClose'] = (_tagChildren, _e, tagKey) => {
        setTagList(tagList().filter((t) => t.tagKey !== tagKey));
    };

    return (
        <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}
                showPopover
                style={{
                    display: 'flex',
                    'align-items': 'center',
                    width: '350px',
                }}
                tagList={tagList()}
                size="large"
                onTagClose={tagListClick}
            />
        </div>
    );
}

SplitTagGroup 组合标签

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

标签一
标签二
标签三
组合
标签
示例
效果
浅色
组合
标签
镂空
样式
组合
代码
import { SplitTagGroup, Space, Tag } from '@fibrous/semi-ui-solid';

export default function TagDemo() {
    return (
        <Space vertical align="start">
            <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-
closable标签是否可以关闭。booleanfalse
color标签颜色,可选色板中的 16 种颜色和 white。TagColor"grey"
colorful是否为多彩标签。booleanfalse
gradient多彩标签是否为渐变色,需 colorful 为 true。booleanfalse
onClose关闭标签时的回调,参数为标签内容、事件与 tagKey。event 为点击关闭图标的 click 事件,或按 Backspace、Delete 时的 keydown 事件。对事件调用 preventDefault 可保持标签显示。Type(tagChildren: JSX.Element, event: TagCloseEvent, tagKey?: string | number) => void-
prefixIcon内容前的图标,传入 JSX 元素。JSX.Element-
shape标签形状,可选 square 和 circle。TagShape"square"
size标签尺寸,可选 default、small 或 large。TagSize"default"
suffixIcon内容后的图标,传入 JSX 元素。JSX.Element-
tagKey标签的唯一标识,作为 onClose 的第三个参数。string | number-
type样式类型,可选 light、ghost 或 solid。TagType"light"
visible标签是否可见。不传时关闭标签后会隐藏;传入后由该值决定显示。boolean-

class、style、ref 与原生属性经展开落在根元素(div)上。声明 onClick 后标签可交互。

TagGroup

Props

属性说明类型默认值
avatarShape组内头像标签的头像形状,可选 square 和 circle。AvatarShape"square"
maxTagCount最多显示的标签数,超出的部分显示为 +N。number-
onPlusNMouseEnter指针移入 +N 标签时的回调。Type() => void-
onTagClose组内标签被关闭时的回调,参数为标签内容、关闭事件与该标签的 tagKey;需在回调中更新 tagList。Type(tagChildren: JSX.Element, event: TagCloseEvent, tagKey?: string | number) => void-
popoverProps传给 Popover 的属性,可设置 position、trigger 等。PopoverProps-
renderTag自定义每个标签的渲染,参数为标签配置与它在 tagList 中的序号,返回值取代默认的 Tag。只为显示的标签调用,超出 maxTagCount 的标签在 Popover 打开时才渲染。Type(tag: TagGroupItem, index: number) => JSX.Element-
restCount+N 中显示的数量,缺省为超出 maxTagCount 的标签数。number-
showPopover悬停在 +N 上时,是否通过 Popover 显示剩余标签。boolean-
size组内标签的尺寸,可选 default、small 或 large。TagSize"default"
tagList标签配置数组,每项为 Tag 的属性,children 为 string 或 number 的标签文字,不含 prefixIcon、suffixIcon;其他内容用 renderTag 渲染。TagGroupItem[]-

class、style、ref 与原生属性经展开落在 TagGroup 的根元素(div)上。

SplitTagGroup

Props

属性说明类型默认值
无

class、style、aria-label 等原生属性经展开落在根元素(div)上。

Accessibility

ARIA

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

键盘和焦点

  • 如果当前 Tag 可交互,那么这个 Tag 可被聚焦到。如:
    • 使用了 onClick 属性(Vue 为 @click)时,键盘用户可以通过 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的字重