アノテーション

注意: アノテーション API は実験中の機能です。将来のバージョンで後方互換性のない形で変更されたり削除される可能性があります。

アノテーションはブロックエディターで作成された投稿の特定箇所を強調表示する方法です。アノテーションの例としては選択したテキストのコメントやスペルチェックがあります。どちらもアノテーション API を使用して選択したテキストをマークできます。

API を簡単に確認するには、ブロックエディターで書式を含めずに200文字入力し、コンソールに次のコードを貼り付けてください。

wp.data.dispatch( 'core/annotations' ).addAnnotation( {
	source: 'my-annotations-plugin',
	blockClientId: wp.data.select( 'core/block-editor' ).getBlockOrder()[ 0 ],
	richTextIdentifier: 'content',
	range: {
		start: 50,
		end: 100,
	},
} );

領域 (range) の始まりと終わりは関連する RichText のテキストのみに基づいて算出されます。たとえば次の HTML では 位置「0」は大文字の「S」の前の位置を参照します。

<strong>Strong text</strong>

正しい位置の決定には wp.richText.create メソッドを使用できます。このメソッドは HTML のコードをテキストと書式に分けます。

すべての利用可能なプロパティは addAnnotation アクションの API ドキュメントを参照してください。

プロパティ richTextIdentifier はアノテーションを適用する RichText インスタンスの識別子です。ブロックは異なる属性のデータ管理のため複数の RichText インスタンスを持つ可能性があります。このとき正しいテキストを強調表示するには識別子を渡す必要があります。

たとえば「段落」ブロックにはただ1つの RichText インスタンス content しかありません。一方、「引用」ブロックタイプには2つの RichText インスタンスがあり、引用のリード文を強調表示したければアノテーションを追加する際、richTextIdentifier に citation を渡す必要があります。引用内容の本文を強調表示するには識別子 value を使用する必要があります。正しい識別子を見つけるにはブロックタイプのソースコードを参照してください。

ブロック全体にアノテーションをつけることも可能です。この場合 selector プロパティに block を設定します。selector のデフォルトはテキストアノテーションで使用される range です。

wp.data.dispatch( 'core/annotations' ).addAnnotation( {
	source: 'my-annotations-plugin',
	blockClientId: wp.data.select( 'core/block-editor' ).getBlockOrder()[ 0 ],
	selector: 'block',
} );

ボックスへのスタイルがありませんので、アノテーションが見えるように CSS を提供する必要があります。

.is-annotated-by-my-annotations-plugin {
	outline: 1px solid black;
}

テキストアノテーションは start プロパティと end プロパティで制御されます。単純に求めた start と end では HTML で正しく動作しません。rich-text 内部構造内のオフセットを想定しているためです。便宜上、すべての HTML タグが削除されたと仮定してアノテーションのstart と end を算出すると良いでしょう。

原文

最終更新日: 2023年5月7日