注釈（Annotations）

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,
   },
} );

範囲の開始と終了は、関連するRichTextのテキストのみに基づいて計算されるべきです。例えば、次のHTMLでは位置0は大文字のSの前の位置を指します：

<strong>Strong text</strong>

正しい位置を特定するために、wp.richText.createメソッドを使用できます。これにより、HTMLの一部をテキストとフォーマットに分割できます。

利用可能なすべてのプロパティは、addAnnotationアクションのAPIドキュメントに記載されています。

プロパティrichTextIdentifierは、注釈が適用されるRichTextインスタンスの識別子です。これは、ブロックが異なる属性のデータを管理するために使用される複数のリッチテキストインスタンスを持つ可能性があるため、正しいインスタンス内でテキストをハイライトするために渡す必要があります。

例えば、Paragraphブロックには識別子contentを持つ単一のRichTextインスタンスしかありません。引用ブロックタイプには2つのRichTextインスタンスがあるため、引用内のテキストをハイライトしたい場合は、注釈を追加する際にcitationをrichTextIdentifierとして渡す必要があります。引用内容をターゲットにするには、識別子valueを使用する必要があります。正しい識別子を見つけるには、ブロックタイプのソースコードを参照してください。

Block annotation

ブロック全体に注釈を付けることも可能です。その場合は、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;
}

Text annotation

テキスト注釈は、startおよびendプロパティによって制御されます。シンプルなstartおよびendプロパティはHTMLには機能しないため、これらのプロパティはrich-text内部構造内のオフセットであると見なされます。簡単に考えると、すべてのHTMLが削除され、その後注釈のstartおよびendを計算するように考えることができます。