README

为 Laravel & Livewire 提供美观的通知 Toast

一个可以从后端（通过控制器、Blade 视图、组件）或前端（JS、Alpine 组件）调用的 Toast 全局变量，以渲染可定制的 Toast。

支持 TALL 栈运行： Laravel、TailwindCSS、Livewire、AlpineJS。

展示在

为什么

如果您正在使用 TALL 栈构建 web 应用，您必须选择这个库而不是其他过时的库

大小很重要

由于前端是一个纯 AlpineJS 组件，不依赖于外部 JS 库，并且后端处理了大部分逻辑，JavaScript 的足迹非常小 (不到一千字节！)。

CSS 的足迹也非常小，因为它使用默认的 TailwindCSS 类。即使您覆盖了默认视图，您也可以放心 Tailwind 的清除只会保留您使用的样式/类。

简而言之，它不会像使用其他 JS 库那样膨胀您的生成的 JS/CSS 文件，也不会添加额外的文件下载！

充分利用 TALL 的所有优点

您可以从任何地方调用它！记住前端是 Toast，后端是 toast()。

请参阅使用部分以获取示例。

可定制

您控制视图：由于您正在覆盖 blade 视图，您可以使用 TailwindCSS 类按您喜欢的形状塑造它。

不再需要与自定义 CSS 覆盖纠缠！

使用方法

从前端

Toast.info('Notification from the front-end...', 'The Title');

Toast.success('A toast without a title also works');

Toast.warning('Watch out!');

Toast.danger('I warned you!', 'Yikes');

Toast.debug('I will NOT show in production! Locally, I will also log in console...', 'A Debug Message');

Toast.success('This toast will display only for 3 seconds', 'The Title', 3000);

Toast.success('This toast will display until you remove it manually', 'The Title', 0);

从后端

toast()
    ->info('I will appear only on the next page!')
    ->pushOnNextPage();

toast()
    ->info('Notification from the backend...', 'The Title')
    ->push();

toast()
    ->success('A toast without a title also works')
    ->push();

toast()
    ->warning('Watch out!')
    ->push();

toast()
    ->danger('I warned you!', 'Yikes')
    ->push();

toast()
    ->danger('I will go…<br><i>to the next line 💪</i>', 'I am <span style="color:red;">HOT</span>')
    ->doNotSanitize()
    ->push();

toast()
    ->debug('I will NOT show in production! Locally, I will also log in console...', 'A Debug Message')
    ->push();

// debug also accepts objects as message
toast()
    ->debug(User::factory()->createOne()->only(['name', 'email']), 'A User Dump')
    ->push();

toast()
    ->success('This toast will display only for 3 seconds')
    ->duration(3000)
    ->push();

toast()
    ->success('This toast will display until you remove it manually')
    ->sticky()
    ->push();

您可以从控制器、blade 视图和组件中调用上面的 toast 辅助函数。

支持我

我计划使用 TALL 栈开发许多开源包。
通过推文介绍这个库或为此包做出贡献来支持我的工作。

查看我为 TALL 栈构建的其他包列表其他包。
要获取最新信息，请在 Twitter 上关注我。

要求

您可以在此处找到旧的 v1 文档

安装

您可以通过 Composer 安装此包

composer require usernotnull/tall-toasts

设置

TailwindCSS

像往常一样构建您的 CSS，例如

npm run dev

使用 Tailwind JIT 的用法

如果您使用的是即时模式，请在您的 tailwind.config.js 文件中添加以下附加行

// use `purge` instead of `content` if using TailwindCSS v2.x
content: [
    './vendor/usernotnull/tall-toasts/config/**/*.php',
    './vendor/usernotnull/tall-toasts/resources/views/**/*.blade.php',
    // etc...
]

这样，Tailwind JIT 将将此库中使用的类包含在您的 CSS 中。

与往常一样，如果 tailwind.config.js 的内容发生变化，您应该重新运行 npm 命令。

使用 AlpineJS 注册 Toast

在您的 app.js 中添加 Toast 组件

import {Alpine, Livewire} from '../../vendor/livewire/livewire/dist/livewire.esm';
import ToastComponent from '../../vendor/usernotnull/tall-toasts/resources/js/tall-toasts'

Alpine.plugin(ToastComponent)

Livewire.start()

将 <livewire:toasts /> 放在 body 标签中尽可能高的位置，例如

<!DOCTYPE html>
<html lang="en">

<head>
    <!-- Metas, Styles, JS... -->
</head>

<body>
    <livewire:toasts />

    <!-- Below toasts, your contents... -->

    @livewireScriptConfig
</body>

</html>

为了从 livewire 组件内部正确分发 toast，请 添加属性

use Livewire\Component;
use Usernotnull\Toast\Concerns\WireToast;

class DemoComponent extends Component
{
    use WireToast; // <-- add this

    public function sendCookie(): void
    {
        toast()
            ->success('You earned a cookie! 🍪')
            ->pushOnNextPage();

        redirect()->route('dashboard');
    }

就是这样！🎉

RTL 支持

默认布局现在支持 RTL。

有关 RTL 支持的 TailwindCSS 文档 RTL 支持
始终设置方向，即使从左到右是默认方向.

<html dir="ltr">
  <!-- ... -->
</html>

自定义

Toast 最初看起来应该相当不错。然而，我们已经记录了两种自定义视图和功能的方法。

配置

您可以使用以下命令发布配置文件

php artisan vendor:publish --provider="Usernotnull\Toast\ToastServiceProvider" --tag="tall-toasts-config"

这是发布配置文件中的默认内容

<?php

return [
    /*
     * How long each toast will be displayed before fading out, in ms
     */
    'duration' => 5000,

    /*
     * How long to wait before displaying the toasts after page loads, in ms
     */
    'load_delay' => 400,
];

自定义视图

您可以发布并更改此包中的所有视图

php artisan vendor:publish --provider="Usernotnull\Toast\ToastServiceProvider" --tag="tall-toasts-views"

发布视图可以在 resources/views/vendor/tall-toast/ 中找到和更改。

发布的文件是

includes/content.blade.php - 每个弹出通知的内容视图，完全可配置
includes/icon.blade.php - 每种通知类型的图标
livewire/toasts.blade.php - 所有 toast 的父元素

文本清理

内容视图使用 x-html 显示标题和消息。由于后端默认清理标题和消息，所以这很好。

⚠️ 如果您希望跳过清理以显示 HTML 内容，例如加粗文本或添加 <br> 以转到下一行，您将调用 doNotSanitize()，如使用部分所见。在这种情况下，请确保没有用户输入！

故障排除

请首先彻底阅读此说明。

如果以下清单无法解决您的问题，请随时提交问题。请确保遵循错误报告模板。它有助于我们快速重现错误并解决它。

Toast 只在刷新后显示多次

如果您从 livewire 组件调用 toast，您是否已将 trait WireToast 添加到组件中？ (see)
您是否交换了 push() 和 pushOnNextPage()？

Toast 不会显示

是否将 <livewire:toasts /> 放在具有 livewire 和 alpine/app.js 脚本标签的页面上？
您是否省略了将 ToastComponent 作为 Alpine 数据组件添加？
你是否忘记了在链式方法结束时调用push()？ (查看)
你尝试在其他应用部分调用toast()辅助函数并检查它是否工作了吗（这将帮助我们确定问题范围）？ (查看)
你是否尝试过调用php artisan view:clear？
你在控制台中遇到任何错误吗？

通知显示但看起来很奇怪

你是否使用TailwindCSS JIT？别忘了更新你的清除列表！ (查看)
你可能需要通过运行以下命令来重建你的CSS： npm run dev 或重新运行 npm run watch (查看)

其他包

要获取最新信息，请在 Twitter 上关注我。

测试

此包使用PestPHP来运行其测试。

要运行无覆盖的测试，运行

composer test

要运行带覆盖的测试，运行

composer test-coverage

贡献

此包有3个GitHub工作流程，当推送PR时按顺序运行

首先，它检查样式问题，并使用
1. PHP CS Fixer
2. PHP代码美化器
然后，它使用静态分析，然后使用以下标准单元测试
最后，它生成由@toastScripts注入的精简JS dist

在推送PR时，快速运行并确保工作流程通过是一个好主意，这可以在合并前节省代码审查的时间。

为了方便，你可以在推送PR之前运行以下命令

composer workflow

请参阅CONTRIBUTING以获取详细信息。

变更日志

请参阅CHANGELOG以获取有关最近更改的更多信息。

版本控制

此项目遵循语义版本控制指南。

安全漏洞

根据安全最佳实践，不要在包含用户输入消息或标题的toast上调用doNotSanitize()！

请查看安全策略以了解如何报告安全漏洞。

致谢

John F ( @usernotnull )
所有贡献者

许可

MIT许可证（MIT）。请参阅许可文件以获取更多信息。

usernotnull / tall-toasts

维护者

详细信息