README

Laravel Toastie

简单的Toast通知，内置ALT堆栈（Alpine、Laravel、Tailwind）应用的默认设计，可轻松自定义

安装最新版本 · 报告错误 · 请求功能

📔 目录

• 关于项目
  • 屏幕截图
  • 技术栈
  • 功能
• 安装
  • 版本矩阵
• 用法
  • 配置
  • PHP API
  • Blade组件
• 贡献
  • 项目工具快速参考
• 变更日志
• 许可证
• 致谢

🌟 关于项目

其他所有的Laravel Toast通知库似乎都很好地解决了创建Toast的API问题，但它们缺少的关键领域是保持更新和✨风格✨。

此包旨在通过提供一套看起来不错且易于使用的Toast，以及非常容易更改设计（如果你不喜欢它们的样式，可以自己创建）来解决此问题！

Toastie支持4种关键Toast类型/状态；成功、信息、警告和错误。

📷 屏幕截图

👾 技术栈

• 语言：PHP
• 依赖管理器：Composer
• 容器化：Docker
• 构建工具：Make
• 框架：Laravel
• 框架：Alpine
• 框架：Tailwind
• 包：illuminate/support
• 包：orchestra/testbench
• 包：pestphp/pest
• 包：laravel/pint
• 包：phpstan/phpstan

🎯 功能

• 易于使用
• Laravel化
• Alpine & Tailwind
• 表达式API
• 自动隐藏或仅在取消时隐藏
• ✨ 时尚 ✨ 且现代的默认设计
• 高度可定制
• 俏皮

💾 安装

可以通过 Composer 进行安装

composer require othyn/laravel-toastie

安装后，您需要通过您选择的任何前端构建工具重新构建任何资产，这可能是 Vite。这是为了让 Tailwind 打包器能够获取新的视图并将该软件包使用的类（如果它们尚未在应用程序的其他部分使用过）加载到您的应用程序包中。如果您仍然遇到问题，您可能还需要重新启动任何 Docker 容器。

接下来，您将想要前往 配置，让我们开始 使用！在那里见。

版本矩阵

以下是当前版本矩阵，列出项目支持的使用的框架和库的版本。

如果您需要支持较旧的 Laravel 版本，请提交一个问题，因为我们可能能够查看是否可以降低版本要求，因为我认为不需要这么新。或者，您也可以提交一个 PR！

🛠️ 使用

Toastie 有三个关键部分；

1. 配置。
   • 在这里您可以自定义 Toastie 的行为。
2. PHP API。
   • 如何调用和操作 Toastie。
3. Blade 组件。
   • 如何渲染 Toastie。

让我们从配置开始，我会在那里等你。

🔧 配置

你好！我们首先需要发布配置，以便我们可以按照我们想要的方式设置。

我们通过告诉 Laravel 将配置文件发布到我们的工作目录来实现这一点，而不是依赖于该软件包捆绑的默认配置文件

php artisan vendor:publish \
    --provider="Othyn\\Toastie\\Providers\\ToastieServiceProvider" \
    --tag="toastie-config"

您现在应该在项目中有一个可编辑的 config/toastie.php 文件。如果您打开它，您会看到如下内容：

<?php

declare(strict_types=1);

return [
    'timings' => [
        /*
         * Whether the toasts should automatically close after a specified time.
         *
         * This time can be specified by setting the 'timings.dismiss_delay' value.
         */
        'auto_dismiss' => env('TOASTIE_AUTO_DISMISS', true),

        /*
         * Time, in seconds, that the toast should take to be dismissed when dismissing automatically.
         *
         * REQUIRES the 'timings.auto_dismiss' setting to be enabled.
         */
        'dismiss_delay' => env('TOASTIE_DISMISS_DELAY', 4),
    ],
];

根据您的喜好进行自定义，配置选项和简短说明在上文或您的新 config/toastie.php 文件中提供。

让我们继续使用 PHP API。

🐘 PHP API

调用 Toastie 可以通过以下三种方式之一实现；

• ... 通过辅助方法。
• ... 通过外观。
• ... 通过创建类的新的实例。

选择您喜欢的方式。我个人偏好辅助方法，因为它既简单又方便，有良好的 IDE 类型提示。

辅助方法

如果您喜欢简单行事

// An info type & style toast
toastie()->info('Remember to pick a movie to watch tonight!');

// A warning type & style toast
toastie()->warning('Its getting late, you should watch that movie...');

// An error type & style toast
toastie()->error('Ran out of popcorn.');

// A success type & style toast
toastie()->success("Watched {$favouriteMovie}.");

外观

如果您喜欢更静态的生活方式

// Remember to include the class!
use Othyn\Toastie\Facades\Toastie;

// ... some ungodly code ...

// An info type & style toast
Toastie::info('Dinner\'s 5 minutes away.');

// A success type & style toast
Toastie::success('Dinner\'s ready!');

// A warning type & style toast
Toastie::warning('Dinner\'s getting cold... you should eat now.');

// An error type & style toast
Toastie::error('Dog ate it.');

您会注意到，外观在 PHPDoc 块上将具体类作为 mixin，这样您的 IDE 会很高兴。我的就是。

类的实例

如果您喜欢老式方法

// Remember to include the class!
use Othyn\Toastie\Services\Toastie;

// ... some ungodly code ...

// Create the new toastie instance
$toastie = new Toastie();

// ... yet more ungodly code ...

// An info type & style toast
$toastie->info('Hey! How are you? Heads up, the next toast will be a warning.');

// A warning type & style toast
$toastie->warning('Uh-oh! Oh well, the next toast will be a success...');

// A success type & style toast
$toastie->success('Yes! Got the good one. Although the next one\'s going to sting...');

// An error type & style toast
$toastie->error('Ran out of bread.');

// ... when will it end?!

// Oh.

让我们继续使用 Blade 组件。

📄 Blade 组件

默认情况下，Toastie 随带一个 Toast 设计和匹配组件，适用于它支持的 4 种关键 toast 类型。它还有一些“更智能”的选项和允许您根据需要自定义外观的选项，同时保留 Toastie 的表达 API。

为了使 Toastie 在您的页面上加载 toast，您需要做以下三件事之一；

• ... 使用“智能”共享组件来渲染默认设计，但通过一个动态更改的组件；或
• ... 直接添加您想要的 toast 风格/类型的 Blade 组件（可以重写）；或
• ... 使用 'stack' 栈组件来自动加载所有吐司，根据调用内容决定（可以覆盖）。

“可以覆盖”指的是在这些场景下，实际底层组件文件将被加载，这意味着您可以将项目的视图发布并自定义它们，完全改变设计，但保留 Toastie 的表达式 API。如果您想知道如何做，请跳到 “自定义吐司设计”。

让我们从 Toastie 的默认实现开始。

使用动态默认设计

如果您不想更改任何设计，这是最大化 Toastie 利用率的最简单方法。

<!-- my-view.blade.php -->

<!-- Will render only the required style/type of toast when called -->
<x-toastie::shared />

就这样！ 您现在正在使用 Toastie，只需通过上述 PHP API 方法之一调用 Toastie，然后观察吐司出现在任何地方！享受吧！

在底层，这是动态渲染默认吐司设计，这意味着这个不能被覆盖 - 该功能保留给了下面的两种选项，所以如果您想要的话，请继续阅读。

这应该是那些只想让 Toastie 做所有工作的人的首选选项，这样您就可以坐下来再喝一杯咖啡。Ahhhhhhhh。

让我们继续。

使用单个样式/类型组件

这是使用 Blade 组件最困难但最定制的方法

<!-- my-view.blade.php -->

<!-- Will render a success toast when called -->
<x-toastie::success />

<!-- Will render an info toast when called -->
<x-toastie::info />

<!-- Will render a warning toast when called -->
<x-toastie::warning />

<!-- Will render an error toast when called -->
<x-toastie::error />

如您所见，这是高度可定制的，您可以将每个吐司放置在您希望渲染的不同位置。如果您想知道如何做，请跳到 “自定义吐司设计”。

但是，为了访问所有组件而只有四行代码是愚蠢的，这就是下一个组件出现的地方。

懒加载所有组件

这是在保留完全控制设计的同时最大化利用 Blade 组件的最简单方法

<!-- my-view.blade.php -->

<!-- Will render only the required style/type of toast when called -->
<x-toastie::stack />

按照设计，它只会渲染在您在上一个页面周期调用 Toastie 时所需的组件。

在底层，它只是直接拉入每个组件，这意味着如果您想覆盖样式，这将允许您在渲染所有吐司的同时使用您的新设计。如果您想知道如何做，请跳到 “自定义吐司设计”。

自定义吐司设计

所以，您不喜欢默认的 Toastie 设计吗？那么，我想我最好告诉您如何更改它。首先，我们需要将 Toastie 的视图集发布到您的项目中，以便您可以自定义它

php artisan vendor:publish \
    --provider="Othyn\\Toastie\\Providers\\ToastieServiceProvider" \
    --tag="toastie-views"

现在，您应该在项目的 resources/views/vendor/toastie/components 目录中看到许多视图文件，您可以随心所欲地编辑它们。

为了解释您看到的文件，按字母顺序排列

• error.blade.php
  • 描述：错误吐司组件。
  • 用法：在 x-toastie::error 和 x-toastie::stack 组件中使用。
• info.blade.php
  • 描述：信息吐司组件。
  • 用法：在 x-toastie::info 和 x-toastie::stack 组件中使用。
• shared.blade.php
  • 描述：共享吐司组件。
  • 用法：在 x-toastie::shared 组件中使用。
  • 额外：这是默认的动态设计，如果您想的话，可以覆盖它，但它并不是为此设计的。
• stack.blade.php
  • 描述：堆栈吐司组件。
  • 用法：在 x-toastie::stack 组件中使用。
  • 额外：根据调用情况，渲染 error、info、success 和 warning 组件。
• success.blade.php
  • 描述：成功吐司组件。
  • 用法：用于 x-toastie::success 和 x-toastie::stack 组件。
• warning.blade.php
  • 描述：警告弹窗组件。
  • 用法：用于 x-toastie::warning 和 x-toastie::stack 组件。

每个 Blade 组件都可以访问以下变量

• $aToastieShouldBeDisplayed
  • 类型：Bool
  • 描述：是否应该显示弹窗。
• $shouldBeDisplayed
  • 类型：Bool
  • 描述：实例的具体类型弹窗是否应该显示。
• $type
  • 类型：Othyn\Toastie\Enums\ToastieType
  • 描述：实例正在调用的 Toastie 类型。
• $message
  • 类型：string
  • 描述：要显示在弹窗中的消息。
• $shouldAutoDismiss
  • 类型：Bool
  • 描述：弹窗是否应该自动消失。
• $autoDismissInSeconds
  • 类型：Integer
  • 描述：弹窗从页面加载时开始自动消失需要多长时间（秒）。
• $autoDismissInMilliseconds
  • 类型：Integer
  • 描述：弹窗从页面加载时开始自动消失需要多长时间（毫秒）。
• $colour
  • 类型：string
  • 描述：组件应使用的 Tailwind 颜色类。
  • 注意：仅适用于默认 Shared Toastie 类型。
• $icon
  • 类型：string
  • 描述：组件应使用的 SVG 路径字符串来渲染弹窗图标。
  • 注意：仅适用于默认 Shared Toastie 类型。

🍞 贡献

请参阅贡献指南了解如何开始。感谢您的贡献！

该指南中详细说明了...

• ...如何使用问题。
• ...如何设置项目。
• ...应该使用哪些分支。
• ...提交应该如何格式化。
• ...如何提交拉取请求。
• ...在项目工具中构建；Make、Docker、测试、测试覆盖率、静态分析和代码审查。
• ...构建过程是否工作以及驱动它的自动化。

🧰 项目工具快速参考

为了帮助您管理项目，已放置了相当多的易于使用工具，所有这些工具都隐藏在 Make 和 Docker 之后，以尽可能使使用此项目变得顺利。

# Let's get things setup. This will run:
#  - A Docker Compose build.
#  - A Composer install via the now built project Docker container.
$ make setup

# ... happy few hours programming, adding cool new features and smashing bugs ...

# Lets make sure things are formatted correctly.
# This runs Pint (PHP-CS-Fixer) via the projects Docker container.
$ make lint

# Lets make sure things are implemented correctly.
# This runs PHPStan via the projects Docker container.
$ make stan

# Lets make sure things are still functioning as intended. This will:
#  - Run Pest (PHPUnit) and ensure all tests pass via the projects Docker container.
#  - Ensure that we are reaching the 100% code coverage target as part of that process.
$ make test

# If you want a shortcut to; lint, stan and then test all in one go via the projects Docker container
$ make all

# Finally, if you need access to the projects Docker container's shell
$ make shell

以上就是所有内容，去制作一些酷的东西并提交一个 PR！

⚠️ 许可证

在 MIT 许可证下分发。有关更多信息，请参阅LICENSE。

💎 致谢

在制作此项目过程中使用的一些有用的资源和库。

• Readme：Louis3797/awesome-readme-template
• Readme：ikatyang/emoji-cheat-sheet
• Readme：shields.io
• Logo：Toast SVG Vector 63 (CC Attribution License)
• 设计：Tail-kit
• 包：illuminate/support
• 包：orchestra/testbench
• 包：pestphp/pest
• 包：laravel/pint
• 包：phpstan/phpstan
• 灵感：（设计）Tailwind CSS Toast And Notification Example
• 灵感：（设计）Animated dynamic progress bar