add_screen_option() │ WP 3.1.0

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

Работает на основе метода:

WP_Screen::add_option( $option, $args = array() );

Смотрите файл /wp-admin/includes/class-wp-screen.php

Функция добавляет название опции и её параметры в свойство класса $_options, который затем можно получить с помощью метода WP_Screen::get_option( $option, $key = false )

Также есть предустановленная опция 'per_page'. Если её определить в момент когда экран определен, но вывода еще не было. То в настройках экрана появится настройка "Постраничная навигация":

screen-options-per_page

Вызывать нужно после того как экран определен, т.е. во время или после события current_screen (это после admin_init). Лучше всего во время загрузки страницы: событие load-(page_hook).

Статья по теме: Настройки экрана: опция «количество элементов на странице» для таблиц WP_List_Table

Работает на основе: get_current_screen()

Хуков нет.

Возвращает

null. Ничего.

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

add_screen_option( $option, $args );
$option(строка) (обязательный)
Название опции. Предустановленно название per_page и layout_columns.
$args(смешанный)
Параметры опции в виде массива или как-либо еще.
По умолчанию: array()

Примеры

0

#1 Добавим настройки постраничной навигации на страницу админ панели

Допустим мы регистрируем свою страницу с помощью add_menu_page() и нам нужно добавить на страницу настройку постраничной навигации:

// регистрируем страницу
$hook = add_menu_page( $pg_title, $menu_title, $cap, $slug, $function );

// подключаемся к событию, когда страница загружена, но еще ничего не выводится
add_action( "load-$hook", function () {
	add_screen_option( 'per_page', array(
		'label' => 'Показывать на странице',
		'default' => 10,
		'option' => 'my_page_per_page', // название опции, будет записано в метаполе юзера
	) );
} );

// Теперь чтобы опция сохранялась нужно добавить еще такой хук

// WP 5.4.2. Cохранение опции экрана per_page. Нужно вызывать до события 'admin_menu'
add_filter( 'set_screen_option_'.'my_page_per_page', function( $status, $option, $value ){
	return (int) $value;
}, 10, 3 );

// WP < 5.4.2. Cохранение опции экрана per_page. Нужно вызывать до события 'admin_menu'
add_filter( 'set-screen-option', function( $status, $option, $value ){
	return ( $option == 'my_page_per_page' ) ? (int) $value : $status;
}, 10, 3 );

Получить указанную опцию там где она нужна можно с помощью такого кода:

$per_page_option = get_current_screen()->get_option('per_page');
$per_page = get_user_meta( get_current_user_id(), $per_page_option['option'], true ) ?: $per_page_option['default'];
// $per_page будет равно 10 или сколько было установлено...

Список изменений

С версии 3.1.0 Введена.

Код add_screen_option() WP 6.7.1

wp-admin/includes/screen.php 
function add_screen_option( $option, $args = array() ) {
	$current_screen = get_current_screen();

	if ( ! $current_screen ) {
		return;
	}

	$current_screen->add_option( $option, $args );
}

Плагины, хуки