#TagMultiselect 标签输入

源代码 | 原版组件

标签输入：把值以可移除的标签（chip）呈现。自由输入形态，需要“输入过滤 + 下拉候选”时用 MenuTagMultiselect。

#基本用法

在输入框内输入文本，按 Enter 提交为一个标签；标签末尾按 Backspace（输入框为空时）移除前一个标签；点击标签把它移回输入框编辑。

自由输入需要 allowArbitrary：与原版一致，未开启它且没有给出 allowedValues 时，输入的任何值都不在合法值域内，Enter 会被拒绝（不报错，但不生成标签）。白名单形态见下一节。

import { useState } from "react";
import { TagMultiselect } from "ooui-react";

function App() {
  const [tags, setTags] = useState<(string | number)[]>(["React", "TypeScript"]);

  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 8, maxWidth: 360 }}>
      <TagMultiselect
        value={tags}
        onChange={setTags}
        allowArbitrary
        placeholder="回车添加标签"
      />
      <div>当前标签：{tags.join("、") || "（空）"}</div>
    </div>
  );
}

export default App;

#键盘编辑

• Enter 提交输入文本为标签；Backspace（inline 输入框为空时）移除末尾标签并把其文本回填输入框以便编辑——按住 Ctrl / Cmd 则只移除、不回填。
• ← / →：光标处于输入框两端时转入标签间导航，向前越过末项后焦点交还输入框（RTL 布局方向随之反转）；Escape 清空输入框中的未提交文本。

#白名单与限制

• allowedValues 给出合法值域，落在其外的标签被判为非法（除非 allowArbitrary）。
• allowDuplicates 允许重复值；tagLimit 限制标签数量，达到后输入禁用。
• allowDisplayInvalidTags 让非法值仍以标签呈现并标 invalid，而非直接拒绝添加。

import { useState } from "react";
import { TagMultiselect } from "ooui-react";

function App() {
  const [tags, setTags] = useState<(string | number)[]>([]);

  return (
    <div style={{ maxWidth: 360 }}>
      <TagMultiselect
        value={tags}
        onChange={setTags}
        allowedValues={["红", "绿", "蓝"]}
        tagLimit={2}
        placeholder="只能输入 红 / 绿 / 蓝，最多 2 个"
      />
    </div>
  );
}

export default App;

注意：组件整体的 invalid 标志（红框）比 onInvalidTagsChange 的口径更宽——失焦时输入框里还留着未提交文本也会标红。看到红框却没收到 onInvalidTagsChange，先检查输入框是否残留文本。

#外部值清洗：pickValidTags

导出的纯函数 pickValidTags(values, { options?, allowedValues?, allowDuplicates? }) 返回传入值集合中合法的子集——剔除值域外的值与 allowDuplicates 为假时的重复项，与组件用同一套规则（传组件同款 props 即得与 onInvalidTagsChange 互补的集合）。外部数据回填 value 之前、或提交之前清洗标签时用它。

#输入框位置与重排

inputPosition 取 inline（缺省，输入框接在标签末尾）、outline（输入框在标签区下方）、none（无输入，纯展示，配合受控值使用）。allowReordering（默认开）允许拖拽调整标签顺序，关闭时新增按 allowedValues 的给定顺序插入。原版可经 config.input / inputWidget 替换内部输入控件，本工程输入框内置、不可替换。

#API

#另见

• 带候选菜单的标签输入：MenuTagMultiselect
• 选项数据的 label / labelText / data 约定：选择与选项