README

网格

允许您在 Craft CMS 中内容管理 CSS Grid 的字段。

注意：此插件的许可证费用为 $49.00，通过 Craft Plugin Store 购买。

截至 2019 年 10 月：Grid 不会移植到 Craft 4。Grid 将在 Craft 3.x 中得到支持，直到 Craft 3 达到 EOL。

要求

此插件需要 Craft CMS 3.1.7 或更高版本。支持 CSS Grid Layout 和 CSS Custom Properties 的浏览器。有关浏览器支持更多信息，请参阅下面的浏览器支持。

安装

要安装插件，您可以在 Craft Plugin Store 中找到它，或遵循以下说明。

打开您的终端并转到您的 Craft 项目
```
 cd /path/to/project
```
然后告诉 Composer 加载插件
```
 composer require wbrowar/craft-grid
```
在控制面板中，转到设置→插件，并点击 Grid 的“安装”按钮。

网格概览

Grid 是一个字段，允许内容编辑通过矩阵和其他关系字段（条目、资产等）布局内容。

Grid 的设置允许您为不同的布局断点定义 CSS 网格规则。

内容编辑可以针对不同的屏幕尺寸优化内容布局。

灵活的 Twig 标签创建网格容器，并包裹所有网格项目，同时为每个布局生成 CSS。

新手 CSS Grid Layout？

如果您之前的项目中没有使用过 CSS Grid Layout，以下是一些资源，可以帮助您了解其概念

浏览器支持

CSS Grid 实际上最初是 Internet Explorer 10 的一个功能特性，然而，从那时起，一个更新的规范已经出现，并在现代浏览器中获得了支持。虽然支持 IE 规范是可能的——并且通常很简单——但 Grid 插件仅支持现代的非前缀规范。

为了确保提供正确的 CSS 支持，Grid 生成的所有 CSS 都被包装在一个功能查询（@supports）中。CSS 功能查询和 CSS Custom Properties（查询验证的是这些）在任何版本的 IE 上都不可用。

如果您需要为网格项目提供 CSS 降级方案，请查看以下这些优秀的文章

配置网格

目标字段

网格字段可以与基于元素的字段配对。在 Grid 中，这被称为“目标字段”。

当设置网格字段时，下拉字段从支持的字段类型列表中选择目标字段，因此最好在创建网格字段之前创建目标字段。

一旦使用网格字段并将数据存储在 CMS 中，就非常重要，不要更改目标字段。更改目标字段会导致丢失或损坏网格数据。

支持的字段类型

核心

资产
分类
条目
矩阵
用户

Craft Commerce

产品
变体

无需目标字段使用网格

当您想要布局的内容不是通过CMS管理时，网格也可以用作通用布局字段。例如，这可以用于通过元素查询收集的内容、表格字段中的条目和从解码的JSON字符串中提取的数据。

要使用不带目标字段的网格字段，请将字段设置页面上的“目标字段”选项设置为“None”。

当渲染不带目标字段的网格字段时，数据必须以数组的形式，并且必须传递到{% grid %}块中，具体请参阅高级Twig选项。

字段设置

布局

网格的CSS代码是先从移动端开始生成的，因此第一个网格布局是为了移动设备设计的，或者可以不使用任何其他断点来使用。要创建更多的网格布局，请在页面底部创建一个断点。

添加布局时，需要指定断点的min-width值。这是一个以像素为单位的数字。网格布局按照从最小到最大的断点min-width值进行排序。

列和行

列和行可以配置为固定布局，或者可以给编辑器提供根据需要添加或删除列和行的能力。当你更改列或行的模式时，你将看到定义网格的字段会发生变化。

自动模式

将行模式设置为auto类似于定义CSS的grid-auto-rows属性。内容编辑器将能够创建所需数量的行，布局将遵循你在网格自动行字段中放置的值。

网格自动行字段可以使用的任何有效的grid-auto-rows值。Mozilla在其网络文档页面上提供了一些很好的示例：MDN grid-auto-rows

注意：列模式的工作方式相同，示例值可以在这里找到：MDN grid-auto-columns

固定模式

当你想要定义确切的列布局时，将列模式设置为fixed将允许你定义每一列，就像grid-template-columns一样。对于每一列，输入一个有效的尺寸，你将看到网格预览反映你定义的列数。

你可以使用有效的尺寸单位——例如fr、px、%、em或rem——你甚至可以使用函数——如minmax()——或关键字值——如max-content。但是，创建多个列的值——如repeat()函数——不应在fixed模式下使用，因为它们将不会被网格字段解释。

对于固定行布局，行模式的工作方式相同。

项目可见性

默认情况下，未布局到网格字段布局的项目将使用CSS隐藏（display: none、visibility: hidden、opacity: 0等）。使用Item Visibility选项，您可以允许所有项目可见，并且它们将根据网格的CSS添加到您的网格中。

这可能在单列布局中很有用，您想按顺序显示所有网格项目，而无需花费时间将每个项目添加到布局中。

注意：当网格布局中没有更多空间时，项目有时可能出现在网格之外。

隐藏布局

如果项目可见性设置为Visible，您可以通过将隐藏布局设置为Yes来从输入字段中隐藏布局。

这对于应按目标字段排序的单列布局可能很有用。

注意：将“隐藏布局”设置为是仅隐藏输入字段中的布局。网格设置仍然应用，并且任何现有字段数据都将被渲染。

使用网格字段

当将网格字段添加到元素（例如条目）中时，它将查找其目标字段并显示填充目标字段的所有项。最初，字段显示最小布局的信息，并在字段顶部显示一个图标，允许您选择其他布局。

要将内容布局到网格上，请单击内容的标题开始。单击网格中的单元格以设置该单元格的起点，然后单击相同的单元格或另一个单元格以设置终点。

当内容被放置到网格上时，标题旁边将出现一个勾选标记。

提示：由于CSS Grid允许这样做，您可以在布局中重叠项目。目标字段中项目的顺序决定了哪些项目在前面，哪些在后面。

将网格添加到Twig模板中

要渲染网格字段，请将其放入您的Twig模板中。

{% grid entry.gridHandle as gridItems %}
    {% for item in gridItems %}
        {% griditem %}
            {# use item.content.fieldHandle to render grid item content #}
        {% endgriditem %}
    {% endfor %}
{% endgrid %}

grid 块要求您传入您的网格字段（entry.gridHandle）。网格将确定与网格字段关联的元素和目标字段，但这也可以设置（参见高级Twig选项）。grid 块创建一个HTML元素，并添加适当的类。
在grid块中，gridItems是一个可以设置为您喜欢的任何名称的变量。
gridItems代表目标字段中的所有内容——包括来自grid块的数据。使用for循环访问每个网格项。
griditem块创建一个具有正确类的HTML元素，以便您的布局正常工作。
可以通过{{ item.content.fieldHandle }}访问每个item的内容。例如，如果每个item.content都是一个条目，则{{ item.content.title }}将显示标题字段。
以下是在griditem块中处理的矩阵字段的示例。

{% grid entry.grid as gridItems %}
    {% for item in gridItems %}
        {% griditem %}
            {% switch item.content.type.handle %}
                {% case 'text' %}
                    <p>{{ item.content.myText }}</p>
                {% case 'image' %}
                    <img src="{{ item.content.myImage.one().url }}" alt="{{ item.content.myImage.one().title }}">
            {% endswitch %}
        {% endgriditem %}
    {% endfor %}
{% endgrid %}

高级Twig选项

当需要时，grid块和griditem块可以接受更多的参数和配置。

目标数组

要指定您的目标字段或为目标字段使用预加载，请在grid块中在您的网格字段之前添加目标字段和关键字using。

{% grid entry.relatedEntries.with['featuredImage'].all() using entry.grid as gridItems %}
    {# ... #}
{% endgrid %}

在此示例中，指定了entry.relatedEntries并使用了预加载来获取featuredImage资产。

注意：这必须以数组的形式提供，因此当传递元素条件时，使用.all()很重要。

修改网格容器

默认情况下，grid块被转换为带有预定义类的<div>标签。可以传入一个配置对象来修改该标签，添加类，并设置自定义属性。

{% grid entry.grid as gridItems with { attributes:"id='my_grid'" classes:"my classes", element:"nav", } %}
    {# ... #}
{% endgrid %}

修改网格项

griditem块为每个网格项创建一个<div>标签。可以传入一个配置对象来修改该标签，添加类，并设置自定义属性。

{% grid entry.grid as gridItems %}
    {% for item in gridItems %}
        {% griditem with { attributes:"@click='clickHandler'" classes:"my_grid__item", element:"a", } %}
            {# ... #}
        {% endgriditem %}
    {% endfor %}
{% endgrid %}

使用网格项辅助类

可以将辅助类添加到网格项中，以根据它们在每个布局中的位置协助对它们进行样式设计。

将helperClasses设置为true将为每个网格项添加匹配以下情况的类

由于所有这些类都可能产生不必要的标记，因此您可能希望传递一个仅包含您需要的类的数组，而不是布尔值。

辅助类示例

例如，在这张截图的网格字段中，如果您想知道“图像”块是否在右侧布局，以便您可以在图像上放置边框，辅助类可能会有所帮助。

通过将 helperClasses 设置为 ['right']，将添加一个类 grid__grid__page_content--right--640 到“图像”网格项（以及任何其他在任何布局中在右侧布局的网格项）。

将特定于每个网格布局的样式添加到CSS中，以匹配每个媒体查询的辅助类。

@media (min-width: 640px) and (max-width: 767px) {
    .grid__grid__page_content--right--640 {
        border-left: 2px solid rebeccapurple;
    }
}
@media (min-width: 768px) {
    .grid__grid__page_content--right--768 {
        border-left: 2px solid rebeccapurple;
    }
}

在这个示例布局中，只有640布局会显示边框，但如果768布局发生变化，此CSS已经准备好应用边框。

使用辅助类有一些注意事项

辅助类仅应用于已布局到网格字段中的网格项。
关于网格项位置的所有计算仅基于已布局到网格字段中的网格项。
如果布局的断点发生变化，辅助类将更改以反映新的断点值。
- 因此，需要更新自定义CSS或JavaScript选择器。
- 还需要更新CSS中的媒体查询以匹配新的断点值。

获取网格值

使用 $element->gridHandle（在PHP中）或 {{ element.gridHandle }}（在Twig中）访问网格字段值将为您提供Craft中存储的数据，但这是一种压缩形式，并不用于输出。

如果您想访问网格/目标对的值，PHP函数和Twig变量都可用。两者返回相同的信息数组，并且它们都需要您传入目标和网格值。

输出将包括

注意：PHP方法和twig变量都需要您将目标作为数组传入，因此在使用之前请使用 .all() 或预加载。

从模块或插件中获取网格值

$entry = Entry::find()
    ->with(['pageContent'])
    ->one();

$gridValue = Grid::$plugin->grid->getGridValue($entry->pageContent, $entry->grid);

从Twig获取网格值

{% set gridValue = craft.grid.value(entry.pageContent.all(), entry.grid) %}

由 Will Browar 提供。

感谢 Marc Hartwig 和 Andrew Welch 提供的建议和意见。

wbrowar / craft-grid

维护者

详细信息