yahnis-elsts / admin-notices
WordPress 插件的一个实用库,可以更轻松地创建管理员通知。支持持久性可 dismiss 的通知。
Requires
- php: >=5.3.0
This package is auto-updated.
Last update: 2024-09-07 09:28:47 UTC
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 -> 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()
立即显示通知。此方法绕过任何检查和先决条件,直接输出通知。这主要用于调试。