Регистрация параметров экрана в WordPress с функцией add_screen_option()

## Функция ADD_SCREEN_OPTION() │ WP 3.1.0

### Регистрация и настройка параметров экрана администратора

**Назначение:** Функция get_current_screen()

**Хуки:** Нет.

### Возвращаемое значение

null. Ничего (null).

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

```php
add_screen_option( $option, $args );

• $option (string) (обязательный) — название параметра.
• $args (mixed) — аргументы, зависящие от параметра.
  • По умолчанию: array()

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

Пример 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 Сохранение параметра 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. Сохранение параметра 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

function add_screen_option( $option, $args = array() ) {
    $current_screen = get_current_screen();

    if ( ! $current_screen ) {
        return;
    }

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

Связанные функции

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

• activate_plugins()
• content_url()
• deactivate_plugins()
• get_file_data()
• get_plugin_data()
• get_plugins()
• is_plugin_active()
• plugin_basename()
• plugin_dir_path()
• plugin_dir_url()
• plugins_url()
• register_activation_hook()
• register_deactivation_hook()
• register_uninstall_hook()
• validate_plugin_requirements()
• wp_get_active_and_valid_plugins()