Component Reference - Autocomplete - 《WordPress開発者リソース》日本語

Props
Autocompleters
- The Completer Interface
Usage

Props

以下のプロパティは、コンポーネントの動作を制御するために使用されます。

record

オートコンプリートが適用されるリッチテキスト値オブジェクトです。

必須: はい
タイプ: RichTextValue

onChange

オプションが選択されたときに既存のテキストに挿入するために呼び出される関数です。

必須: はい
タイプ: ( value: string ) => void

onReplace

オプションが選択されたときに既存のテキストを置き換えるために呼び出される関数です。

必須: はい
タイプ: ( values: RichTextValue[] ) => void

completers

現在の要素に適用されるすべてのコンプリータの配列です。

必須: はい
タイプ: Array< WPCompleter >

contentRef


- 必須: はい 
- `````MutableRefObject< HTMLElement | undefined >

children

オートコンプリート内にレンダリングされるノードを返す関数です。

必須: はい
タイプ: Function

isSelected

オートコンプリートコンポーネントが選択されているかどうか、またそのPopoverが表示されるべきかどうかです。

必須: はい
タイプ: Boolean

Autocompleters

オートコンプリータは、ユーザーにテキスト入力を完了するためのオプションを提供することを可能にします。たとえば、Gutenbergにはユーザー名のリストを提供し、@maryのようなユーザー言及で選択を完了するユーザーオートコンプリータが含まれています。

各コンプリータは次のことを宣言します:

その名前。
完了オプションの表示をトリガーするテキストプレフィックス。
生のオプションデータ。
オプションのラベルをレンダリングする方法。
オプションのキーワード、ユーザー入力とオプションを一致させるために使用される単語。
オプションの完了がどのように見えるか、テキストに挿入されるべきか、現在のブロックを置き換えるために使用されるべきかを含みます。

さらに、コンプリータはオプションで次のことを宣言できます:

完了メニューに適用されるクラス名。
特定のテキストノードに適用されるべきかどうか。
コンプリータが特定のコンテキストで適用されるかどうか、オートコンプリートトリガーとクエリの前後に定義された範囲によって。

The Completer Interface

name

コンプリータの名前。拡張性フックを介してオーバーライドされる特定のコンプリータを識別するのに便利です。

タイプ: String
必須: はい

options

完了のための生のオプション。配列、配列を返す関数、または配列のためのプロミスを返す関数である可能性があります。

オプションは任意のタイプまたは形状である可能性があります。コンプリータは、これらのオプションがどのようにレンダリングされ、選択されたときにその完了がどのようになるべきかを宣言します。

タイプ: Array|Function
必須: はい

triggerPrefix

コンプリータをトリガーする文字列プレフィックス。たとえば、Gutenbergのブロックコンプリータは「/」文字が入力されたときにトリガーされます。

タイプ: String
必須: はい

getOptionLabel

指定されたオプションのラベルを返す関数です。ラベルは文字列または文字列、要素、コンポーネントの混合配列である可能性があります。

タイプ: Function
必須: はい

getOptionKeywords

指定されたオプションのキーワードを返す関数です。

タイプ: Function
必須: いいえ

isOptionDisabled

指定されたオプションが無効にされるべきかどうかを返す関数です。無効なオプションは選択できません。

タイプ: Function
必須: いいえ

getOptionCompletion

オプションを受け取り、そのオプションがどのように完了されるべきかに応答する関数です。デフォルトでは、結果はテキストに挿入される値です。ただし、コンプリータは、actionおよびvalueプロパティを持つオブジェクトを返すことで、完了がどのように扱われるべきかを明示的に宣言できます。actionはvalueに対して何をすべきかを宣言します。

現在サポートされているアクションは2つあります:

“insert-at-caret” – テキストにvalueを挿入します（デフォルトの完了アクション）。
“replace” – 現在のブロックをvalueプロパティで指定されたブロックで置き換えます。

allowContext

オートコンプリートトリガーとクエリテキストの前後の範囲を受け取り、そのコンテキストに対してコンプリータが考慮されるべきかどうかを示すブール値を返す関数です。

タイプ: Function
必須: いいえ

className

オートコンプリートポップアップメニューに適用するクラス名です。

タイプ: String
必須: いいえ

isDebounced

オートコンプリータにデバウンスを適用するかどうか。デバウンスを有効にするにはtrueに設定します。

タイプ: Boolean
必須: いいえ

Usage


ブロックエディタは、フィルタを介してカスタムコンプリータの追加をサポートする`````Autocomplete`````の別のラップされたバージョンを提供します。  
ブロックエディタで独自のコンプリータを実装するには、次の手順を行います:  
 1. コンプリータを定義します  
 2. 既存のコンプリータのリストにあなたのコンプリータを追加するコールバックを書く  
 3. コールバックを呼び出す`````editor.Autocomplete.completers`````フックにフィルタを追加します  
次の例では、作成された「フルーツ」オートコンプリータをブロックエディタに追加します。このコールバックでは、この新しいコンプリータを特定のブロックタイプに制限することが可能です。この場合、私たちの「フルーツ」コンプリータは「core/paragraph」ブロックタイプからのみ利用可能です。  
``````bash
( 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ファイルと同様に、次のプラグインの例のように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' );