Шорткоды WordPress: использовать, настраивать, создавать

Оглавление

• Что такое шорткод WordPress?
• Встроенные шорткоды WordPress
• Как вставить шорткод в запись WordPress
  • В редакторе Gutenberg
  • В классическом редакторе
• Настройка темы через шорткод
• Можно ли добавлять шорткоды в виджеты
• Создание кастомного шорткода
• Безопасность и лучшие практики
• Альтернативы шорткодам
• Когда шорткоды не подходят
• Полезные сниппеты и шпаргалка
• Чеклисты и SOP
• Критерии приёмки
• Краткий глоссарий

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

Шорткод — это короткая метка в квадратных скобках, которую WordPress заменяет на более сложный HTML, JavaScript или PHP-результат при выводе страницы. Главная идея — инкапсулировать повторяемую логику в удобную для автора форму.

Типы шорткодов:

• Самозакрывающиеся шорткоды: один тег в квадратных скобках, без отдельного закрытия. Пример: [gallery].
• Оборачивающие шорткоды: имеют открывающий и закрывающий теги и заключают контент. Пример: [caption]контент[/caption].

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

Встроенные шорткоды WordPress

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

• [caption] — оборачивает контент подписью.
• [gallery] — формирует аккуратную сетку изображений.
• [audio] — встраивает аудиофайлы.
• [video] — встраивает видео.
• [playlist] — выводит коллекцию аудиотреков или видео.
• [embed] — универсальная обёртка для внешних вставок: tweets, YouTube, карты и др.

Эти шорткоды покрывают стандартные сценарии. Настоящая гибкость приходит, когда вы создаёте собственные шорткоды для уникальных задач.

Как вставить шорткод в запись WordPress

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

В редакторе Gutenberg

Gutenberg имеет специальный блок для шорткодов. Нажмите на плюс в левом верхнем углу и выберите блок Shortcode в разделе Виджеты. Вставьте шорткод в текстовое поле, включая квадратные скобки. Нажмите «Опубликовать» или «Предпросмотр», чтобы увидеть результат.

Примечание: если вам не нравится Gutenberg, можно восстановить классический редактор через плагин.

В классическом редакторе

Поместите курсор в нужное место записи и вставьте шорткод прямо в текстовый редактор. Достаточно квадратных скобок и самого имени шорткода.

Настройка темы через шорткод

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

Пример: вы хотите добавить бейдж «Подлинно» в конец каждой записи. Создаёте шорткод, а затем в нужном месте шаблона single.php вызываете do_shortcode.

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

Вставьте этот вызов в файл single.php через Редактор файлов темы (Внешний вид → Редактор файлов темы) в том месте, где хотите видеть бейдж.

do_shortcode возвращает HTML, который затем вставляется в страницу. Это удобный способ централизованно управлять отображением элементов.

Можно ли добавлять шорткоды в область виджетов

Да. В разделе внешнего вида можно добавить виджет Shortcode или Custom HTML в сайдбар, футер или любую область, поддерживающую виджеты. Вставьте шорткод в содержимое виджета и сохраните.

Нажмите «Опубликовать» и проверьте результат.

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

С помощью PHP можно создать произвольные шорткоды. Ниже — пошаговая методика и примеры кода, которые можно адаптировать.

Внимание: перед изменением файлов темы сделайте резервную копию. Лучше работать в дочерней теме или использовать плагин для кастомного кода.

Шаги:

1. Откройте Внешний вид → Редактор файлов темы → Theme Functions (functions.php).
2. Вставьте функцию, регистрирующую шорткод через add_shortcode.
3. Сохраните файл и протестируйте шорткод в записи.

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

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

function display_current_time() {
    return date_i18n('g:i a');
}
add_shortcode('current_time', 'display_current_time');

Объяснение: date_i18n учитывает локаль WordPress. Формат ‘g:i a’ выдаст время вида “3:45 pm”. Если вы хотите 24‑часовой формат, используйте ‘H:i’.

Пример 2: шорткод с атрибутами и оборачивающим контентом:

function box_shortcode($atts, $content = null) {
    $atts = shortcode_atts(array(
        'title' => '',
        'class' => 'note'
    ), $atts, 'box');

    $title_html = $atts['title'] ? '
' . esc_html($atts['title']) . '
' : '';
    $content_html = do_shortcode($content);

    return '
' . $title_html . '
' . $content_html . '
';
}
add_shortcode('box', 'box_shortcode');

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

[box title=”Совет” class=”important”]Текст внутри коробки[/box]

Этот пример показывает: 1) как задать значения по умолчанию через shortcode_atts, 2) как экранировать вывод функциями esc_html и esc_attr, и 3) как рекурсивно обрабатывать вложенные шорткоды через do_shortcode.

Безопасность и лучшие практики

• Всегда экранируйте вывод: используйте esc_html, esc_attr, wp_kses_post и другие функции экранирования.
• Не выполняйте произвольный пользовательский ввод без проверки.
• Если шорткод возвращает HTML, явно контролируйте, какие теги разрешены.
• Для операций с данными используйте nonce и проверки прав (current_user_can) там, где это требуется.
• Для производительности: избегайте тяжёлых запросов к базе в хуке вывода шорткода; кэшируйте результат, если он дорогой.

Совет по отладке: при ошибках включите WP_DEBUG в локальной среде, но не на продуктиве.

Альтернативы шорткодам

• Блоки Gutenberg: если вы работаете с современным редактором, кастомные блоки (block.json + JS) дают более тесную интеграцию и визуальное редактирование.
• Плагины и конструкторы страниц: Elementor, Beaver Builder и др. предлагают виджеты и динамические элементы.
• Виджеты и шаблонные части темы: для постоянных элементов удобнее править шаблоны, чем полагаться на шорткоды.

Выбор зависит от роли: редактору проще шорткод, разработчику — блок.

Когда шорткоды не подходят

• Для сложного визуального редактирования лучше сделать блок для Gutenberg.
• Если функционал требует состояния на клиенте (SPA-подход), используйте JavaScript-приложение.
• Когда логика должна выполняться до рендеринга страницы на сервере (например, для роутинга или сложной серверной логики), шорткод — не лучшая опция.

Полезные сниппеты и шпаргалка

Вставка шорткода в PHP шаблон:

echo do_shortcode('[your_shortcode attr="value"]');

Разрешить шорткоды внутри виджетов Custom HTML (если отключены):

add_filter('widget_text', 'do_shortcode');

Удаление шорткода (если больше не нужен):

remove_shortcode('old_shortcode');

Короткая проверка прав и nonce для обработки формы внутри шорткода:

if (!isset($_POST['my_nonce']) || !wp_verify_nonce($_POST['my_nonce'], 'my_action')) {
    return 'Неверный запрос.';
}
if (!current_user_can('edit_posts')) {
    return 'Нет прав.';
}

Чеклисты и SOP

Чеклист для администратора перед добавлением шорткода через functions.php:

• Сделана резервная копия functions.php.
• Тест в локальной среде или на стенд-сайте.
• Код проверен на синтаксические ошибки (php -l).
• Выполнена проверка прав доступа и экранирование вывода.
• Проведен тест в разных браузерах и на мобильных устройствах.

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

• Правильные квадратные скобки [] используются.
• Нет лишних пробелов в имени шорткода.
• Проверены атрибуты и их значения.
• Нажата кнопка Предпросмотр перед публикацией.

SOP: быстрое внедрение нового шорткода

1. Создайте функцию с ясными входными параметрами и экранированием вывода.
2. Зарегистрируйте шорткод через add_shortcode.
3. Протестируйте локально с разными значениями атрибутов.
4. Деплой на тестовый сайт, затем на продуктив.
5. Добавьте запись в CHANGELOG темы или в документацию сайта.

Критерии приёмки

• Шорткод выводит ожидаемый HTML и корректно экранирован.
• Нет PHP-ошибок или предупреждений.
• Производительность в пределах нормы (время генерации страницы не увеличилось существенно).
• Кроссбраузерная проверка пройдена.
• Для шорткодов с правами — доступ ограничен корректно.

Тесты и сценарии приёмки

1. Базовый вывод: вставить шорткод в запись и проверить, что содержимое появляется.
2. Атрибуты: передать разные значения атрибутов и убедиться в корректном поведении.
3. Вложенные шорткоды: использовать шорткод внутри другого и проверить вывод.
4. Безопасность: ввести попытку XSS в атрибут — убедиться, что вывод экранируется.
5. Производительность: замерить время загрузки страницы с шорткодом и без него.

Ментальные модели и эвристики

• Модель инкапсуляции: шорткод = чёрный ящик, который получает параметры и возвращает HTML.
• Правило единственной ответственности: шорткод должен выполнять одну задачу.
• Эвристика производительности: если генерация занимает более 200–300 мс на странице, рассматривайте кеширование.

Примеры ошибок и когда шорткод может подвести

• Шорткод делает дорогие SQL-запросы на каждой загрузке без кеша — тормозит сайт.
• Некорректное экранирование приводит к уязвимости XSS.
• Использование функций, недоступных в контексте шаблона, может вызывать фатальные ошибки.

Диаграмма принятия решения

flowchart TD
  A[Нужен кастомный элемент?] --> B{Требуется визуальное редактирование}
  B -- Да --> C[Создать блок Gutenberg]
  B -- Нет --> D{Требуется серверная логика}
  D -- Да --> E[Шорткод или функция в шаблоне]
  D -- Нет --> F[Простейший HTML или виджет]
  E --> G{Нужны права администратора}
  G -- Да --> H[Добавить проверку current_user_can]
  G -- Нет --> I[Публиковать шорткод]

Краткий глоссарий

• Шорткод — короткая метка в квадратных скобках, возвращающая HTML.
• do_shortcode — PHP-функция WordPress для выполнения шорткода в шаблоне.
• shortcode_atts — функция для задания значений по умолчанию атрибутов.

Короткая шпаргалка для разработчика

• Всегда экранируйте вывод.
• Используйте date_i18n для времени.
• Применяйте do_shortcode для вложенных шорткодов.
• Кешируйте дорогую работу.

Image credit: Pixabay. All screenshots by David Morelo.

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