README

预制的简单 Laravel Blade 邮件组件集合。

安装与设置

您可以通过 composer 安装此包

composer require bjnstnkvc/mail-components

包将自动注册其服务提供者。

用法

配置

使用以下命令发布组件的配置文件

php artisan vendor:publish --provider="Bjnstnkvc\MailComponents\MailComponentsServiceProvider" --tag=mail-config

这将发布一个名为 mail_components.php 的文件到您的配置目录中。

样式

使用以下命令发布组件的 CSS 文件

php artisan vendor:publish --provider="Bjnstnkvc\MailComponents\MailComponentsServiceProvider" --tag=mail-styles

这将把一个 mail-components.css 发布到 resources/views/vendor/mail/html/themes 目录。

主题

如果您想通过 Markdown 渲染邮件，您需要将 Mailable 的 theme 属性设置为 mail-components。

/**
 * Create a new message instance.
 */
public function __construct()
{
    $this->theme = 'mail-components';
}

或者，在您的 config/mail.php 文件中将 theme 属性设置为 mail-components

    'markdown' => [
        'theme' => 'mail-components',

        'paths' => [
            resource_path('views/vendor/mail'),
        ],
    ],

邮件组件

为了使用邮件组件，请从文档中使用标准的 Blade 组件语法。默认情况下，邮件组件可以使用 mail 前缀。

布局

布局组件是每封邮件的基础。除了创建一个将包含邮件内容的样板表格外，它还处理响应式媒体查询。

布局组件接受的属性列表如下

为了渲染组件，使用以下语法

<x-mail::layout>
    ...
</x-mail::layout>

如果您想向布局的 <head> 标签添加额外内容，使用以下语法

<x-mail::layout>
    <x-slot:head>
        ...
    </x-slot>
</x-mail::layout>

头部

头部组件接受的属性列表如下

为了渲染组件，使用以下语法

<x-mail::header />

如果您想向头部添加额外内容，使用以下语法

<x-mail::header>
    ...
</x-mail::header>

页脚

页脚组件接受的属性列表如下

为了渲染组件，使用以下语法

<x-mail::footer />

如果您想向头部添加额外内容，使用以下语法

<x-mail::footer>
    ...
</x-mail::footer>

内容

内容组件创建一个适合任何注入内容的样板 HTML 结构。

页脚组件接受的属性列表如下

为了渲染组件，使用以下语法

<x-mail::content>
    ...
</x-mail::content>

网格

网格组件创建一个适合任何注入 '网格状' 内容的样板 HTML 结构。它可以创建最多 4 个完全响应式的网格列。

网格组件接受的属性列表如下

为了渲染不同列数的网格组件，只需向组件中添加 columns 属性，后跟列数即可。

<x-mail::grid columns="2">
    ...
</x-mail::grid>

如果您的列包含简单文本，您也可以使用以下语法将其作为属性传递

<x-mail::grid columns="2" one="Lorem ipsum dolor sit amet..." two="Lorem ipsum dolor sit amet..." />

但是，如果您想注入更复杂的 HTML，请使用标准的 Blade 插槽语法

<x-mail::grid columns="2">
    <x-slot:one>
        <h1>Column 1 Title</h1>
        <p>Column 1 paragraph</p>
    </x-slot>
    <x-slot:two>
        <h1>Column 2 Title</h1>
        <p>Column 2 paragraph</p>
    </x-slot>
</x-mail::grid>

英雄

英雄组件创建一个适合任何注入 '英雄' 内容的样板 HTML 结构。

英雄组件接受的属性列表如下

为了渲染英雄组件，使用以下语法

<x-mail::hero background="https://via.placeholder.com/1200x800" title="Hello" subtitle="How are you doing?" button="Answer" button-url="{{ route('answer') }}" />

但是，如果您想注入更复杂的语法，请使用标准的 Blade 插槽语法

<x-mail::hero background="https://via.placeholder.com/1200x800">
    <x-slot:title>
        <h1>Title</h1>
    </x-slot>

    <x-slot:subtitle>
        <ol>
            <li>Item 1</li>
            <li>Item 2</li>
            <li>Item 3</li>
        </ol>
    </x-slot>

    <x-slot:button>
        <a class="button btn-black" href="#">Button</a>
    </x-slot>
</x-mail::hero>

副文本

副文本组件接受的属性列表如下

为了渲染组件，使用以下语法

<x-mail::subcopy>
    ...
</x-mail::subcopy>

表格

表格组件接受的属性列表如下

表格组件提供了三种方法来填充表格数据

字符串

<x-mail::table headers="First Name, Last Name, Email" columns="1:John|Doe|john.doe@example.com, 2:Jane|Doe|jane.doe@example.com" />

数组

$headers = ['First Name', 'Last Name', 'Email'];
$columns = [
    ['John', 'Doe', 'john.doe@example.com'],
    ['Jane', 'Doe', 'jane.doe@example.com'],
];

<x-mail::table row-index="false" :headers="$headers" :columns="$columns" />

在两种情况下，都会生成以下表格

模型

假设我们有一个包含以下数据的用户表

从控制器传递过来

return view('welcome', [
    'users' => User::all();
]);

为了与表格组件一起使用，使用以下语法

<x-form::table :model="$users" />

将生成以下表格

使用模型生成的表格将为模型的每个属性创建一个标题。例如，如果我们传递以下数据

return view('welcome', [
    'users' => User::get([
        'first_name', 
        'last_name', 
        'email', 
        'email_verified_at as verified_at'
    ]);
]);

到上面的相同blade中，我们将得到以下输出

表格组件提供了一个选项，通过添加row-index属性并将其设置为true来渲染带有行索引的行内容。

<x-form::table row-index="true" :model="$users" />

上面的组件将渲染以下表格

图像

图像组件接受的全部属性列表如下

为了渲染组件，使用以下语法

<x-mail::image />

默认情况下，渲染的图像不会超过其宽度，无论屏幕大小如何。如果您添加is-responsive属性并将其设置为true，则在较小的屏幕上图像将占满整个屏幕宽度。

默认情况下，图像组件被渲染为邮件部分，这意味着img标签被包裹在邮件内容组件中，这将导致图像占据其自己的表格行。

如果您想将图像作为另一个组件的一部分包含，或者简单地将其渲染为纯文本，请添加is-section属性并将其设置为false。

按钮

按钮组件接受的全部属性列表如下

为了渲染组件，使用以下语法

<x-mail::button />

如果您的按钮包含简单的文本/标题，您可以使用以下语法将其作为属性传递

<x-mail::button title="Button"/>

但是，如果您想注入更复杂的 HTML，请使用标准的 Blade 插槽语法

<x-mail::button>
    <h1>Button</h1>
</x-mail::button>

新行

新行组件接受的全部属性列表如下

为了渲染组件，使用以下语法

<x-mail::new-line />

示例

验证电子邮件

假设我们想要创建一个验证电子邮件，当用户成功注册时发送。

首先，我们将使用以下Artisan命令创建一个邮件类

php artisan make:mail VerificationMail

上面的命令将在app\Mail目录中创建一个与命令同名的VerificationMail.php邮件类。

下一步是将我们将在类中使用的数据附加到类中。

class VerificationMail extends Mailable
{
    /**
     * Create a new message instance.
     */
    public function __construct(public User $user, public string $email, public string $token)
    {
        // 
    }
    
    /**
     * Get the message envelope.
     */
    public function envelope(): Envelope
    {
        return new Envelope(
            from   : new Address('example@example.com', 'Example'),
            subject: 'Verify Email',
        );
    }

    /**
     * Get the message content definition.
     */
    public function content(): Content
    {
        return new Content(
            view: 'mail.verification-mail',
        );
    }
}

下一步是创建一个视图。在这个示例中，我们将在resources/views/emails目录中创建一个名为verify-email.blade.php的文件。

最后，我们将使用邮件组件为上述电子邮件创建HTML。

让我们从创建带有标题和页脚的基本布局开始。下面的Blade语法

<x-mail::layout title="Verify Email">
    <x-mail::header />
    
    <x-mail::footer />
</x-mail::layout>

将渲染以下HTML

接下来，我们将添加电子邮件内容

<x-mail::layout title="Verify Email">
    <x-mail::header />
    
    <x-mail::content background="#FFFFFF">
        <h1>Hello, {{ $user->first_name }}!</h1>
        <br>
        <p>Please click the button below to verify your email address.</p>
        <br>
        <x-mail::button url="{{ route('verify.email', ['user' => $user, 'token' => $token]) }}">Verify Email Address</x-mail::button>
        <br>
        <p>If you did not create an account, no further action is required.</p>
    </x-mail::content>
    
    <x-mail::footer />
</x-mail::layout>

这将生成以下HTML

我们将添加一个副标题，其中包含验证链接作为字符串，以防用户在通过按钮验证电子邮件时遇到麻烦。

<x-mail::layout title="Verify Email">
    <x-mail::header />
    
    <x-mail::content background="#FFFFFF">
        <h1>Hello, User!</h1>
        <br>
        <p>Please click the button below to verify your email address.</p>
        <br>
        <x-mail::button url="{{ route('verify.email', ['user' => $user, 'token' => $token]) }}">Verify Email Address</x-mail::button>
        <br>
        <p>If you did not create an account, no further action is required.</p>
    </x-mail::content>
    
    <x-mail::subcopy>
        If you're having trouble clicking the "Verify Email Address" button, copy and paste the URL below into your web browser:
        <strong>{{ route('verify.email', ['user' => $user, 'token' => $token]) }}</strong>
    </x-mail::subcopy>
    
    <x-mail::footer />
</x-mail::layout>

现在，我们的电子邮件看起来如下

自定义

配置

prefix - 邮件组件的前缀，默认为'mail'（例如）。
separator - 邮件组件的分隔符，默认为'::'（例如x-mail::button）。
layout - 包含邮件组件布局设置的数组。
- font_link - 邮件组件将使用的字体链接。（例如https://fonts.googleapis.com/css2?family=Roboto&display=swap）。
- font_family - 字体家族名称（例如Roboto）。
- background - 布局组件的背景颜色。
header - 包含邮件组件标题设置的数组。
- show - 确定标题邮件组件是否可见（默认为true）。
- logo - 标题logo（url或资源路径）。
- width - 标题logo宽度（如果没有传递，它将采用logo图像宽度）。
- height - 标题logo高度（如果没有传递，它将采用logo图像宽度）。
页脚 - 包含邮件组件页脚设置的数组。
- 显示 - 确定页脚邮件组件是否可见（默认为 true）。
- 显示版权 - 确定页脚邮件组件版权行是否可见（默认为 true）。
- 地址 - 您的公司街道地址。
- 城市 - 您的公司所在城市。
- 州 - 您的公司所在州。
- 邮编 - 您的公司邮政编码。
- 电话 - 您的公司电话号码。
内容 - 包含邮件组件内容设置的数组。
- 背景 - 内容组件的背景颜色。
网格 - 包含邮件组件网格设置的数组。
- 背景 - 网格组件的背景颜色。
- 间距 - 在网格与其他组件之间的间距渲染（选项：none、top、bottom、top, bottom）。
英雄 - 包含邮件组件英雄设置的数组。
- 背景 - 英雄组件的背景颜色。
- 高度 - 英雄组件的高度。
副标题 - 包含邮件组件副标题设置的数组。
- 背景 - 副标题组件的背景颜色。
表格 - 包含邮件组件表格设置的数组。
- 行索引 - 确定表格组件是否带有行索引列。
- 背景 - 表格组件的背景颜色。
- 表头背景 - 表格组件表头的背景颜色。
图像 - 包含邮件组件图像设置的数组。
- 响应式 - 确定图像组件是否响应。
- 作为部分 - 确定图像组件是否作为部分或普通图像渲染。
按钮 - 包含邮件组件按钮设置的数组。
- 宽度 - 按钮宽度（默认为 200）。
- 高度 - 按钮高度（默认为 40）。
- 颜色 - 按钮颜色（默认为 black）。
新行 - 包含邮件组件新行设置的数组。
- 高度 - 新行高度（默认为 16）。
- 背景 - 新行背景颜色

注意：在修改 .env 文件后，您可能需要使用 php artisan cache:clear 命令清除配置缓存。

发布

您可以使用 artisan 命令发布所有组件类和视图

php artisan components:publish

可选地，您可以传递组件名称作为参数，这将仅发布这些组件。

php artisan components:publish Header Footer Table

从现在起，您可以按自己的喜好更改已发布的组件类和视图。

恢复

如果您想恢复组件的默认设置，请使用以下 artisan 命令

php artisan components:restore

可选地，您可以传递组件名称作为参数，这将仅恢复这些组件。

php artisan components:restore Header Footer Table

此外，如果您想删除之前发布的组件类和视图，可以附加 --delete 选项

php artisan components:restore --delete

或

php artisan components:restore Header Footer Table --delete

注意：在发布或恢复组件后，您可能需要使用 php artisan cache:clear 命令清除配置缓存。

许可证

MIT 许可证（MIT）。请参阅许可证文件了解更多信息。

bjnstnkvc / mail-components

维护者

详细信息

README

安装与设置

用法

配置

样式

主题

邮件组件

布局

头部

页脚

内容

网格

英雄

副文本

表格

字符串

数组

模型

图像

按钮

新行

示例

验证电子邮件

自定义

配置

发布

恢复

许可证