README

一个用于 WordPress 插件的 PHP 实用库，帮助创建管理员通知。

亮点

流畅的接口。
持久性可 dismiss 的通知，可选的 dismiss 时间。
在特定页面上显示通知。
向具有特定能力的用户显示通知。

要求

PHP 5.3 或更高版本。
WordPress 4.2 或更高版本。

安装

使用 Composer 安装

composer require "yahnis-elsts/admin-notices"

或者，您可以手动安装

下载最新版本。
将 admin-notices 目录移动到您的插件中。

加载库

require '/path/to/admin-notices/AdminNotice.php';

关于加载顺序的说明：为了确保持久性可 dismiss 的通知可以正确工作，您应该在 admin_init 动作之前 require 库。例如，您可以在 plugins_loaded 钩子中放置 require，或者简单地将其放在插件顶部。

用法

基本示例

use \YeEasyAdminNotices\V1\AdminNotice;

AdminNotice::create()
	->success('Hello world!')
	->show();

结果

您不需要将此代码放入钩子中。`show()` 方法很智能。它会检查 `admin_notices` 动作是否已执行，并立即显示通知或添加一个将在适当时候显示通知的新 `admin_notices` 钩子。它还会在实际显示通知之前检查任何能力要求和页面过滤器（见前提条件）。

类型快捷键

WordPress 内置了几个用于不同类型管理员通知的 CSS 类。您可以使用以下快捷方法同时设置通知类型和内容。

`success([$message])`

AdminNotice::create()->success('Success')->show();

`error([$message])`

AdminNotice::create()->error('Error')->show();

`warning([$message])`

AdminNotice::create()->warning('Warning')->show();

`info([$message])`

AdminNotice::create()->info('Information')->show();

内容

您可以选择不将字符串传递给特定类型的任何方法，而是通过调用以下方法之一来设置通知内容。

`text($message)`

将通知内容设置为文本字符串。`text()` 会转义 HTML 特殊字符，如 `<`, `>`, `&` 等。

示例

AdminNotice::create()
	->info()
	->text('<script>/* This will be displayed as plain text. */</script>')
	->show();

`html($arbitraryHtml)`

将通知内容设置为 HTML 字符串。与 `text()` 不同，此方法不会执行任何转义或编码。

AdminNotice::create()
	->info()
	->html('Tip: Go to <a href="#">Settings -&gt; My Plugin</a> to configure the plugin.')
	->show();

`rawHtml($arbitraryHtml)`

通常，通知内容被包裹在一个单个的段落 (`<p>`) 标签中。要防止这种包装，使用 `rawHtml()` 来设置通知内容。这非常有用，如果您想使用复杂的 HTML 或显示一条长消息，其中一段内容不足以显示。

AdminNotice::create()
	->rawHtml('<p>First paragraph</p><p>Second paragraph</p>')
	->show();

可 dismiss 的通知

`dismissible()`

向通知添加 "(x)" 图标。点击图标将隐藏通知。但是，这不会防止通知在未来重新出现。使用 `persistentlyDismissible()` 来实现这一点。

AdminNotice::create()
	->text('You can hide this notice by clicking the "(x)" =>')
	->dismissible()
	->show();

`persistentlyDismissible([$scope, $duration])`

使通知持久性可 dismiss。当用户 dismiss 通知时，库会在数据库中存储一个标志，防止通知再次显示。持久性可 dismiss 的通知必须具有唯一 ID。

参数$scope控制点击"(x)"后是否隐藏通知对所有用户或仅对当前用户。支持的值包括

AdminNotice::DISMISS_PER_SITE - 在整个网站上隐藏通知。这是默认值。
AdminNotice::DISMISS_PER_USER - 仅隐藏当前用户的通知。

示例

AdminNotice::create('my-notice-id')
	->persistentlyDismissible(AdminNotice::DISMISS_PER_SITE)
	->success('This notice can be permanently dismissed.')
	->show();

参数$duration控制通知被认为是已忽略的时间长度（以秒为单位）。默认情况下，通知将被永久忽略。

示例

AdminNotice::create('my-notice-id')
	->persistentlyDismissible(AdminNotice::DISMISS_PER_SITE, WEEK_IN_SECONDS)
	->success('This notice can be dismissed for 1 week.')
	->show();

注意

您必须在admin_init动作之前加载AdminNotice.php，以确保默认的AJAX处理程序被正确设置。
在忽略的通知上调用show()是安全的。它不会显示通知，也不会抛出错误。

`dismiss([$duration])`

永久忽略通知。仅适用于已标记为persistentlyDismissible()的通知。

参数$duration控制通知被认为是已忽略的时间长度（以秒为单位）。默认情况下，持续时间与传递给persistentlyDismissible()的持续时间相同。您还可以传递AdminNotice::DISMISS_PERMANENTLY来永久忽略通知。

`undismiss()`

恢复之前已忽略的通知。

`isDismissed() : 布尔值`

检查通知是否已被忽略。

`AdminNotice::cleanUpDatabase($prefix)`

从数据库中删除具有指定ID前缀的所有"此通知已忽略"标志。如果您正在使用可永久忽略的通知，当您的插件被卸载时，调用此函数是一个好主意。

例如，如果您的通知ID以myplugin-开头，您可以按如下方式删除数据库条目

AdminNotice::cleanUpDatabase('myplugin-');

先决条件

这些方法控制通知将出现在哪里以及谁将能看到它们。

`onPage($screenId)`

仅在指定的管理页面上显示通知。$screenId可以是页面的屏幕ID（即字符串），或屏幕ID的数组。

查看管理屏幕参考，以获取屏幕及其ID的列表。在插件和主题管理页面的情况下，屏幕ID通常与add_*_page()函数返回的值相同。

示例

AdminNotice::create()
	->info()
	->text('This message will only appear on the "Plugins -> Installed Plugins" page')
	->onPage('plugins')
	->show();
	
add_action('admin_menu', function() {
	$id = add_options_page(
		'Example',
		'Example',
		'manage_options',
		'example-admin-page',
		'__return_false'
	);

	AdminNotice::create()
		->info()
		->text('This will appear on "Settings -> Example"')
		->onPage($id)
		->show();
});

`requiredCap($capability)`

仅向具有指定$capability的用户显示通知。

显示现在或稍后

创建通知后，调用这些方法之一以显示它。

`show()`

当所有先决条件都满足时，自动在当前页面上显示通知。

`showOnNextPage()`

在当前用户访问的下一条管理页面上显示通知。通知只会显示一次。

此方法在无法立即显示通知的任何原因时很有用，例如插件激活钩子、重定向和其他情况。库将通知存储在数据库中。它将在下次在当前用户上下文中调用admin_notices动作时显示通知，无论发生在此页面加载期间还是之后的某个时间，甚至是一周之后。

`outputNotice()`

立即显示通知。此方法绕过任何检查和先决条件，直接输出通知。这主要用于调试。

yahnis-elsts / admin-notices

维护者

详细信息