當(dāng)你在 WordPress 管理后臺界面時，你會遇到一些“管理通知（Admin Notices）”，讓你知道錯誤、更新設(shè)置、請求操作等等。大多數(shù)默認(rèn)的管理通知都是由 WordPress 添加的，但如果你是主題或插件開發(fā)者，你可能也需要添加一些自定義的管理通知。文本將深入講解 WordPress 的管理通知，解釋它是如何實行、定制 等。
四種類型的管理通知
- 成功 – 當(dāng)遇到好事，比如設(shè)置成功更新顯示
- 錯誤 – 當(dāng)出現(xiàn)錯誤或未知情況顯示
- 警告 – 當(dāng)要警示用戶時顯示
- 信息 – 將一般信息傳達給用戶
可能大家都很熟悉了這些通知，它們?yōu)樵诤笈_進行操作的用戶提供反饋。下來我們主要講解如何在插件和主題添加 WordPress 管理通知。
底層機制
這些不同類型的管理通知的源代碼基本上是相同的。唯一的區(qū)別是類名和消息。例如，這里是展示一個典型的“成功”的通知時，由WordPress默認(rèn)生成的html標(biāo)記：
<div class="notice notice-success is-dismissible">
<p><strong>Settings saved.</strong></p>
<button type="button" class="notice-dismiss">
<span class="screen-reader-text">Dismiss this notice.</span>
</button>
</div>
其他通知也是類似的結(jié)構(gòu)，但可能包含一些不通的類名，比如 settings-error，這是WordPress 自動在“設(shè)置”頁面顯示的管理通知所用的類名。一些管理頁面也許還會在管理通知中包含一個 id 屬性。例如，在“設(shè)置”頁面顯示的管理通知就有下面的id：
id="setting-error-settings_updated"
幸運的是，我們并不需要擔(dān)心這些 id 屬性和額外的類，WordPress 會自動添加到管理通知。當(dāng)添加自己的自定義管理通知，只需要標(biāo)記的最小量：
<div class="notice notice-success is-dismissible">
<p><strong>Settings saved.</strong></p>
</div>
使用這個基本的結(jié)構(gòu)，我們可以通過簡單地改變類名和消息本身創(chuàng)建任何類型的管理通知。其他一切保持不變和/或由WordPress自動處理。
dismissed 類
在上一節(jié)中提供的示例代碼中，注意有一個類 is-dismissible 添加到了<div>元素中。這個類是什么使管理通知“可取消”，使用戶可以點擊一個小“X”按鈕來刪除該消息。這有助于簡化工作效率，節(jié)省時間。當(dāng)管理員通知不可取消，刪除它的唯一方法就是重新訪問該網(wǎng)頁。
當(dāng)包含了 is-dismissible 類，WordPress 會自動添加“X”按鈕。之前的代碼添加了 is-dismissible 類：
<div class="notice notice-success is-dismissible">
<p><strong>Settings saved.</strong></p>
</div>
輸出就變?yōu)榱耍?/p>
<div class="notice notice-success is-dismissible">
<p><strong>Settings saved.</strong></p>
<button type="button" class="notice-dismiss">
<span class="screen-reader-text">Dismiss this notice.</span>
</button>
</div>
注意下，WordPress 還提供了所需的 CSS 和 JS 讓它生效。要查看 CSS 和 JS 代碼，訪問 常規(guī)設(shè)置 頁面，點擊“保存設(shè)置”按鈕，并使用瀏覽器（例如 Chrome 或 Firefox）檢查通知部分即可。
通知類型
正如上文配圖所示，有四種類型的通知：
notice-error– 錯誤信息使用紅框notice-warning– 警告信息使用黃框notice-success– 成功信息使用綠框notice-info– 一般信息使用藍(lán)框
以下為基本的代碼樣例：
<div class="notice notice-error is-dismissible">
<p>出錯了。</p>
</div>
<div class="notice notice-warning is-dismissible">
<p>這是一個警告信息。</p>
</div>
<div class="notice notice-success is-dismissible">
<p>這是一個成功信息。</p>
</div>
<div class="notice notice-info is-dismissible">
<p>這是一般信息。</p>
</div>
在你使用 WordPress 的過程中，可能會遇到不同于上面四種的類，比如：
updated– 用綠框顯示信息error– 用紅框顯示信息update-nag– 用黃框顯示信息
這些是舊版本的 WordPress 的類，雖然還可以生效，但是不建議使用，因為它們已被棄用。
添加默認(rèn)的管理通知
如果頁面添加到 設(shè)置 菜單，WordPress 會自動顯示“錯誤”和“更新”信息。所以假如你的設(shè)置頁面是添加到 設(shè)置菜單 下的，WordPress 會默認(rèn)自動處理這些管理通知。例如，下圖中的 Dashboard Widgets Suite 的菜單就在 設(shè)置菜單下，所以 WordPress 會處理插件的 默認(rèn)管理通知。
至于添加到其他位置的設(shè)置頁面，默認(rèn)管理通知是不會自動顯示的。如果你的插件或主題的設(shè)置頁面是顯示在自己的菜單下的，或在任何其他設(shè)置界面的子菜單中，WordPress 不會自動顯示默認(rèn)管理通知。在這些情況下，你需要調(diào)用 settings_errors() 來顯示默認(rèn)“錯誤”和“更新新”信息，有兩種方法可以實現(xiàn)。
方法1
最快捷的方法是直接在你的設(shè)置頁面的代碼中添加 settings_errors()，例如：
<div class="wrap">
<h1>My Plugin Title</h1>
<?php settings_errors(); ?>
<form method="post" action="options.php">
.
.
.
</form>
</div>
就這樣，WordPress 將在設(shè)置被成功更新時或出錯時顯示默認(rèn)的管理通知。
方法2
一個功能更簡潔的方法是通過 admin_notices 鉤子添加 settings_errors() ，例如：
// display default admin notice
function shapeSpace_add_settings_errors() {
settings_errors();
}
add_action('admin_notices', 'shapeSpace_add_settings_errors');
這樣做的效果和方法1一樣，但是我們更推薦這個方法，因為它更靈活和可拓展。
添加自定義管理通知
到這里為止，我們已經(jīng)知道了默認(rèn)管理通知是如何實現(xiàn)的，如果我們要添加自定義管理通知，又該如何？這就是我們下來要講解的。正如 WordPress 幾乎每樣功能都有多種方式實現(xiàn)一樣，添加自定義管理通知也是有多種方法的。
要添加自定義管理通知，你可以使用 admin_notices 鉤子或 add_settings_error() 函數(shù)。一起看下這兩種方法。
方法1：admin_notices 鉤子
顯示自定義管理通知的最直接的方法就是創(chuàng)建一個函數(shù)，然后掛載到 admin_notices 鉤子，例如：
// display custom admin notice
function shapeSpace_custom_admin_notice() { ?>
<div class="notice notice-success is-dismissible">
<p><?php _e('Congratulations, you did it!', 'shapeSpace'); ?></p>
</div>
<?php }
add_action('admin_notices', 'shapeSpace_custom_admin_notice');
代碼中的“shapeSpace”是我示例插件或主題中的名字，所以我們用它作為 _e() 的文本域（text-domain），以及用作函數(shù)名的前綴。函數(shù)本身輸出我們的自定義管理通知，然后掛載到 admin_notices 鉤子來通過 WordPress 顯示。請記住，我們可以使用各種css類來更改顯示效果（例如：notice-error, notice-warning, notice-success 或 notice-info）
實例
這個添加通知的方法是非常靈活的，讓你可以在任何時間、任何地點顯示自定義信息。例如，我的 bad bots 插件提供了一個選項，讓用戶可以恢復(fù)插件的默認(rèn)設(shè)置。當(dāng)用戶點擊“恢復(fù)設(shè)置”按鈕，會發(fā)生如下情況：
- 提交了設(shè)置表單
- 一個函數(shù)嘗試恢復(fù)默認(rèn)設(shè)置
- 如果設(shè)置恢復(fù)成功，reset-options=true 會通過 GET 參數(shù)進行傳遞
- 或者，如果恢復(fù)不成功， reset-options=false 會通過 GET 參數(shù)進行傳遞
- 下面的函數(shù)將檢查 reset-options 的值，然后顯示正確的管理通知
// display custom admin notice
function blackhole_tools_admin_notice() {
$screen = get_current_screen();
if ($screen->id === 'toplevel_page_blackhole_settings') {
if (isset($_GET['reset-options'])) {
if ($_GET['reset-options'] === 'true') : ?>
<div class="notice notice-success is-dismissible">
<p><?php _e('Default settings restored.', 'bbb'); ?></p>
</div>
<?php else : ?>
<div class="notice notice-error is-dismissible">
<p><?php _e('No changes made.', 'bbb'); ?></p>
</div>
<?php endif;
}
}
}
add_action('admin_notices', 'blackhole_tools_admin_notice');
該函數(shù)會檢查當(dāng)前界面和 GET 的參數(shù)，然后判斷默認(rèn)的設(shè)置是否被成功恢復(fù)來顯示對應(yīng)的管理通知。這個例子很好地展示了通過 admin_notices 鉤子來顯示任意自定義管理通知給用戶的功能。
方法2：add_settings_error() 函數(shù)
另一種規(guī)范顯示自定義管理通知的方法是使用 add_settings_error() 函數(shù)，可以直接在你的設(shè)置驗證函數(shù)中使用。例如，假設(shè)我們的插件注冊了下面的設(shè)置：
// register_setting( $option_group, $option_name, $sanitize_callback );
register_setting('my_option_group', 'my_option_group', 'my_option_group_validate');
這個設(shè)置調(diào)用了 my_option_group_validate 作為 $sanitize_callback 的參數(shù)，假設(shè) my_option_group_validate 是這樣的：
// my $sanitize_callback function
function my_option_group_validate($input) {
if (null != $input) {
if (false === get_option('my_option')) {
add_option('my_option', $input);
} else {
update_option('my_option', $input);
}
}
return $input;
}
該函數(shù)會檢查/消毒所有 my_option_group 設(shè)置的表單輸入。這是一個標(biāo)準(zhǔn)規(guī)范：注冊一個帶有驗證回調(diào)函數(shù)的設(shè)置是很多 WordPress 插件所使用的。
回到代碼上來，假設(shè)我們要根據(jù)一個具體的設(shè)置是否滿足某些標(biāo)準(zhǔn)，從而顯示對應(yīng)的自定義管理通知。不同于一般的“設(shè)置已保存”這個通知，我們要針對某個具體的設(shè)置來顯示一個通知。這就到了 add_settings_error() 一展身手的時候了，我們可以在驗證函數(shù)中添加 add_settings_error() 來顯示自定義錯誤通知，例如：
// my $sanitize_callback function
function my_option_group_validate($input) {
message = null;
$type = null;
if (null != $input) {
if (false === get_option('my_option')) {
add_option('my_option', $input);
$message = __('Option added! Congrats man.');
$type = 'updated';
} else {
update_option('my_option', $input);
$message = __('Option updated! Miller time.');
$type = 'updated';
}
} else {
$message = __('Oh noes! There was a problem.');
$type = 'error';
}
// add_settings_error( $setting, $code, $message, $type )
add_settings_error('my_option_notice', 'my_option_notice', $message, $type);
return $input;
}
我們已經(jīng)在原有的驗證函數(shù)中添加了條件代碼，這些代碼會跟蹤 $message 和 $type 變量，可用于 add_settings_error() 根據(jù) my_option 所發(fā)生的情況來顯示自定義管理通知。這個技術(shù)是非常有用的，便于我們控制不同的設(shè)置所出現(xiàn)的錯誤，來顯示不同的信息給用戶。非常棒的一點是，這個方法不需要任何鉤子來實現(xiàn)。僅僅在驗證回調(diào)中包含 add_settings_error()，WordPress 就可以顯示對應(yīng)的通知。
方法3：快速添加
雖然上面的兩種方法都是最好的，但是它們不可能在任何情況下都可行或有效。所以這里有第3種方法可以在任何地方快速添加自定義管理通知。方法如下：
<?php if (isset($_GET['settings-updated'])) : ?>
<div class="notice notice-success is-dismissible"><p><?php _e('Something happened!'); ?>.</p></div>
<?php endif; ?>
以上代碼會抓取全局 $_GET 變量，檢查是否設(shè)置了 settings-updated，然后顯示預(yù)設(shè)的管理通知。
這個方法生效的關(guān)鍵，在于檢測相應(yīng)的變量和包含的類來顯示所需的通知。
總結(jié)
本文試圖涵蓋所有可能的情況下添加管理員通知。如有缺失，請發(fā)表評論告知。
參考
- WP Codex: admin_notices
- WP Codex: settings_errors()
- WP Codex: add_settings_error()
- WP Codex: register_setting()
- WP Codex: Settings API
原文出自：https://digwp.com/2016/05/wordpress-admin-notices/，由 倡萌@WordPress大學(xué) 原創(chuàng)翻譯（標(biāo)題有改動）。
