WordPress 6.4 引入新的后台管理通知函数

后台管理通知（Admin notices）在 WordPress核心和扩展程序社区中广泛使用。管理通知具有通用的标记模式和CSS类，但需要为整个项目中的每个通知独立维护HTML 。

在#57791中，提出了两个新函数：wp_get_admin_notice()和wp_admin_notice()。

这些函数抽象了 HTML 标记生成，以减少维护负担、鼓励一致性并为所有管理通知启用参数和消息过滤。此外，wp_admin_notice还引入了一个新动作钩子，该动作在输出通知之前触发。

新函数

wp_get_admin_notice()

• 返回管理通知的标记。
• 注意：标记未完全转义，在输出之前应注意选择适当的转义函数。

wp_admin_notice()

• 输出管理通知的标记。
• 标记是使用wp_get_admin_notice()创建和在输出之前使用wp_kses_post()转义的。

参数

这两个函数都有以下参数：

• string $message 通知的消息。
• array $args 通知的参数数组。
  • string $type 可选。管理通知的类型。这将被附加到'notice-'创建 HTML 类名称。例如，'success' 的类型将生成'notice-success'HTML 类。默认空字符串。
  • bool $dismissible 可选。通知是否可以驳回。默认为 false。
  • string $id 可选。HTML 属性的值id。默认空字符串。
  • array $additional_classes 可选。用于通知的附加类名称的数组。这些按规定使用。默认空数组。
  • array $attributes 可选。通知的 HTML 属性的关联数组。布尔true属性可能只包括属性的名称。默认空数组。
  • array $paragraph_wrap 可选。是否将消息包装在<p></p>标签中。默认为true。

过滤器

wp_get_admin_notice()应用以下过滤器：

• wp_admin_notice_args– 过滤管理员通知的参数。
  • 传递的参数：array $args,string $message
• wp_admin_notice_markup– 过滤管理员通知的标记。
  • 传递的参数：string $markup, string $message,array $args

动作钩子

wp_admin_notice()触发以下操作：

• wp_admin_notice– 在输出管理通知之前触发。
  • 传递的参数：string $message,array $args

用法示例

输出可隐藏的成功通知

wp_admin_notice(
  __( 'Plugin update failed.', 'my-text-domain' ),
  array(
    'type'               => 'error',
    'dismissible'        => true,
    'additional_classes' => array( 'inline', 'notice-alt' ),
    'attributes'         => array( 'data-slug' => 'plugin-slug' )
  )
);

结果

<div class="notice notice-error is-dismissible inline notice-alt" data-slug="plugin-slug"><p>Plugin update failed.</p></div>

创建要立即输出的通知集合 

$output = '';
foreach ( $success_messages as $message ) {
  $output .= wp_get_admin_notice(
    $message,
    array( 'type' => 'success' )
  );
}
 
echo wp_kses_post( $output );

结果

<div class="notice notice-success"><p>Success message 1</p></div>

（每个通知都重复）

为每个“警告”管理通知添加一个类

add_filter( 'wp_admin_notice_args', 'myprefix_add_class_to_warnings' );
function myprefix_add_class_to_warnings( $args ) {
  if ( 'warning' === $args['type'] ) {
    $args['additional_classes'][] = 'my-class';
  }
 
  return $args;
}

结果

<div class="notice notice-warning my-class"><p>Warning message 1</p></div>

（对每个警告通知重复）

WordPress 核心中的用法

新的管理通知功能已在 WordPress Core 的大多数位置实现。进一步的工作将在 WordPress 6.5 中完成，以完成该过程并将旧通知（使用 'updated'和'error'类）迁移到当前的管理通知模式（'notice-success'、'notice-info'、'notice-warning'和'notice-error'）。