title: "注解" post_status: publish comment_status: open taxonomy: category: - gutenberg-docs post_tag: - Block Api - Reference Guides - Repos

注解

注解是一种高亮区块编辑器所创建文章中特定片段的方式。例如对文本片段进行评论和拼写检查。两者都可以使用注解 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 实例的标识符。这是必需的，因为区块可能包含多个富文本实例，用于管理不同属性的数据，因此您需要传入此标识符，以便在正确的实例中高亮显示文本。

例如，段落区块只有一个 RichText 实例，其标识符为 content。引用区块类型有 2 个 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 位置。