Как добавить собственное поле виджета в административную панель WordPress с примерами кода

Автор: Руслан Карпов | Опубликовано: 17.02.2026

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

Зачем добавлять собственные поля в виджеты WordPress

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

Дополнительные поля позволяют:

Настроить отображение виджета более гибко;
Собрать дополнительную информацию от пользователя;
Интегрировать виджет с другими частями сайта или API.

Основные методы добавления своих полей в виджет

Добавление новых полей в виджет обычно происходит в двух методах класса виджета — wpcorp_widget_form и wpcorp_widget_update. Первый отвечает за вывод формы настроек в админке, второй — за сохранение введённых данных.

Рассмотрим пример на основе стандартного виджета WordPress, в который добавим поле для ввода дополнительного текста.

Пример: добавляем поле дополнительного текста в виджет

class Wpcorp_Custom_Widget extends WP_Widget {

    public function __construct() {
        parent::__construct(
            'wpcorp_custom_widget',
            'WPCorp: Кастомный виджет'
        );
    }

    public function widget($args, $instance) {
        echo $args['before_widget'];
        if (!empty($instance['title'])) {
            echo $args['before_title'] . apply_filters('widget_title', $instance['title']) . $args['after_title'];
        }
        if (!empty($instance['custom_text'])) {
            echo '<p>' . esc_html($instance['custom_text']) . '</p>';
        }
        echo $args['after_widget'];
    }

    public function form($instance) {
        $title = !empty($instance['title']) ? $instance['title'] : '';
        $custom_text = !empty($instance['custom_text']) ? $instance['custom_text'] : '';
        ?>
        <p>
            <label for="<?php echo esc_attr($this->get_field_id('title')); ?>">Заголовок:</label>
            <input class="widefat" id="<?php echo esc_attr($this->get_field_id('title')); ?>" name="<?php echo esc_attr($this->get_field_name('title')); ?>" type="text" value="<?php echo esc_attr($title); ?>">
        </p>
        <p>
            <label for="<?php echo esc_attr($this->get_field_id('custom_text')); ?>">Дополнительный текст:</label>
            <textarea class="widefat" id="<?php echo esc_attr($this->get_field_id('custom_text')); ?>" name="<?php echo esc_attr($this->get_field_name('custom_text')); ?>"><?php echo esc_textarea($custom_text); ?></textarea>
        </p>
        <?php
    }

    public function update($new_instance, $old_instance) {
        $instance = [];
        $instance['title'] = sanitize_text_field($new_instance['title']);
        $instance['custom_text'] = sanitize_textarea_field($new_instance['custom_text']);
        return $instance;
    }
}

function wpcorp_register_custom_widget() {
    register_widget('Wpcorp_Custom_Widget');
}
add_action('widgets_init', 'wpcorp_register_custom_widget');

В этом примере мы создали новый виджет с полем custom_text, которое выводится в настройках в виде текстового поля. При сохранении данные проходят очистку с помощью функций sanitize_text_field и sanitize_textarea_field. Это обязательная практика для безопасности.

Добавление полей выбора и загрузки файлов

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

Пример: поле цвета и загрузка изображения

public function form($instance) {
    $color = !empty($instance['color']) ? $instance['color'] : '#000000';
    $image = !empty($instance['image']) ? $instance['image'] : '';
    ?>
    <p>
        <label for="<?php echo esc_attr($this->get_field_id('color')); ?>">Выберите цвет:</label><br>
        <input class="wpcorp-color-picker" id="<?php echo esc_attr($this->get_field_id('color')); ?>" name="<?php echo esc_attr($this->get_field_name('color')); ?>" type="text" value="<?php echo esc_attr($color); ?>" />
    </p>
    <p>
        <label>Изображение:</label><br>
        <img class="wpcorp-image-preview" src="<?php echo esc_url($image); ?>" style="max-width:100%; height:auto; display:<?php echo $image ? 'block' : 'none'; ?>;" />
        <input class="widefat wpcorp-image-url" id="<?php echo esc_attr($this->get_field_id('image')); ?>" name="<?php echo esc_attr($this->get_field_name('image')); ?>" type="text" value="<?php echo esc_attr($image); ?>" />
        <button class="button wpcorp-upload-button">Загрузить</button>
    </p>
    <script>
    jQuery(document).ready(function($){
        $('.wpcorp-color-picker').wpColorPicker();
        $('.wpcorp-upload-button').on('click', function(e){
            e.preventDefault();
            var button = $(this);
            var input = button.prev('.wpcorp-image-url');
            var preview = button.parent().find('.wpcorp-image-preview');
            var frame = wp.media({
                title: 'Выберите изображение',
                button: { text: 'Выбрать' },
                multiple: false
            });
            frame.on('select', function() {
                var attachment = frame.state().get('selection').first().toJSON();
                input.val(attachment.url);
                preview.attr('src', attachment.url).show();
            });
            frame.open();
        });
    });
    </script>
    <?php
}

public function update($new_instance, $old_instance) {
    $instance = [];
    $instance['color'] = sanitize_hex_color($new_instance['color']);
    $instance['image'] = esc_url_raw($new_instance['image']);
    return $instance;
}

Здесь мы использовали встроенный в WordPress wpColorPicker для выбора цвета и медиабиблиотеку для загрузки изображений. Такой подход делает настройки виджета визуально удобными и функциональными.

Полезные плагины для расширения функционала виджетов

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

Clearfy Pro — плагин для оптимизации и расширения WordPress, в том числе улучшает работу с виджетами.
WPStories — позволяет создавать интерактивные виджеты с визуальными элементами.

Советы по безопасности и производительности при добавлении полей в виджеты

При добавлении собственных полей в виджеты всегда соблюдайте правила безопасности:

Используйте функции очистки данных (например, sanitize_text_field, sanitize_hex_color, esc_url_raw).
Экранируйте вывод данных с помощью esc_html, esc_attr и других функций.
Не загружайте лишних скриптов и стилей без необходимости, чтобы не замедлять сайт.

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

Пример подключения скриптов для виджета

function wpcorp_enqueue_widget_admin_scripts($hook) {
    if ('widgets.php' !== $hook) {
        return;
    }
    wp_enqueue_style('wp-color-picker');
    wp_enqueue_script('wp-color-picker');
    wp_enqueue_media();
    wp_enqueue_script('wpcorp-widget-admin', plugin_dir_url(__FILE__) . 'widget-admin.js', ['jquery', 'wp-color-picker'], '1.0', true);
}
add_action('admin_enqueue_scripts', 'wpcorp_enqueue_widget_admin_scripts');

Такой подход позволит избежать излишней нагрузки на админку и фронтенд сайта.

Итоги

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

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