FormTokenField 是一个类似于临时编辑器界面中的标签和分类字段，或 OS X Mail 应用中的“收件人”字段的字段。可以通过键入或从建议令牌列表中选择来输入令牌。

最多会显示一百个与用户当前输入内容匹配的建议供用户选择（自动补全）。令牌以“,”字符分隔。可以使用上箭头或下箭头选择建议，并通过 Tab 键或 Enter 键添加。

value 属性的处理方式类似于受控表单组件。有关更多信息，请参阅 React 文档中的 Forms。

键盘无障碍性

  • left arrow – 如果输入字段为空，将插入点移至前一个令牌之前
  • right arrow – 如果输入字段为空，将插入点移至后一个令牌之后
  • up arrow – 选择上一个建议
  • down arrow – 选择下一个建议
  • tab / enter – 如果已选择建议，则将该建议作为新令牌插入；否则，将输入到输入框中的值作为新令牌插入
  • comma – 将输入到输入框中的值作为新令牌插入

属性

  • value – 要显示为字段中令牌的字符串或对象数组。如果数组中包含对象，它们必须具有 value 属性。以下是可以作为 value 传入的对象示例：
{
    value: '(string) The value of the token.',
    status: "(string) One of 'error', 'validating', or 'success'. Applies styles to token."
    title: '(string) If not falsey, will add a title to the token.',
    onMouserEnter: '(function) Function to call when onMouseEnter event triggered on token.'
    onMouseLeave: '(function) Function to call when onMouseLeave is triggered on token.'
}
  • displayTransform – 用于转换令牌以供显示的函数。（在编辑器中，这是为了解码嵌入在标签中的 HTML 实体——否则，如标签名称中的 & 会被双重编码为 &，一次由 REST API 处理，另一次由 React 处理）。
  • saveTransform – 用于转换令牌以供保存的函数。默认情况下会修剪令牌值。此函数也在将建议与当前值进行匹配时应用，以便正确处理前导或尾随空格。（在编辑器中，这是为了去除标签名称的前导和尾随空格，就像 wp-admin 所做的那样。否则 REST API 不会保存它们。）
  • onChange – 当令牌发生变化时调用的函数。新的令牌数组会传递给回调函数。
  • onInputChange – 当用户在输入字段中键入内容时调用的函数。可用于触发自动补全请求。
  • onFocus – 当 TokenField 获得焦点时调用的函数。事件会传递给回调函数。对分析很有用。
  • suggestions – 呈现给用户的建议令牌字符串数组。
  • maxSuggestions – 同时显示的最大建议数量。
  • tokenizeOnSpace – 如果为 true，当 TokenField 获得焦点且按下 space 键时，将添加令牌。
  • isBorderless – 当为 true 时，渲染不带背景的令牌。
  • maxLength – 如果传递了该参数，当令牌数量大于或等于 maxLength 时，TokenField 将禁用添加新令牌的能力。
  • disabled – 当为 true 时，无法添加或删除令牌。
  • placeholder – 如果传递了该参数，当没有值令牌存在时，TokenField 输入框将显示占位符字符串。
  • help – 控件的附加说明。仅用于控件的有意义描述或说明。包含描述的元素将通过 aria-describedby 程序化地关联到 FormTokenField。默认为操作指南消息（例如：用逗号或 Enter 键分隔。）；传递空字符串可隐藏它。
  • messages – 允许自定义屏幕阅读器在不同场合下呈现的消息：
    • added – 用户添加了新令牌。
    • removed – 用户移除了现有令牌。
    • remove – 用户聚焦于移除令牌的按钮。
    • __experimentalInvalid – 用户尝试添加未通过验证的令牌。
  • __experimentalRenderItem – 为建议列表中的每个选项调用的自定义渲染器。渲染 prop 接收一个对象作为其参数，该对象在 item 键下包含单个选项的数据（直接来自传递给 options prop 的数据数组）。
  • __experimentalExpandOnFocus – 如果为 true，当输入字段获得焦点时，建议列表将始终展开。
  • __experimentalShowHowTo – 已弃用。请使用 help prop 代替。help prop 现在默认为之前的操作指南文本；如果您之前传递 __experimentalShowHowTo={ false } 来隐藏它，请改为向 help 传递空字符串。
  • __experimentalValidateInput – 如果传递了该参数，所有输入的值的将在作为令牌添加之前进行验证。
  • __experimentalAutoSelectFirstMatch – 如果为 true，当用户按下 Enter 键时（或当 tokenizeOnSpace 为 true 时按下空格键），选择第一个匹配的建议。
  • tokenizeOnBlur – 如果为 true，当字段失去焦点时，将任何 incompleteTokenValue 作为新令牌添加。

用法

import { useState } from 'react';
import { FormTokenField } from '@wordpress/components';

const continents = [
    'Africa',
    'America',
    'Antarctica',
    'Asia',
    'Europe',
    'Oceania',
];

const MyFormTokenField = () => {
    const [ selectedContinents, setSelectedContinents ] = useState( [] );

    return (
        <FormTokenField
            value={ selectedContinents }
            suggestions={ continents }
            onChange={ ( tokens ) => setSelectedContinents( tokens ) }
        />
    );
};