yahnis-elsts/admin-notices

WordPress 插件的一个实用库,可以更轻松地创建管理员通知。支持持久性可 dismiss 的通知。

v1.1 2019-02-06 10:22 UTC

This package is auto-updated.

Last update: 2024-09-07 09:28:47 UTC


README

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

亮点

要求

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

安装

使用 Composer 安装

composer require "yahnis-elsts/admin-notices"

或者,您可以手动安装

  1. 下载 最新版本
  2. admin-notices 目录移动到您的插件中。
  3. 加载库
    require '/path/to/admin-notices/AdminNotice.php';

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

用法

基本示例

use \YeEasyAdminNotices\V1\AdminNotice;

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

结果

Basic admin notice

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

类型快捷键

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

success([$message])
AdminNotice::create()->success('Success')->show();

Success notice

error([$message])
AdminNotice::create()->error('Error')->show(); 

Error notice

warning([$message])
AdminNotice::create()->warning('Warning')->show();

Warning notice

info([$message])
AdminNotice::create()->info('Information')->show();

Informational notice

内容

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

text($message)

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

示例

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

Text escaping

html($arbitraryHtml)

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

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

HTML content

rawHtml($arbitraryHtml)

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

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

Raw HTML content

可 dismiss 的通知

dismissible()

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

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

Dismissible notice (not persistent)

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();

Persistently dismissible notice

参数$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()

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