Функция add_settings_field() в WordPress: создание поля настроек с примерами

Функция add_settings_field() является частью API настроек WordPress и используется для добавления нового поля в секцию страницы настроек. Это особенно полезно для разработчиков, которые хотят добавить свои собственные настройки к существующим страницам настроек WordPress или создать свои собственные страницы настроек для плагинов или тем.

add_settings_field( 
    string $id, 
    string $title, 
    callable $callback, 
    string $page, 
    string $section = 'default', 
    array $args = array() 
);

• $id (string, обязательный) — уникальный идентификатор поля.
• $title (string, обязательный) — заголовок поля, который будет отображаться в админке.
• $callback (callable, обязательный) — функция обратного вызова, которая выводит HTML для поля.
• $page (string, обязательный) — страница настроек, к которой будет добавлено поле.
• $section (string, опциональный) — секция на странице, куда будет добавлено поле (по умолчанию 'default').
• $args (array, опциональный) — дополнительные аргументы для передачи в функцию обратного вызова.

Важные моменты

• Функция обратного вызова: Она должна выводить HTML для поля ввода, используя функцию get_option() для получения сохранённого значения опции.
• Регистрация опции: Для правильной работы поля необходимо зарегистрировать опцию с помощью функции register_setting().

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

Рассмотрим пример добавления текстового поля на страницу настроек «Общие» (general):

Шаг 1: Регистрация опции и добавление поля

function my_custom_settings() {
    // Регистрируем опцию
    register_setting( 'general', 'my_custom_option' );

    // Добавляем новое поле
    add_settings_field(
        'my_custom_field_id',                   // ID поля
        'Моя настраиваемая опция',              // Название поля
        'my_custom_field_callback',             // Callback функция для вывода поля
        'general',                              // Страница настроек (general)
        'default',                              // Секция (по умолчанию default)
        array( 'label_for' => 'my_custom_field_id' ) // Аргументы для callback
    );
}
add_action( 'admin_init', 'my_custom_settings' );

Шаг 2: Создание функции обратного вызова для вывода поля

function my_custom_field_callback( $args ) {
    // Получаем сохраненное значение опции
    $value = get_option( 'my_custom_option' );
    
    // Выводим HTML для поля ввода
    echo '<input type="text" id="' . esc_attr( $args['label_for'] ) . '" name="my_custom_option" value="' . esc_attr( $value ) . '" />';
}

После этого в админке WordPress, на странице «Общие» появится новое текстовое поле для ввода данных.

Пример с чекбоксом

Добавим чекбокс на страницу настроек:

Шаг 1: Регистрация чекбокса

function my_checkbox_settings() {
    // Регистрируем чекбокс
    register_setting( 'general', 'my_checkbox_option' );

    // Добавляем чекбокс на страницу настроек
    add_settings_field(
        'my_checkbox_field_id',                 // ID поля
        'Включить опцию',                       // Название поля
        'my_checkbox_field_callback',           // Callback функция
        'general',                              // Страница настроек
        'default',                              // Секция
        array( 'label_for' => 'my_checkbox_field_id' ) // Аргументы
    );
}
add_action( 'admin_init', 'my_checkbox_settings' );

Шаг 2: Callback функция для чекбокса

function my_checkbox_field_callback( $args ) {
    // Получаем текущее значение чекбокса
    $checked = get_option( 'my_checkbox_option' ) ? 'checked' : '';
    
    // Выводим HTML для чекбокса
    echo '<input type="checkbox" id="' . esc_attr( $args['label_for'] ) . '" name="my_checkbox_option" value="1" ' . $checked . '/>';
}

Теперь на странице «Общие» появится чекбокс, который можно включать и выключать.

Пример с использованием класса

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

class MySettingsClass {
    public function __construct() {
        add_action( 'admin_init', array( $this, 'add_settings_fields' ) );
    }

    public function add_settings_fields() {
        // Регистрируем опцию
        register_setting( 'general', 'my_class_option' );

        // Добавляем поле
        add_settings_field(
            'my_class_field_id', 
            'Настройка через класс', 
            array( $this, 'field_callback' ), 
            'general', 
            'default', 
            array( 'label_for' => 'my_class_field_id' )
        );
    }

    public function field_callback( $args ) {
        $value = get_option( 'my_class_option' );
        echo '<input type="text" id="' . esc_attr( $args['label_for'] ) . '" name="my_class_option" value="' . esc_attr( $value ) . '" />';
    }
}

new MySettingsClass();

Этот подход полезен для крупных плагинов, где необходимо управлять несколькими настройками через объектно-ориентированное программирование (ООП).

Заключение

Функция add_settings_field() — это мощный инструмент для создания пользовательских полей на страницах настроек WordPress. Она легко комбинируется с register_setting() и другими функциями API настроек, что позволяет разработчикам создавать как простые, так и сложные страницы настроек для своих плагинов и тем.