README

此包旨在统一、简化在 Laravel 应用程序的 Web 界面中注册和显示消息。

这允许在多个项目中使用通知/警报，而无需每次都实现相同的程序。

注意不要在 Laravel 中混淆 "通知" 和 "Session Flash Data"；此包使用后者，与前者毫无关联。

使用此包声明和显示消息有两种方式

要么用于 "flash" 消息，这些消息将在下一个 HTTP 请求中显示
要么用于 "即时" 消息，这些消息将在当前的 HTTP 请求中显示

消息可以是四种不同类型

info
success
warning
error

更新

有关更新说明，请参阅 UPGRADE.md 文件。

安装

使用 Composer 包含此包

composer require axn/laravel-notifier

声明消息

入口点是助手函数 notify()，它返回 Axn\Notifier\Notify 的实例。

“flash” 消息

通常它们在表单提交后（因此是重定向后）显示确认。

这对应于 Laravel 的 "Flash Data"，但通过 类型化 消息以便更容易控制屏幕渲染。

要添加消息 flash，请使用

notify()->info('message');

notify()->success('message');

notify()->warning('message');

notify()->error('message');

例如

class function PostController()
{
    public function update(Post $post)
    {
        //...
        $post->update([/*...*/]);

        notify()->success('Post '.e($post->title).' successfully updated.');

        return back();
    }
}

“即时”消息

它们允许在不进行预先重定向的情况下直接在屏幕上显示一条信息。

为此，您可以使用 now* 函数

notify()->nowInfo('message');

notify()->nowSuccess('message');

notify()->nowWarning('message');

notify()->nowError('message');

例如

class function PostController()
{
    public function edit(Post $post)
    {
        //...
        notify()->nowInfo('Editing '.e($post->title).' post.');

        return view('post.edit');
    }
}

标题

可以添加一个第二个参数 $title

notify()->success('Post '.e($post->title).' successfully updated.', 'Success');

notify()->nowInfo('Editing '.e($post->title).' post.', 'Information');

安全和 XSS 攻击预防

为了允许在消息中放置 HTML，模板中的 $message 和 $title 变量 没有转义。

如果您必须放置来自数据库或用户输入的数据，您必须像上述示例中那样使用助手函数 e($string) 进行转义。

否则，这是 XSS 安全漏洞。

注意：但是，字符 ' 和 " 被替换为 ' 和 "

显示时间

某些模板在消息消失之前有一个显示时间。

如果您想修改消息的显示时间，例如因为它很长。

可以添加一个第三个参数 $delay

notify()->success('Post '.e($post->title).' successfully updated.', 'Success', 5000);

notify()->nowInfo('Editing '.e($post->title).' post.', 'Information', 15000);

此参数以毫秒为单位，默认为

info：10000（10秒）
success：5000（5秒）
warning：12000（12秒）
error：15000（15秒）

注意：在提供的模板中，错误显示时间将乘以错误数量。

多个消息和条件

您可以将多个消息连续添加，并对其进行条件化。

// messages flash
notify()
    ->info('message')
    ->success('message')
    ->when($condition, function($notify) {
        $notify->warning('message');
    })
    ->unless($otherCondition, function($notify) {
        $notify->error('message');
    });

// messages instantanés
notify()
    ->nowInfo('message')
    ->nowSuccess('message')
    ->when($condition, function($notify) {
        $notify->nowWarning('message');
    })
    ->unless($otherCondition, function($notify) {
        $notify->nowError('message');
    });

注意：并非所有模板都支持显示不同类型的多个消息。

消息堆栈

可以在非默认堆栈中声明消息。

这样您就可以在同一页面上显示不同的消息堆栈。

例如，使用默认堆栈来处理当前消息，并根据页面上下文偶尔显示补充消息；例如，在另一个位置使用不同的模板。

这允许将业务逻辑放在控制器中，而不是在 Blade 视图中。

为此，您必须在 notify() 助手中指定堆栈名称。

notify()->success('message'); // stack par defaut
notify('custom-stack')->success('message'); // stack personnalisée

notify()->nowInfo('message'); // stack par defaut
notify('custom-stack')->nowInfo('message'); // stack personnalisée

可以向同一自定义堆栈中添加多个消息。

notify('custom-stack')
    ->nowInfo('message')
    ->nowSuccess('message')
    ->when($condition, function($notify) {
        $notify->nowWarning('message');
    });

请注意：请不要使用“custom-stack”这个名字，这里只是为了举例，请根据上下文选择一个明确的名字。

共享错误视图

可以通过应用程序添加由视图共享的错误。

通常情况下，Laravel 会自动为验证错误消息执行此操作。

但也可以通过控制器添加，例如。

class function PostController()
{
    public function post(Request $request)
    {
        //...

        return back()->withErrors([
            'Une erreur',
            'Une autres erreur',
        ])
    }
}

默认情况下，所有视图共享的错误消息都会自动添加到默认消息堆栈的即时消息堆栈中。

查找消息

您可以将“闪存”消息和/或“即时”消息以Laravel 集合的形式找到。

查找默认堆栈的消息

notify()->flashMessages();

notify()->nowMessages();

或自定义堆栈的消息

notify('custom-stack')->flashMessages();

notify('custom-stack')->nowMessages();

这可以让你通过 Laravel 集合来操作消息内容。

或者根据是否存在消息执行特殊操作。

例如，如果您只使用条件性消息并且希望在确实有消息时触发一个动作

notify()
    ->when($condition, function($notify) {
        $notify->warning('message');
    })
    ->unless($otherCondition, function($notify) {
        $notify->error('message');
    });

if (notify()->flashMessages()->isNotEmpty()) {
    return back();
}

显示消息

组件

要显示消息，您必须使用由包提供的 Blade 组件。

<x-notify />

根据使用的视图模板，您需要将此调用放在正确的位置。

例如，对于使用 JavaScript 组件的模板，您必须在应用程序的脚本之后放置它。

相反，如果您使用直接显示视图的模板，则必须将其放置在您希望显示消息的地方。

属性

此组件将默认使用包的配置值，但您可以通过向组件传递属性来修改它们。

还可以控制消息显示的各个方面。

模板

要更改模板

<x-notify view-name="notifier::bootstrap-5-alert" />

例如，这可能有助于根据您是处于公共部分还是管理部分显示不同的模板。或者根据显示的堆栈显示不同的模板。

显示特定堆栈

如果您在非默认堆栈中声明了消息并且希望显示其消息

<x-notify stack="custom-stack" />

按类型排序消息

默认情况下，消息按类型排序，但您可以更改此设置

<x-notify :sort-by-type="false" />

然后，消息将按照它们声明的顺序显示，无论它们的类型如何。

注意

如果您不使用此属性并允许类型排序，则类型显示的顺序由配置文件（sort_type_order）中的默认设置定义。默认情况下

error
warning
success
info

按类型分组消息

默认情况下，每个消息都会触发一个不同的通知。可以按类型将消息分组。

<x-notify :group-by-type="true" />

因此，如果您有 3 个验证错误，它们将显示在单个通知中，而不是在 3 个不同的通知中。

分组消息的格式化

分组消息在包的配置文件中具有预定义的格式

//...
    'group_messages_format' => '<ul class="list-unstyled mb-0">%s</ul>',

    'group_title_format' => '<strong>%s&nbsp;:&nbsp;</strong>',

    'group_message_format' => '<li>%s%s</li>',
//...

注意在列表上使用Bootstrap类...

例如：

<ul class="list-unstyled mb-0">
    <li><strong>Success&nbsp;:&nbsp;</strong>féliciations</li>
    <li>encore féliciations</li>
</ul>

可以通过修改包的配置来全局更改这些格式。但是，不能在组件级别进行修改。

要显示的消息

有时你可能只需要显示一种类型的信息（闪存或即时）。

要隐藏闪存消息

<x-notify :without-flash-messages="true" />

要隐藏即时消息

<x-notify :without-now-messages="true" />

例如，根据是即时消息还是闪存消息来显示不同的模板。

<x-notify view-name="notifier::bootstrap-5-alert" :without-flash-messages="true" />

<x-notify :without-now-messages="true" />

查看共享的错误

这些消息会始终在默认堆栈和即时消息中显示。

如果你不希望在通知器中显示这些错误，你可以在默认堆栈的组件中添加

<x-notify :without-view-shared-errors="true" />

然后由你来管理这些消息的显示。

组合

根据需要，可以组合所有这些属性

<x-notify
    view-name="notifier::bootstrap-5-alert"
    stack="custom-stack"
    :sort-by-type="false"
    :group-by-type="true"
    :without-flash-messages="true"
    :without-now-messages="false"
    :without-view-shared-errors="true" />

视图模板

当前包提供的视图模板如下

bootstrap-5 代码 notifier::bootstrap-5
bootstrap-5-toast 代码 notifier::bootstrap-5-toast
bootstrap-5-alert 代码 notifier::bootstrap-5-alert
bootstrap-5-alert-advanced 代码 notifier::bootstrap-5-alert-advanced
bootstrap-4 代码 notifier::bootstrap-4
bootstrap-4-toast 代码 notifier::bootstrap-4-toast
bootstrap-4-alert 代码 notifier::bootstrap-4-alert
bootstrap-4-alert-advanced 代码 notifier::bootstrap-4-alert-advanced
sweetalert2 代码 notifier::sweetalert2
pnotify-5 代码 notifier::pnotify-5

bootstrap-5

以简单的段落形式显示消息，颜色为类型颜色。

显然需要Bootstrap 5。

将组件的调用放在你希望消息出现的位置。

注意：此视图无法按类型组合消息。

bootstrap-5-toast

以Bootstrap 5的吐司组件显示消息。

显然需要Bootstrap 5以及组件的样式和JS插件。

在调用应用程序脚本之后放置显示组件的调用。

bootstrap-5-alert

以Bootstrap 5的警告组件显示消息。

显然需要Bootstrap 5以及组件的样式。

将组件的调用放在你希望警告出现的位置。

bootstrap-5-alert-advanced

这是前一个的扩展，添加了图标和关闭按钮。

因此，在你的项目中需要Bootstrap警告的JS插件。

将组件的调用放在你希望警告出现的位置。

bootstrap-4

以简单的段落形式显示消息，颜色为类型颜色。

显然需要Bootstrap 4。

将组件的调用放在你希望消息出现的位置。

注意：此视图无法按类型组合消息。

bootstrap-4-toast

以Bootstrap 4的吐司组件显示消息。

显然需要Bootstrap 4以及组件的样式和JS插件。

在调用应用程序脚本之后放置显示组件的调用。

bootstrap-4-alert

以Bootstrap 4的警告组件显示消息。

显然需要Bootstrap 4以及组件的样式。

将组件的调用放在你希望警告出现的位置。

bootstrap-4-alert-advanced

这是对之前版本的扩展，增加了fontawesome5图标和关闭alert的按钮。

因此，在您的项目中需要包含fontawesome4和Bootstrap 4的基本JS。

将组件的调用放在你希望警告出现的位置。

sweetalert2

尽管视觉上很优雅，但sweetalert2不允许在同一页面上显示多个实例，只有第一个会被显示（实际上是一种模态框）。

因此，您不能声明多个不同类型的消息，如果您使用这个视图，消息将自动按类型分组。

如果它不存在，请安装它

npm install sweetalert2 --save-dev

并将其添加到您的JS文件中

import Swal from 'sweetalert2'
window.Swal = Swal;

所有的显示配置都在模板中。如果您想修改它，您必须发布模板，并参考其文档。

在调用应用程序脚本之后放置显示组件的调用。

pnotify-5

尽管这个包提供了许多可能性，但它已经过时，并且不再真正得到维护；因此，它需要jQuery。

出于这些原因，尽管这是我们多年来“标准”的解决方案，但我建议用更现代的解决方案来替换它。

尽管如此，我们仍然维护它，因为许多项目仍在使用它。

以下是一个安装示例，有关更多详细信息，请参阅包的文档https://github.com/sciactive/pnotify

如果它不存在，请安装它

npm install pnotify --save-dev

添加CSS，例如

// PNotify
@import '~@pnotify/core/dist/PNotify.css';
@import '~@pnotify/mobile/dist/PNotifyMobile.css';
@import '~@pnotify/bootstrap4/dist/PNotifyBootstrap4.css';

加载模块，例如

// PNotify
window.PNotify = require('@pnotify/core');
window.PNotifyAnimate = require('@pnotify/animate');
window.PNotifyMobile = require('@pnotify/mobile');
window.PNotifyBootstrap4 = require('@pnotify/bootstrap4');
window.PNotifyFontAwesome5Fix = require('@pnotify/font-awesome5-fix');
window.PNotifyFontAwesome5 = require('@pnotify/font-awesome5');

例如，配置默认值

PNotify.defaultStack.close(true);
PNotify.defaultStack.maxOpen = Infinity;
PNotify.defaultStack.modal = false;

PNotify.defaults.animateSpeed = 'slow';
PNotify.defaults.delay = 5000;
PNotify.defaults.titleTrusted = true;
PNotify.defaults.textTrusted = true;

PNotify.defaults.styling = 'bootstrap4';
PNotify.defaults.icons = 'fontawesome5';

PNotify.defaultModules.set(PNotifyMobile, {});
PNotify.defaultModules.set(PNotifyAnimate, {
    inClass: 'bounceInDown',
    outClass: 'bounceOut'
});
PNotify.defaultModules.set(PNotifyBootstrap4, {});
PNotify.defaultModules.set(PNotifyFontAwesome5, {});

在调用应用程序脚本之后放置显示组件的调用。

模板定制

您可以通过使用此命令发布它们来定制包提供的视图模板

php artisan vendor:publish --tag="notifier-views"

然后，它们将被复制到resources/views/vendor/notifier并自动由应用程序加载。

提示： 仅替换您定制的视图文件，其他文件将来自包。

创建自定义模板

如果您想使用包中没有实现的基本JS库或仅用简单的HTML格式化消息，您有创建自己的模板的能力。

首先，为组件创建自己的Vue Blade视图，例如：/resources/views/components/custom-notify.blade.php

例如，在显示时指定其使用方法

<x-notify view-name="components.custom-notify" />

或在配置文件中将其定义为默认视图。

请勿使用“custom-notify”这个名字，这里仅作为示例，根据您的定制实现选择一个明确的名称。

显然，您可以使用组件的<x-notify />的所有属性，如“显示消息”一章中所述。

在您的新视图中，您将能够访问组件的公开变量

$flashMessages：闪存消息集合
$nowMessages：瞬时消息集合
$flashErrorsCount：闪存消息中的错误数量
$nowErrorsCount：瞬时消息中的错误数量

然后，您需要遍历消息

<div>
    @foreach ($flashMessages as $flashMessage)
        {!! ici votre implémentation d'affichage d'un message !!}
    @endforeach
    @foreach ($nowMessages as $nowMessage)
        {!! ici votre implémentation d'affichage d'un message !!}
    @endforeach
</div>

在这些循环中，变量$flashMessage和$nowMessage是包含以下值的数组

[
    'id', // l'identifiant unique du message
    'type', // le type du message ('info', 'success', 'warning' ou 'error')
    'message', // le contenu du message
    'title', // l'éventuel titre du message
    'delay', // la durée d'affichage du message
]

这个阶段，创建一个partial来共享您的代码是个好主意，例如：/resources/views/components/partials/custom-notify-message.blade.php

然后，在组件的视图中

<div>
    @foreach ($flashMessages as $flashMessage)
        @include ('components.partials.custom-notify-message', [
            'id' => $flashMessage['id'],
            'type' => $flashMessage['type'],
            'message' => $flashMessage['message'],
            'title' => $flashMessage['title'],
            'errorsCount' => $flashErrorsCount,
        ])
    @endforeach
    @foreach ($nowMessages as $nowMessage)
        @include ('components.partials.custom-notify-message', [
            'id' => $nowMessage['id'],
            'type' => $nowMessage['type'],
            'message' => $nowMessage['message'],
            'title' => $nowMessage['title'],
            'errorsCount' => $nowErrorsCount,
        ])
    @endforeach
</div>

如果您不需要修改上面的代码，您可以使用通用的视图组件

@include ('notifier::partials.a-generic-component', [
    'viewName' => 'components.partials.custom-notify-message',
])

现在，您只需实现消息视图components/partials/custom-notify-message.blade.php。

在这个视图中，您将能够访问以下变量

$id : 消息的唯一标识符
$type : 消息类型 ('info', 'success', 'warning' 或 'error')
$message : 消息内容
$title : 消息的潜在标题
$errorsCount : 错误消息的数量
$delay : 消息显示的持续时间

现在轮到你了：）

共享：如果您实现了可重用的模板，我们可以考虑将其集成到包中，而不是在不同项目中复制粘贴。

以下是一些想法。

要创建和添加的模板想法

Notiflix

Toastify JS

JS-Snackbar

VanillaToasts

Notyf

simple-notify

配置

此包提供了一个配置文件。

查看此文件以了解您可以修改的内容，每个选项都有文档说明。

此文件的值可以通过这种方式访问：config('notifier.option')，其中 option 是配置表单的键。

为了自定义配置，您必须通过执行以下命令将文件发布到您的应用程序中：

php artisan vendor:publish --tag="notifier-config"

然后，文件将被复制到 config/notifier.php 并由应用程序自动加载。

技巧： 只将您更改的内容放入此文件中，其余内容将来自包的合并。

axn / laravel-notifier

维护者

详情

README

更新

安装

声明消息

“flash” 消息

“即时”消息

标题

安全和 XSS 攻击预防

显示时间

多个消息和条件

消息堆栈

共享错误视图

查找消息

显示消息

组件

属性

模板

显示特定堆栈

按类型排序消息

按类型分组消息

分组消息的格式化

要显示的消息

查看共享的错误

组合

视图模板

bootstrap-5

bootstrap-5-toast

bootstrap-5-alert

bootstrap-5-alert-advanced

bootstrap-4

bootstrap-4-toast

bootstrap-4-alert

bootstrap-4-alert-advanced

sweetalert2

pnotify-5

模板定制

创建自定义模板

要创建和添加的模板想法

配置