注释

注意：此 API 为实验性，这意味着在未来的任何版本中都可能发生不向后兼容的更改或被移除。

注释是一种高亮显示由块编辑器创建的帖子中特定部分的方法。此类示例包括对文本片段进行评论和拼写检查。两者都可以使用注释 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,
    },
} );

范围的开始和结束应仅基于相关 RichText 的文本进行计算。例如，在以下 HTML 中，位置 0 将指向上面大写字母 S 之前的位置：

<strong>Strong text</strong>

为了帮助确定正确的位置，可以使用 wp.richText.create 方法。这将把 HTML 片段拆分为文本和格式。

所有可用属性都可以在 addAnnotation 操作的 API 文档中找到。

属性 richTextIdentifier 是注释所适用的 RichText 实例的标识符。这是必要的，因为块可能具有多个 rich text 实例，这些实例用于管理不同属性的数据，因此您需要传递它以高亮显示正确实例内的文本。

例如，段落块只有一个 RichText 实例，其标识符为 content。引用块类型有两个 RichText 实例，因此如果您希望高亮显示引文中的文本，在添加注释时需要将 citation 作为 richTextIdentifier 传递。要针对引用内容，您需要使用标识符 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。