README

此库在 WordPress 管理通知周围暴露了一个面向对象的接口。

为什么这很有用？

通常，WordPress 插件必须手动构建管理通知

function myplugin_render_my_notice() {
    echo '<div class="notice notice-info"><p>';
    esc_html_e('This is the message body.', 'some-plugin');
    echo '</p></div>';
}

add_action('admin_notices', 'myplugin_render_my_notice');

不幸的是，如果您想有条件地添加类（例如 .inline、.notice-alt 等）或检查用户能力，这会变得非常混乱。此外，WordPress 没有提供一种一致的方式来跟踪某个特定通知是否已被忽略，迫使每个插件都提出自己的解决方案。

此库旨在解决这个问题，为您在插件中构建和渲染管理通知提供了一个流畅的 API

use StellarWP\AdminNotice\AdminNotice;

$notice = AdminNotice::factory(__('This is the message body.', 'some-plugin'), 'info')
    ->setCapability('manage_options')
    ->setDismissible(true)
    ->queue();

只需几行代码，您就拥有了一个可取消的、信息级别的通知，它将自动在 "admin_notices" 上显示，但只有当前用户具有 "manage_options" 能力时才会显示！

安装

强烈建议您通过 Composer 将此库作为项目依赖项安装

$ composer require stellarwp/admin-notice

为了防止您的代码与其他可能实现此库的插件或主题发生冲突，强烈建议您利用 PHP 自动加载，并且不要使用 include_once 或 require_once 来包含这些文件！

用法

AdminNotice 类的最基本版本如下

use StellarWP\AdminNotice\AdminNotice;

$notice = new AdminNotice('Hello, world!');

💡 为了更方便地流畅地构建通知，您还可以使用静态 AdminNotice::factory() 方法，该方法接受与 new AdminNotice() 相同的参数。

此 $notice 对象代表一个信息级别的通知，其标记将类似于以下内容

<div class="notice notice-info stellarwp-admin-notice">
    <p>Hello, world!</p>
</div>

获取此通知的标记有两种方式

$notice->render()：此方法返回标记作为字符串。
$notice->display()：此方法将标记打印到屏幕上，实际上是 echo $notice->render(); 的别名。

💡 AdminNotice 类实现了 __toString() 魔法方法，因此您也可以编写类似 echo $notice 的内容。

管理通知级别

WordPress 支持四个级别的管理通知

success（绿色方案）
warning（黄色方案）
error（红色方案）
info（蓝色方案）

为了您的方便，以下常量在 AdminNotice 类中可用，可传递给类构造函数的第二个参数

AdminNotice::TYPE_SUCCESS
AdminNotice::TYPE_WARNING
AdminNotice::TYPE_ERROR
AdminNotice::TYPE_INFO

use StellarWP\AdminNotice\AdminNotice;

# Create a success message.
AdminNotice::factory('Operation completed sucessfully!', AdminNotice::TYPE_SUCCESS);

# Create a warning message.
AdminNotice::factory('One or more settings are missing, falling back to defaults.', AdminNotice::TYPE_WARNING);

# Create an error message.
AdminNotice::factory('You do not have permission to perform this action.', AdminNotice::TYPE_ERROR);

# Create an info message (second argument optional)
AdminNotice::factory('This is for your information:', AdminNotice::TYPE_INFO);

渲染管理通知

现在，我们需要一种方法来渲染通知，通常在 "admin_notices" 动作期间。

管理通知可以通过几种不同的方式排队

显式调用 add_action() 并将通知的 display() 方法作为回调
```
add_action('admin_notices, [$notice, 'display']);
```

在通知本身上调用queue()方法

AdminNotice::factory('Some message', 'info')->queue();

编写自己的处理程序，可能与通知实例一起工作。

记住已删除的通知

通常，记住用户是否已删除特定通知可能会有所帮助。因此，AdminNotice::setDismissible()接受两个参数

通知是否可以被删除。
用于跟踪删除的可选键。

如果渲染了带有键的可删除管理员通知，AdminNotice将自动排队JavaScript以在删除此类通知时触发AJAX请求：一旦用户删除通知，键和时间戳就会存储在他们的用户元中。

AdminNotice自己无法做的唯一一件事是排队AJAX处理程序。相反，在插件设置过程（你选择注册钩子的地方）中，需要调用StellarWP\AdminNotice\DismissalHandler::listen() 某处。

示例

此示例将显示带有键“some-unique-key”的通知，直到用户将其删除。

use StellarWP\AdminNotice\AdminNotice;
use StellarWP\AdminNotice\DismissalHandler;

// Somewhere in your code, make sure you're listening for the AJAX event.
DismissalHandler::listen();

// Create the dismissible admin notice.
AdminNotice::factory('This notice may be dismissed')
    ->setDismissible(true, 'some-unique-key')
    ->queue();

检查用户权限

通常，管理员通知只针对一小部分用户。例如，如果只有管理员级别的用户可以安装插件，就没有必要告诉所有用户有关您插件的新、高级扩展。

因此，AdminNotice类允许将通知包裹在一个current_user_can()检查中。

# Only show this notice if `current_user_can('install_plugins')` returns true.
AdminNotice::factory('Hey there, you should install this plugin', 'info')
    ->setCapability('install_plugins');

完整的AdminNotice API

这些都是可用于构建管理员通知的方法

`__construct(string $message[, string $type = 'info'])`

构造一个新的AdminNotice实例。

参数

string $message: 管理员通知的主体。; 这可能包含HTML，并且在渲染之前将通过wpautop()和wp_kses_post()运行。
string $type: 可选。通知的类型，可以是“success”、“error”、“warning”或“info”。默认为“info”。

另请参阅：AdminNotice::factory()

`dismissedByUser(?int $user = null): bool`

检查该通知是否已被指定用户删除。如果用户之前已删除此通知，则返回true，否则返回false。

参数

?int $user: 可选。用户ID。默认为null（当前用户）。

`dismissedByUserAt(?int $user = null): DateTimeImmutable`

检索一个表示指定用户[最后]删除此通知的DateTime对象。

此方法将返回表示通知被删除的DateTimeImmutable对象，或者如果用户未删除此通知，则返回NULL。

参数

?int $user: 可选。用户ID。默认为null（当前用户）。

`dismissForUser(?int $user = null): self`

将可删除通知标记为指定用户已删除。

此行为与静态dismissNoticeForUser()方法相同，但不需要提供通知键（并且如果没有键，则不会尝试删除）。

参数

?int $user: 可选。用户ID。默认为null（当前用户）。

`display(): void`

渲染并打印管理员通知。

`queue([int $priority = 10]): self`

将此管理员通知排队以在“admin_notices”上显示。

参数

int $priority: 可选。与add_action()一起使用的优先级。默认为10。

`render(): string`

渲染管理员通知。

此方法负责所有关于通知标记构建的逻辑，包括是否应该显示任何内容（基于例如能力检查和/或取消通知历史记录）。

`setAlt(bool $alt): self`

设置WordPress是否应该为这个通知使用交替颜色。

参数

bool $alt: 如果应使用交替颜色，则为真，否则为假。

`setCapability([string $capability = null]): self`

定义一个在渲染此通知之前必须满足的能力检查。

参数

?string $capability: 当前用户必须拥有的能力。传递 NULL 将删除任何现有的能力要求。

`setDismissible(bool $dismissible[, ?string $key = null]): self`

设置此通知是否可以被用户取消。

参数

bool $dismissible: 用户是否可以取消通知。
?string $key = null: 可选。一个唯一标识此通知的键。默认为 null（不跟踪取消）。; 一旦用户取消了具有此 ID 的通知，将来具有相同 ID 的通知将不会渲染。

`setInline(bool $inline): self`

指定通知是应该内联渲染还是拉到页面顶部（默认）。

参数

bool $inline: 如果通知应该内联渲染，则为真，否则为假。

`static dismissNoticeForUser(string $notice[, ?int $user = null]): bool`

将单个通知标记为给定用户 ID 已取消。

如果通知已添加到用户的取消通知列表中，则返回 true，否则返回 false。

参数

string $notice: 管理员通知的取消键。
int $user: 可选。用户ID。默认为null（当前用户）。

`static factory(string $message[, string $type = 'info']): AdminNotice`

此方法是对类构造函数的别名（并接受相同的参数），这使得编写流畅的字符串更加容易。

以下两个通知是等效的

# Using the constructor directly requires extra parentheses.
(new AdminNotice('Some message', 'info'))
    ->setInline(true)
    ->queue();

# The ::factory() method removes this constraint.
AdminNotice::factory('Some message', 'info')
    ->setInline(true)
    ->queue();

贡献

如果您有兴趣为项目做出贡献，请查看我们的贡献文档。

许可证

此库根据 MIT 许可证许可。

stellarwp / admin-notice

维护者

详情