Magento2布局指令

本章内容

改变布局是Magento中自定义页面布局的两种方式之一（第二种方式是改变模板文件）。改变页面线框，修改页面布局文件；所有其它自定义的设置在页面配置或通过布局文件来执行。

使用布局指令来：

• 移动页面元素到另一个父元素
• 添加内容
• 删除页面元素

对于所有类型的布局文件来说基础指令集是相同的。这篇文章描述这些基本指令；至于如何在特定布局文件类型中使用的细节，请参阅下一篇文章。

常用布局指令

使用下面的布局指令来自定义你的布局：

• <block>
• <container>
• before和after属性
• <action>
• <referenceBlock>和<referenceContainer>
• <move>
• <update>
• <argument>

<block>

定义一个块

详细信息：块是页面输出呈现出不同内容的单元-一片信息，一个用户界面元素-任何客户视觉上可见的东西。块使用模板来生成HTML。模块的例子有：分类列表，迷你购物车，产品标签和产品列表。

属性	描述	值	必须性
class（类）	生成特定块的类名，这个类对应一个实际输出的块。	类名	是的
name（名字）	用于处理分配到该属性的块，在每个生成的页面中名字必须是唯一的。 如果没有指定就会自动以 ANONYMOUS_n的格式分配一个名字	0-9, A-Z, a-z, 下划线 (_), 点(.),破折号(-)。必须以字母开头。区分大小写。	否
before(在……之前）	用于块的位置。在相同父元素下，出于一个元素之前。在这个值中元素的名字或别名是指定的。使用破折号(-)将元素放在其他 元素之前。详细信息请看before和after属性	可能值:元素名或破折号(-)	否
after（在……之后）	用于块的位置。在相同父元素下，出于一个元素之后。在这个值中元素的名字或别名是指定的。使用破折号(-)将元素放在其他 元素之后。详细信息请看before和after属性	可能值:元素名或破折号(-)	否
模板	模板用来呈现该属性分配的块的功能。	模板文件名	否
as（别名）	作为父元素范围内的标识	0-9，A-Z，a-z，下划线(_)，点(.)，破折号(-)。区分大小写。	否
cacheable（可缓存）	定义块元素是否可缓存。这可以用于卡发目的并为页面动态元素提供服务	true（真）或false（假）	否

要传递参数，使用<argument></argument>指令。

<container>

用于支持其它元素（如块和容器）的没有内容的结构。

详细信息：在视图输出生成时容器渲染子元素。它可以为空或包含一组<container>和<block> 元素。

属性	描述	值	必须性
名字	用于处理分配到该属性的容器，在每个生成的页面中名字必须是唯一的。	0-9, A-Z, a-z, 下划线 (_), 点(.),破折号(-)。必须以字母开头。区分大小写。	是
标签	用于在浏览器展示的任意名字	任何	否
before	用于块的位置。在相同父元素下，出于一个元素之前。在这个值中元素的名字或别名是指定的。使用破折号(-)将元素放在其他 元素之前。详细信息请看before和after属性	可能值:元素名或破折号(-)	否
after（在……之后）	用于块的位置。在相同父元素下，出于一个元素之后。在这个值中元素的名字或别名是指定的。使用破折号(-)将元素放在其他 元素之后。详细信息请看before和after属性	可能值:元素名或破折号(-)	否
as（别名）	作为父元素范围内的标识	0-9，A-Z，a-z，下划线(_)，点(.)，破折号(-)。区分大小写。	no
output	定义是否输出根元素。如果指定元素将被添加到输出列表。（如果没有指定，父元素渲染他的子元素）	除toHtml外的任何值。推荐值为1。	否
htmlTag（html标签）	输出参数。如果指定，输出被抱进指定的Html标签中		任何可用的html5标签	否
htmlId	输出参数。如果指定，参数值被添加到包着的元素。如果没有包着的元素，该属性就没有效果。	任何可用的html5标签<id>值。	否
htmlClass（html类）	输出参数。如果指定，参数值被添加到包着的元素。如果没有包着的元素，该属性就没有效果。	任何可用的html5标签<class> 值。	否

布局中使用的示例：

...
<container name="div.sidebar.additional" htmlTag="div" htmlClass="sidebar sidebar-additional" after="div.sidebar.main">
    <container name="sidebar.additional" as="sidebar_additional" label="Sidebar Additional"/>
</container>
...

这将在页面布局中新加一行

before和after属性

为帮助你按特定的顺序排列元素以满足设计，搜索引擎优化，实用或其它要求，Magento提供了before和after布局属性。

这些可选属性可被用在布局XML文件中，在公用的父元素中控制顺序。下面的表格给出你使用before和after属性后的结果。第一张表使用一个块作为定位元素。

属性	值	描述
before	破折号(-)	在父节点中显示在其它元素之前。
before	元素名字	块在该名字的元素之前显示。
before	空值或元素名不存在	使用值after。如果值为空或者元素名不存在则被视为未被定位。
after	破折号(-)	在父节点中显示在其它元素之后。
after	元素名字	块在该名字的元素之后显示。
after	空值或元素名不存在	使用值before。如果值为空或者元素名不存在则被视为未被定位。

示例：

情况	结果
before和after属性都存在	after优先。
Both before and after属性都不存在或为空	元素被视为未定位。其它元素按指定位置定位。未被定位的元素随机出现在与其它元素定位不冲突的位置。
几个元素属性值before or after被设置为破折号(-)	所有元素显示在顶部 (或底部，属性为after时)，但该组顺序未被定义。
The before或after属性值中的元素不位于与该元素不在同一父节点中	元素处在一个随机位置但不与正确的元素位置冲突

<action>

<action>指令已被废弃。如果方法生成允许，使用<argument>来访问<block>或<referenceBlock>的公共API。

调用块API的公共方法：

详细信息：在块的生成过程中设置某个方法的执行。<action>结点必须位于块的结点范围。

示例：

<block class="Magento\Module\Block\Class" name="block">
    <action method="setText">
        <argument name="text" translate="true" xsi:type="string">Text</argument>
    </action>
    <action method="setEnabled">
        <argument name="enabled" xsi:type="boolean">true</argument>
    </action>
</block>

<action>子节点被翻译成块的方法参数。子节点的名称是任意的。如果<action>下有多个同名的子节点，那么这些子节点会作为数组被传递。

在上面的例子中<arg1>的值作为和<arg2>的值组成的array('one', 'two')中的第一个参数被传递。所有可用的方法取决于块的实现。

属性	描述	值	必须性
method	块的公用方法类名，在块的生成过程中被调用。	块方法名	是

要传递参数，使用<argument></argument>指令。

<referenceBlock>和<referenceContainer>

使用<referenceBlock>和<referenceContainer>来更新对应的<block>或<container>。例如，你如果使用<referenceBlock name="right">，那么你指向的目标块就是<block name="right">。

属性	描述	值	必须性
remove（移除）	允许移除或取消元素的输出，如果一个容器被移除，其子元素也被去除。	真/假	否
display（显示）	允许禁用特定块或容器及其孩子的渲染(都是通过引用直接设置)。块/容器及它们的孩子各自的PHP对象仍然被生产并可供操作 。	真/假	否

remove属性是可选的，默认值为false。在你的布局中设置remove属性值为false来取消块或容器的输出。例如：

<referenceBlock name="block.name" remove="true" />

display属性是可选的，默认值为true。你可以在你的布局中重写这个值。当remove属性为true时，display属性被忽略。例如：

<referenceContainer name="container.name" display="false" />

<ltmove>

设定声明的块或元素以特定的顺序作为另一个元素的子元素。

示例：

<move element="name.of.an.element" destination="name.of.destination.element" as="new_alias" after="name.of.element.after" before="name.of.element.before"/>

• 如果被移动的元素未被定义，则<move>被跳过。
• 如果as属性没有被定义，使用现有的元素别名。如果值不可用则用那么值来代替。
• 在布局生成过程中<move>指令在<remove>指令之前执行。这意味着任何元素移动到预定位置后都将被移除。

属性	描述	值	必须性
element（元素）	要移动的元素的名称。	元素名	是
destination（目的地）	目标父元素的名称	元素名	是
as（别名）	元素在新位置的别名。	0-9，A-Z，a-z，下划线(_)，点(.)，破折号(-)。区分大小写。	否
after | before	指定元素相对同级元素的位置。使用破折号（-）时元素在其它元素之后或之前。如果省略该值则元素在其它同级元素之后。	元素名	否

<update>

包含一个特定的布局文件，如下使用：

<update handle="{name_of_handle_to_include}"/>

指定的句柄被包括并递归执行。

<argument>

用于传递参数。

属性	描述	值	必须性
名称	参数名	唯一	是
xsi:type	参数类型	string|boolean|object|number|null|array	是
translate		真|假	否

要传递多个参数时，使用下面的指令：

<arguments>
   <argument></argument>
   <argument></argument>
   ...
</arguments>

传递的参数为数组时，使用下面的指令：

<argument>
   <item></item>
   <item></item>
   ...
</argument>

在布局中设置的参数值可以在模块中使用get{ArgumentName}()和has{ArgumentName}()方法调用。无论是否有值被设置，最终返回一个布尔值。从name属性获取{ArgumentName}的方法是：获取<argument name="some_string">值的方法名是getSomeString()。例如：在app/code/Magento/Theme/view/frontend/layout/default.xml布局文件中设置css_class的值：

...
<arguments>
    <argument name="css_class" xsi:type="string">header links</argument>
</arguments>
...

在app/code/Magento/Theme/view/frontend/templates/html/title.phtml文件中使用css_class的值：

...
$cssClass = $this->getCssClass() ? ' ' . $this->getCssClass() : '';
...

电商网站开发服务。