Tag Input 标签输入框
@lark-ui/core

Tag Input 标签输入框

可创建的多值输入框，用于输入不在预定义选项列表中的值。

ava@cloudflare.com

粘贴以逗号或换行分隔的电子邮件地址。

import { useState } from "react";
import { TagInput } from "@lark-ui/core";

export function TagInputDemo() {
  const [recipients, setRecipients] = useState(["ava@cloudflare.com"]);
  return (
    <TagInput
      label="收件人"
      description="粘贴以逗号或换行分隔的电子邮件地址。"
      placeholder="name@example.com"
      autoComplete="off"
      value={recipients}
      onValueChange={setRecipients}
      validateValue={(value) => /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value)}
    />
  );
}

安装

import { TagInput } from "@lark-ui/core";

用法

使用 value 配合 onValueChange 来控制标签。非受控用法请使用 defaultValue。

const [tags, setTags] = useState<string[]>([]);

<TagInput
  label="Labels"
  value={tags}
  onValueChange={setTags}
  placeholder="Add a label"
/>

示例

不限制数量

frontendpriority

接受任意非空值。

import { TagInput } from "@lark-ui/core";

export function TagInputUnrestrictedDemo() {
  return (
    <TagInput
      defaultValue={["frontend", "priority"]}
      label="标签"
      description="接受任意非空值。"
      placeholder="添加标签"
    />
  );
}

最大数量

alpha

最多三个组。

import { TagInput } from "@lark-ui/core";

export function TagInputLimitedDemo() {
  return (
    <TagInput
      defaultValue={["alpha"]}
      label="访问组"
      maxValues={3}
      description="最多三个组。"
      placeholder="输入组名"
    />
  );
}

表单

设置 name 可让每个标签作为独立的表单值提交，这样 FormData.getAll(name) 就能取回这些标签。输入框中尚未提交的文本会在失去焦点时变成标签，因此点击提交按钮时也会包含它。只要至少有一个标签，required 校验就会通过。

至少添加一个主题，然后提交。

import { useState } from "react";
import { Button, TagInput } from "@lark-ui/core";

/** 每个标签都会作为独立的表单值提交，`required` 校验跟随标签生效。 */
export function TagInputFormDemo() {
  const [submitted, setSubmitted] = useState<string[] | null>(null);

  return (
    <form
      className="flex w-full max-w-md flex-col gap-3"
      onSubmit={(event) => {
        event.preventDefault();
        const data = new FormData(event.currentTarget);
        setSubmitted(data.getAll("topics").map(String));
      }}
    >
      <TagInput
        name="topics"
        required
        label="主题"
        description="至少添加一个主题，然后提交。"
        placeholder="添加主题"
      />
      <div className="flex items-center gap-3">
        <Button type="submit" variant="primary">
          提交
        </Button>
        {submitted ? (
          <code className="text-sm text-lark-subtle">
            topics: {JSON.stringify(submitted)}
          </code>
        ) : null}
      </div>
    </form>
  );
}

只读

readOnly 会显示标签并保持输入框可聚焦，但无法添加或移除标签。与原生只读输入框一样，它会被表单校验跳过，即使设置了 required。

billingdnsworkers

由你所在组织的管理员管理。

import { TagInput } from "@lark-ui/core";

export function TagInputReadOnlyDemo() {
  return (
    <TagInput
      readOnly
      defaultValue={["billing", "dns", "workers"]}
      label="已分配团队"
      description="由你所在组织的管理员管理。"
    />
  );
}

本地化

uno
import { TagInput } from "@lark-ui/core";

export function TagInputLocalizationDemo() {
  return (
    <TagInput
      defaultValue={["uno"]}
      label="Etiquetas"
      labels={{
        input: "Agregar etiqueta",
        removeValue: (value) => `Eliminar ${value}`,
        invalidValue: (value) => `${value} no es valido.`,
        maxValuesReached: (maxValues) => `Maximo de ${maxValues} etiquetas.`,
      }}
      maxValues={3}
      placeholder="Agregar una etiqueta"
    />
  );
}

行为

按 Enter、逗号或 Tab 键即可创建标签。失去焦点同样会提交当前值。粘贴以逗号或换行分隔的文本时，会先将其插入光标处的文本中，然后同步创建各个值。粘贴不含分隔符的文本时，其行为与普通粘贴相同。重复的值会被忽略。

本地化

使用 labels 可以翻译标签输入框（TagInput）生成的所有文案：默认输入名称、标签移除操作、无效值提示和超限提示。

<TagInput
  label="Etiquetas"
  labels={{
    input: "Agregar etiqueta",
    removeValue: (value) => `Eliminar ${value}`,
    invalidValue: (value) => `${value} no es valido.`,
    maxValuesReached: (maxValues) => `Maximo de ${maxValues} etiquetas.`,
  }}
/>

API 参考

属性类型默认值说明
altstring--
autoCompleteReact.HTMLInputAutoCompleteAttribute--
checkedboolean--
heightnumber | string--
liststring--
namestring-以该名称将每个已接受的标签作为独立的表单值提交。
placeholderstring--
readOnlyboolean-禁止添加或删除标签，同时保持输入框可聚焦。
requiredboolean-原生表单校验要求至少有一个已接受的标签。与原生输入框一样，`readOnly` 的 TagInput 不参与校验。
typeReact.HTMLInputTypeAttribute--
widthnumber | string--
classNamestring--
idstring--
langstring--
titlestring--
childrenReactNode--
valuestring[]--
validateValueobject--
maxValuesnumber--
labelsTagInputLabels-生成的输入、操作和校验文案所对应的翻译标签。
labelReactNode--
labelTooltipReactNode--
descriptionReactNode--
errorstring | object--
variant"default" | "error""default"-
disabledboolean--