标签输入框 - Semi Design Next

代码演示

如何引入

import { Avatar, Button, TagInput, Toast } from '@fibrous/semi-ui-solid';

基本演示

敲击回车键后，输入内容将成为标签。标签内容如果为空串或者纯空格时，则会被过滤。

抖音

火山

西瓜视频

代码

import { TagInput } from '@fibrous/semi-ui-solid';

export default function TagInputDemo() {
    return <TagInput defaultValue={['抖音', '火山', '西瓜视频']} placeholder="请输入..." onChange={(v) => console.log(v)} />;
}

批量添加

可以使用 separator 设置分隔符，来实现批量输入，它的默认值为英文逗号。支持多个分隔符以 string[] 格式传入。

代码

import { TagInput } from '@fibrous/semi-ui-solid';

const separators = ['-', '/', '|', '++'];

export default function TagInputDemo() {
    return (
        <>
            <TagInput separator="-" placeholder="使用 - 进行批量输入" onChange={(v) => console.log(v)} />
            <br />
            <br />
            <TagInput separator={separators} placeholder="支持多个分隔符进行批量输入" onChange={(v) => console.log(v)} />
        </>
    );
}

批量删除

可使用 showClear 设置是否支持一键删除所有标签和输入框内容。

抖音

火山

代码

import { TagInput } from '@fibrous/semi-ui-solid';

export default function TagInputDemo() {
    return <TagInput showClear defaultValue={['抖音', '火山']} placeholder="请输入..." onChange={(v) => console.log(v)} />;
}

禁用

抖音

火山

西瓜视频

代码

import { TagInput } from '@fibrous/semi-ui-solid';

export default function TagInputDemo() {
    return <TagInput disabled showClear defaultValue={['抖音', '火山', '西瓜视频']} placeholder="请输入..." />;
}

尺寸大小

通过 size 控制标签输入框的大小尺寸，可选: small 、 default 、 large。

代码

import { TagInput } from '@fibrous/semi-ui-solid';

export default function TagInputDemo() {
    return (
        <>
            <TagInput size="small" placeholder="small" />
            <br />
            <br />
            <TagInput placeholder="default" />
            <br />
            <br />
            <TagInput size="large" placeholder="large" />
        </>
    );
}

不同校验状态样式

可以使用 validateStatus 设置不同校验状态的样式，它仅影响背景颜色等样式表现，可选值: default 、 warning 、 error。

代码

import { TagInput } from '@fibrous/semi-ui-solid';

export default function TagInputDemo() {
    return (
        <>
            <TagInput placeholder="default" />
            <br />
            <br />
            <TagInput placeholder="warning" validateStatus="warning" />
            <br />
            <br />
            <TagInput placeholder="error" validateStatus="error" />
        </>
    );
}

前缀 / 后缀

可以通过 prefix 传入输入框前缀，通过 suffix 传入输入框后缀，可以为文本或者 JSX 元素。
当 prefix、suffix 传入的内容为文本或者 Icon 时，会自动带上左右间隔；若为自定义 JSX 元素，则左右间隔为 0，如需可以在你传入的元素中自行设置。

Prefix

Suffix

代码

import { IconGift, IconVigoLogo } from '@fibrous/semi-icons-solid';
import { TagInput } from '@fibrous/semi-ui-solid';

export default function TagInputDemo() {
    return (
        <>
            <TagInput prefix={<IconVigoLogo />} />
            <br />
            <br />
            <TagInput prefix="Prefix" />
            <br />
            <br />
            <TagInput suffix={<IconGift />} />
            <br />
            <br />
            <TagInput suffix="Suffix" />
        </>
    );
}

失焦后自动创建标签

可使用 addOnBlur，设置是否在 blur 事件触发时，将当前 input 的值自动创建成 tag。

抖音

火山

西瓜视频

代码

import { TagInput } from '@fibrous/semi-ui-solid';

export default function TagInputDemo() {
    return <TagInput defaultValue={['抖音', '火山', '西瓜视频']} addOnBlur placeholder="请输入..." onChange={(v) => console.log(v)} />;
}

过滤重复标签

可使用 allowDuplicates，设置是否允许创建相同 tag，默认为 true。

抖音

火山

西瓜视频

代码

import { TagInput } from '@fibrous/semi-ui-solid';

export default function TagInputDemo() {
    return <TagInput defaultValue={['抖音', '火山', '西瓜视频']} allowDuplicates={false} placeholder="请输入..." onChange={(v) => console.log(v)} />;
}

输入限制

可使用 max 限制标签数量，添加后超出的部分不会成为标签，并且触发 onExceed() 回调。

可使用 maxLength 限制单个标签的最大长度，超出后将不允许再输入，并且触发 onInputExceed() 回调。

代码

import { TagInput, Toast } from '@fibrous/semi-ui-solid';

export default function TagInputDemo() {
    return (
        <>
            <TagInput
                max={3}
                placeholder="最多输入3条标签.."
                onChange={(v) => console.log(v)}
                onExceed={(v) => {
                    Toast.warning('超过 max');
                    console.log(v);
                }}
            />
            <TagInput
                maxLength={5}
                placeholder="单个标签长度不超过5..."
                style={{ 'margin-top': '12px' }}
                onChange={(v) => console.log(v)}
                onInputExceed={(v) => {
                    Toast.warning('超过 maxLength');
                    console.log(v);
                }}
            />
        </>
    );
}

限制标签展示数量

利用 maxTagCount 可以限制展示的标签数量，超出部分将以 +N 的方式展示。使用 showRestTagsPopover 可以设置在超出 maxTagCount 后，hover +N 是否显示 Popover，并且可以在 restTagsPopoverProps 属性中配置 Popover。

抖音

火山

代码

import { TagInput } from '@fibrous/semi-ui-solid';

export default function TagInputDemo() {
    return <TagInput maxTagCount={2} showRestTagsPopover restTagsPopoverProps={{ position: 'top' }} defaultValue={['抖音', '火山', '西瓜视频']} onChange={(v) => console.log(v)} />;
}

标签受控

可使用 value 设置标签内容，并配合 onChange 实现标签内容受控。

抖音

代码

import { createSignal } from 'solid-js';
import { TagInput } from '@fibrous/semi-ui-solid';

export default function TagInputDemo() {
    const [value, setValue] = createSignal(['抖音']);
    return <TagInput value={value()} onChange={(v) => setValue(v)} />;
}

输入受控

可使用 inputValue 设置输入框内容，并配合 onInputChange 实现输入内容受控。

代码

import { createSignal } from 'solid-js';
import { TagInput } from '@fibrous/semi-ui-solid';

export default function TagInputDemo() {
    const [value, setValue] = createSignal('abc');
    return <TagInput inputValue={value()} onInputChange={(v) => setValue(v)} />;
}

回调

抖音

代码

import { TagInput } from '@fibrous/semi-ui-solid';

export default function TagInputDemo() {
    return (
        <TagInput
            defaultValue={['抖音']}
            placeholder="请输入..."
            showClear
            onFocus={() => {
                console.log(`onFocus`);
            }}
            onBlur={() => {
                console.log(`onBlur`);
            }}
            onChange={(tag) => {
                console.log(`onChange,当前标签数组：${tag}`);
            }}
            onAdd={(tag) => {
                console.log(`onAdd，新增：${tag}`);
            }}
            onRemove={(v, i) => {
                console.log(`onRemove，移除：${v}, 序号：${i}`);
            }}
            onInputChange={(input) => {
                console.log(`onInputChange，当前输入内容：${input}`);
            }}
        />
    );
}

焦点管理

可以通过组件的 ref 拿到根元素，调用其 focus() 和 blur() 方法对焦点进行管理。focus() 会聚焦输入框并激活组件，blur() 使组件内持有焦点的元素失去焦点。

抖音

火山

代码

import { Button, TagInput } from '@fibrous/semi-ui-solid';

export default function TagInputDemo() {
    let tagInput: HTMLDivElement | undefined;

    return (
        <>
            <TagInput defaultValue={['抖音', '火山']} ref={(node) => (tagInput = node)} />
            <Button style={{ 'margin-top': '10px' }} onClick={() => tagInput?.focus()}>
                点击按钮聚焦
            </Button>
        </>
    );
}

自定义标签渲染

可以使用 renderTagItem 自定义标签渲染。renderTagItem(value: string, index: number, onClose: () => void) => JSX.Element，第三个参数 onClose 用于关闭该标签，可直接作为按钮的 onClick。

夏可漫@semi.com

代码

import { createSignal } from 'solid-js';
import { IconClose } from '@fibrous/semi-icons-solid';
import { Avatar, Button, TagInput } from '@fibrous/semi-ui-solid';

const list = [
    {
        name: '夏可漫',
        avatar: '/assets/root-web-sites/avatarDemo.jpeg',
    },
    {
        name: '申悦',
        avatar: '/assets/root-web-sites/bf8647bffab13c38772c9ff94bf91a9d.jpg',
    },
    {
        name: '曲晨一',
        avatar: '/assets/root-web-sites/bf8647bffab13c38772c9ff94bf91a9d.jpg',
    },
    {
        name: '文嘉茂',
        avatar: '/assets/root-web-sites/avatarDemo.jpeg',
    },
];
const mapList = new Map(list.map((item) => [item.name, item]));
const fallbackAvatar = '/assets/placeholder/avatar-a.svg';

function renderTagItem(value: string, _index: number, onClose: () => void) {
    const data = mapList.get(value);
    return (
        <div
            style={{
                'background-color': 'var(--semi-color-info-light-default)',
                padding: '4px 8px',
                'border-radius': '12px',
                display: 'flex',
                'align-items': 'center',
                'font-size': '14px',
                'margin-right': '10px',
            }}
        >
            <Avatar alt="avatar" src={data ? data.avatar : fallbackAvatar} size="extra-small" />
            <span style={{ 'margin-left': '8px' }}>{`${value}@semi.com`}</span>
            <Button theme="borderless" type="tertiary" size="small" icon={<IconClose size="small" />} aria-label={`移除 ${value}`} onClick={onClose} />
        </div>
    );
}

export default function TagInputDemo() {
    const [tags, setTags] = createSignal(['夏可漫']);
    return <TagInput value={tags()} onChange={(v) => setTags(v)} renderTagItem={renderTagItem} />;
}

拖拽排序

将 draggable设为 true，开启拖拽排序功能。拖拽功能开启后，聚焦 TagInput（点击或 Tab）后 Tag 可拖拽，焦点离开 TagInput 后 Tag 不可拖拽。拖拽句柄位于标签旁边，可用键盘操作，见下文「键盘和焦点」。值相同的标签也能分别拖拽排序。

抖音

火山

西瓜视频

代码

import { TagInput } from '@fibrous/semi-ui-solid';

export default function TagInputDemo() {
    return <TagInput draggable allowDuplicates={false} defaultValue={['抖音', '火山', '西瓜视频']} placeholder="请输入..." onChange={(v) => console.log(v)} />;
}

API 参考

Props

属性	说明	类型	默认值
addOnBlur	焦点离开组件时，是否将输入框内容自动创建为标签。	`boolean`	`false`
allowDuplicates	是否允许添加相同的标签。	`boolean`	`true`
aria-label	输入框的可访问名称，落在输入框上，根节点不带。	`string`	-
autofocus	挂载时是否自动聚焦输入框并激活组件，禁用时不生效。	`boolean`	`false`
clearIcon	替换清除按钮中的图标；内容为空时使用默认图标。	`JSX.Element`	-
defaultValue	非受控时的初始标签。	`string[]`	-
disabled	是否禁用。	`boolean`	-
draggable	是否开启拖拽排序。	`boolean`	`false`
expandRestTagsOnClick	不可拖拽时，焦点进入组件（点击、Tab 或 focus 方法）后是否展开被折叠的标签。	`boolean`	`true`
inputValue	当前输入框内容，配合 onInputChange 实现受控。	`string`	-
insetLabel	内嵌标签，显示在输入框前；同时提供 prefix 时只显示 prefix。显示时，没有 aria-label、aria-labelledby 的输入框以它命名。	`JSX.Element`	-
insetLabelId	内嵌标签容器的 id，供 aria-labelledby 引用；未设置时组件自动生成。	`string`	-
max	允许的标签最大数量。	`number`	-
maxLength	单个标签的最大长度。	`number`	-
maxTagCount	标签的最大展示数量，超出后以 +N 形式展示。	`number`	-
name	输入框的 name，供表单使用。	`string`	-
onAdd	添加标签时触发，参数为新增的标签。	`Type`	-
onBlur	焦点离开整个组件时触发一次；焦点在组件内部移动不触发。	`Type`	-
onChange	标签变化时触发，参数为完整的标签数组。	`Type`	-
onExceed	添加后超过 max 时触发，参数为截断前的完整列表。	`Type`	-
onFocus	焦点从组件外进入时触发一次；焦点在输入框、标签、清除按钮之间移动不触发。	`Type`	-
onInputChange	输入框内容变化时触发；事件可能是输入事件、KeyboardEvent（Enter 添加）、FocusEvent（addOnBlur）、MouseEvent（清除）或 CompositionEvent（输入法截断），读取专有字段前先按 `event.type` 收窄。	`Type`	-
onInputExceed	输入内容超过 maxLength 时触发，参数为被拒绝的输入内容。	`Type`	-
onKeyDown	输入框按键时在组件处理之后触发；在其中调用 `preventDefault` 不会阻止 Enter 添加标签。	`Type`	-
onRemove	移除标签时触发，参数为被移除的标签及其序号。	`Type`	-
placeholder	没有标签时输入框的占位文字。	`string`	-
prefix	输入框前缀，文字或图标会自动带上左右间隔；自定义元素的左右间隔为 0，可在元素中自行设置。	`JSX.Element`	-
preventScroll	组件内 focus 方法是否阻止浏览器滚动到新聚焦的元素。	`boolean`	-
renderTagItem	自定义标签渲染，返回的元素替换默认标签。第三个参数 onClose 关闭该标签，可直接作为按钮的 `onClick`。	`Type`	-
restTagsPopoverProps	+N 浮层的 Popover 配置属性，可以控制弹出方向、trigger 等；不要传 `content`，它会替换剩余标签的列表。	`RestTagsPopoverProps`	-
separator	批量输入时的分隔符，可传多个；传 null 不拆分。	`string \| string[] \| null`	`","`
showClear	是否显示一键清除所有标签和输入内容的按钮。	`boolean`	`false`
showContentTooltip	标签文字被截断时，hover 标签是否通过浮层显示全部内容；传对象时用 `type` 指定浮层类型（`tooltip` 或 `popover`），用 `opts` 透传给浮层的属性。	`boolean \| ShowTooltip`	`true`
showRestTagsPopover	超过 maxTagCount 后，hover 到 +N 时是否通过 Popover 显示剩余标签。	`boolean`	`true`
size	尺寸，可选 small、default、large。	`TagInputSize`	`"default"`
split	自定义分隔符处理函数，参数为原始字符串与 separator，返回拆分后的字符串数组。	`Type`	-
suffix	输入框后缀，文字或图标会自动带上左右间隔；自定义元素的左右间隔为 0，可在元素中自行设置。	`JSX.Element`	-
validateStatus	校验状态，仅影响样式；error 时输入框带 aria-invalid。	`TagInputValidateStatus`	`"default"`
value	当前标签，配合 onChange 实现受控；undefined 时按非受控处理，null 表示受控且没有标签。	`string[] \| null`	-

class、style、ref 与原生属性和事件落在根元素上，但 id、name、role、tabIndex 以及描述输入框的 aria-*（aria-label、aria-labelledby、aria-describedby、aria-invalid、aria-required、aria-controls、aria-expanded、aria-haspopup、aria-autocomplete、aria-activedescendant、aria-errormessage）落在内部输入框上。onClick、onMouseDown、onFocusIn、onFocusOut 在组件自己的处理之外也会调用你传入的函数。

Accessibility

ARIA

TagInput 支持传入 aria-label 来表示该 TagInput 作用，它落在输入框上，根节点不带；
根节点的角色是 group，把输入框、标签和清除按钮作为一个整体；禁用时根节点带 aria-disabled="true"，未禁用时不带；
禁用时输入框是原生 disabled，标签是静态文本，不带 aria-label；validateStatus 为 error 时输入框带 aria-invalid，显式传入的 aria-invalid 优先；
showClear 开启、有标签或输入内容且未禁用时，渲染清除按钮。它是原生 button，名称为语言包中的「清空标签输入」，在 hover 或焦点位于 TagInput 内时显示。从输入框按 Tab 移到清除按钮，Enter 或 Space 清空，效果与鼠标点击相同，清空后焦点回到输入框；也可在空输入框中按 Backspace 删除最后一个标签。

键盘和焦点

输入框中按 Enter 把输入内容添加为标签，空输入时不做任何事。Enter 一律阻止默认行为，TagInput 位于表单内时不会提交表单。
输入框为空时按 Backspace 删除最后一个标签。
可关闭的标签是 role="button" 的 Tab 停靠点，位于输入框之前；聚焦标签后按 Backspace 或 Delete 关闭它，标签被移除后焦点回到输入框。禁用时标签是静态文本，不可聚焦。
开启 showClear 且有内容时，清除按钮在输入框之后：Tab 到达，Enter 或 Space 清空，焦点回到输入框。
激活状态跟随焦点：焦点从组件外进入（点击、Tab 或 focus()）即激活，焦点离开整个组件即退出。焦点在输入框、标签与清除按钮之间移动不算离开组件，不触发 focus、blur，也不会触发 addOnBlur。激活时，被 maxTagCount 折叠的标签会展开（expandRestTagsOnClick 为 false 时不展开）。
开启 draggable 并激活后，每个标签前出现拖拽句柄，句柄是独立的 Tab 停靠点，位于它所属的标签之前。聚焦句柄后按 Space 拿起，方向键移动，Space 放下，读屏会播报拿起、移动与放下。

设计变量

下表是组件内部的 Sass 变量，不能覆写。定制样式请覆写 --semi-* CSS 变量（见 Design Token 页），或写不分层的 CSS 规则。

Sass 变量	值	用法
$transition_duration-tagInput-bg	var(--semi-transition_duration-none)	标签输入框-背景色-动画持续时间
$transition_function-tagInput-bg	var(--semi-transition_function-easeIn)	标签输入框-背景色-过渡曲线
$transition_delay-tagInput-bg	var(--semi-transition_delay-none)	标签输入框-背景色-延迟时间
$transition_duration-tagInput-border	var(--semi-transition_duration-none)	标签输入框-边框-动画持续时间
$transition_function-tagInput-border	var(--semi-transition_function-easeIn)	标签输入框-边框-过渡曲线
$transition_delay-tagInput-border	var(--semi-transition_delay-none)	标签输入框-边框-延迟时间
$color-tagInput-icon-default	var(--semi-color-text-2)	标签输入框图标颜色 - 默认
$color-tagInput-icon-hover	var(--semi-color-primary-hover)	标签输入框图标颜色 - 悬浮
$color-tagInput_disabled-text-default	var(--semi-color-disabled-text)	标签输入框禁用文字颜色
$color-tagInput_disabled-bg	var(--semi-color-disabled-fill)	标签输入框禁用背景色
$color-tagInput_default-bg-focus	var(--semi-color-fill-0)	标签输入框背景颜色 - 选中态
$color-tagInput-border-default	transparent	标签输入框描边颜色 - 默认
$color-tagInput-border-hover	transparent	标签输入框描边颜色 - 悬浮
$color-tagInput-border-focus	var(--semi-color-focus-border)	标签输入框描边颜色 - 选中态
$color-tagInput_prefix-default	var(--semi-color-text-2)	标签输入框 prefix 颜色
$color-tagInput_suffix-default	var(--semi-color-text-2)	标签输入框 suffix 颜色
$color-tagInput_default-bg-default	var(--semi-color-fill-0)	标签输入框背景颜色 - 默认
$color-tagInput_default-bg-hover	var(--semi-color-fill-1)	标签输入框背景颜色 - 悬浮
$color-tagInput_warning-bg-default	var(--semi-color-warning-light-default)	警告标签输入框背景颜色 - 默认
$color-tagInput_warning-border-default	var(--semi-color-warning-light-default)	警告标签输入框描边颜色 - 默认
$color-tagInput_warning-bg-hover	var(--semi-color-warning-light-hover)	警告标签输入框背景颜色 - 悬浮
$color-tagInput_warning-border-hover	var(--semi-color-warning-light-hover)	警告标签输入框描边颜色 - 悬浮
$color-tagInput_warning-bg-focus	var(--semi-color-warning-light-default)	警告标签输入框背景颜色 - 选中
$color-tagInput_warning-border-focus	var(--semi-color-warning)	警告标签输入框描边颜色 - 选中
$color-tagInput_danger-bg-default	var(--semi-color-danger-light-default)	危险标签输入框背景颜色 - 默认
$color-tagInput_danger-border-default	var(--semi-color-danger-light-default)	危险标签输入框描边颜色 - 默认
$color-tagInput_danger-bg-hover	var(--semi-color-danger-light-hover)	危险标签输入框背景颜色 - 悬浮
$color-tagInput_danger-border-hover	var(--semi-color-danger-light-hover)	危险标签输入框描边颜色 - 悬浮
$color-tagInput_danger-bg-focus	var(--semi-color-danger-light-default)	危险标签输入框背景颜色 - 选中
$color-tagInput_danger-border-focus	var(--semi-color-danger)	危险标签输入框描边颜色 - 选中
$color-tagInput_sortable_item_over-bg	var(--semi-color-primary)	拖拽经过的元素前竖线背景色
$color-tagInput_handler-icon-default	var(--semi-color-text-2)	可拖拽的标签拖拽按钮颜色
$spacing-tagInput_small-Y	1px	小尺寸标签输入框标签顶部外边距
$spacing-tagInput_default-Y	$spacing-super-tight	默认尺寸标签输入框标签顶部外边距
$spacing-tagInput_large-Y	3px	大尺寸标签输入框标签顶部外边距
$spacing-tagInput_wrapper_n_paddingX	$spacing-tight	标签输入框标签容器水平内边距
$spacing-tagInput_drag_handler-marginRight	4px	拖拽handler icon的右外边距
$spacing-tagInput_tag_icon_paddingLeft	4px	tag中有handler icon时tag的左内边距
$spacing-tagInput_prefix_suffix-marginX	$spacing-base-tight	标签输入框 prefix/suffix 水平外边距
$height-tagInput-large	$height-control-large	大尺寸标签输入框高度
$height-tagInput-default	$height-control-default	默认尺寸标签输入框高度
$height-tagInput-small	$height-control-small	小尺寸标签输入框高度
$height-tagInput_input_small	20px	小尺寸标签输入框Input框高度
$height-tagInput_input_default	24px	默认尺寸标签输入框Input框高度
$height-tagInput_input_large	24px	大尺寸标签输入框Input框高度
$width-tagInput-clear-medium	$width-icon-medium * 2	标签输入框清空按钮宽度
$width-tagInput-border-default	$border-thickness-control	标签输入框描边描边宽度 - 默认
$width-tagInput-border-hover	$width-tagInput-border-default	标签输入框描边描边宽度 - 悬浮
$width-tagInput-border-focus	$border-thickness-control-focus	标签输入框描边宽度 - 选中态
$width-tagInput_sortable_item_over	2px	拖拽经过的元素前竖线宽度
$radius-tagInput	var(--semi-border-radius-small)	标签输入框圆角
$font-tagInput_prefix_suffix-fontWeight	$font-weight-bold	标签输入框 prefix/suffix 文字字重