README

总的来说，你只是布局中的另一块砖

composer require corrivate/magento2-layout-bricks

现代前端框架采用可重用组件，如按钮、输入字段和卡片。它们使用如 Tailwind 之类的实用 CSS 来进行样式设计。将一打类堆叠在主按钮上是可以的，因为你只需构建一次。

Magento 并没有自带这些功能。许多模板都非常 大，如果你谈到 UI 组件，人们会对你做出 交叉 XML 的手势。

这个包是一种让事情变得更好的方法。使用小型匿名组件而无需麻烦。它深受 Laravel 匿名 blade 组件的启发。在 Magento 中，我们前端模板的单位是块。匿名块是一个 砖块。

以下是一个 phtml 模板示例

<?php declare(strict_types=1);
/** @var \Magento\Framework\View\Element\Template $block */
/** @var \Magento\Framework\Escaper $escaper */
/** @var \Corrivate\LayoutBricks\Model\Mason $mason */
?>

<form method="post" action="/newsletter/subscribe">
<?= $mason('cms.block', props: ['block_id' => 'newsletter-explanation']) ?>

<?= $mason('ExampleCorp_ExampleModule::theme/input/text.phtml', [
    'required', 
    'class' => 'rounded-md text-stone-800 bg-stone-100', 
    'placeholder' => 'joe@examplecorp.com'
]) ?>

<?= $mason('btn-primary', attributes: ['type' => 'submit'], props: ['label' => __('Save')]) ?>
</form>

它是如何工作的？

$mason 对象被全局注入到每个 .phtml 模板中。它只有一个方法，__invoke()，它会将一个完整渲染的子块输出为字符串。所以它本质上是一种紧凑、便捷的方式来做到这一点

<?= $block
    ->getLayout()
    ->createBlock(\Magento\Framework\View\Element\Template::class)
    ->setTemplate($template) 
?>

这已经很好了，因为我们仍然在使用 Magento 的模板引擎

• 我们可以调用小型模板，而无需使用大量样板代码。现在，为单个按钮制作模板变得可行。因此，我们可以在整个网站上重用相同的按钮外观和感觉。如果按钮实际上有很多实用 CSS 类，这非常有帮助。嗨 Tailwind。
• 我们可以制作一个基础组件库作为可重用模块。
• 我们仍然有机会使用 Magento 的主题覆盖。我们可以在网站或单个店铺中更改按钮的外观。但因为我们正在到处重用按钮模板，所以我们可以在一个地方更改它，并将更改应用于所有地方。

但还有更多

• 您可以为组件设置默认的 HTML 属性（例如类），并根据上下文注入额外的属性。它们将被合并，新属性将覆盖默认属性。
• 您可以将属性注入到组件中，为它们提供数据。

例如，考虑 cms.block 砖块

<?= $mason('cms.block', 
        attributes: ['class' => 'border-2 border-stone-400 rounded-lg'], 
        props: ['block_id' => 'text-block']) 
?>

这将渲染 ID 为 'text-block' 的 CMS 块，但将其包围在一个带有灰色圆角的 div 中。

别名

别名详细说明

您可以通过两种方式放置砖块

• 完全引用 Magento 模板路径

<?= $mason('Corrivate_LayoutBricks::cms/block.phtml', props: ['block_id' => 'test-block']) ?>

• 为它创建一个 别名，以便您可以更简洁地引用它

<?= $mason('cms.block', props: ['block_id' => 'test-block']) ?>

别名详细说明

属性

属性详细说明

$mason 对象调用的方法接受一个属性数组。例如

<?= $mason('input.text', attributes: [
    'required', 
    'disabled' => false, 
    'class' => 'text-black', 
    'placeholder' => 'your input please', 
    'name' => 'user_comment'
]) ?>

在砖块模板中，这将可用作 BrickAttributesBag，例如具有以下默认属性/值

<input <?= $attributes->default([
    'class' => 
    'bg-white', 
    'disabled' => true, 
    'type' => 'text'
]) ?> />

这将导致以下 HTML 在默认值和您的自定义输入合并后的结果

<input class="bg-white text-black" 
       type="text" 
       required 
       placeholder="your input please" 
       name="user_comment"/>

属性详细说明

属性

属性详细说明

属性用于将数据传递给砖块。例如，如果您正在制作一个用于渲染“产品卡”的砖块，您将传递需要显示的产品

<?= $mason('product-cart', props: ['product' => $product]) ?>

在砖块模板中，属性通过自动存在的 $props 变量可用

<?php declare(strict_types=1);
/** @var \Magento\Framework\View\Element\Template $block */
/** @var \Magento\Framework\Escaper $escaper */
/** @var \Corrivate\LayoutBricks\Model\BrickAttributesBag $attributes */
/** @var \Corrivate\LayoutBricks\Model\BrickPropsBag $props */
?>

<div class="border-2 border-color-stone-600 rounded-md">
    <?= $props['product']->getSku() ?>
</div>

$props 变量不是一个数组，但它实现了 ArrayAccess 接口，以提供对其内容的访问。

$props 变量还具有 $props->default([]) 方法，因此您可以提供默认（标量）属性。您始终可以从父模板中覆盖这些默认值。

$props 对象还具有 $props->expect([]) 方法，这允许您指定期望的属性及其数据类型，从而可以采用更高级的类型安全性。

属性详细说明

转义器

使用 $escaper 过滤来自数据库或用户输入的原始数据输出对于防止各种攻击非常重要。有关此内容的官方文档：官方文档。

然而，$mason() 的输出是另一个已经生成 HTML 的块的输出。因此，调用 $mason() 时不应进行转义，但在实现您的砖块功能的 PHTML 模板内部，您应正常使用它。

空的 PHTML 砖块模板

只需将其复制粘贴到文件中，然后开始设计

<?php declare(strict_types=1);
/** @var \Magento\Framework\View\Element\Template $block */
/** @var \Magento\Framework\Escaper $escaper */
/** @var \Corrivate\LayoutBricks\Model\BrickAttributesBag $attributes */
/** @var \Corrivate\LayoutBricks\Model\BrickPropsBag $props */

// For Hyva users:
/** @var \Hyva\Theme\Model\ViewModelRegistry $viewModels */

$props->default([
    // you can supply default scalar values for your props
])->expect([
    // specify propName => type for your props
]);
?>


<div <?= $attributes->default(['class' => '']) ?>>

</div>

Corrivate

(en.wiktionary.org)

词源

来自拉丁语 corrivatus，是 corrivare 的过去分词（"使…流动"）。

动词

corrivate （第三人称单数现在时 corrivates，现在分词 corrivating，简单过去时和过去分词 corrivated）

（已废弃）使…流动，如同从几条溪流中抽取的水。