Section groups

Section group 是一个 JSON 数据文件，里面存了一组要被渲染的 sections 和 app blocks，还有它们对应的 settings。商家可以在 theme editor 里添加、移除或重新排序 section group 里的 sections。

你可以在 layout 文件里 引用一个 section group，这样就能在 layout 控制的区域（比如 header 或 footer）里支持 sections。

section group 里的 sections 和 app blocks 会按照 order 属性里指定的顺序进行渲染，中间不会插入其他 markup。一个 section group 最多可以渲染 25 个 sections，每个 section 最多可以有 50 个 blocks。

section group 里引用的 sections 和 app blocks 和 template 里引用的是同一套，应该遵循同样的 规范。

你也可以用 section group 来代替 static sections 来做 layout。了解怎么从 static sections 迁移到 section groups。

小提示

大多数主题里，section group 主要用在 header 和 footer。如果你想在其他地方（比如导航 sidebar）也用 section group，建议给 section group 起一个能体现用途的名字。

概览 - 图1

存放位置

section group 文件存放在 theme 的 sections 目录下：

  1. └─ theme
  2.     ...
  3.     ├─ layout
  4.     │  └─ theme.liquid
  5.     ├─ sections
  6.     │  ├─ footer-group.json
  7.     │  ├─ header.liquid
  8.     │  ├─ header-group.json
  9.     │  └─ ...
  10.     ...

Schema

section groups 必须是合法的 JSON 文件。根对象需要包含下面这些属性：

属性 类型 必填 描述
type String 是 section group 的类型。可选值：header、footer、aside，或者自定义类型，比如 custom.<name>，其中 <name> 是你自定义的唯一标识符。
name String 是 section group 的名字。最大长度 50 个字符。
sections Object 是 一个对象，使用 section ID 作为 key，section 的数据作为 value。可以留空。模板里不允许有重复的 ID。section data 的格式和 settings_data.json 里的格式一样。一个 JSON 模板最多可以渲染 25 个 sections，每个 section 最多 50 个 blocks。
order Array 是 一个数组，列出 sections 应该按什么顺序渲染。IDs 必须存在于 sections 对象里。可以留空。不允许有重复的 IDs。

例如：

  1. {
  2.  "type": "header",
  3.  "name": "Header Group",
  4.  "sections": {
  5.    "header": {
  6.      "type": "header",
  7.      "settings": {}
  8.    }
  9.  },
  10.  "order": ["header"]
  11. }

Section data

section groups 里的 sections 属性保存了要渲染的 sections 的数据。这些可以是 theme sections 或 app sections。section group 之间不能共享 section data，所以每个 section 的 ID 在组内必须是唯一的。

section groups 最多可以渲染 25 个 sections，每个 section 最多可以有 50 个 blocks。

你可以通过代码或者 theme editor 给 group 添加 sections。

下面是 section data 的格式说明：

值 类型 必填 描述
<SectionID> String - section 的唯一 ID，只能包含字母和数字。
<SectionType> String 是 要渲染的 section 文件名（不带扩展名）。
<SectionDisabled> Boolean 否 如果为 true，section 不渲染，但可以在 theme editor 里进行自定义。默认是 false。
<BlockID> String - block 的唯一 ID，只能包含字母和数字。
<BlockType> String 是 要渲染的 block 类型，在 section 文件的 schema 中定义。
<BlockOrder> Array 否 block IDs 的数组，按渲染顺序排列。IDs 必须存在于 blocks 对象中，不允许重复。
<SettingID> String - setting 的 ID，在 section 或 block 的 schema 里定义。
<SettingValue> (多种类型) - setting 的有效值。

比如：

  1. sections: {
  2.   <SectionID>: {
  3.     "type": <SectionType>,
  4.     "disabled": <SectionDisabled>,
  5.     "settings": {
  6.       <SettingID>: <SettingValue>
  7.     },
  8.     "blocks": {
  9.       <BlockID>: {
  10.         "type": <BlockType>,
  11.         "settings": {
  12.           <SettingID>: <SettingValue>
  13.         }
  14.       }
  15.     },
  16.     "block_order": <BlockOrder>
  17.   }
  18. }

举个例子，下面这个 section group 渲染了 quick-links 和 newsletter-signup 这两个 section 文件：

  1. {
  2.  "type": "footer",
  3.  "name": "Footer group",
  4.  "sections": {
  5.    "quick-links": {
  6.      "type": "quick-links",
  7.      "settings": {}
  8.    },
  9.    "newsletter-signup": {
  10.      "type": "newsletter-signup",
  11.      "settings": {}
  12.    }
  13.  },
  14.  "order": [
  15.     "newsletter-signup",
  16.     "quick-links"
  17.  ]
  18. }

注意

section group 里引用的 sections，如果不是 app sections，就必须在 theme 中实际存在。如果引用了一个不存在的 section，会导致错误。

使用方法

在使用 section groups 的时候，你需要了解怎么在 layout 中引用 section group，以及在 layout 中同时使用 section groups 和 static sections 的注意事项。

你也可以选择用 section groups 来渲染 template 内容。

Contextual section groups

当商家 根据不同买家上下文自定义 section group 时，会创建一个新的 contextual section group 文件。这个文件名是按照下面的格式命名的：header-group.context.<context-string>.json。

contextual section group 文件包含了你针对特定上下文对原 section group 的改动。模板开头会定义 context 和 parent 文件。context 的值可以是 "market": "market-handle" 或 "b2b": true。比如，下面的代码针对 market handle 为 ca 的情况，对 announcement-bar section 进行了定制：

  1. {
  2.   "context": {
  3.     "market": "ca"
  4.   },
  5.   "parent": "header-group.json",
  6.   "sections": {
  7.     "announcement-bar": {
  8.       "blocks": {
  9.         "announcement-bar-one": {
  10.           "settings": {
  11.             "text": "Free shipping for Canada!"
  12.           }
  13.         }
  14.       },
  15.       "settings": {
  16.         "change_slides_speed": 5
  17.       }
  18.     }
  19.   }
  20. }

在 layout 文件中引用 section group

使用 sections Liquid tag 把 section groups 渲染到 theme 的 layout 内容中。把 sections tag 放在你希望渲染的位置。

sections Liquid tag 的语法如下，<filename> 是 section group 文件名（不带扩展名）：

  1. {% sections '<filename>' %}

比如，如果你有一个 /sections/header-group.json 文件，里面放了主题的 header 内容（比如 header section 和 announcement bar section），那你可以在 theme.liquid 文件中引用它，这样在所有用到这个 layout 的页面上都会渲染 header：

  1. {% sections 'header-group' %}

Static section 和 section group 共存

尽量不要在同一个 layout 文件里同时用 section groups 和 static sections。如果必须同时用，建议在 section 名字里明确标注哪些是 static sections。