WordPress 6.4 引入新的后臺(tái)管理通知函數(shù)

后臺(tái)管理通知（Admin notices）在 WordPress核心和擴(kuò)展程序社區(qū)中廣泛使用。管理通知具有通用的標(biāo)記模式和CSS類，但需要為整個(gè)項(xiàng)目中的每個(gè)通知獨(dú)立維護(hù)HTML 。

在#57791中，提出了兩個(gè)新函數(shù)：wp_get_admin_notice()和wp_admin_notice()。

這些函數(shù)抽象了 HTML 標(biāo)記生成，以減少維護(hù)負(fù)擔(dān)、鼓勵(lì)一致性并為所有管理通知啟用參數(shù)和消息過(guò)濾。此外，wp_admin_notice還引入了一個(gè)新動(dòng)作鉤子，該動(dòng)作在輸出通知之前觸發(fā)。

新函數(shù)

wp_get_admin_notice()

• 返回管理通知的標(biāo)記。
• 注意：標(biāo)記未完全轉(zhuǎn)義，在輸出之前應(yīng)注意選擇適當(dāng)?shù)霓D(zhuǎn)義函數(shù)。

wp_admin_notice()

• 輸出管理通知的標(biāo)記。
• 標(biāo)記是使用wp_get_admin_notice()創(chuàng)建和在輸出之前使用wp_kses_post()轉(zhuǎn)義的。

參數(shù)

這兩個(gè)函數(shù)都有以下參數(shù)：

• string $message 通知的消息。
• array $args 通知的參數(shù)數(shù)組。
  • string $type 可選。管理通知的類型。這將被附加到'notice-'創(chuàng)建 HTML 類名稱。例如，'success' 的類型將生成'notice-success'HTML 類。默認(rèn)空字符串。
  • bool $dismissible 可選。通知是否可以駁回。默認(rèn)為 false。
  • string $id 可選。HTML 屬性的值id。默認(rèn)空字符串。
  • array $additional_classes 可選。用于通知的附加類名稱的數(shù)組。這些按規(guī)定使用。默認(rèn)空數(shù)組。
  • array $attributes 可選。通知的 HTML 屬性的關(guān)聯(lián)數(shù)組。布爾true屬性可能只包括屬性的名稱。默認(rèn)空數(shù)組。
  • array $paragraph_wrap 可選。是否將消息包裝在<p></p>標(biāo)簽中。默認(rèn)為true。

過(guò)濾器

wp_get_admin_notice()應(yīng)用以下過(guò)濾器：

• wp_admin_notice_args– 過(guò)濾管理員通知的參數(shù)。
  • 傳遞的參數(shù)：array $args,string $message
• wp_admin_notice_markup– 過(guò)濾管理員通知的標(biāo)記。
  • 傳遞的參數(shù)：string $markup, string $message,array $args

動(dòng)作鉤子

wp_admin_notice()觸發(fā)以下操作：

• wp_admin_notice– 在輸出管理通知之前觸發(fā)。
  • 傳遞的參數(shù)：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' )
  )
);

結(jié)果

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

創(chuàng)建要立即輸出的通知集合?

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

結(jié)果

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

（每個(gè)通知都重復(fù)）

為每個(gè)“警告”管理通知添加一個(gè)類

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;
}

結(jié)果

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

（對(duì)每個(gè)警告通知重復(fù)）

WordPress 核心中的用法

新的管理通知功能已在 WordPress Core 的大多數(shù)位置實(shí)現(xiàn)。進(jìn)一步的工作將在 WordPress 6.5 中完成，以完成該過(guò)程并將舊通知（使用 'updated'和'error'類）遷移到當(dāng)前的管理通知模式（'notice-success'、'notice-info'、'notice-warning'和'notice-error'）。