Функция wp_admin_notice() в WordPress с примерами

Функция wp_admin_notice() формирует и выводит HTML-код уведомления в верхней части страницы админ-панели. Это позволяет разработчикам предоставлять важную информацию или сообщения прямо в интерфейсе администратора.

wp_admin_notice( string $message, array $args = [] );

Параметры

• $message (string): Сообщение, которое будет показано в уведомлении. Текст можно форматировать с помощью HTML, но переданное содержимое будет отфильтровано функцией wp_kses_post() для обеспечения безопасности.
• $args (array): Массив аргументов для кастомизации уведомления. Возможные ключи:
  • type (string): Тип уведомления, например, 'success', 'error', 'warning', 'info'. По умолчанию тип не указан, что означает стандартное уведомление.
  • dismissible (bool): Позволяет ли уведомление быть закрытым пользователем. Если установлено в true, уведомление можно скрыть кликом по кнопке закрытия. По умолчанию false.
  • id (string): Значение атрибута ID для HTML-контейнера уведомления. По умолчанию пусто.
  • additional_classes (array): Массив дополнительных CSS-классов для контейнера уведомления. Эти классы добавляются к базовому классу notice и другим классам, основанным на параметре type.
  • paragraph_wrap (bool): Определяет, следует ли оборачивать сообщение в тег <p>. По умолчанию true.

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

Функция не возвращает значения; она выводит HTML-код уведомления на экран.

Хуки для использования

Функцию wp_admin_notice() можно вызывать в любом месте админ-панели, но для правильного отображения уведомления лучше использовать следующие хуки:

• network_admin_notices
• user_admin_notices
• admin_notices
• all_admin_notices

Несмотря на наличие этих хуков, уведомление можно вызвать в любом месте HTML-кода админки. Если уведомление выводится после срабатывания хука admin_notices, оно будет перемещено под заголовок с помощью JavaScript. Например:

add_action( 'admin_head', function () {
    wp_admin_notice( 'Ваше уведомление' );
} );

add_action( 'admin_footer', function () {
    wp_admin_notice( 'Ваше уведомление' );
} );

add_action( 'shutdown', function () {
    wp_admin_notice( 'Ваше уведомление' );
} );

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

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

// Функция для добавления уведомлений в админ-панель
function my_plugin_admin_notice() {
    // Проверяем, если параметр 'settings-updated' установлен в URL
    if ( isset($_GET['settings-updated']) && $_GET['settings-updated'] == 'true' ) {
        // Вызываем функцию для отображения уведомления
        wp_admin_notice( 'Настройки успешно сохранены!', 'success' );
    }
}

// Хук для добавления уведомления в админ-панель
add_action( 'admin_notices', 'my_plugin_admin_notice' );

Объяснение примера

1. Функция my_plugin_admin_notice: Эта функция проверяет наличие параметра settings-updated в URL. Если он установлен и имеет значение true, это означает, что настройки были успешно сохранены.
2. Функция wp_admin_notice: Вызывается с параметрами сообщения и типа уведомления. В этом случае используется тип 'success', чтобы показать успешное уведомление.
3. Хук admin_notices: Используется для добавления уведомления в административную панель. Функция my_plugin_admin_notice будет вызываться каждый раз, когда будут выводиться уведомления в админ-панели.

Заключение

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