JSON templates

JSON templates 让你可以通过使用 sections 来控制线上商店不同页面的外观和结构。

JSON templates 是一种数据文件，用来存储要渲染的 section 列表以及相关的设置。商家可以通过主题编辑器添加、删除或重新排序这些 section。

当某个页面使用 JSON template 渲染时，这些 section 会按照 order 属性 中的顺序被渲染，中间不会有额外的 HTML 标记。JSON template 最多可以渲染 25 个 section，每个 section 最多可以包含 50 个 block。

支持的功能

虽然 JSON templates 和 Liquid templates 在内容上不同，但它们依然是模板文件，并支持以下 Shopify 主题功能：

当你构建一个 JSON template 时，也应该同时构建一个包含核心功能的 section。比如说，如果你在做一个 list-collections 的 JSON template，那它就应该引用一个使用 collections object 的 section。

一个主题最多可以包含 1,000 个 JSON templates。超过这个限制后，就无法再创建新的 JSON template。

Schema

一个 JSON template 只能接受具有固定 schema 和属性列表的 JSON 文件。根对象应该包含以下属性：

属性 类型 是否必须 描述
layout String 或 false 否 渲染模板时要使用的 layout 文件名。比如指定 "full-width" 会渲染 layout/full-width.liquid。

默认 layout 是 theme.liquid。
如果设置为 false，则渲染时不使用 layout。没有 layout 的模板不能在主题编辑器中自定义。 | | wrapper | String | 否 | 模板中 section 的 HTML 包装元素。想了解更多请参考 The wrapper property。 | | sections | Object | 是 | 使用 section ID 作为键、section 数据作为值的对象。这个属性必须至少包含一个 section。
不能在模板中使用重复的 ID。
section 数据的格式和 settings_data.json 中的数据一样。详细内容请看 Section data。JSON template 最多可渲染 25 个 section，每个 section 最多 50 个 block。 | | order | Array | 是 | 一个 section ID 的数组，决定它们的渲染顺序。ID 必须存在于 sections 对象中，不能重复。 |

小提示

section 文件必须在它们的 schema 中定义 presets，才能通过主题编辑器添加到 JSON template 中。没有 preset 的 section 必须手动添加到 JSON 文件里，而且不能通过主题编辑器删除。

JSON template 命名规则

文件名必须是合法的 theme template type，也可以添加后缀表示 alternate template。例如，一个 product 模板可以叫做 product.json 或 product.alternate.json。

同一个模板只能存在 JSON 或 Liquid 版本，不能两个都有。例如，如果已经存在 product.liquid，那就不能创建 product.json。

wrapper 属性

wrapper 属性允许你在 JSON template 中所有 section 外面包一层 HTML 标签。可以使用的 HTML 标签有：

  • <div>
  • <main>
  • <section>

比如下面这个 JSON 文件中的 wrapper 属性会生成以下输出：

  1. {
  2.   "wrapper": "div#div_id.div_class[attribute-one=value]",
  3.   "sections": {
  4.     "main": {
  5.       "type": "product"
  6.     }
  7.   },
  8.   "order": [
  9.     "main"
  10.   ]
  11. }

输出结果：

  1. <div id="div_id" class="div_class" attribute-one="value">
  2.     <!-- product.json sections -->
  3. </div>

Section 数据

JSON template 的 sections 属性保存的是模板要渲染的 section 数据。这些 section 可以是 theme sections，也可以是 app sections。section 数据不能在不同的 JSON template 之间共享，所以每个 section 在模板中必须有唯一的 ID。

JSON template 最多渲染 25 个 section，每个 section 最多 50 个 block。

你可以在代码中添加 section，也可以通过主题编辑器添加。能否在主题编辑器中添加某个 section 可能会受限于 section schema 中的 enabled_on 或 disabled_on 属性。如果没有定义这些属性，那这个 section 可以添加到任何模板中。

下面是 section 数据格式的表格：

值 类型 是否必须 描述
<SectionID> String - section 的唯一 ID，只接受字母数字。
<SectionType> String 是 要渲染的 section 文件名（不带扩展名）。
<SectionDisabled> Boolean 否 如果是 true，这个 section 不会渲染出来，但可以在主题编辑器中设置。默认是 false。
<BlockID> String - block 的唯一 ID，只接受字母数字。
<BlockType> String 是 要渲染的 block 类型，这个定义在 section 文件的 schema 里。
<BlockOrder> Array 否 block ID 的数组，决定它们的渲染顺序。ID 必须存在于 blocks 对象中，不能重复。
<SettingID> String - section 或 block 中定义的某个设置 ID。
<SettingValue> 多种类型 - 这个设置的合法值。

比如说：

  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. }

举个例子，下面这个模板会在产品页面上渲染 product.liquid 和 product-recommendations.liquid 这两个 section 文件：

  1. {
  2.   "sections": {
  3.     "main": {
  4.       "type": "product",
  5.       "settings": {
  6.         "show_vendor": true
  7.       }
  8.     },
  9.     "recommendations": {
  10.       "type": "product-recommendations"
  11.     }
  12.   },
  13.   "order": [
  14.     "main",
  15.     "recommendations"
  16.   ]
  17. }

注意

任何不是 app section 的 section，如果被包含在模板中，那它必须存在于主题中。否则就会报错。

平台控制的设置

在主题编辑器里，Shopify 会在主题和 section 层级提供一个 自定义 CSS 设置。商家为某个 section 实例添加的自定义 CSS 会保存在 custom_css 属性中。

这个设置是为了让用户可以在不改动主题代码的情况下自定义店铺样式。作为主题开发者，你不应该添加这个设置，也不要修改它的值。你应该使用专用的 CSS 资源 和 stylesheet Liquid 标签，并通过 theme settings 提供 CSS 的自定义选项。

内容

一个 JSON template 只能接受符合固定 schema 和属性列表的 JSON 文件。想了解更多，请查看 JSON templates。