块编辑器开发文档

💡 云策文档标注

概述

本文档介绍了 editor.Autocomplete.completers 过滤器,用于扩展和覆盖块编辑器中的自动完成器列表。该过滤器由 @wordpress/block-editor 包中的 Autocomplete 组件应用,而 @wordpress/components 包提供了基础组件,但块通常应使用前者。

关键要点

  • editor.Autocomplete.completers 过滤器用于管理块编辑器的自动完成器列表。
  • @wordpress/block-editor 包中的 Autocomplete 组件应用此过滤器,而 @wordpress/components 包的基础组件不应用。
  • 开发者可以通过此过滤器添加自定义自动完成器,例如缩写补全器。

代码示例

// Our completer
const acronymCompleter = {
    name: 'acronyms',
    triggerPrefix: '::',
    options: [
        { letters: 'FYI', expansion: 'For Your Information' },
        { letters: 'AFAIK', expansion: 'As Far As I Know' },
        { letters: 'IIRC', expansion: 'If I Recall Correctly' },
    ],
    getOptionKeywords( { letters, expansion } ) {
        const expansionWords = expansion.split( /s+/ );
        return [ letters, ...expansionWords ];
    },
    getOptionLabel: acronym => acronym.letters,
    getOptionCompletion: ( { letters, expansion } ) => (
        <abbr title={ expansion }>{ letters }</abbr>,
    ),
};

// Our filter function
function appendAcronymCompleter( completers, blockName ) {
    return blockName === 'my-plugin/foo' ?
        [ ...completers, acronymCompleter ] :
        completers;
}

// Adding the filter
wp.hooks.addFilter(
    'editor.Autocomplete.completers',
    'my-plugin/autocompleters/acronym',
    appendAcronymCompleter
);

📄 原文内容

The editor.Autocomplete.completers filter is for extending and overriding the list of autocompleters used by blocks.

The Autocomplete component found in @wordpress/block-editor applies this filter. The @wordpress/components package provides the foundational Autocomplete component that does not apply such a filter, but blocks should generally use the component provided by @wordpress/block-editor.

Example

Here is an example of using the editor.Autocomplete.completers filter to add an acronym completer. You can find full documentation for the autocompleter interface with the Autocomplete component in the @wordpress/components package.

// Our completer
const acronymCompleter = {
    name: 'acronyms',
    triggerPrefix: '::',
    options: [
        { letters: 'FYI', expansion: 'For Your Information' },
        { letters: 'AFAIK', expansion: 'As Far As I Know' },
        { letters: 'IIRC', expansion: 'If I Recall Correctly' },
    ],
    getOptionKeywords( { letters, expansion } ) {
        const expansionWords = expansion.split( /s+/ );
        return [ letters, ...expansionWords ];
    },
    getOptionLabel: acronym => acronym.letters,
    getOptionCompletion: ( { letters, expansion } ) => (
        <abbr title={ expansion }>{ letters }</abbr>,
    ),
};

// Our filter function
function appendAcronymCompleter( completers, blockName ) {
    return blockName === 'my-plugin/foo' ?
        [ ...completers, acronymCompleter ] :
        completers;
}

// Adding the filter
wp.hooks.addFilter(
    'editor.Autocomplete.completers',
    'my-plugin/autocompleters/acronym',
    appendAcronymCompleter
);