Аннотации

Примечание. Этот API является экспериментальным, что означает, что в любой будущей версии он может быть изменен или удален без обратной совместимости.

Аннотации — это способ выделить конкретную часть в посте Гутенберга. Примеры этого включают комментирование фрагмента текста и проверку орфографии. Оба могут использовать API аннотаций для пометки фрагмента текста.

API

Чтобы увидеть API для себя, проще всего иметь блок длиной не менее 200 символов без форматирования и поместить в консоль следующее:

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

Начало и конец диапазона должны быть рассчитаны только на основе текста соответствующего RichText. Например, в следующем HTML-положении 0 будет означать позицию перед заглавной S:

<strong>Strong text</strong>

Чтобы помочь с определением правильных позиций, wp.richText.createможно использовать метод. Это разделит часть HTML на текст и форматы.

Все доступные свойства можно найти в документации API addAnnotationдействия.

Блок аннотации

Также возможно полностью аннотировать блок. В этом случае просто укажите selectorсвойство и установите его block. По умолчанию selectorэто range, который может быть использован для текста аннотации.

wp.data.dispatch( 'core/annotations' ).addAnnotation( {
    source: "my-annotations-plugin",
    blockClientId: wp.data.select( 'core/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аннотации.