Представьте: вы добавляете галерею из 20 снимков в статью. Без шорткодов это десятки строк HTML с обёртками, классами, data-атрибутами и ссылками на миниатюры. С шорткодом, одна строка [gallery]. Именно ради такого контраста между объёмом рутины и результатом в WordPress 2.5 появились шорткоды, и спустя почти два десятилетия механизм остаётся незаменимым.

Проблема в том, что большинство пользователей либо боятся шорткодов как «программистской магии», либо копируют их наугад, не вникая в синтаксис. А между тем один кастомный шорткод способен заменить плагин на сорок мегабайт или сэкономить час рутины в месяц. Этот разбор, от встроенных [gallery] и [audio] до собственного шорткода в functions.php, даст вам полный контроль над инструментом.

💡 Быстрый обзор:

• Что такое шорткод: тег в квадратных скобках, который WordPress заменяет на результат PHP-функции при загрузке страницы.
• Встроенные шорткоды: gallery, audio, video, caption, embed и playlist работают сразу после установки WordPress, без плагинов.
• Параметры шорткодов: синтаксис key="value" позволяет настраивать вывод без изменения кода.
• Создание своего шорткода: от простого URL-заменителя до шорткода изображения с атрибутами, готовый PHP-код для functions.php.
• Шорткоды в виджетах и шаблонах: как включить поддержку одной строкой и где это пригождается.

Что такое шорткод и как он устроен

Шорткод, это короткий тег в квадратных скобках, который WordPress заменяет результатом выполнения PHP-функции в момент вывода страницы. Вы пишете [gallery] в редакторе, посетитель видит аккуратную сетку изображений. Никакой магии: за каждым шорткодом стоит функция, зарегистрированная через add_shortcode() в ядре, теме или плагине.

Ключевое отличие от статичных HTML-вставок: шорткод выполняется на стороне сервера. Вы передаёте ему параметры, и результат формируется динамически. Меняется контент, меняется вывод, без правки десятков страниц вручную.

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

Встроенные шорткоды WordPress: что доступно без плагинов

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

Самый гибкий из них, [gallery]. Атрибут ids позволяет указать конкретные изображения по ID, даже те, что не прикреплены к текущей записи. Атрибут size задаёт размер миниатюр (thumbnail, medium, large или full). Комбинация этих двух параметров покрывает большинство сценариев, ради которых раньше ставили отдельный плагин галереи.

[audio] и [video] поддерживают множественные источники, браузер сам выберет совместимый формат. Плейлисты через [playlist] собираются из ID вложений аналогично галерее, но выводят плеер с переключением треков.

Параметры шорткодов: как управлять выводом

Большинство шорткодов принимают атрибуты в формате key="value". Подстановка значений меняет логику работы функции без вмешательства в код.

Возьмём [gallery]. Без параметров он показывает все изображения записи в стандартном размере. Добавляем конкретику:

1
[gallery ids="12,34,56" size="large" columns="3"]

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

Некоторые шорткоды используют открывающий и закрывающий теги, когда между ними нужно передать содержимое. Скажем, плагин Google Maps может ожидать конструкцию вида:

1
[maps]Нью-Йорк, США[/maps]

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

Как создать собственный шорткод

Когда вы десятый раз за неделю вставляете в статью один и тот же URL, HTML-блок или call-to-action, самое время написать шорткод. Это не требует быть PHP-разработчиком: базовая конструкция умещается в три строки.

Простой шорткод для URL

Добавьте этот код в конец файла functions.php вашей темы (Внешний вид → Редактор темы → functions.php):

1
function techblog_short_url() {
2
    return 'https://techblog.sdstudio.top';
3
}
4
add_shortcode( 'techblog', 'techblog_short_url' );

Теперь в любой записи [techblog] автоматически заменится на URL сайта. Функция возвращает строку, WordPress подставляет её вместо шорткода.

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

• Функция возвращает значение через return, а не выводит через echo. Прямой вывод ломает порядок рендеринга и приводит к неожиданным результатам.
• Регистрируйте шорткоды на хуке init, чтобы WordPress успел загрузить все зависимости:

1
add_action( 'init', 'techblog_register_shortcodes' );
2
function techblog_register_shortcodes() {
3
    add_shortcode( 'techblog', 'techblog_short_url' );
4
}

Шорткод для изображения с настраиваемыми атрибутами

Чуть более сложный сценарий: вы хотите вставлять изображение, задавая ширину и высоту прямо в редакторе. В functions.php:

1
function techblog_img_shortcode( $atts, $content = null ) {
2
    $atts = shortcode_atts(
3
        array(
4
            'width'  => '',
5
            'height' => '',
6
        ),
7
        $atts,
8
        'img'
9
    );
10
    return '<img src="' . esc_url( $content ) . '" width="' . esc_attr( $atts['width'] ) . '" height="' . esc_attr( $atts['height'] ) . '" alt="" />';
11
}
12
add_shortcode( 'img', 'techblog_img_shortcode' );

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

1
[img width="800" height="600"]https://example.com/photo.jpg[/img]

Функция shortcode_atts() смешивает переданные атрибуты со значениями по умолчанию, это стандартный и безопасный способ обработки параметров. Обратите внимание на esc_url() и esc_attr(): экранирование обязательно при выводе пользовательского ввода на frontend. Полный перечень доступных атрибутов изображения есть в спецификации W3C.

Отдельно стоит сказать о валидации атрибутов. Когда вы принимаете значения от редактора и подставляете их в HTML, всегда проверяйте тип данных. Для числовых атрибутов вроде width и height используйте intval(), это отсечёт случайные буквы. Для строк задавайте допустимый набор значений через in_array(), например размеры миниатюр (thumbnail, medium, large). Так вёрстка останется целой, а результат на frontend-е будет предсказуемым, даже если автор ошибётся в значении атрибута.

Шорткоды в текстовых виджетах и PHP-файлах

С версии WordPress 4.9 (ноябрь 2017) шорткоды автоматически работают в текстовых виджетах. Но если вы используете кастомную тему без встроенной поддержки, включить её можно одной строкой в functions.php:

1
add_filter( 'widget_text', 'do_shortcode' );

Чтобы избежать автоматической вставки тегов <p> и <br> вокруг шорткода в виджете (WordPress auto-форматирует переносы строк), добавьте также:

1
add_filter( 'widget_text', 'shortcode_unautop' );

Этот же принцип работает для PHP-шаблонов. Если нужно выполнить шорткод прямо в header.php или другом файле темы, оберните его в do_shortcode():

1
echo do_shortcode( '[techblog]' );

Так одна и та же логика доступна и в редакторе, и в виджете, и в шаблоне, без дублирования кода.

Экранирование: как показать текст шорткода без выполнения

Иногда нужно не выполнить шорткод, а показать его синтаксис читателю, как в этой статье. Если просто вставить [gallery] в редактор, WordPress немедленно его выполнит или покажет плейсхолдер. Есть два способа этого избежать.

Двойные квадратные скобки. Самый простой метод, удвоить внешние скобки:

1
[[gallery]]

Для парных тегов удваиваются первая открывающая и последняя закрывающая:

1
[[maps]Нью-Йорк, США[/maps]]

HTML-коды символов. В текстовом редакторе можно заменить скобки их ASCII-кодами: [ вместо [ и ] вместо ]. Запись [gallery] отобразится как текст [gallery], но выполнена не будет.

Первый способ проще и читаемее в исходном коде, второй надёжнее при сложном форматировании. Выбирайте двойные скобки для быстрых правок в текстовом редакторе и ASCII-коды, когда шорткод соседствует с другими квадратными скобками, например, внутри блоков кода или описаний мета-полей. В обоих случаях посетитель сайта видит именно текст шорткода, а WordPress не выполняет его.

Видео: полный разбор шорткодов WordPress

Для тех, кто предпочитает визуальное объяснение, держите детальный туториал от команды Kinsta. Автор показывает создание, отладку и реальные примеры шорткодов в живом проекте, от установки темы до вывода на фронтенд.

⁉️🤔 Частые вопросы

Можно ли использовать шорткоды в Gutenberg?

Да, через блок «Shortcode» в панели добавления блоков. Вы вставляете шорткод в поле блока, и WordPress выполняет его при рендеринге. Однако сложные шорткоды с вложенным контентом могут работать непредсказуемо, в таких случаях надёжнее переключиться в режим редактирования кода. Gutenberg рендерит шорткоды через серверный callback, поэтому результат зависит от того, возвращает ли функция корректный HTML. Блоковые темы (Full Site Editing) с theme.json могут частично ограничивать вывод шорткодов в шаблонах, проверяйте совместимость конкретной темы.

Что делать, если шорткод не работает?

Проверьте три типовые причины. Первое: вы вставили шорткод в визуальном редакторе, который преобразовал скобки в HTML-entities, переключитесь в текстовый режим и убедитесь, что скобки прямые. Второе: плагин, регистрирующий шорткод, деактивирован, зайдите в «Плагины» и проверьте статус. Третье: в функции шорткода используется echo вместо return, это ошибка разработчика, вывод появляется не в том месте страницы. Системный способ диагностики: откройте wp-config.php, включите WP_DEBUG и WP_DEBUG_LOG. После загрузки страницы со шорткодом проверьте wp-content/debug.log, там будут конкретные ошибки PHP с указанием файла и строки.

Можно ли вставить PHP-код прямо в шорткод?

Нет. Шорткод, это триггер, а не контейнер для произвольного кода. Выполняется функция, зарегистрированная на стороне сервера через add_shortcode(). Если нужна кастомная логика, пишите её в functions.php (или в отдельном плагине) и привязывайте к шорткоду. Между квадратными скобками можно передавать только контент и атрибуты, не исполняемый код. Для безопасного выполнения PHP в контенте изучите плагины типа «Code Snippets», они позволяют управлять сниппетами через интерфейс админки без правки functions.php и с защитой от фатальных ошибок.

Шорткоды замедляют сайт?

Сами по себе, нет. add_shortcode() лишь регистрирует соответствие тега и функции в глобальном массиве $shortcode_tags. Накладные расходы возникают, когда функция шорткода выполняет тяжёлые запросы к базе данных или внешним API при каждой загрузке страницы. Проблема не в механизме шорткодов, а в реализации конкретного плагина. Ориентир: если страница содержит 20+ шорткодов, каждый из которых дёргает WP_Query или wp_remote_get(), кешируйте результаты через Transients API. Для типовых сценариев (один-два шорткода на страницу) влияние на производительность пренебрежимо мало.

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

Используйте remove_shortcode() в functions.php. Например, чтобы отключить встроенную галерею: remove_shortcode( 'gallery' ). После этого [gallery] в тексте записи отобразится как обычный текст в квадратных скобках, без выполнения. Пригождается при миграции на другое решение или отладке конфликтов. Частичное отключение: можно переопределить шорткод, зарегистрировав свой обработчик с тем же тегом через add_shortcode(). Последний зарегистрированный обработчик имеет приоритет.

Стоит ли учить шорткоды в 2026 году

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

Если вы регулярно повторяете в статьях один и тот же HTML-блок, ссылку или шаблон, потратьте 10 минут на add_shortcode() в functions.php. Возврат инвестиций: десятки часов в год, которые вы не тратите на копипасту. Шорткоды обратно совместимы, написанный сегодня код будет работать в следующих версиях WordPress, потому что API шорткодов не менялось с момента появления и остаётся одним из самых стабильных элементов ядра.