orba/magento2-module-style-guide

该软件包已被废弃，不再维护。作者建议使用lingaro/magento2-module-style-guide软件包。

Magento 2 风格指南模块

维护者

详细信息

github.com/ORBA/magento2-module-style-guide

源代码

问题

安装次数: 28,938

依赖关系: 0

建议者: 0

安全: 0

星标: 5

关注者: 5

分支: 2

公开问题: 1

语言:HTML

类型:magento2-module

1.0.4 2023-06-01 09:10 UTC

Requires

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

Beerware f8f1851d3e5024c919587831d53239b289802a8d

This package is auto-updated.

Last update: 2023-06-07 10:58:42 UTC

README

由Orba提供

1. 简介

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

它为商店添加以下页面：/style_guide。风格指南列出了通用块、小部件和 HTML 元素。目的是首先为这些元素设计样式，然后在它们之上构建特定的主题页面。风格指南也是一个为特定主题设计的任何自定义元素的地方，如花哨的滑块、手风琴等。由于依赖注入和主题继承系统，风格指南的每个条目都很容易自定义。很容易从风格指南中添加或删除条目。

该库是开源的。欢迎贡献！

2. 安装

推荐通过 Composer 安装此软件包。

composer require orba/magento2-module-style-guide

3. 风格指南部分概述

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

默认部分在 etc/frontend/di.xml 文件中定义为 Orba\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, 文本输入, 密码输入, 多行文本输入, 选择框, 单选按钮, 复选框, 提交按钮）。表单已添加基本验证。每个表单输入元素都有禁用版本。如果它们是为全球使用而设计的（例如，不同尺寸的输入），请毫不犹豫地添加自定义表单元素。

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

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="Orba\StyleGuide\ViewModel\SectionBlocksProvider">
        <arguments>
            <argument name="sections" xsi:type="array">
            </argument>
        </arguments>
    </virtualType>
</config>

Orba\StyleGuide\ViewModel\SectionBlocksProvider是风格指南页面的主要视图模型。所有定制将在此处注入。

在类顶部定义 ProjectVendor\StyleGuide\ViewModel\SectionBlocksProvider\YourThemeName 虚拟类型的原因是，这样您可以针对项目中使用的每个主题定义不同的风格指南。

要将自定义视图模型应用于特定主题，您需要在主题文件夹中创建以下布局 XML 文件：Orba_StyleGuide/layout/orba_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="orba.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="Orba\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="Orba\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/teplates/section/your_section.phtml，在 ProjectVendor_StyleGuide 模块中。下面是一个模板。

<?php

declare(strict_types=1);

/** @var \Orba\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="Orba\StyleGuide\Model\Section\Tooltips">
        <arguments>
            <argument name="isRemoved" xsi:type="boolean">true</argument>
        </arguments>
    </virtualType>
    <virtualType name="ProjectVendor\StyleGuide\ViewModel\SectionBlocksProvider\YourThemeName"
                 type="Orba\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="Orba\StyleGuide\ViewModel\SectionBlocksProvider">
        <arguments>
            <argument name="sections" xsi:type="array">
                <item name="tooltips" xsi:type="object" sortOrder="123">Orba\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="Orba\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="Orba\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="Orba\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="Orba\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>

完成此操作后，您需要添加一些用于颜色可视化的样式。将更改放在您的主题的 Orba_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="Orba\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="Orba\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="Orba\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="Orba\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. 骨架集成

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