Шорткоды в WordPress: подробное руководство

Александр Писклов
Александр Писклов
Разрабатываю сайты на WordPress с 2011 года.
147
9 минут на чтение

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

Что такое шорткод?

Шорткод (shortcode) — это текст в квадратных скобках (например, [gallery]), который при выводе контента заменяется на определённый HTML или PHP-вывод. Система шорткодов позволяет внедрять в контент сложные функции, при этом сохраняя визуальную чистоту записи.

Какие шорткоды присутствуют по умолчанию в WordPress

WordPress предоставляет несколько встроенных шорткодов:

  • gallery — выводит галерею изображений, загруженных в медиабиблиотеку. Поддерживает атрибуты ids, columns, size и др.
  • audio — отображает встроенный HTML5 аудиоплеер. Можно использовать с атрибутом src или вложить ссылку на аудио внутри шорткода.
  • video — отображает HTML5 видеоплеер. Поддерживает атрибуты src, poster, width, height.
  • caption — позволяет задать подпись к изображению. Часто используется автоматически при вставке изображений через редактор.
  • embed — автоматически встраивает внешние медиа по ссылке (YouTube, Twitter, Vimeo и т.д.). Этот шорткод чаще всего используется системой WordPress при включённой авто-обработке ссылок.

Примеры использования:

[gallery ids="1,2,3" columns="3"]
[audio src="https://example.com/music.mp3"]
[video src="https://example.com/video.mp4"]
[caption id="" align="alignnone" width="300"]<img src="image.jpg" alt=""> Подпись к изображению[/caption]

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

Синтаксис шорткода

Именование

Имя шорткода может содержать только латинские буквы, цифры, дефис (-) и нижнее подчёркивание (_). Запрещено использовать пробелы, специальные символы и символы пунктуации.

Примеры корректных названий:

[my_shortcode]
[custom-gallery]

Атрибуты

Шорткоды могут принимать параметры (атрибуты), которые задаются внутри скобок:

[button text="Нажми меня" url="https://example.com"]

Атрибуты по умолчанию

При создании собственного шорткода можно задать значения атрибутов по умолчанию с помощью функции shortcode_atts().

$atts = shortcode_atts( [
	'name' => 'Иван Петров',
	'position'  => 'Менеджер',
], $atts );

Экранирование

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

[[my_shortcode]]

Вложение шорткодов

WordPress поддерживает вложенные шорткоды. Чтобы они работали, нужно использовать do_shortcode() внутри обработчика шорткода:

add_shortcode('my_shortcode', 'output_my_shortcode');

function output_my_shortcode( $atts, $content ) {
   return '<div class="about__text">' . do_shortcode( $content ) . '</div>';
}

Как шорткоды влияют на производительность?

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

Если функционал шорткода использует внешнее API для загрузки данных, используйте транзиенты для кэширования результата запроса.

add_shortcode( 'users_api', 'get_users_api_shortcode' );

function get_users_api_shortcode() {
    $endpoint = 'https://example-api.ru/users';
    $response = wp_remote_post( $endpoint );
    $transient_name = 'users_api';
    $output = get_transient( $transient_name );

    if( $output === false ) {
        set_transient( $transient_name, $response, HOUR_IN_SECONDS ); 
    }

    return $output;
}

Создание своего шорткода

Чтобы добавить новый шорткод на сайт WordPress нужно использовать функцию add_shortcode. Она имеет два праметра:

  • $name string обязательный – название шорткода
  • $callback string обязательный – название функции, которая сработает в случае вывода шорткода на сайте. В свою очередь, коллбэк-функция получает три параметра:
    • $atts array – массив атрибутов шорткода
    • $content string – содержимое шорткода, если используется закрывающийся шорткод[content]Тут контент[/content]
    • $tag string – название шорткода
add_shortcode( $name, $callback );

Итак, давайте зарегистрируем новый шорткод person.

add_shortcode( 'person', 'output_shortcode_person' );

function output_shortcode_person() {
    return 'Меня зовут Иван!';
}

Данный код размещаем в файле functions.php. Если ваша тема регулярно обновляется, то используйте дочернюю тему.

Чтобы проверить, как он работает, попробуем добавить шорткод на страницу в wordpress. После сохранения страницы, вместо конструкции [person] на странице отобразится "Меня зовут Иван!".

Теперь расширим функционал шорткода и зададим параметры.

add_shortcode( 'person', 'output_shortcode_person' );

function output_shortcode_person( $atts ) {
    $atts = shortcode_atts( [
        'name' => 'Иван',
        'position' => 'редактор'
    ], $atts );
    return 'Меня зовут ' . $atts['name'] . ' и я ' . $atts['position'] . ' этого сайта!';
}

Шорткод стал динамическим и вы можете использовать его добавляя разные параметры. По-умолчанию, без указаний параметров, будет выведено "Меня зовут Иван и я редактор этого сайта".

Укажите значение параметров при выводе шорткода, чтобы изменить стандартный текст. Например, [person name="Александр" position="администратор"] выведет на странице "Меня зовут Александр и я администратор этого сайта"

Буферизация вывода

Во всех примерах выше мы использовали вывод простого текста. Если ваш шорткод будет выводить большой html-код или использовать подключение файлов шаблона (get_template_part), то в этом случае необходимо использовать буферизацию вывода.

Буферизация – это механизм PHP, позволяющий временно сохранять весь вывод (например, echo) в буфер, а затем извлекать его как строку и использовать, где нужно. В контексте шорткодов это позволяет:

  • Избежать случайного вывода напрямую в браузер (вместо возврата из шорткода).
  • Не использовать множественные return и сложные конкатенации.
  • Писать чистую HTML-разметку внутри PHP-файлов.
  • Повысить читаемость кода.

Простой пример шорткода с буферизацией

<?php
add_shortcode('features', 'output_shortcode_features');

function output_shortcode_features()
{
    $items = ['Гарантия 2 года', 'Возврат товара в течение 14 дней', 'Круглосуточная поддержка'];

    ob_start(); // Запускаем буферизацию
    ?>
    <ul class="features">
        <?php foreach ($items as $item) { ?>
            <li class="features__item"><?php echo esc_html($item) ?></li>
        <?php } ?>
    </ul>
    <?php
    return ob_get_clean(); // возвращаем HTML как строку
}

Использование шорткода на сайте

Использовать шорткоды можно где угодно на сайте WordPress, но метод использования зависит о того, в каком конкретно месте вы его выводите.

Использование шорткода в Gutenberg

Чтобы добавить шорткод на страницу или статью через Gutenberg зайдите в редактор и добавьте новый блок Шорткод.

Введите название шорткода в квадратных скобка в поле ввода.

Сохраните изменения и можно смотреть результат работы шорткода.

Использование шоркода в классическом редакторе

Откройте классический редактор и введите шорткод.

  • Готово!

Использование шорткода в файлах шаблона

Шорткоды чаще всего используются в контенте страниц и записей, но нередко возникает необходимость использовать их напрямую в PHP-файлах темы — например, в single.php, page.php, footer.php или других файлах шаблона. В таких случаях WordPress предоставляет удобную функцию do_shortcode().

Эта функция позволяет выполнить шорткод вручную и отобразить его результат:

<?php echo do_shortcode('[features]'); ?>

Шорткод с параметрами выводим так:

<?php echo do_shortcode('[features count="2"]'); ?>

Вставьте этот код в том месте, где нужно вывести результат шорткода.

Удаление шорткода

Удалить шорткод с сайта WordPress можно несколькими способами, в зависимости от задачи.

Удаление с помощью функции remove_shortcode()

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

remove_shortcode('features');

Лучше вызывать remove_shortcode() на хуке init или позже, чтобы убедиться, что нужный шорткод уже зарегистрирован:

add_action('init', function() {
    remove_shortcode('features');
});

Удаление всех зарегистрированных шоркодов

Для полного отключения всех зарегистрированных шорткодов используйте функцию:

remove_all_shortcodes();

Удаление шорткода из контента вручную

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

  1. Открыть редактор нужной записи.
  2. Найти в содержимом шорткод, например [features].
  3. Удалить или заменить его.

Удаление шорткода, добавленного плагином

Если шорткод регистрируется сторонним плагином, самый корректный способ — отключить или удалить плагин.

Будьте осторожны: это может повлиять на другие функции плагина.

Если плагин важен, но конкретный шорткод больше не нужен — используйте remove_shortcode().

Удаление шорткодов из содержимого при выводе

Если вы хотите автоматически удалять все (или конкретные) шорткоды при выводе поста, можно использовать фильтр:

add_filter( 'the_content', function( $content ) {
    $content = strip_shortcodes( $content );
    return $content;
});

Если нужно удалить конкретный шорткод, используйте конструкцию:

add_filter( 'the_content', function( $content ) {
    $shortcode = '[features]';
    return str_replace( $shortcode, '', $content );
});

Функции WordPress для работы с шорткодами

  • add_shortcode() – регистрирует новый шорткод.
  • remove_shortcode() – удаляет конкретный шорткод по его названию
  • remove_all_shortcodes() – удаляет все зарегистрированные шорткоды
  • shortcode_atts() – объединяет переданные атрибуты с набором значений по умолчанию
  • do_shortcode() – выполняет все шорткоды, найденные в строке
  • has_shortcode() – проверяет наличие определённого шорткода в контенте
  • shortcode_exists() – проверяет, зарегистрирован ли шорткод

Частые проблемы при использовании шорткодов

  1. Использование echo вместо return

Шорткод должен возвращать значение, а не выводить напрямую через echo. Иначе он не отобразится или нарушит верстку.

// ❌ Не правильно!
function my_shortcode() {
    echo 'Текст';
}

// ✅ Правильно 
function my_shortcode() {
    return 'Текст';
}
  1. Отсутствие обработки атрибутов по умолчанию

Без shortcode_atts() атрибуты становятся обязательными и могут вызвать предупреждение Undefined index.

// ❌ Ошибка!
function my_shortcode($atts) {
    return 'URL: ' . $atts['url'];
}

// ✅ Правильно 
function my_shortcode() {
    $atts = shortcode_atts([
        'url' => 'https://example.com'
    ], $atts);
    return 'URL: ' . esc_url($atts['url']);
}
  1. Небезопасный вывод данных

Отсутствие экранирования может привести к XSS-уязвимостям. Используйте esc_html(), esc_url(), esc_attr().

// ❌ Ошибка!
function my_shortcode($atts) {
    ...
    return '<a href="' . $atts['url'] . '">' . $atts['text'] . '</a>';
}

// ✅ Правильно 
function my_shortcode() {
    ...
    return '<a href="' . esc_url($atts['url']) . '">' . esc_html($atts['text']) . '</a>';
}
  1. Отображение [shortcode] как текст

Такое может происходить по нескольким причинам:

  • Шорткод не зарегистрирован.
  • Не правильно указано имя шорткода.
  • Шорткод был удалён или отключён.
  • Для вывода контента используется функция get_the_content(), которая не фильтрует контент хуком the_content. 
// Вместо нее используйте функцию the_content()
the_content();

// или примените хук the_content к содержимому функции
$content = apply_filters( 'the_content', get_the_content() );
echo $content;
Содержание:

Похожие материалы

Пользуясь нашим сайтом, вы соглашаетесь с тем, что мы используем cookies.
ОК