cyberpunkcodes/laravel-flashmessages

为您的Laravel项目添加闪存消息（警报）。

维护者

详细信息

github.com/CyberPunkCodes/laravel-flashmessages

主页

源代码

问题

资助包维护！
CyberPunkCodes

安装: 3

依赖者: 0

建议者: 0

安全: 0

星级: 0

观察者: 1

分支: 0

开放问题: 0

v1.0.0 2023-10-31 07:46 UTC

Requires

Requires (Dev)

MIT f7cf8bfa23295bc4fa84218a2e8c6ec18505a460

  • CyberPunkCodes

bootstrapalertsflashlaravelmessagesalertflashMessages

This package is auto-updated.

Last update: 2024-08-30 01:34:33 UTC

README

将闪存消息（警报）添加到您的Laravel项目中。支持Tailwind v2、Bootstrap v4、Bootstrap v5或您需要的任何自定义CSS。

截图

Laravel 8与Breeze和Tailwind v2

Laravel 8与AdminLTE和Bootstrap v4

目录

警告

我想确保您看到这条警告信息，这就是为什么它排在最前面，在安装说明之前。

icon和message将不会被转义/编码。

对于图标，这通常没问题，因为它们是从配置生成的，是一个数组映射。但是，您应该知道这一点，以防万一（出于某种疯狂的原因）您将用户输入用作传递给单个消息配置数组的图标。

对于消息，在大多数情况下，这通常没问题。这允许您在消息本身中使用HTML，因此您可以包含链接、下划线或加粗某些内容、制作列表等。

您可以使用应用程序生成并由用户生成数据，如他们的用户ID。

如果您出于某种疯狂的原因确实需要将用户输入传递到消息中，您应该使用Laravel的e()辅助函数进行编码。不是整个消息，只是您要插入到其中的单个数据片段，如他们的名字。如果可疑，请编码。请参阅：https://laravel.net.cn/docs/10.x/blade#html-entity-encoding

安装

要安装此包，请运行

composer require cyberpunkcodes/laravel-flashmessages

将容器组件的代码放置在您希望显示闪存消息的位置。

<x-flashmessages-container />

注意：如果您想在多种不同类型的布局上显示闪存消息，您将需要将一个<div>包装在组件的调用周围。这样，您可以在登录/注册页面和仪表板上使用不同的包装器。

示例

<div class="auth-page-alert-wrapper">
    <x-flashmessages-container />
</div>

和

<div class="dashboard-alert-wrapper">
    <x-flashmessages-container />
</div>

此包支持Tailwind v2（Laravel 8默认包含），Bootstrap v4和Bootstrap v5。

由于这种灵活性，我们无法默认加载适当的配置或视图文件。因此，如果您不安装它们，您将收到错误。

请按照以下说明为您使用的适当CSS环境进行操作。

Tailwind v2

安装配置文件

php artisan vendor:publish --provider="CyberPunkCodes\FlashMessages\FlashMessagesProvider" --tag="tailwind2-config"

安装视图文件

php artisan vendor:publish --provider="CyberPunkCodes\FlashMessages\FlashMessagesProvider" --tag="tailwind2-views"

Bootstrap v4

安装配置文件

php artisan vendor:publish --provider="CyberPunkCodes\FlashMessages\FlashMessagesProvider" --tag="bootstrap4-config"

安装视图文件

php artisan vendor:publish --provider="CyberPunkCodes\FlashMessages\FlashMessagesProvider" --tag="bootstrap4-views"

Bootstrap v5

安装配置文件

php artisan vendor:publish --provider="CyberPunkCodes\FlashMessages\FlashMessagesProvider" --tag="bootstrap5-config"

安装视图文件

php artisan vendor:publish --provider="CyberPunkCodes\FlashMessages\FlashMessagesProvider" --tag="bootstrap5-views"

其他CSS模板

如果您不使用Bootstrap或Tailwind，则只需选择它们中的任何一个，并根据需要修改生成的文件。

在未来的某个时候，当Tailwind或Bootstrap的新版本发布时，只需选择最新合适的版本，并根据需要修改它。根据未来版本的变化程度，您可能需要修改的程度也会有所不同。

安装图标

默认的 Laravel 安装不包括 FontAwesome，所以图标将无法正常工作。您可以使用任何您想要的图标，只需修改配置来使用它们即可。如果您使用的是某种第三方模板，请确保 FontAwesome 没有已经安装。您只需尝试在某个视图文件中使用图标即可。

如果您想使用 FontAwesome，必须首先安装它。您有 2 个选项，CDN 或 NPM :)

通过CDN安装FontAwesome

在所有您想要使用闪存消息的布局中，将样式表添加到 head 部分

<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.4.2/css/all.min.css" integrity="sha512-z3gLpd7yknf1YoNbCzqRKc4qyor8gaKU1qmn+CShxbuBusANI9QpRohGBreCFkKxLhei6S9CQXFEbbKuqLg0DA==" crossorigin="anonymous" referrerpolicy="no-referrer" />

然后在关闭 body 标签之前添加相应的 JavaScript 文件

<script src="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.4.2/js/all.min.js" integrity="sha512-uKQ39gEGiyUJl4AI6L+ekBdGKpGw4xJ55+xyJG7YFlJokPNYegn9KwQ3P8A7aFQAUtUsAQHep+d/lrGqrbPIDQ==" crossorigin="anonymous" referrerpolicy="no-referrer"></script>

通过NPM安装FontAwesome

npm install @fortawesome/fontawesome-free --save-dev

然后在您的 resources/css/app.css 文件中导入它

@import '@fortawesome/fontawesome-free/css/fontawesome';

在您的 resources/js/app.js 文件中要求它

require("@fortawesome/fontawesome-free/js/all");

最后，运行

npm run dev

关于视图文件的信息

视图文件将被发布到 resources/views/vendor/flashmessages。

容器组件 blade 文件：这是一个包含单个闪存消息的容器。它简单地遍历所有闪存消息，并将每个消息加载到它们自己的组件中。

消息组件 blade 文件：每个闪存消息本身的模板。有几个辅助函数可用于辅助生成消息。请使用辅助函数，不要直接输出变量。辅助函数在值未设置（null）时返回空字符串。

使用方法

为 FlashMessages Facade 创建了一个 Composer 别名，因此您不必手动导入它，但您仍然可以。

使用反斜杠，您无需导入它：\FlashMessages::addFlashMessage($type, $message)

或者，您可以在类的顶部简单地导入它：use \FlashMessages;

或者，您可以像导入其他任何内容一样导入它：use CyberPunkCodes\FlashMessages\Facades\FlashMessages;

现在您只需添加闪存消息即可

\FlashMessages::addFlashMessage(
    'success',
    'This is a success message!',
);

您还可以在控制器中的重定向上使用 flash() 宏

示例

return redirect()->route('home')->flash('success', 'This is a success message!');

如果您需要传递特定选项，可以将配置选项数组作为第三个参数传递。您需要这样做以覆盖配置中定义的任何默认/全局设置。例如，如果全局闪存消息是可关闭的，您可以强制单个消息不可关闭

return redirect()->route('home')->flash('warning', 'Your subscription has expired!', ['dismissable' => false]);

这可能是首选的方法，除非您需要添加多个闪存消息。在这种情况下，您需要为每个消息使用 Facade。在下一页加载时，所有闪存消息都将显示。

安全地使用用户输入/数据

请阅读 README 文件开头的大警告。消息不是由 blade 的 {{ $message }} 渲染标签编码的。消息使用 {!! $message !!} 渲染，因此可以使用 HTML。

如果您需要将用户数据传递到消息中，这里是如何安全地做到这一点的

\FlashMessages::addFlashMessage(
    'success',
    'Thank you ' . e($user->name) . ' for your payment!',
);

高级使用

现在添加闪存消息

除了 addFlashMessage() 方法之外，还有一个 addFlashMessageNow() 方法，可以用于立即使用消息。它使用 Laravel 的 request()->session()->now()，这允许您添加一个闪存消息并在同一页面上显示它。

我添加这个是因为我想将内置的状态消息转换为漂亮的 Bootstrap 提醒（闪存消息）。例如：当启用电子邮件验证时，Laravel 返回一个 verification-link-sent 状态。这并不容易处理。在这个时候，页面已经加载或者被重定向到它应该去的地方。由于页面已经加载，如果我们现在使用 addFlashMessage()，闪存消息将在这个页面上加载并在下一次加载时显示。这是一个问题，消息不应该在下一个后续页面上显示。

为了解决这个问题，我们可以使用 addFlashMessageNow()

\FlashMessages::addFlashMessageNow(
    'success',
    'A verification link has been emailed to you!',
);

我编写了一个中间件，它简单地检测所有通用的Laravel和Fortify "状态"，并将它们转换为闪存消息，有两个独立的数组，一个是常规的闪存消息，另一个需要使用 "now" 来调用。我计划稍后将其添加到此包中。

辅助函数

有一个应用级别的辅助函数，用于确定是否有任何闪存消息。如果你将组件的调用包裹在一个div中并且它正在创建间距问题，这会很有用。

@if ( hasFlashMessages() )
    <div class="my-2 mx-4">
        <x-flashmessages-container />
    </div>
@endif

此外，还有9个FlashMessages辅助函数可供在resources/views/vendor/flashmessages/components/message.blade.php文件中使用。你可以在该blade文件中看到这些的大部分示例。

  • isDismissable() - (布尔值) 确定闪存消息是否可关闭。
  • getClass() - 获取从typeToClassMap确定的类名或默认值。
  • shouldShowIcon() - (布尔值) 确定是否显示图标。
  • getIcon() - 获取从typeToIconMap确定的图标或默认值。
  • shouldShowTitle() - (布尔值) 确定是否显示标题。
  • hasTitle() - (布尔值) 确定闪存消息是否有标题。
  • getTitle() - 获取标题。
  • hasMessage() - 确定闪存消息是否有消息（应该有，但以防万一添加了）。
  • getMessage() - 获取消息。

在消息中使用HTML

如果需要，你可以向消息传递HTML。

以下是如何在消息中传递链接的方法

\FlashMessages::addFlashMessage(
    'error',
    'Your subscription has expired. Click <a href="https://www.google.com" class="alert-link">here</a> to renew!',
);

注意： alert-link 是一个Bootstrap类，可以使链接颜色与警告的类型/颜色匹配。如果你不使用Bootstrap，则这不是必需的。如果你使用Bootstrap并创建自己的自定义类型，你可能还想要创建这些类的CSS。

创建新类型

创建新的类型非常简单。

将你图标的HTML添加到typeToIconMap数组中，在config/flashmessages.php中

'typeToIconMap' => [
    'foo' => '<i class="fab fa-fw fa-apple mr-2"></i>',
],

对于FontAwesome，我喜欢使用fa-fw类。这使得所有图标都具有相同的宽度，整体看起来更好。尤其是在屏幕上显示多个消息时。

然后，将你的类添加到typeToClassMap数组中，也位于config/flashmessages.php中

'typeToClassMap' => [
    'foo' => 'custom-class',
],

注意： 如果你使用Bootstrap，该类将作为alert-custom-class添加到警告前缀。

别忘了为你的自定义类创建CSS。

.alert-custom-class {
    color: #fff;
    background: #673ab7;
    border-color: #552d9c;
}

.alert-custom-class .alert-link {
    color: #b8ebff;
    text-decoration: none;
}

如果你想要，可以添加悬停/激活/访问效果。你可能正在使用mix或SASS而不是CSS。正确地做，而不是通过在布局中抛出一个style标签来使用自定义hack... 如果需要，别忘了运行npm run dev来重新编译你刚刚添加的CSS。

单个消息自定义配置

addFlashMessage()方法支持第三个参数，一个$config数组。大部分可用选项都可以传递给单个消息的配置数组。但是，你不能传递message、typeToIconMap或typeToClassMap。

示例

\FlashMessages::addFlashMessage(
    'success',
    'This is a highly configured success message!',
    [
        // common config options
        'title' => 'Custom Title',
        'class' => 'custom-classname',           // if you want to use a different class for this message
        'icon'  => '<i class="fas fa-fw fa-taxi"></i>',// if you want to use a different icon for this message

        // rare config options (set in default config and rarely have to change)
        'showIcon'    => true,                   // override the default config values
        'showTitle'   => false,                  // override the default config values
        'dismissable' => false,                  // override the default config values

        // In the VERY RARE event you need to override the "forced" settings (defined in config)
        // This allows you to override the override for this individual message itself

        // very rare config options
        'forceIcon' => false,                    // override `forceIcon` (if enabled in config)
        'forceTitle'  => false,                  // override `forceTitle` (if enabled in config)
        'forceDismissable'  => false,            // override `forceDismissable` (if enabled in config)
    ],
);

如何查看消息以修改视图文件？

为了编辑容器或消息视图文件，你很可能需要至少看到一个闪存消息，以便你可以对其进行测试。

创建一个路由

Route::get('/redirect-test', [App\Http\Controllers\Controller::class, 'redirectTest'])->name('redirect.test');

将Controller更改为适当的控制器。任何一个都行，但可能就是你主要的控制器，该控制器渲染你的仪表板。

将测试函数添加到该控制器中

public function redirectTest(\Request $request)
{
    \FlashMessages::addFlashMessage(
        'success',
        'This is a success message!',
    );

    \FlashMessages::addFlashMessage(
        'warning',
        'This is a warning message!',
    );

    \FlashMessages::addFlashMessage(
        'info',
        'This is an info message!',
    );

    \FlashMessages::addFlashMessage(
        'error',
        'This is an error message!',
        [
            'title' => 'Custom Error Title',
            'dismissable' => false,
        ]
    );

    // Let's also ensure a message with an undefined type looks fine while we are here
    \FlashMessages::addFlashMessage(
        'foo',                              // some type that does not exist, falls back to default class/icon
        'This is an error message!',
    );

    return redirect()->route('home');       // change home to whatever named route you need (ie: dashboard)
}

这是一个我从Laravel 8中得到的包，我迅速将其组装起来用于Laravel 10项目。它在Laravel 10上运行得很好。我将在不久的将来更新文档和截图。

如果你擅长编写文档，请随意整理这个乱糟糟的文档 :)