Функция shortcode_atts() в WordPress: Описание и Примеры

Функция shortcode_atts() используется для комбинирования пользовательских атрибутов шорткода с известными атрибутами и заполнения их значениями по умолчанию. Она позволяет задать значения по умолчанию для атрибутов шорткода и гарантирует, что только поддерживаемые атрибуты будут обработаны.

shortcode_atts( array $pairs, array $atts, string $shortcode = '' ): array

• $pairs (массив) — обязательный параметр. Массив поддерживаемых атрибутов и их значений по умолчанию.
• $atts (массив) — обязательный параметр. Массив пользовательских атрибутов, переданных в шорткоде.
• $shortcode (строка) — необязательный параметр. Имя шорткода, передается для контекста и фильтрации.

Возвращаемое значение: Массив объединенных атрибутов, который включает только поддерживаемые атрибуты и значения по умолчанию для отсутствующих.

Когда использовать?

Функция shortcode_atts() широко используется при создании шорткодов для удобного управления передаваемыми параметрами. Она позволяет задать значения по умолчанию и обрабатывать только те атрибуты, которые определены разработчиком, игнорируя другие.

Пример 1: Шорткод с поддержкой атрибутов

Создадим шорткод [bartag], который поддерживает два атрибута foo и bar с заданными значениями по умолчанию.

function wpdocs_bartag_func( $atts ) {
    // Устанавливаем значения по умолчанию для атрибутов
    $atts = shortcode_atts(
        array(
            'foo' => 'no foo',    // Значение по умолчанию для 'foo'
            'bar' => 'default bar', // Значение по умолчанию для 'bar'
        ), 
        $atts, 
        'bartag'
    );

    return 'bartag: ' . esc_html( $atts['foo'] ) . ' ' . esc_html( $atts['bar'] );
}

add_shortcode( 'bartag', 'wpdocs_bartag_func' );

Результаты использования:

• [bartag foo="koala" bar="bears"] выведет: bartag: koala bears
• [bartag foo="koala"] выведет: bartag: koala default bar
• [bartag] выведет: bartag: no foo default bar

Пример 2: Игнорирование неподдерживаемых атрибутов

Функция shortcode_atts() проигнорирует атрибуты, не указанные в массиве $pairs. Например, если шорткод передан с атрибутом, который не поддерживается, он не будет обработан.

function my_shortcode_func( $atts ) {
    $atts = shortcode_atts(
        array(
            'width'  => '300',
            'height' => '200',
        ), 
        $atts, 
        'my_shortcode'
    );

    return 'Width: ' . esc_html( $atts['width'] ) . 'px, Height: ' . esc_html( $atts['height'] ) . 'px';
}

add_shortcode( 'my_shortcode', 'my_shortcode_func' );

Результаты использования:

• [my_shortcode width="400" height="500"] выведет: Width: 400px, Height: 500px
• [my_shortcode width="400" color="red"] выведет: Width: 400px, Height: 200px (атрибут color будет проигнорирован)

Пример 3: Кастомизация значений через фильтры

Можно использовать фильтры для добавления или изменения атрибутов шорткода на основе его имени. Это позволяет гибко изменять поведение шорткодов.

function my_callback_func( $atts, $content, $tag ) {
    // Устанавливаем атрибуты и значения по умолчанию
    $atts = shortcode_atts(
        array(
            'foo' => 'default foo',
            'bar' => 'default bar',
        ), 
        $atts, 
        $tag
    );

    // Возвращаем результат
    return 'foo: ' . esc_html( $atts['foo'] ) . ', bar: ' . esc_html( $atts['bar'] );
}

add_shortcode( 'myshortcode1', 'my_callback_func' );
add_shortcode( 'myshortcode2', 'my_callback_func' );

// Фильтр для добавления параметра 'zoo' только для 'myshortcode1'
add_filter( 'shortcode_atts_myshortcode1', 'add_zoo', 10, 3 );
function add_zoo( $out, $pairs, $atts ) {
    $out['zoo'] = 'default zoo';
    return $out;
}

Теперь при использовании [myshortcode1 foo="lion" zoo="elephant"], результат будет: foo: lion, bar: default bar, zoo: elephant. Для [myshortcode2 foo="lion" zoo="elephant"], результат: foo: lion, bar: default bar, так как атрибут zoo не будет учтен.

Примечания

• Имена атрибутов в шорткодах чувствительны к регистру, но результат обработки возвращает их в нижнем регистре. Например, [shortcode Foo="value"] передаст в массив атрибутов элемент 'foo' => 'value'.
• Если имена атрибутов шорткода и массива $pairs не совпадают по регистру, они не будут учтены. Чтобы избежать проблем, используйте одинаковый регистр.

Заключение

Функция shortcode_atts() — это удобный инструмент для обработки атрибутов шорткодов в WordPress, позволяющий задать значения по умолчанию и игнорировать неподдерживаемые атрибуты. Она помогает сделать шорткоды гибкими и безопасными для использования, а также упрощает управление их параметрами.