thanhhua/magento2-basic-style-guide

Magento 2 Basic Style Guide

维护者

详细信息

github.com/HuaZilly/Magento2StyleGuide

源代码

问题

安装: 5

依赖: 0

建议者: 0

安全性: 0

星标: 0

关注者: 1

分支: 0

语言:HTML

类型:magento2-module

1.0.1 2024-06-10 09:39 UTC

Requires

  • php: ^7.4 || ^8.1
  • magento/framework: 103.0.*
  • magento/module-theme: 101.1.*
  • magento/module-ui: 101.2.*

MIT 97d26b929cbd66d49f0806c16ed5a261c8ddec4d

  • Thanh Hua <huathanh2k.woop@gmail.com>

This package is auto-updated.

Last update: 2024-09-10 10:33:39 UTC

README

由 [Thanh Hua] 编写

1. 简介

此模块旨在帮助 Magento 2 开发者构建一致的主题。

它向商店添加以下页面： /style_guide。样式指南包括

  • 所有元素都遵循核心主题
  • 通用块、小工具和 HTML 元素。
  • 样式指南也是一个地方，用于为特定主题设计的任何自定义元素，例如花哨的滑块、手风琴等。由于依赖注入和主题继承系统，样式指南中的每个项目都可以轻松自定义。添加或从样式指南中删除项目非常简单。

2. 安装

推荐通过 Composer 安装此包。

composer require thanhhua/magento2-basic-style-guide

3. 样式指南部分概述

样式指南的主要组件是部分。每个部分都有一个标签和一个 PHTML 模板。如果需要，部分可能有一个视图模型。部分可能被标记为已删除，以便不在样式指南页面上显示。

默认部分在 etc/frontend/di.xml 文件中定义为 ThanhHua\StyleGuide\ViewModel\SectionBlocksProvider 类的参数。

3.1. 布局

本节提供指向示例页面的链接，每个页面都设置了不同的页面布局：1列、2列左侧、2列右侧、3列。使用它们来设计如下内容：断点、列宽度、边距和填充、侧边栏块标题。

3.2. 颜色

本节提供主题颜色列表，并具有漂亮的可视化效果。其目的是在一个地方向开发者展示主要主题调色板。

3.3. 标题

本节提供 HTML 标题元素（h1、h2、h3、h4、h5、h6）。如果主题设计需要在不同页面上具有不同样式的相同级别标题，请不要犹豫添加自定义标题。

3.4. 段落

本节提供 HTML 段落元素（p）。如果它们为全局使用而设计，请不要犹豫添加自定义段落。

3.5. 无序列表

本节提供 HTML 无序列表元素（ul、li）。如果它们为全局使用而设计，请不要犹豫添加自定义无序列表。

3.5. 有序列表

本节提供 HTML 有序列表元素（ol、li）。如果它们为全局使用而设计，请不要犹豫添加自定义有序列表。

3.6. 链接

本节提供 HTML 链接（a）。如果它们为全局使用而设计，请不要犹豫添加自定义链接。

请记住为悬停、活动、焦点和已访问状态设计样式！

3.7. 按钮

本节提供 HTML 按钮（button）。如果它们为全局使用而设计，请不要犹豫添加自定义按钮。

请记住为悬停、活动、焦点和已访问状态设计样式！

3.8. 表单

本节提供 HTML 表单元素（form、fieldset、legend、label、文本输入、密码输入、textarea、select、radio、checkbox、提交按钮）。表单已添加基本验证。每个表单输入元素也有禁用版本。如果它们为全局使用而设计（例如，不同大小的输入），请不要犹豫添加自定义表单元素。

请记住为验证错误消息和输入的悬停、活动、焦点和错误状态设计样式！

3.9. 标签

本节提供原生的 Magento 标签小部件。如果您的主题不打算使用此小部件，可以将其删除或更改为自定义小部件。

3.10. 标签

本节提供了原生的Magento面包屑块。

3.11. 工具提示

本节提供了原生Magento工具提示的示例。如果你的主题不打算使用工具提示，请不要犹豫，移除它，或者将其更改为自定义实现/示例。

3.12. 消息

本节提供了原生Magento闪存消息。

注意：有些Magento模块在其模板文件中使用不同的消息HTML结构。为了保证一致性，在这种情况下，你应该覆盖这些模板并使用标准的HTML结构。

3.13. 分页

本节提供了原生Magento分页器。如果你的主题不打算使用分页器，请不要犹豫，移除它。

3.14. 弹窗

本节提供了原生Magento弹窗。如果它们是为全局使用而设计的，请不要犹豫，添加自定义弹窗。

3.15. 颜色

本节提供了主题图标列表及其可视化。其目的是在一个地方向开发者展示主要的主题图标调色板。

4. 自定义化

样式指南模块允许为您的主题创建高度可定制的样式指南。在本章中，我们将介绍自定义化技术。

4.1. 前置条件

创建自定义样式指南需要自定义模块。您可以根据需要命名它，但通常的做法是使用您项目的供应商名称后跟"StyleGuide"，例如："ProjectVendor_StyleGuide"。

样式指南模块在很大程度上依赖于Magento的DI系统。对于自定义化，您需要创建etc/frontend/di.xml文件。下面您可以找到一个示例。

<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:ObjectManager/etc/config.xsd">
    <virtualType name="ProjectVendor\StyleGuide\ViewModel\SectionBlocksProvider\YourThemeName"
                 type="ThanhHua\StyleGuide\ViewModel\SectionBlocksProvider">
        <arguments>
            <argument name="sections" xsi:type="array">
            </argument>
        </arguments>
    </virtualType>
</config>

ThanhHua\StyleGuide\ViewModel\SectionBlocksProvider是样式指南页面的主要视图模型。所有自定义化都会被注入到这里。

在类之上定义ProjectVendor\StyleGuide\ViewModel\SectionBlocksProvider\YourThemeName虚拟类型的原因是，这样您可以为项目中使用的每个主题定义不同的样式指南。

要将自定义视图模型应用到特定的主题，您需要在主题文件夹中创建以下布局XML文件：ThanhHua_StyleGuide/layout/thanhhua_style_guide_index_index.xml。下面您可以找到一个示例。

<?xml version="1.0" encoding="UTF-8"?>
<page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" layout="1column" xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd">
    <body>
        <referenceBlock name="
        thanhhua.style_guide">
            <arguments>
                <argument name="view_model" xsi:type="object">ProjectVendor\StyleGuide\ViewModel\SectionBlocksProvider\YourThemeName</argument>
            </arguments>
        </referenceBlock>
    </body>
</page>

您可以在样式指南模块的etc/frontend/di.xml文件中找到默认的样式指南配置。

4.2. 添加新章节

要将新章节添加到主题的样式指南中，您需要在etc/frontend/di.xml文件中定义它，并将其注入到您的自定义章节视图模型中。下面您可以找到一个示例。

<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:ObjectManager/etc/config.xsd">
    <virtualType name="ProjectVendor\StyleGuide\Model\Section\YourSection" type="ThanhHua\StyleGuide\Model\Section">
        <arguments>
            <argument name="title" xsi:type="string" translatable="true">Your section name</argument>
            <argument name="template" xsi:type="string">ProjectVendor_StyleGuide::section/your_section.phtml</argument>
            <!-- View model is optional. Add it only if you need to collect some data in section's template -->
            <argument name="viewModel" xsi:type="object">ProjectVendor\StyleGuide\ViewModel\YourSection</argument>
        </arguments>
    </virtualType>
    <virtualType name="ProjectVendor\StyleGuide\ViewModel\SectionBlocksProvider\YourThemeName"
                 type="ThanhHua\StyleGuide\ViewModel\SectionBlocksProvider">
        <arguments>
            <argument name="sections" xsi:type="array">
                <item name="your_section_code" xsi:type="object" sortOrder="100">ProjectVendor\StyleGuide\Model\Section\YourSection</item>
            </argument>
        </arguments>
    </virtualType>
</config>

注意"sections"数组中的"sortOrder"属性。多亏了它，您可以将自定义章节定位在已创建的章节中。

完成以上步骤后，您需要为在DI XML文件中定义的章节创建PHTML模板文件。在我们的例子中，它应该位于view/frontend/templates/section/your_section.phtml，位于ProjectVendor_StyleGuide模块中。下面您可以找到一个示例。

<?php

declare(strict_types=1);

/** @var \ThanhHua\StyleGuide\Block\Section $block */
/** @var \Magento\Framework\Escaper $escaper */
?>
<!-- Your code here -->

如果您为章节定义了视图模型，当然您需要在您的模块中创建它。下面您可以找到一个示例。

<?php

declare(strict_types=1);

namespace ProjectVendor\StyleGuide\ViewModel;

use Magento\Framework\View\Element\Block\ArgumentInterface;

class YourSection implements ArgumentInterface
{
    // Your code here
}

清理以下缓存以查看更改：config, full_page。

4.3. 删除章节

要从主题的样式指南中删除章节，您需要在etc/frontend/di.xml文件中覆盖它，并将更改注入到您的自定义章节视图模型中。下面您可以找到一个示例。

<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:ObjectManager/etc/config.xsd">
    <virtualType name="ProjectVendor\StyleGuide\Model\Section\Tooltips" type="ThanhHua\StyleGuide\Model\Section\Tooltips">
        <arguments>
            <argument name="isRemoved" xsi:type="boolean">true</argument>
        </arguments>
    </virtualType>
    <virtualType name="ProjectVendor\StyleGuide\ViewModel\SectionBlocksProvider\YourThemeName"
                 type="ThanhHua\StyleGuide\ViewModel\SectionBlocksProvider">
        <arguments>
            <argument name="sections" xsi:type="array">
                <item name="tooltips" xsi:type="object">ProjectVendor\StyleGuide\Model\Section\Tooltips</item>
            </argument>
        </arguments>
    </virtualType>
</config>

清理以下缓存以查看更改：config, full_page。

4.4. 覆盖现有章节

要覆盖现有章节，您只需在主题中覆盖其模板即可。

清理以下缓存以查看更改：full_page。

4.5. 改变现有章节的位置

要改变主题的样式指南中现有章节的位置，您需要更改etc/frontend/di.xml文件中章节的'sortOrder'属性。下面您可以找到一个示例。

<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:ObjectManager/etc/config.xsd">
    <virtualType name="ProjectVendor\StyleGuide\ViewModel\SectionBlocksProvider\YourThemeName"
                 type="ThanhHua\StyleGuide\ViewModel\SectionBlocksProvider">
        <arguments>
            <argument name="sections" xsi:type="array">
                <item name="tooltips" xsi:type="object" sortOrder="123">ThanhHua\StyleGuide\Model\Section\Tooltips</item>
            </argument>
        </arguments>
    </virtualType>
</config>

清理以下缓存以查看更改：config, full_page。

4.6. 向调色板添加颜色

要将颜色添加到主题的样式指南调色板中，您需要在您的etc/frontend/di.xml文件中创建自定义颜色提供者，将其添加到其中，并将提供者注入到您的自定义主题视图模型中。以下是一个示例。

<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:ObjectManager/etc/config.xsd">
    <!-- Colors -->
    <virtualType name="ProjectVendor\StyleGuide\Model\Color\YourThemeName\ColorName" type="ThanhHua\StyleGuide\Model\Color">
        <arguments>
            <argument name="code" xsi:type="string">color_code</argument>
            <argument name="label" xsi:type="string" translatable="true">label for visualization</argument>
            <argument name="cssColor" xsi:type="string">#000000</argument>
        </arguments>
    </virtualType>
    <virtualType name="ProjectVendor\StyleGuide\ViewModel\ColorsProvider\YourThemeName"
                 type="ThanhHua\StyleGuide\ViewModel\ColorsProvider">
        <arguments>
            <argument name="colors" xsi:type="array">
                <item name="color_code" xsi:type="object">ProjectVendor\StyleGuide\Model\Color\YourThemeName\ColorName</item>
            </argument>
        </arguments>
    </virtualType>
    <virtualType name="ProjectVendor\StyleGuide\Model\Section\Colors\YourThemeName"
                 type="ThanhHua\StyleGuide\Model\Section\Colors">
        <arguments>
            <argument name="viewModel" xsi:type="object">ProjectVendor\StyleGuide\ViewModel\ColorsProvider\YourThemeName</argument>
        </arguments>
    </virtualType>
    <!-- / Colors -->
    <virtualType name="ProjectVendor\StyleGuide\ViewModel\SectionBlocksProvider\YourThemeName"
                 type="ThanhHua\StyleGuide\ViewModel\SectionBlocksProvider">
        <arguments>
            <argument name="sections" xsi:type="array">
                <item name="colors" xsi:type="object">ProjectVendor\StyleGuide\Model\Section\Colors\YourThemeName</item>
            </argument>
        </arguments>
    </virtualType>
</config>

完成后，您需要添加一些颜色可视化的样式。将这些更改放置在您的主题的ThanhHua_StyleGuide/web/css/source/_extend.less文件中。以下是一个示例。

.style-guide-container {
  .style-guide-colors {
    .style-guide-color {
      &.style-guide-color-example {
        .style-guide-color-visualization {
          background-color: @color-color-name;
        }
      }
    }
  }
}

请记住，在您的主题变量文件中定义@color-color-name。

清理以下缓存以查看更改：config, full_page。

4.7. 添加图标到图标集

要将图标添加到主题的样式指南图标集中，您需要在您的etc/frontend/di.xml文件中创建自定义图标提供者，将其添加到其中，并将提供者注入到您的自定义主题视图模型中。以下是一个示例。

<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:ObjectManager/etc/config.xsd">
    <!-- Icons -->
    <virtualType name="ProjectVendor\StyleGuide\Model\Icon\YourThemeName\IconName" type="ThanhHua\StyleGuide\Model\Icon">
    <arguments>
        <argument name="name" xsi:type="string">icon-name</argument>
        <argument name="cssClass" xsi:type="string">icon-css-class</argument>
    </arguments>
    <virtualType name="ProjectVendor\StyleGuide\ViewModel\IconsProvider\YourThemeName"
                 type="ThanhHua\StyleGuide\ViewModel\IconsProvider">
        <arguments>
            <argument name="icons" xsi:type="array">
                <item name="icon-name" xsi:type="object">ProjectVendor\StyleGuide\Model\Icon\YourThemeName\IconName</item>
            </argument>
        </arguments>
    </virtualType>
    <virtualType name="ProjectVendor\StyleGuide\Model\Section\Icons\YourThemeName"
                 type="ThanhHua\StyleGuide\Model\Section\Icons">
        <arguments>
            <argument name="viewModel" xsi:type="object">ProjectVendor\StyleGuide\ViewModel\IconsProvider\YourThemeName</argument>
        </arguments>
    </virtualType>
    <!-- / Icons -->
    <virtualType name="ProjectVendor\StyleGuide\ViewModel\SectionBlocksProvider\YourThemeName"
                 type="ThanhHua\StyleGuide\ViewModel\SectionBlocksProvider">
        <arguments>
            <argument name="sections" xsi:type="array">
                <item name="icons" xsi:type="object">ProjectVendor\StyleGuide\Model\Section\Icons\YourThemeName</item>
            </argument>
        </arguments>
    </virtualType>
</config>

当然，您还需要在主题中添加正确的.icon-css-class样式。

清理以下缓存以查看更改：config, full_page。

5. 支持的Magento版本

目前，样式指南模块支持以下Magento版本

  • 2.4.x

6. 截图

6.1. 在Luma主题上应用样式指南

Style Guide applied on Luma theme

6.2. 在示例项目主题上应用并自定义样式指南

Style Guide applied and customized for exemplary project theme

7. 骨架集成

您可以为模块开发自动设置thanhhua Skeleton。为此，将Makefile.dist复制到Makefile，并将SKELETON变量填充为Skeleton的GIT仓库URL。然后，运行make。这将设置一个新的Skeleton项目到您的当前根目录，并将模块文件复制到source/packages/module-style-guide。要运行项目，只需运行make up。