Регистрация блока

register_block_type

Тип: Function

Каждый блок начинается с регистрации нового определения типа блока. Функция registerBlockType принимает два аргумента: блок name и объект конфигурации блока.

Block Name

Тип: String

Имя для блока — это уникальная строка, которая идентифицирует блок. Имена должны быть структурированы как namespace/block-name, где namespace — это имя вашего плагина или темы.

// Registering my block with a unique name
registerBlockType( 'my-plugin/book', {} );

Примечание. Имя блока может содержать только строчные буквенно-цифровые символы и тире и должно начинаться с буквы.

Примечание. Это имя используется в качестве разделителей комментариев как . Блоки, предоставляемые ядром, не включают пространство имен при сериализации.

Конфигурация блока

Тип: Object [ { key: value }]

Блок требует указания нескольких свойств, прежде чем он может быть успешно зарегистрирован. Они определяются через объект конфигурации, который включает в себя следующее:

Title

Тип: String

Это отображаемое название для вашего блока, которое можно перевести с помощью функций перевода. Вставка блоков покажет это имя.

// Our data object
title: __( 'Book' )

Description (необязательно)

Тип: String

Это краткое описание вашего блока, которое можно перевести с помощью наших функций перевода. Оно будет показано при вставке блока.

description: __( 'Block showing a Book card.' )

Icon (необязательно)

Тип: String |Object

Необходимо указать свойство значка, чтобы упростить идентификацию блока. Это может быть любой из Dashicons WordPress или пользовательский svg элемент.

// Specifying a dashicon for the block
icon: 'book-alt',

// Specifying a custom svg for the block
icon: <svg viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><path fill="none" d="M0 0h24v24H0V0z" /><path d="M19 13H5v-2h14v2z" /></svg>,

Примечание: Пользовательская SVG иконка будет автоматически обернута в wp.components.SVGкомпонент , чтобы добавить атрибуты доступности ( aria-hidden, roleи focusable).

Объект также может быть передан как icon, в этом случае icon, как указано выше, должен быть включен в свойство src. Помимо src объект может содержать цвета фона и переднего плана, эти цвета будут отображаться со значком, когда они применимы, например: во вставке.

icon: {
    // Specifying a background color to appear with the icon e.g.: in the inserter.
    background: '#7e70af',
    // Specifying a color for the icon (optional: if not set, a readable color will be automatically defined)
    foreground: '#fff',
    // Specifying a dashicon for the block
    src: 'book-alt',
} ,

Keywords (необязательно)

Тип: Array

Иногда блок может иметь псевдонимы, которые помогают пользователям обнаружить его во время поиска. Например, imageблок может также захотеть быть обнаруженным photo. Вы можете сделать это, предоставив массив терминов (которые можно перевести). Разрешается добавлять не более трех терминов на блок.

// Make it easier to discover a block with keyword aliases.
// These can be localised so your keywords work across locales.
keywords: [ __( 'image' ), __( 'photo' ), __( 'pics' ) ],

Styles (необязательно)

Тип: Array

Стили блоков могут использоваться для предоставления альтернативных стилей для блока. Это работает путем добавления имени класса в оболочку блока. Используя CSS, разработчик темы может выбрать имя класса для изменения стиля, если оно существует.

// Register block styles.
styles: [
    // Mark style as default.
    {
        name: 'default',
        label: __( 'Rounded' ),
        isDefault: true
    },
    {
        name: 'outline',
        label: __( 'Outline' )
    },
    {
        name: 'squared',
        label: __( 'Squared' )
    },
],

Плагины и Темы также могут регистрировать пользовательский стиль блока для существующих блоков.

Attributes (необязательно)

Тип: Object

Атрибуты обеспечивают потребности структурированных данных блока. Они могут существовать в разных формах при сериализации, но они объявляются вместе в общем интерфейсе.

// Specifying my block attributes
attributes: {
    cover: {
        type: 'string',
        source: 'attribute',
        selector: 'img',
        attribute: 'src',
    },
    author: {
        type: 'string',
        source: 'html',
        selector: '.book-author',
    },
    pages: {
        type: 'number',
    },
},

Смотрите: Attributes.

Transforms (необязательно)

Тип: Array

Преобразования предоставляют правила для того, из чего и во что он может быть преобразован. Блок может быть преобразован из другого блока, шорткода, регулярного выражения, файла или необработанного узла DOM.

Например, блок абзаца может быть преобразован в блок заголовка.

ES5
ESNext

transforms: {
    from: [
        {
            type: 'block',
            blocks: [ 'core/paragraph' ],
            transform: function ( content ) {
                return createBlock( 'core/heading', {
                    content,
                } );
            },
        },
    ]
},

transforms: {
    from: [
        {
            type: 'block',
            blocks: [ 'core/paragraph' ],
            transform: ( { content } ) => {
                return createBlock( 'core/heading', {
                    content,
                } );
            },
        },
    ]
},

Существующий шорткод может быть преобразован в блок.

ES5
ESNext

transforms: {
    from: [
        {
            type: 'shortcode',
            // Shortcode tag can also be an array of shortcode aliases
            tag: 'caption',
            attributes: {
                // An attribute can be source from a tag attribute in the shortcode content
                url: {
                    type: 'string',
                    source: 'attribute',
                    attribute: 'src',
                    selector: 'img',
                },
                // An attribute can be source from the shortcode attributes
                align: {
                    type: 'string',
                    shortcode: function( attributes ) {
                        var align = attributes.named.align ? attributes.named.align : 'alignnone';
                        return align.replace( 'align', '' );
                    },
                },
            },
        },
    ]
},

transforms: {
    from: [
        {
            type: 'shortcode',
            // Shortcode tag can also be an array of shortcode aliases
            tag: 'caption',
            attributes: {
                // An attribute can be source from a tag attribute in the shortcode content
                url: {
                    type: 'string',
                    source: 'attribute',
                    attribute: 'src',
                    selector: 'img',
                },
                // An attribute can be source from the shortcode attributes
                align: {
                    type: 'string',
                    shortcode: ( { named: { align = 'alignnone' } } ) => {
                        return align.replace( 'align', '' );
                    },
                },
            },
        },
    ]
},

Блок также может быть преобразован в другой тип блока. Например, блок заголовка может быть преобразован в блок абзаца.

ES5
ESNext

transforms: {
    to: [
        {
            type: 'block',
            blocks: [ 'core/paragraph' ],
            transform: function( content ) {
                return createBlock( 'core/paragraph', {
                    content,
                } );
            },
        },
    ],
},

transforms: {
    to: [
        {
            type: 'block',
            blocks: [ 'core/paragraph' ],
            transform: ( { content } ) => {
                return createBlock( 'core/paragraph', {
                    content,
                } );
            },
        },
    ],
},

Необязательная isMatchфункция может быть указана для объекта преобразования. Это дает возможность выполнить дополнительные проверки того, должно ли быть возможно преобразование. Возврат falseиз этой функции предотвратит отображение преобразования в качестве опции для пользователя.

ES5
ESNext

transforms: {
    to: [
        {
            type: 'block',
            blocks: [ 'core/paragraph' ],
            isMatch: function( attribute ) {
                return attributes.isText;
            },
            transform: function( content ) {
                return createBlock( 'core/paragraph', {
                    content,
                } );
            },
        },
    ],
},

transforms: {
    to: [
        {
            type: 'block',
            blocks: [ 'core/paragraph' ],
            isMatch: ( { isText } ) => isText,
            transform: ( { content } ) => {
                return createBlock( 'core/paragraph', {
                    content,
                } );
            },
        },
    ],
},

Чтобы контролировать приоритет, с которым применяется преобразование, определите
числовое свойство priority для вашего объекта преобразования, где более низкое значение будет иметь приоритет над более высокими значениями. Это ведет себя так же, как хук WordPress . Как и у хуков, приоритет по умолчанию — это 10, когда не установлено иное.

Файл можно поместить в редактор и преобразовать в блок с соответствующим преобразованием.

ES5
ESNext

transforms: {
    from: [
        {
            type: 'files',
            isMatch: function ( files ) {
                return files.length === 1;
            },
            // We define a lower priority (higher number) than the default of 10. This
            // ensures that the File block is only created as a fallback.
            priority: 15,
            transform: function( files ) {
                var file = files[ 0 ];
                var blobURL = createBlobURL( file );

                // File will be uploaded in componentDidMount()
                return createBlock( 'core/file', {
                    href: blobURL,
                    fileName: file.name,
                    textLinkHref: blobURL,
                } );
            },
        },
    ]
}

transforms: {
    from: [
        {
            type: 'files',
            isMatch: ( files ) => files.length === 1,
            // We define a lower priority (higher number) than the default of 10. This
            // ensures that the File block is only created as a fallback.
            priority: 15,
            transform: ( files ) => {
                const file = files[ 0 ];
                const blobURL = createBlobURL( file );

                // File will be uploaded in componentDidMount()
                return createBlock( 'core/file', {
                    href: blobURL,
                    fileName: file.name,
                    textLinkHref: blobURL,
                } );
            },
        },
    ]
}

Префиксное преобразование — это преобразование, которое будет применяться, если пользователь префиксирует некоторый текст, например, в блоке абзаца с заданным шаблоном и завершающим пробелом.

ES5
ESNext

transforms: {
    from: [
        {
            type: 'prefix',
            prefix: '?',
            transform: function( content ) {
                return createBlock( 'my-plugin/question', {
                    content,
                } );
            },
        },
    ]
}

transforms: {
    from: [
        {
            type: 'prefix',
            prefix: '?',
            transform( content ) {
                return createBlock( 'my-plugin/question', {
                    content,
                } );
            },
        },
    ]
}

parent (необязательно)

Тип: Array

Блоки могут быть вставлены в блоки, которые используют InnerBlocksкак вложенный контент. Иногда полезно ограничить блок так, чтобы он был доступен только как вложенный блок. Например, вы можете захотеть, чтобы блок «Добавить в корзину» был доступен только в блоке «Продукт».

Параметр parentпозволяет блоку требовать, чтобы он был доступен только тогда, когда он вложен в указанные блоки.

// Only allow this block when it is nested in a Columns block
parent: [ 'core/columns' ],

supports (необязательно)

Некоторые блоки поддерживают, например, anchorилиclassNameприменяют свои атрибуты, добавляя дополнительные пропсы в элемент, возвращаемый save. Это будет работать автоматически для элементов HTML-тегов по умолчанию ( divи т. Д.).Однако, если возвращаемое значение вашего save это элемент кастомного компонента, вам нужно будет убедиться, что ваш настраиваемый компонент обрабатывает эти пропсы для сохранения атрибутов.

Тип: Object

Дополнительный блок расширенной поддержки функций. Поддерживаются следующие параметры:

align(по умолчанию false): это свойство добавляет блочные элементы управления, которые позволяют изменить выравнивание блока. Важно: пока не работает с динамическими блоками.

// Add the support for block's alignment (left, center, right, wide, full).
align: true,
// Pick which alignment options to display.
align: [ 'left', 'right', 'full' ],

Когда поддерживается выравнивание, определение атрибутов блока расширяется и включает атрибут выравнивания со строковым типом.
По умолчанию блоку не назначено выравнивание.
Блок может применить выравнивание по умолчанию, указав свой собственный атрибут выравнивания со значением по умолчанию, например:

attributes: {
    ...
    align: {
        type: 'string',
        default: 'right'
    },
    ...
}

alignWide(по умолчанию true): это свойство позволяет включить выравнивание по ширине для вашей темы. Чтобы отключить это поведение для одного блока, установите этот флаг на false.

// Remove the support for wide alignment.
alignWide: false,

anchor(по умолчанию false): якоря позволяют напрямую ссылаться на определенный блок на странице. Это свойство добавляет поле для определения идентификатора блока и кнопку для копирования прямой ссылки.

// Add the support for an anchor link.
anchor: true,

customClassName(по умолчанию true): это свойство добавляет поле для определения пользовательского className для оболочки блока.

// Remove the support for the custom className.
customClassName: false,

className(по умолчанию true): по умолчанию Gutenberg добавляет класс с формой .wp-block-your-block-nameк корневому элементу сохраненной разметки. Это помогает иметь согласованный механизм для стилизации блоков, на которые могут опираться темы и плагины. Если по какой-либо причине класс не нужен в разметке, эту функцию можно отключить.

// Remove the support for the generated className.
className: false,

html(по умолчанию true): по умолчанию Gutenberg разрешает редактировать разметку блока по отдельности. Чтобы отключить это поведение, установите html false.

// Remove support for an HTML mode.
html: false,

inserter(по умолчанию true): по умолчанию все блоки отображаются во вставке Gutenberg. Чтобы скрыть блок, чтобы он мог быть вставлен только программно, установите inserterдля false.

// Hide this block from the inserter.
inserter: false,

multiple(по умолчанию true): не множественный блок может быть вставлен в каждый пост только один раз. Например, встроенный блок «Больше» не может быть вставлен снова, если он уже существует в редактируемой публикации. Значок не множественных блоков автоматически затемняется (не активируется), чтобы предотвратить несколько экземпляров.

// Use the block just once per post
multiple: false,

reusable(по умолчанию true): блок может захотеть отключить возможность преобразования в повторно используемый блок.
По умолчанию все блоки могут быть преобразованы в повторно используемый блок. Если для параметра многоразового использования установлено значение false, опция преобразования блока в повторно используемый блок не появится.

// Don't allow the block to be converted into a reusable block.
reusable: false,