标签输入 · Tokenizer

标签输入用于表单输入场景。下面的官方示例展示原生用法与状态，属性名保持上游 API。

安装与前置条件

npm install @astryxdesign/core@0.7.1 @astryxdesign/theme-neutral@0.7.1 @stylexjs/stylex@0.19.0

需要 React 19+，按顺序导入基础 CSS 和主题，并设置 Theme Provider。参见开始使用。

示例与使用方式

• 标签输入 · 综合展示 1：首先体验这个示例，再查看代码理解组件的组合方式。
• 标签输入 · 交互示例 2：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
• 标签输入 · 交互示例 3：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
• 标签输入 · 交互示例 4：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
• 标签输入 · 交互示例 5：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
• 标签输入 · 交互示例 6：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
• 标签输入 · 溢出处理 7：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
• 标签输入 · 多种状态 8：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。

API 与上游详细参考

优先使用 0.7.1 官方中文说明；上游尚未提供中文的条目保留英文。属性名、类型及默认值保持原生 API，不把示例状态名称当成组件属性。

Tokenizer

Tokenizer is a multi-select input that lets users search, select, and manage multiple items displayed as removable chips. Use it when users need to build a set of selections from a searchable data source, like adding team members, applying tags, or choosing filters.

使用建议

• Write a placeholder that tells users what they can search for, such as "Search people..." or "Add tags...", so the input is not a blank mystery.
• Set maxEntries when the number of selections should be bounded, like limiting a review to 5 approvers.
• Use hasCreate for free-form tagging where users need to enter values that do not exist in the search source.
• Show validation status with the status prop so users know immediately when a selection is missing or invalid.
• 避免：Don't use Tokenizer for single-item selection; use Typeahead instead. Tokenizer is for building sets of two or more items.
• 避免：Avoid applying custom colors to individual tokens inside a Tokenizer; use the default token style for visual consistency across the set.
• 避免：Don't hide the label; every Tokenizer needs a visible label so users understand what they are selecting. Use isLabelHidden only when surrounding context makes the purpose obvious.
• 避免：Wrap a disabled Tokenizer in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.

主题 API

{
  "targets": [
    {
      "className": "astryx-tokenizer",
      "visualProps": [
        "size",
        "status"
      ],
      "states": [
        "disabled"
      ]
    }
  ]
}

组件结构

• Label: The visible text above the input describing what the user is selecting. Also used as the accessible name.
• Token chips: Removable chips representing each selected item. Each chip shows a label and a remove button.
• Search input: The text input where users type to search the data source. Hides when maxEntries is reached.
• Dropdown menu: The search results list that appears below the input as the user types.
• Spinner: Loading indicator shown at the end of the field while a search is in flight.
• End content: A trailing slot after the input for action buttons, counts, or other controls.
• Clear button: A button that removes all selected tokens at once. Shown when hasClear is true and tokens are present.

完整示例的额外依赖

部分示例使用独立图标包。示例清单中的每条安装命令包含该示例实际需要的依赖；若要运行本页全部示例，还需安装：

npm install @heroicons/react@2.2.0