Фильтры блоков - Wordpress Gutenberg - новости, руководства, оптимизация WordPress

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

Варианты

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

Пример:

wp.blocks.registerBlockStyle( 'core/quote', {
    name: 'fancy-quote',
    label: 'Fancy Quote'
} );

В приведенном выше примере регистрируется вариация стиля блока, названная fancy-quoteдля core/quoteблока. Когда пользователь выбирает этот вариант стиля блока в селекторе стилей, имя is-style-fancy-quoteкласса будет добавлено в оболочку блока.

Добавив isDefault: true, вы можете сделать зарегистрированное изменение стиля активным по умолчанию при вставке блока.

Для удаления варианта стиля блока используйте wp.blocks.unregisterBlockStyle().

Пример:

wp.blocks.unregisterBlockStyle( 'core/quote', 'fancy-quote' );

Вышеупомянутое удаляет вариацию, названную fancy-quoteиз core/quoteблока.

Фильтры

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

`blocks.registerBlockType`

Используется для фильтрации настроек блока. Он получает параметры блока и имя блока зарегистрированного блока в качестве аргументов.

Пример:

Убедитесь, что блоки списка сохранены с каноническим сгенерированным именем класса ( wp-block-list):

function addListBlockClassName( settings, name ) {
    if ( name !== 'core/list' ) {
        return settings;
    }

    return lodash.assign( {}, settings, {
        supports: lodash.assign( {}, settings.supports, {
            className: true
        } ),
    } );
}

wp.hooks.addFilter(
    'blocks.registerBlockType',
    'my-plugin/class-names/list-block',
    addListBlockClassName
);

`blocks.getSaveElement`

Фильтр, который применяется к результату функции блока save. Этот фильтр используется для замены или расширения элемента, например, wp.element.cloneElementдля изменения реквизита элемента или замены его дочерних элементов или для возврата полностью нового элемента.

Обратный вызов фильтра получает элемент, тип блока и атрибуты блока в качестве аргументов. Он должен вернуть элемент.

`blocks.getSaveContent.extraProps`

Фильтр, который применяется ко всем блокам, возвращающим элемент WP в saveфункции. Этот фильтр используется для добавления дополнительных реквизитов к корневому элементу saveфункции. Например: добавить className, id или любой допустимый объект для этого элемента.

Фильтр получает saveреквизиты текущего элемента, тип блока и атрибуты блока в качестве аргументов. Он должен вернуть объект реквизита.

Пример:

Добавление фона по умолчанию для всех блоков.

function addBackgroundColorStyle( props ) {
    return lodash.assign( props, { style: { backgroundColor: 'red' } } );
}

wp.hooks.addFilter(
    'blocks.getSaveContent.extraProps',
    'my-plugin/add-background-color-style',
    addBackgroundColorStyle
);

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

`blocks.getBlockDefaultClassName`

Сгенерированные HTML-классы для блоков следуют wp-block-{name}номенклатуре. Этот фильтр позволяет указать альтернативное имя класса.

Пример:

// Our filter function
function setBlockCustomClassName( className, blockName ) {
    return blockName === 'core/code' ?
        'my-plugin-code' :
        className;
}

// Adding the filter
wp.hooks.addFilter(
    'blocks.getBlockDefaultClassName',
    'my-plugin/set-block-custom-class-name',
    setBlockCustomClassName
);

`blocks.switchToBlockType.transformedBlock`

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

`blocks.getBlockAttributes`

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

`editor.BlockEdit`

Используется для изменения editкомпонента блока . Он получает оригинальный BlockEditкомпонент блока и возвращает новый упакованный компонент.

Пример:

ES5
ESNext

var el = wp.element.createElement;

var withInspectorControls = wp.compose.createHigherOrderComponent( function( BlockEdit ) {
    return function( props ) {
        return el(
            wp.element.Fragment,
            {},
            el(
                BlockEdit,
                props
            ),
            el(
                wp.editor.InspectorControls,
                {},
                el(
                    wp.components.PanelBody,
                    {},
                    'My custom control'
                )
            )
        );
    };
}, 'withInspectorControls' );

wp.hooks.addFilter( 'editor.BlockEdit', 'my-plugin/with-inspector-controls', withInspectorControls );

const { createHigherOrderComponent } = wp.compose;
const { Fragment } = wp.element;
const { InspectorControls } = wp.editor;
const { PanelBody } = wp.components;

const withInspectorControls =  createHigherOrderComponent( ( BlockEdit ) => {
    return ( props ) => {
        return (
            <Fragment>
                <BlockEdit { ...props } />
                <InspectorControls>
                    <PanelBody>
                        My custom control
                    </PanelBody>
                </InspectorControls>
            </Fragment>
        );
    };
}, "withInspectorControl" );

wp.hooks.addFilter( 'editor.BlockEdit', 'my-plugin/with-inspector-controls', withInspectorControls );

`editor.BlockListBlock`

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

Пример:ES5ESNext

ES5
ESNext

var el = wp.element.createElement;

var withClientIdClassName = wp.compose.createHigherOrderComponent( function( BlockListBlock ) {
    return function( props ) {
        var newProps = lodash.assign(
            {},
            props,
            {
                className: "block-" + props.clientId,
            }
        );

        return el(
            BlockListBlock,
            newProps
        );
    };
}, 'withClientIdClassName' );

wp.hooks.addFilter( 'editor.BlockListBlock', 'my-plugin/with-client-id-class-name', withClientIdClassName );

const { createHigherOrderComponent } = wp.compose;

const withClientIdClassName = createHigherOrderComponent( ( BlockListBlock ) => {
    return ( props ) => {
        return <BlockListBlock { ...props } className={ "block-" + props.clientId } />;
    };
}, 'withClientIdClassName' );

wp.hooks.addFilter( 'editor.BlockListBlock', 'my-plugin/with-client-id-class-name', withClientIdClassName );

Удаление блоков

Использование черного списка

Добавить блоки достаточно просто, удалить их так же просто. Авторы плагинов или тем имеют возможность «отменить регистрацию» блоков.

// my-plugin.js

wp.blocks.unregisterBlockType( 'core/verse' );

и загрузите этот скрипт в редакторе

<?php
// my-plugin.php

function my_plugin_blacklist_blocks() {
    wp_enqueue_script(
        'my-plugin-blacklist-blocks',
        plugins_url( 'my-plugin.js', __FILE__ ),
        array( 'wp-blocks' )
    );
}
add_action( 'enqueue_block_editor_assets', 'my_plugin_blacklist_blocks' );

Использование белого списка

Если вы хотите отключить все блоки, кроме белого списка, вы можете изменить приведенный выше скрипт следующим образом:

// my-plugin.js

var allowedBlocks = [
    'core/paragraph',
    'core/image',
    'core/html',
    'core/freeform'
];

wp.blocks.getBlockTypes().forEach( function( blockType ) {
    if ( allowedBlocks.indexOf( blockType.name ) === -1 ) {
        wp.blocks.unregisterBlockType( blockType.name );
    }
} );

Сокрытие блоков от устройства вставки

На сервере вы можете отфильтровать список блоков, показанных во вставке, используя allowed_block_typesфильтр. Вы можете вернуть либо true (все поддерживаемые типы блоков), false (без поддерживаемых типов блоков), либо массив разрешенных имен типов блоков. Вы также можете использовать второй предоставленный параметр $postдля фильтрации типов блоков на основе его содержимого.

<?php
// my-plugin.php

function my_plugin_allowed_block_types( $allowed_block_types, $post ) {
    if ( $post->post_type !== 'post' ) {
        return $allowed_block_types;
    }
    return array( 'core/paragraph' );
}

add_filter( 'allowed_block_types', 'my_plugin_allowed_block_types', 10, 2 );

Управление категориями блоков

С помощью фильтра можно отфильтровать список категорий блоков по умолчанию block_categories. Вы можете сделать это на сервере, реализовав функцию, которая возвращает список категорий. Он будет использоваться при регистрации блоков и группировать блоки во вставке. Вы также можете использовать второй предоставленный параметр, $postчтобы создать другой список в зависимости от содержимого сообщения.

<?php
// my-plugin.php

function my_plugin_block_categories( $categories, $post ) {
    if ( $post->post_type !== 'post' ) {
        return $categories;
    }
    return array_merge(
        $categories,
        array(
            array(
                'slug' => 'my-category',
                'title' => __( 'My category', 'my-plugin' ),
                'icon'  => 'wordpress',
            ),
        )
    );
}
add_filter( 'block_categories', 'my_plugin_block_categories', 10, 2 );

Вы также можете отобразить значок с вашей категорией блока, установив iconатрибут. Значение может быть куском WordPress Dashicon .

Можно установить SVG в качестве значка категории, если необходим пользовательский значок. Для этого значок должен быть отображен и установлен во внешнем интерфейсе, чтобы он мог использовать WordPress SVG, обеспечивая мобильную совместимость и делая значок более доступным.

Чтобы установить значок SVG для категории, показанной в предыдущем примере, добавьте следующий код JavaScript в редактор, вызвав, wp.blocks.updateCategoryнапример:

( function() {
    var el = wp.element.createElement;
    var SVG = wp.components.SVG;
    var circle = el( 'circle', { cx: 10, cy: 10, r: 10, fill: 'red', stroke: 'blue', strokeWidth: '10' } );
    var svgIcon = el( SVG, { width: 20, height: 20, viewBox: '0 0 20 20'}, circle);
    wp.blocks.updateCategory( 'my-category', { icon: svgIcon } );
} )();