Использование функции add_screen_option() в WordPress: добавляем настраиваемые опции экрана

Функция add_screen_option() позволяет добавить на страницы админ-панели специальные настройки, которые появляются в разделе «Настройки экрана». Эти настройки включают, например, возможность выбора количества элементов на странице или количества колонок.

add_screen_option( string $option, mixed $args = array() )

Функция позволяет задавать настройки вида «Количество элементов на странице» (per_page) или «Количество колонок» (layout_columns) для различных страниц админ-панели.

Параметры функции

• $option (строка, обязательный): Название параметра. В WordPress поддерживаются два значения — per_page и layout_columns.
• $args (смешанный, необязательный): Параметры опции в виде массива. Например, можно указать текст метки, значение по умолчанию или имя опции.

Поддерживаемые параметры

1. per_page — задает количество элементов на странице.
2. layout_columns — задает количество колонок на странице.

Пример 1: Добавление опции «Количество элементов на странице»

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

// Регистрируем страницу и получаем ее хук
$hook = add_menu_page( 'Тестовая страница', 'Тест', 'manage_options', 'test_page', 'render_test_page' );

// Добавляем настройку на страницу через событие загрузки страницы
add_action( "load-$hook", function() {
    add_screen_option( 'per_page', array(
        'label'   => 'Элементов на странице',
        'default' => 15,
        'option'  => 'test_page_per_page'
    ) );
});

// Сохраняем значение опции через фильтр `set_screen_option`
add_filter( 'set_screen_option_test_page_per_page', function($status, $option, $value) {
    return (int) $value;
}, 10, 3 );

Этот код добавит на страницу выбор количества отображаемых элементов. Значение по умолчанию — 15, и оно будет сохранено в метаполе пользователя.

Пример 2: Установка количества колонок

Можно задать опцию для управления количеством колонок на админ-странице с помощью параметра layout_columns:

add_action( 'admin_menu', function() {
    $hook = add_menu_page( 'Демо страница', 'Демо', 'manage_options', 'demo_page', 'render_demo_page' );
    add_action( "load-$hook", function() {
        add_screen_option( 'layout_columns', array(
            'max'     => 3,
            'default' => 2
        ) );
    });
});

Этот код добавит выбор количества колонок, с максимумом в три колонки и значением по умолчанию в две.

Пример 3: Получение значения настройки

Для получения значения, выбранного пользователем в настройке экрана, можно использовать функцию get_current_screen():

$current_screen = get_current_screen();
$items_per_page = get_user_meta( get_current_user_id(), $current_screen->get_option( 'per_page', 'option' ), true ) ?: $current_screen->get_option( 'per_page', 'default' );

// Значение $items_per_page будет равно значению, установленному пользователем или значению по умолчанию
echo 'Элементов на странице: ' . $items_per_page;

Рекомендации по использованию add_screen_option()

1. Используйте add_screen_option() для добавления уникальных настроек экрана, которые помогут администратору адаптировать страницу под свои задачи.
2. Если нужно использовать опцию на пользовательской странице админ-панели, регистрируйте её во время или после события load-(page_hook).

Заключение

add_screen_option() — полезная функция для настройки страниц админ-панели WordPress. С ее помощью можно упростить управление контентом, добавив гибкие опции, такие как количество отображаемых элементов и количество колонок.