此组件用于为子输入组件提供自动补全支持。

Props

以下 props 用于控制组件的行为。

record

应用自动补全器的富文本值对象。

  • Required: Yes
  • Type: RichTextValue

onChange

当选择选项以插入到现有文本中时调用的函数。

  • Required: Yes
  • Type: ( value: string ) => void

onReplace

当选择选项以替换现有文本时调用的函数。

  • Required: Yes
  • Type: ( values: RichTextValue[] ) => void

completers

要应用于当前元素的所有补全器的数组。

  • Required: Yes
  • Type: Array< WPCompleter >

contentRef

包含可编辑元素的 ref，该元素将作为 Autocomplete 的 Popover 的锚点。

  • Required: Yes
  • RefObject< HTMLElement | undefined >

children

返回要在 Autocomplete 内部渲染的节点的函数。

  • Required: Yes
  • Type: Function

isSelected

是否选中了 Autocomplete 组件，以及是否应显示其 Popover。

  • Required: Yes
  • Type: Boolean

Autocompleters

自动补全器使我们能够为用户提供完成文本输入的选项。例如，Gutenberg 包含一个用户自动补全器，它提供用户名称列表，并使用类似 @mary 的用户提及来完成选择。

每个补全器声明：

  • 其名称。
  • 应触发补全选项显示的文本前缀。
  • 原始选项数据。
  • 如何渲染选项标签。
  • 选项的关键字，即用于将选项与用户输入匹配的词。
  • 选项补全的外观，包括是将其插入文本还是用于替换当前块。

此外，补全器还可以选择性地声明：

  • 应用于补全菜单的类名。
  • 是否应应用于指定的文本节点。
  • 补全器是否在给定上下文中适用，该上下文通过自动补全触发器和查询前后的 Range 来定义。

The Completer Interface

name

补全器的名称。有助于通过可扩展性钩子标识特定的补全器以便覆盖。每个补全器应具有唯一的名称。

  • Type: String
  • Required: Yes

options

补全的原始选项。可以是数组、返回数组的函数或返回数组 Promise 的函数。

选项可以是任何类型或形状。补全器声明如何渲染这些选项以及在选中时它们的补全结果是什么。

  • Type: Array|Function
  • Required: Yes

triggerPrefix

应触发补全器的字符串前缀。例如，Gutenberg 的块补全器在输入“/”字符时被触发。

  • Type: String
  • Required: Yes

getOptionLabel

返回给定选项标签的函数。标签可以是字符串，也可以是字符串、元素和组件的混合数组。

  • Type: Function
  • Required: Yes

getOptionKeywords

返回指定选项关键字的函数。

  • Type: Function
  • Required: No

isOptionDisabled

返回指定选项是否应被禁用的函数。禁用的选项无法被选中。

  • Type: Function
  • Required: No

getOptionCompletion

接受一个选项并响应如何完成该选项的函数。默认情况下，结果是插入到文本中的值。但是，补全器可以通过返回具有 action 和 value 属性的对象来显式声明如何处理补全结果。action 声明对 value 应执行的操作。

目前支持两种操作：

  • “insert-at-caret” – 将 value 插入到文本中（默认的补全操作）。
  • “replace” – 使用 value 属性中指定的块替换当前块。

allowContext

接受自动补全触发器和查询文本之前的 Range 和之后的 Range，并返回一个布尔值，指示是否应在该上下文中考虑补全器。

  • Type: Function
  • Required: No

className

应用于自动补全弹出菜单的类名。

  • Type: String
  • Required: No

isDebounced

是否对自动补全器进行防抖处理。此设置仅影响 options 参数；useItems 会忽略它。

  • Type: Boolean
  • Required: No

Usage

Autocomplete 组件目前不打算作为独立组件使用。它被其他包用来为块编辑器提供自动补全支持。

块编辑器提供了一个单独的包装版本 Autocomplete，支持通过过滤器添加自定义补全器。

要在块编辑器中实现你自己的补全器，你需要：
1. 定义补全器
2. 编写一个回调函数，将你的补全器添加到现有补全器列表中
3. 向 editor.Autocomplete.completers 钩子添加一个过滤器，该过滤器将调用你的回调函数

下面的示例将在块编辑器中添加一个虚构的“fruits”自动补全器。注意，在回调中可以将这个新的补全器限制为特定的块类型。在这种情况下，我们的“fruits”补全器仅在“core/paragraph”块类型中可用。

( function () {
    // Define the completer
    const fruits = {
        name: 'fruit',
        // The prefix that triggers this completer
        triggerPrefix: '~',
        // The option data
        options: [
            { visual: '🍎', name: 'Apple', id: 1 },
            { visual: '🍊', name: 'Orange', id: 2 },
            { visual: '🍇', name: 'Grapes', id: 3 },
            { visual: '🥭', name: 'Mango', id: 4 },
            { visual: '🍓', name: 'Strawberry', id: 5 },
            { visual: '🫐', name: 'Blueberry', id: 6 },
            { visual: '🍒', name: 'Cherry', id: 7 },
        ],
        // Returns a label for an option like "🍊 Orange"
        getOptionLabel: ( option ) => `${ option.visual } ${ option.name }`,
        // Declares that options should be matched by their name
        getOptionKeywords: ( option ) => [ option.name ],
        // Declares that the Grapes option is disabled
        isOptionDisabled: ( option ) => option.name === 'Grapes',
        // Declares completions should be inserted as abbreviations
        getOptionCompletion: ( option ) => option.visual,
    };

    // Define a callback that will add the custom completer to the list of completers
    function appendTestCompleters( completers, blockName ) {
        return blockName === 'core/paragraph'
            ? [ ...completers, fruits ]
            : completers;
    }

    // Trigger our callback on the `editor.Autocomplete.completers` hook
    wp.hooks.addFilter(
        'editor.Autocomplete.completers',
        'fruit-test/fruits',
        appendTestCompleters,
        11
    );
} )();

最后，像往常一样入队你的 JavaScript 文件，如下面的插件示例所示：

<?php
/**
 * Plugin Name: Fruit Autocompleter
 * Plugin URI: https://github.com/WordPress/gutenberg
 * Author: Gutenberg Team
 */

/**
 * Registers a custom script for the plugin.
 */
function enqueue_fruit_autocompleter_plugin_script() {
    wp_enqueue_script(
        'fruit-autocompleter',
        plugins_url( '/index.js', __FILE__ ),
        array(
            'wp-hooks',
        ),
    );
}

add_action( 'init', 'enqueue_fruit_autocompleter_plugin_script' );