Block schema

Theme blocks 支持 {% schema %} Liquid 标签。这个标签用于定义以下块属性和设置：

这些属性和设置允许在主题编辑器中对块进行不同的自定义选项和预配置。

以下是一个块 schema 示例，它通过 blocks 属性支持嵌套块，定义了一些背景相关的 settings，并通过 presets 属性组合了这些设置的不同变体：

  1. {% schema %}
  2. {
  3.   "name": "Slide",
  4.   "blocks": [{"type": "@app"}, {"type": "@theme"}],
  5.   "settings": [
  6.     {
  7.       "type": "image_picker",
  8.       "id": "image",
  9.       "label": "Background image"
  10.     },
  11.     {
  12.       "type": "color_background",
  13.       "id": "background",
  14.       "label": "Background color"
  15.     }
  16.   ],
  17.   "presets": [
  18.     {
  19.       "name": "Slide",
  20.       "settings": {
  21.         "background": "#000000"
  22.       },
  23.       "blocks": [
  24.         {
  25.           "type": "text",
  26.           "settings": {
  27.             "text": "This is a slide!"
  28.           }
  29.         }
  30.       ]
  31.     }
  32.   ]
  33. }
  34. {% endschema %}

每个块只能包含一个 {% schema %} 标签，且必须仅包含有效 JSON，且只能使用下面列出的属性。schema 标签可以放置在块文件的任何位置，但不能嵌套在另一个 Liquid 标签内。它不会输出其内容，也不会渲染其中包含的任何 Liquid。

警告

包含多个 {% schema %} 标签，或将其放置在另一个 Liquid 标签内，会导致错误。

name

name 属性决定了在主题编辑器中显示的块标题。例如，以下 schema 返回以下输出：

  1. {% schema %}
  2. {
  3.   "name": "Slide"
  4. }
  5. {% endschema %}

在主题编辑器中显示动态块标题

在特定情况下，主题编辑器可以将输入设置值显示为块标题，以帮助商家在主题编辑器侧边栏中识别和重新排列块。

主题编辑器会检查块中设置的 id 值，以确定最佳的块标题。

主题编辑器按照以下优先顺序使用具有以下 id 值的设置：

  1. heading
  2. title
  3. text

如果没有匹配的 id 值的设置，则使用块名称作为标题。

例如，以下块具有 text 设置 id，将在侧边栏中显示标题 Welcome to our store。

  1. {
  2.   "name": "Text",
  3.   "settings": [
  4.     {
  5.       "type": "text",
  6.       "id": "text",
  7.       "default": "Welcome to our store",
  8.       "label": "Content"
  9.     }
  10.   ]
  11. }

settings

你可以创建块特定的 settings，以通过 settings 对象让商家自定义块：

  1. {% schema %}
  2. {
  3.   "name": "Slide",
  4.   "settings": [
  5.     {
  6.       "type": "image_picker",
  7.       "id": "image",
  8.       "label": "Background image"
  9.     },
  10.     {
  11.       "type": "color_background",
  12.       "id": "background",
  13.       "label": "Background color"
  14.     }
  15.   ]
  16. }
  17. {% endschema %}

警告

所有块设置 ID 必须在每个块内唯一。在块内重复的 ID 会抛出错误。

访问块设置

可以通过 block 对象访问块设置。更多信息请参阅 Access settings。

blocks

主题块可以通过其 schema 的 blocks 属性接受其他应用和主题块作为子块：

  1. {% schema %}
  2. {
  3.   "name": "Slide",
  4.   "blocks": [{"type": "@app"}, {"type": "@theme"}]
  5. }
  6. {% endschema %}

"@app" 类型表示此块接受应用块。App blocks 允许应用开发者创建块，让商家无需直接编辑主题代码即可将应用内容添加到主题中。

"@theme" 类型表示此块兼容主题中 /blocks 文件夹内的其他主题定义块。

主题块也可以通过显式引用单独访问。

  1. {% schema %}
  2. {
  3.   "name": "Slideshow",
  4.   "blocks": [{"type": "@app"}, {"type": "slide"}]
  5. }
  6. {% endschema %}

注意

与可以通过 schema 的 blocks 属性定义本地块的部分不同，主题块不能在其 schema 的 blocks 属性中定义本地块。

渲染嵌套块

可以通过使用 {% content_for 'blocks' %} Liquid 标签渲染块的子块：

  1. <div class="slide">
  2.   {% content_for 'blocks' %}
  3. </div>

在上面的示例中，每个块的内容通过 {% content_for 'blocks' %} 标签按 JSON 模板 中存储的顺序输出。

提示

主题块最多可以嵌套 8 层，不包括部分层级。

presets

预设是块的默认配置，允许商家通过主题编辑器轻松地将块添加到 JSON 模板中。一个块可以有多个不同的预设，以各种配置组合其设置。此外，块的预设可以引用其他子块，并以任意数量的配置组合它们。

预设有以下属性：

presets 属性 | 属性 | 描述 | 必需 | | —- | —- | —- | | name | 预设名称，显示在主题编辑器的 添加部分 选择器和侧边栏中，并在添加部分时持久化到 JSON 模板中。 | 是 | | settings | 要填充的任何设置的默认值列表。每个条目应包括设置名称和值。 | 否 | | blocks | 要包含的子块列表。每个条目应是一个具有 type 和 settings 属性的对象。type 属性值应反映要包含的块类型，settings 对象应与上述 settings 属性格式相同。name 属性是可选的，其值在商家将块添加到页面时显示在主题编辑器中。 | 否 |

以下是一个在块中包含预设的示例，假设主题中还有一个位于 /blocks/text.liquid Liquid 文件中的文本块：

  1. {% schema %}
  2. {
  3.   "name": "Slide",
  4.   "blocks": [{"type": "@app"}, {"type": "@theme"}],
  5.   "settings": [
  6.     {
  7.       "type": "image_picker",
  8.       "id": "image",
  9.       "label": "Background image"
  10.     },
  11.     {
  12.       "type": "color_background",
  13.       "id": "background",
  14.       "label": "Background color"
  15.     }
  16.   ],
  17.   "presets": [
  18.     {
  19.       "name": "Slide",
  20.       "settings": {
  21.         "background": "#000000"
  22.       },
  23.       "blocks": [
  24.         {
  25.           "type": "text",
  26.           "settings": {
  27.             "text": "This is a slide!"
  28.           }
  29.         }
  30.       ]
  31.     }
  32.   ]
  33. }
  34. {% endschema %}

tag

默认情况下，当 Shopify 渲染一个块时，它会被包裹在一个带有唯一 id 属性的 <div> 元素中：

  1. <div id="shopify-block-[id]" class="shopify-block">
  2.   // 块内容的输出
  3. </div>

如果你不想使用 <div>，则可以通过 tag 属性指定要使用的 HTML 元素类型。

例如，以下 schema 返回以下输出：

  1. {% schema %}
  2. {
  3.   "name": "Image",
  4.   "tag": "picture"
  5. }
  6. {% endschema %}
  1. <picture id="shopify-block-[id]" class="shopify-block">
  2.   // 块内容的输出
  3. </picture>

提示

tag 属性接受任何字符串，最多 50 个字符。它也可以用于渲染自定义 HTML 元素。

不带包装器的块渲染

在某些高级用例中，你可能需要对传递给标签和属性的控制有更多灵活性。例如，根据块的设置动态设置标签或类名。在这些场景中，可以通过将 tag 属性设置为 null 来渲染不带包装器的块。

当 tag 属性设置为 null 时，Shopify 不会将块的内容包裹在包装器元素中，而是直接输出块的内容。

警告

使用 "tag": null 的块应在同一个 Liquid 文件中包含一个顶级 HTML 标签。只有单个 HTML 元素可以标记为 {{ block.shopify_attributes }}。此元素应是文件中最顶层的 HTML 元素。这是为了确保当商家重新排序块时，主题编辑器可以移动整个块的标记到新索引，而不会留下孤立的 HTML 元素。

  1. <{{ block.settings.tag }} class=”heading” {{ block.shopify_attributes }}>
  2.   ...
  3. </{{ block.settings.tag }}>
  5. {% schema %}
  6. {
  7.   "name": "Heading",
  8.   "tag": null,
  9.   "settings": [
  10.     {
  11.       "type": "select",
  12.       "id": "heading_size",
  13.       "label": "Heading size",
  14.       "options": [
  15.         {
  16.           "value": "h3",
  17.           "label": "Small"
  18.         },
  19.         {
  20.           "value": "h2",
  21.           "label": "Medium"
  22.         },
  23.         {
  24.           "value": "h1",
  25.           "label": "Large"
  26.         }
  27.       ]
  28.     }
  29.   ]
  30. }
  31. {% endschema %}
  1. <h3 class=”heading”>
  2.   ...
  3. </h3>

为了使块与主题编辑器兼容，顶级 HTML 元素必须标记为 {{ block.shopify_attributes }} Liquid 标签。这会添加必要的数据属性，以便主题编辑器识别块。Shopify 的主题编辑器使用此属性通过其 JavaScript API 识别块。

注意

当 Shopify 渲染块的包装器时，它会自动为你添加此属性。但当 tag 属性设置为 null 时，你必须确保块的顶级 HTML 元素包含此属性，以确保与主题编辑器的兼容性。

class

当 Shopify 渲染一个块时，它会被包裹在一个带有 shopify-block 类的 HTML 元素中。你可以通过使用 class 属性追加其他类：

  1. {% schema %}
  2. {
  3.   "name": "Slide",
  4.   "class": "slide"
  5. }
  6. {% endschema %}

输出

  1. <div id="shopify-block-[id]" class="shopify-block slide">
  2.   // 块内容的输出
  3. </div>