如何为 WordPress 主题和插件添加管理通知(Admin Notices)

风景旧曾谙,阳春三月归;烟云十年后,又见江南花。夜晚的这一刻,我独赏风景。有很多人觉得,一个人旅行好无聊。可我却偏偏喜欢一个人。

当你在 WordPress 管理后台界面时,你会遇到一些“管理通知(Admin Notices)”,让你知道错误、更新设置、请求操作等等。大多数默认的管理通知都是由 WordPress 添加的,但如果你是主题或插件开发者,你可能也需要添加一些自定义的管理通知。文本将深入讲解 WordPress 的管理通知,解释它是如何实行、定制 等。

四种类型的管理通知

  1. 成功 - 当遇到好事,比如设置成功更新显示
  2. 错误 - 当出现错误或未知情况显示
  3. 警告 - 当要警示用户时显示
  4. 信息 - 将一般信息传达给用户

可能大家都很熟悉了这些通知,它们为在后台进行操作的用户提供反馈。下来我们主要讲解如何在插件和主题添加 WordPress 管理通知。

底层机制

这些不同类型的管理通知的源代码基本上是相同的。唯一的区别是类名和消息。例如,这里是展示一个典型的“成功”的通知时,由WordPress默认生成的html标记:

1
2
3
4
5
6
<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>

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

其他通知也是类似的结构,但可能包含一些不通的类名,比如 settings-error,这是WordPress 自动在“设置”页面显示的管理通知所用的类名。一些管理页面也许还会在管理通知中包含一个 id 属性。例如,在“设置”页面显示的管理通知就有下面的id:

1
id="setting-error-settings_updated"

id="setting-error-settings_updated"

幸运的是,我们并不需要担心这些 id 属性和额外的类,WordPress 会自动添加到管理通知。当添加自己的自定义管理通知,只需要标记的最小量:

1
2
3
<div class="notice notice-success is-dismissible"> 
	<p><strong>Settings saved.</strong></p>
</div>

<div class="notice notice-success is-dismissible"> <p><strong>Settings saved.</strong></p> </div>

使用这个基本的结构,我们可以通过简单地改变类名和消息本身创建任何类型的管理通知。其他一切保持不变和/或由WordPress自动处理。

dismissed 类

在上一节中提供的示例代码中,注意有一个类 is-dismissible 添加到了<div>元素中。这个类是什么使管理通知“可取消”,使用户可以点击一个小“X”按钮来删除该消息。这有助于简化工作效率,节省时间。当管理员通知不可取消,删除它的唯一方法就是重新访问该网页。

当包含了 is-dismissible 类,WordPress 会自动添加“X”按钮。之前的代码添加了 is-dismissible 类:

1
2
3
<div class="notice notice-success is-dismissible"> 
	<p><strong>Settings saved.</strong></p>
</div>

<div class="notice notice-success is-dismissible"> <p><strong>Settings saved.</strong></p> </div>

输出就变为了:

1
2
3
4
5
6
<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>

<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 代码,访问 常规设置 页面,点击“保存设置”按钮,并使用浏览器(例如 Chrome 或 Firefox)检查通知部分即可。

通知类型

正如上文配图所示,有四种类型的通知:

  • notice-error – 错误信息使用红框
  • notice-warning – 警告信息使用黄框
  • notice-success – 成功信息使用绿框
  • notice-info – 一般信息使用蓝框

以下为基本的代码样例:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
<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>

<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 的类,虽然还可以生效,但是不建议使用,因为它们已被弃用。

添加默认的管理通知

如果页面添加到 设置 菜单,WordPress 会自动显示“错误”和“更新”信息。所以假如你的设置页面是添加到 设置菜单 下的,WordPress 会默认自动处理这些管理通知。例如,下图中的 Dashboard Widgets Suite 的菜单就在 设置菜单下,所以 WordPress 会处理插件的 默认管理通知。

至于添加到其他位置的设置页面,默认管理通知是不会自动显示的。如果你的插件或主题的设置页面是显示在自己的菜单下的,或在任何其他设置界面的子菜单中,WordPress 不会自动显示默认管理通知。在这些情况下,你需要调用 settings_errors() 来显示默认“错误”和“更新新”信息,有两种方法可以实现。

方法1

最快捷的方法是直接在你的设置页面的代码中添加 settings_errors(),例如:

1
2
3
4
5
6
7
8
9
10
11
12
13
<div class="wrap">
	<h1>My Plugin Title</h1>

	<?php settings_errors(); ?>

	<form method="post" action="options.php">

		.
		.
		.

	</form>
</div>

<div class="wrap"> <h1>My Plugin Title</h1> <?php settings_errors(); ?> <form method="post" action="options.php"> . . . </form> </div>

就这样,WordPress 将在设置被成功更新时或出错时显示默认的管理通知。

方法2

一个功能更简洁的方法是通过 admin_notices 钩子添加 settings_errors() ,例如:

1
2
3
4
5
6
7
// display default admin notice
function shapeSpace_add_settings_errors() {

    settings_errors();

}
add_action('admin_notices', 'shapeSpace_add_settings_errors');

// display default admin notice function shapeSpace_add_settings_errors() { settings_errors(); } add_action('admin_notices', 'shapeSpace_add_settings_errors');

这样做的效果和方法1一样,但是我们更推荐这个方法,因为它更灵活和可拓展。

添加自定义管理通知

到这里为止,我们已经知道了默认管理通知是如何实现的,如果我们要添加自定义管理通知,又该如何?这就是我们下来要讲解的。正如 WordPress 几乎每样功能都有多种方式实现一样,添加自定义管理通知也是有多种方法的。

要添加自定义管理通知,你可以使用 admin_notices 钩子或 add_settings_error() 函数。一起看下这两种方法。

方法1:admin_notices 钩子

显示自定义管理通知的最直接的方法就是创建一个函数,然后挂载到 admin_notices 钩子,例如:

1
2
3
4
5
6
7
8
9
// 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');

// 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),以及用作函数名的前缀。函数本身输出我们的自定义管理通知,然后挂载到 admin_notices 钩子来通过 WordPress 显示。请记住,我们可以使用各种css类来更改显示效果(例如:notice-error, notice-warning, notice-successnotice-info

实例

这个添加通知的方法是非常灵活的,让你可以在任何时间、任何地点显示自定义信息。例如,我的 bad bots 插件提供了一个选项,让用户可以恢复插件的默认设置。当用户点击“恢复设置”按钮,会发生如下情况:

  1. 提交了设置表单
  2. 一个函数尝试恢复默认设置
  3. 如果设置恢复成功,reset-options=true 会通过 GET 参数进行传递
  4. 或者,如果恢复不成功, reset-options=false 会通过 GET 参数进行传递
  5. 下面的函数将检查 reset-options 的值,然后显示正确的管理通知
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
// 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');

// 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');

该函数会检查当前界面和 GET 的参数,然后判断默认的设置是否被成功恢复来显示对应的管理通知。这个例子很好地展示了通过 admin_notices 钩子来显示任意自定义管理通知给用户的功能。

方法2:add_settings_error() 函数

另一种规范显示自定义管理通知的方法是使用 add_settings_error() 函数,可以直接在你的设置验证函数中使用。例如,假设我们的插件注册了下面的设置:

1
2
// register_setting( $option_group, $option_name, $sanitize_callback );
register_setting('my_option_group', 'my_option_group', 'my_option_group_validate');

// register_setting( $option_group, $option_name, $sanitize_callback ); register_setting('my_option_group', 'my_option_group', 'my_option_group_validate');

这个设置调用了 my_option_group_validate 作为 $sanitize_callback 的参数,假设 my_option_group_validate 是这样的:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
// 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;

}

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

该函数会检查/消毒所有 my_option_group 设置的表单输入。这是一个标准规范:注册一个带有验证回调函数的设置是很多 WordPress 插件所使用的。

回到代码上来,假设我们要根据一个具体的设置是否满足某些标准,从而显示对应的自定义管理通知。不同于一般的“设置已保存”这个通知,我们要针对某个具体的设置来显示一个通知。这就到了 add_settings_error() 一展身手的时候了,我们可以在验证函数中添加 add_settings_error() 来显示自定义错误通知,例如:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
// 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;

}

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

我们已经在原有的验证函数中添加了条件代码,这些代码会跟踪 $message$type 变量,可用于 add_settings_error() 根据 my_option 所发生的情况来显示自定义管理通知。这个技术是非常有用的,便于我们控制不同的设置所出现的错误,来显示不同的信息给用户。非常棒的一点是,这个方法不需要任何钩子来实现。仅仅在验证回调中包含 add_settings_error(),WordPress 就可以显示对应的通知。

方法3:快速添加

虽然上面的两种方法都是最好的,但是它们不可能在任何情况下都可行或有效。所以这里有第3种方法可以在任何地方快速添加自定义管理通知。方法如下:

1
2
3
<?php if (isset($_GET['settings-updated'])) : ?>
	<div class="notice notice-success is-dismissible"><p><?php _e('Something happened!'); ?>.</p></div>
<?php endif; ?>

<?php if (isset($_GET['settings-updated'])) : ?> <div class="notice notice-success is-dismissible"><p><?php _e('Something happened!'); ?>.</p></div> <?php endif; ?>

以上代码会抓取全局 $_GET 变量,检查是否设置了 settings-updated,然后显示预设的管理通知。

这个方法生效的关键,在于检测相应的变量和包含的类来显示所需的通知。

总结

本文试图涵盖所有可能的情况下添加管理员通知。如有缺失,请发表评论告知。

参考

  • 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大学 原创翻译(标题有改动)。

以上就是如何为 WordPress 主题和插件添加管理通知(Admin Notices)。不经历磨难,怎能见彩虹遇到困难不能够退缩,否则你就还没上战场就输给了自己。要具备不屈服的精神,在困难面前永不低头!更多关于如何为 WordPress 主题和插件添加管理通知(Admin Notices)请关注haodaima.com其它相关文章!

您可能有感兴趣的文章
WordPress站点Gravatar头像前后台不显示的如何解决办法

WordPress做公司官网好吗?会不会显得档次很低?

WordPress主题需要支持https吗?WordPress站点如何如何实现https?

WordPress站点的页面/标签/分类URL地址如何添加.html?

WordPress站点更换了域名后数据库应该如何操作替换新旧域名?