Шорткоды WordPress: как создавать свои — гайд с примерами кода

Шорткоды появились в WordPress ещё в 2008 году и до сих пор остаются одним из самых простых способов добавить на сайт динамический вывод «из коробки». Короткая запись вида [ds_button] превращается в целый элемент интерфейса — кнопку, врезку, галерею или форму. PHP-логику вы пишете один раз, а потом используете шорткод где угодно: в записях, на страницах, в виджетах и даже в шаблонах темы.

Многие новички считают, что шорткоды устарели и их полностью заменили блоки Гутенберга. На практике это не так: шорткоды работают во всех актуальных версиях WordPress, их используют тысячи плагинов, а в старом контенте они остаются единственным способом вывода, который не требует переписывания записей. Понимание механизма шорткодов пригодится любому разработчику — хотя бы для того, чтобы читать чужой код и быстро находить, откуда берётся тот или иной блок на странице.

В этом гайде разберём на примерах, как создавать свои шорткоды с нуля: от простейшего [current_year] до вложенных конструкций с атрибутами и защищённым выводом. Все примеры можно копировать и адаптировать под свои задачи.

Что такое шорткоды WordPress и зачем они нужны

Шорткод (shortcode) — это короткая метка в квадратных скобках, которую WordPress при выводе страницы заменяет на результат работы PHP-функции. Например, запись

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

В WordPress уже встроено несколько стандартных шорткодов, с которыми вы наверняка сталкивались:

Шорткод	Что выводит
	Галерею изображений из вложений записи
	Изображение с подписью
,	Аудио- и видеоплеер
	Плейлист из аудио или видеофайлов
	Встраивание контента с внешних сервисов

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

1. Повторяющиеся блоки. Кнопка, врезка, цена, слайдер — написали один раз, используете в сотне записей.
2. Передача параметров. Один шорткод [ds_button] с разными атрибутами заменяет десяток разных элементов: [ds_button url="..." color="red"].
3. Вывод без доступа к PHP. Редактор контента не видит код, но может вставлять шорткоды в записи — это безопасно и удобно.
4. Совместимость со старым контентом. Если на сайте тысячи записей со шорткодами плагинов, они продолжат работать, даже когда вы смените тему.

Если вы только начинаете разбираться с устройством WordPress, рекомендую сначала посмотреть наш раздел «Разработка WordPress» — там собраны материалы для новичков: от настройки до кастомизации.

add_shortcode: создаём первый шорткод

Регистрация шорткода — это функция add_shortcode() с двумя аргументами: имя шорткода (без квадратных скобок) и имя функции-обработчика. Рассмотрим классический пример — шорткод [current_year], который выводит текущий год. Он пригодится в футере, чтобы не обновлять копирайт вручную каждый год:

<?php
// Шорткод [current_year] — выводит текущий год
function ds_current_year_shortcode() {
    return date( 'Y' );
}
add_shortcode( 'current_year', 'ds_current_year_shortcode' );

Как это работает: при обработке контента WordPress находит [current_year], вызывает функцию ds_current_year_shortcode() и подставляет её результат на место шорткода. Обратите внимание: функция должна возвращать строку через return, а не выводить её через echo. Если использовать echo, шорткод сработает, но результат окажется не в том месте страницы — WordPress подставляет возвращаемое значение строго туда, где стоял шорткод.

Куда вставлять код шорткода:

1. В functions.php дочерней темы WordPress — правки не сотрутся при обновлении родительской темы.
2. В собственный плагин — если шорткод нужен на любых темах.
3. В плагин Code Snippets — самый простой вариант для новичка: код добавляется из админки и включается переключателем.

Если вы ещё не знакомы с тем, куда и как добавлять код в WordPress, почитайте подборку полезных сниппетов для functions.php — там разобраны десятки готовых примеров с пояснениями.

Атрибуты шорткода: параметры через $atts

Простой шорткод без параметров редко решает реальные задачи. Гораздо полезнее шорткод, которому можно передать настройки. Атрибуты приходят в функцию-обработчик вторым аргументом — массивом $atts. Например, шорткод кнопки:

<?php
// Шорткод [ds_button url="..." color="blue" target="_blank"]Текст[/ds_button]
function ds_button_shortcode( $atts, $content = null ) {
    // Значения по умолчанию + слияние с переданными атрибутами
    $atts = shortcode_atts(
        array(
            'url'    => '#',
            'color'  => 'blue',
            'target' => '_self',
        ),
        $atts,
        'ds_button'
    );

    return '<a class="ds-btn ds-btn--' . esc_attr( $atts['color'] ) . '" '
        . 'href="' . esc_url( $atts['url'] ) . '" '
        . 'target="' . esc_attr( $atts['target'] ) . '">'
        . esc_html( $content )
        . '</a>';
}
add_shortcode( 'ds_button', 'ds_button_shortcode' );

Теперь в записи можно написать [ds_button url="https://example.com" color="red"]Купить[/ds_button] — и получить готовую кнопку. Что важно знать об атрибутах:

• Используйте shortcode_atts() — она подставляет значения по умолчанию и защищает от лишних параметров. Третий аргумент — имя шорткода — нужен для фильтров.
• Все атрибуты приходят строками. Числа придётся приводить: (int) $atts['count'].
• Имена атрибутов регистрозависимы (до версии WordPress 4.4), поэтому пишите их в одном стиле.
• Экранируйте вывод. esc_url() для ссылок и esc_attr() для значений атрибутов — об этом подробнее в разделе о безопасности.

Если атрибут не передан, WordPress всё равно передаст его в $atts с пустым значением — поэтому дефолты из shortcode_atts() так важны: без них color окажется пустой строкой.

Шорткоды с контентом: обёртки через $content

Многие шорткоды работают как обёртки: они принимают контент между открывающим и закрывающим тегами и оформляют его. Классика — цветная врезка-алерт:

<?php
// Шорткод [ds_alert type="success"]Текст[/ds_alert]
function ds_alert_shortcode( $atts, $content = null ) {
    $atts = shortcode_atts(
        array( 'type' => 'info' ),
        $atts,
        'ds_alert'
    );

    // Пропускаем контент через do_shortcode, чтобы вложенные шорткоды сработали
    $content = do_shortcode( $content );

    return '<div class="ds-alert ds-alert--' . esc_attr( $atts['type'] ) . '">'
        . wp_kses_post( $content )
        . '</div>';
}
add_shortcode( 'ds_alert', 'ds_alert_shortcode' );

В контенте это выглядит так: [ds_alert type="warning"]Внимание: сайт обновляется ночью[/ds_alert]. WordPress передаёт текст между тегами в $content, а функция оборачивает его в нужный HTML с классом, который уже стилизуется в CSS темы.

Три важных момента при работе с контентом шорткода:

• Контент может быть пустым. Если закрывающий тег не указан, $content равен null — проверяйте это перед выводом.
• Автоматические параграфы. WordPress обрабатывает контент через wpautop(), из-за чего вокруг блочных шорткодов появляются лишние <p>. Это частая причина «сломанной» вёрстки.
• Пропускайте контент через do_shortcode(), если внутри могут быть другие шорткоды (см. следующий раздел).

С проблемой лишних параграфов сталкиваются почти все новички. Самый простой способ её избежать — возвращать из функции полноценный блочный HTML и не оставлять пустых строк между шорткодом и текстом в редакторе. Если врезки используются часто, удобнее сделать их отдельными Gutenberg-блоками — сравнение подходов я привёл ниже.

Вложенные шорткоды: колонки и составные элементы

Шорткоды можно вкладывать друг в друга — так строятся составные элементы вроде колонок, табов или аккордеонов. Внешний шорткод получает в $content внутренние шорткоды «как есть» и должен явно вызвать для них do_shortcode():

<?php
// [ds_columns] обёртка + [ds_column] колонки внутри
function ds_columns_shortcode( $atts, $content = null ) {
    return '<div class="ds-columns">' . do_shortcode( $content ) . '</div>';
}
add_shortcode( 'ds_columns', 'ds_columns_shortcode' );

function ds_column_shortcode( $atts, $content = null ) {
    return '<div class="ds-column">' . do_shortcode( $content ) . '</div>';
}
add_shortcode( 'ds_column', 'ds_column_shortcode' );

Использование в записи:

[ds_columns]
[ds_column]Первый блок текста[/ds_column]
[ds_column]Второй блок текста[/ds_column]
[/ds_columns]

Современный WordPress умеет обрабатывать вложенные шорткоды автоматически, но явный вызов do_shortcode($content) делает поведение предсказуемым: контент обрабатывается независимо от того, в какой момент и как он попал в переменную (из базы, из поля ACF, из настройки). Это правило стоит сделать привычкой.

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

Шорткоды, Gutenberg-блоки или PHP: что выбрать

Перед тем как писать шорткод, стоит решить, а нужен ли он вообще. В современном WordPress ту же задачу часто решают Gutenberg-блоки или прямое подключение PHP в шаблоне. Сравним подходы:

Критерий	Шорткоды	Gutenberg-блоки	PHP в шаблоне
Где используется	Контент, виджеты, шаблоны	Редактор записей	Только файлы темы
Нужен ли опыт в PHP	Базовый	Нет (JS)	Да
Сложность для новичка	Низкая	Средняя	Средняя
Передача параметров	Атрибуты в скобках	Настройки в панели блока	Аргументы функций
Работает в старом контенте	Да	Нет	—
Переносимость между темами	Да (если в плагине)	Зависит от регистрации	Нет
Может использовать редактор	Да, вставкой текста	Да, через интерфейс	Нет

Практическая рекомендация: новый сайт без старого контента — используйте блоки, они удобнее в редакторе. Шорткоды берите, когда нужен вывод в нестандартных местах (виджеты, шаблоны, старый контент), элемент должен работать на любой теме, или вы хотите дать редактору простой способ вставки без возни с блоками. PHP в шаблоне — для элементов, которые жёстко привязаны к месту вывода и не должны меняться из контента.

Если вы заказываете разработку сайта на WordPress, уточните у подрядчика, как реализованы повторяющиеся элементы. Подробнее о том, что должно входить в проект, — в статье о заказе сайта на WordPress: плюсы, минусы и цена.

Как вывести шорткод в виджетах, тексте и шаблонах

Создать шорткод — полдела. Важно понимать, где он будет работать:

• В записях и страницах — просто вставьте [ds_button ...] в контент. Это работает из коробки.
• В блоках Гутенберга — используйте блок «Короткий код» (Shortcode) и вставьте шорткод в его поле.
• В виджетах — в блочных виджетах добавьте блок «Короткий код». Для старых текстовых виджетов нужно включить обработку фильтром:

<?php
// Разрешить шорткоды в текстовых виджетах (классические виджеты)
add_filter( 'widget_text', 'do_shortcode' );

• В шаблонах темы — через do_shortcode(). Например, кнопка в шапке или подвале:

<?php
// Вывод шорткода в PHP-шаблоне: header.php, footer.php и т.д.
echo do_shortcode(
    '[ds_button url="' . esc_url( home_url( '/portfolio/' ) ) . '" color="blue"]Смотреть работы[/ds_button]'
);

Универсальная рекомендация: вывод шорткода через do_shortcode() работает везде — в шаблонах, в строках, полученных из переменных, и даже в контенте, собранном динамически. Если шорткод выводится «как текст» и не срабатывает — почти всегда это значит, что контент обрабатывается без вызова do_shortcode() (например, произвольное поле выводится напрямую через the_field() без фильтра).

Кстати, сами страницы портфолио на нашем сайте сверстаны именно так: портфолио проектов — посмотрите, как выглядит вывод сложных карточек на реальном сайте.

remove_shortcode: отключаем и заменяем шорткоды

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

не подходит по вёрстке, или нужно переопределить вывод чужого шорткода. Для этого есть remove_shortcode():

<?php
// 1. Удаляем стандартный шорткод галереи
remove_shortcode( 'gallery' );

// 2. Регистрируем свой обработчик под тем же именем
function ds_gallery_shortcode( $atts ) {
    return '<div class="ds-gallery">Своя галерея</div>';
}
add_shortcode( 'gallery', 'ds_gallery_shortcode' );

После remove_shortcode() старый обработчик перестаёт работать, а add_shortcode() с тем же именем вешает на шорткод новую логику. Так можно полностью контролировать вывод, не трогая код плагина.

Полезная пара функций для отладки:

• has_shortcode( $content, $tag ) — проверяет, есть ли шорткод в контенте. Удобно, чтобы подключать стили только там, где шорткод реально используется.
• shortcode_exists( $tag ) — проверяет, зарегистрирован ли шорткод вообще. Пригодится, чтобы аккуратно вывести заглушку, если плагин, предоставляющий шорткод, отключён.

<?php
// Пример: добавить CSS только если в посте есть шорткод ds_button
function ds_maybe_add_button_styles() {
    global $post;
    if ( isset( $post ) && has_shortcode( $post->post_content, 'ds_button' ) ) {
        wp_enqueue_style( 'ds-button-styles' );
    }
}
add_action( 'wp_enqueue_scripts', 'ds_maybe_add_button_styles' );

Безопасность шорткодов: esc_html, wp_kses и права доступа

Шорткод вставляет PHP-логику в контент, которым управляют редакторы. Значит, к атрибутам и контенту нужно относиться как к пользовательскому вводу: никогда не выводить их «как есть». Иначе редактор (или злоумышленник, получивший доступ к редактированию) сможет вставить в шорткод JavaScript и сломать сайт.

Три базовых правила:

1. esc_html() — для обычного текста: нейтрализует HTML-теги.
2. esc_url() и esc_attr() — для ссылок и значений атрибутов.
3. wp_kses() / wp_kses_post() — когда контент должен содержать ограниченный набор HTML-тегов.

Пример безопасного вывода с разрешённым списком тегов:

<?php
// Шорткод, который разрешает только жирный текст, курсив и ссылки
function ds_safe_text_shortcode( $atts, $content = null ) {
    $allowed = array(
        'strong' => array(),
        'em'     => array(),
        'a'      => array(
            'href'  => array(),
            'title' => array(),
            'rel'   => array(),
        ),
    );
    return '<p>' . wp_kses( $content, $allowed ) . '</p>';
}
add_shortcode( 'ds_safe_text', 'ds_safe_text_shortcode' );

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

<?php
// Шорткод [ds_admin] — виден только администраторам
function ds_admin_only_shortcode( $atts, $content = null ) {
    if ( ! current_user_can( 'manage_options' ) ) {
        return ''; // для остальных — пусто
    }
    return '<div class="ds-admin">' . wp_kses_post( $content ) . '</div>';
}
add_shortcode( 'ds_admin', 'ds_admin_only_shortcode' );

Не забывайте и про общую защиту сайта: даже идеально написанные шорткоды не спасут, если у сайта слабые пароли или открыты лишние функции. Полный набор настроек — в гайде о безопасности WordPress для новичков: 10 настроек.

Вывод

Шорткоды — один из самых доступных инструментов кастомизации WordPress для новичка. Чтобы создать свой шорткод, достаточно трёх вещей: функции с return, регистрации через add_shortcode() и вывода через do_shortcode(). Дальше — по нарастающей: атрибуты через shortcode_atts() дают гибкие настройки, контент и вложенность позволяют строить составные элементы, а remove_shortcode() — управлять чужими шорткодами. И всегда помните про экранирование вывода: esc_html(), esc_url(), wp_kses().

Главное правило практики: не пишите шорткод, если задачу решает обычный блок. Шорткоды сильны там, где нужен вывод вне редактора, переносимость между темами или работа со старым контентом. В остальных случаях проще и надёжнее использовать Gutenberg.

Попробуйте начать с малого: добавьте [current_year] в футер своей темы, затем соберите шорткод кнопки с атрибутами — и вы быстро почувствуете логику работы. А если нужен готовый сайт на WordPress, где все такие элементы уже настроены и проверены, — посмотрите наши работы в портфолио и закажите разработку под вашу задачу. Больше технических материалов для разработчиков — в блоге delai-sait.ru и в разделе «Разработка WordPress».