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

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

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

Шорткод — это простой текстовый тег в квадратных скобках, который WordPress заменяет на определённый вывод или функциональность. Например, [gallery] выводит галерею изображений, а [audio] — аудиоплеер. Создание собственных шорткодов полезно, когда стандартных возможностей CMS недостаточно, и нужно быстро вставлять повторяющийся или динамический контент без копирования большого кода.

Типичные применения шорткодов:

• Вставка кастомных блоков с информацией (контакты, отзывы, кнопки).
• Добавление интерактивных элементов (формы, калькуляторы).
• Вывод данных из базы или внешних API.

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

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

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

function wp_puzzle_simple_shortcode() {
    return '<div style="padding:10px; background:#f0f0f0; border:1px solid #ccc;">Привет от WP-Puzzle!</div>';
}
add_shortcode('wp_puzzle_hello', 'wp_puzzle_simple_shortcode');

Этот пример создаёт шорткод [wp_puzzle_hello], который выводит стилизованный блок с текстом. Вы можете вставить этот шорткод в любую запись или страницу, и WordPress заменит его на HTML.

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

Шорткод с параметрами: как передавать аргументы

Очень часто шорткоды нужно делать гибкими, чтобы можно было менять поведение через параметры. Рассмотрим пример, где шорткод принимает параметр color и меняет цвет текста:

function wp_puzzle_colored_text_shortcode($atts, $content = null) {
    $atts = shortcode_atts(array(
        'color' => 'blue',
    ), $atts, 'wp_puzzle_colored_text');

    $color = esc_attr($atts['color']);
    $text = $content ? $content : 'Текст по умолчанию';

    return '<span style="color:'. $color .'">' . esc_html($text) . '</span>';
}
add_shortcode('wp_puzzle_colored_text', 'wp_puzzle_colored_text_shortcode');

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

[wp_puzzle_colored_text color="red"]Важный текст[/wp_puzzle_colored_text]

Этот шорткод выведет красный текст "Важный текст". Если параметр или содержимое не указаны, используются значения по умолчанию.

Разбор кода

Мы используем функцию shortcode_atts — она объединяет переданные атрибуты с дефолтными. Это стандартная практика для обработки параметров шорткодов.

Функции esc_attr и esc_html обеспечивают безопасность, экранируя входные данные, чтобы предотвратить XSS-уязвимости.

Сложный шорткод: вывод постов с определённой категорией

Теперь создадим шорткод, который выводит список из 5 последних постов определённой категории. Это пример, который часто требуется для кастомных лендингов и разделов сайта.

function wp_puzzle_recent_posts_shortcode($atts) {
    $atts = shortcode_atts(array(
        'category' => '',
        'posts_per_page' => 5,
    ), $atts, 'wp_puzzle_recent_posts');

    $query_args = array(
        'posts_per_page' => intval($atts['posts_per_page']),
        'category_name' => sanitize_text_field($atts['category']),
        'post_status' => 'publish',
    );

    $query = new WP_Query($query_args);

    if (!$query->have_posts()) {
        return '<p>Посты не найдены.</p>';
    }

    $output = '<ul>';
    while ($query->have_posts()) {
        $query->the_post();
        $output .= '<li><a href="' . get_permalink() . '">' . get_the_title() . '</a></li>';
    }
    wp_reset_postdata();
    $output .= '</ul>';

    return $output;
}
add_shortcode('wp_puzzle_recent_posts', 'wp_puzzle_recent_posts_shortcode');

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

[wp_puzzle_recent_posts category="wordpress" posts_per_page="3"]

Этот шорткод выведет список из трёх последних постов из категории "wordpress".

Подробности реализации

Используем класс WP_Query для выборки постов по параметрам. Обязательно вызываем wp_reset_postdata() после цикла для восстановления глобального состояния.

Обработка параметров с помощью shortcode_atts, а также фильтрация и санитизация входных данных (intval, sanitize_text_field) повышают безопасность и надёжность кода.

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

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

• Всегда фильтруйте и экранируйте пользовательский ввод.
• Не выводите данные напрямую, используйте esc_html, esc_attr, esc_url.
• Избегайте выполнения тяжёлых запросов без кеширования.

Для повышения производительности можно использовать встроенный в WordPress transient API для кеширования результатов шорткодов, если они запрашивают данные из базы или внешних сервисов.

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

Если вы не хотите писать шорткоды вручную, существуют плагины, которые упрощают работу:

• Shortcodes Ultimate — набор из 50+ готовых шорткодов с визуальным редактором.
• Custom Content Shortcode — позволяет создавать шорткоды для отображения контента с условиями.
• WPBakery Page Builder и Elementor — визуальные конструкторы с поддержкой шорткодов и виджетов.

Однако для полной кастомизации и оптимизации лучше создавать собственные шорткоды, как описано выше.

Заключение: когда и почему стоит создавать собственные шорткоды

Создание собственных шорткодов — это обязательный навык для разработчика WordPress, который позволяет:

• Сделать контент динамическим и легко управляемым.
• Обеспечить удобство редактирования для контент-менеджеров без знаний кода.
• Увеличить повторное использование функционала на сайте.

В статье мы рассмотрели разные уровни сложности: от простого вывода текста до динамических списков постов. Используйте эти подходы и адаптируйте их под свои задачи.