Section schema（区块模式）

Section 支持 {% schema %} Liquid 标签。这个标签允许你定义一个区块的各种属性，比如区块名称、区块内的子模块（block）、以及供主题编辑器自定义使用的设置项。

Schema（结构）

每个 Section 只能包含一个 {% schema %} 标签，并且里面必须是有效的 JSON，只允许使用 Content（内容）部分列出的属性。
{% schema %} 标签可以放在 Section 文件中的任何地方，但不能嵌套在其他 Liquid 标签内部。

注意事项

如果有多个 {% schema %} 标签，或者把 {% schema %} 放在其他 Liquid 标签里面，会导致报错。

以下是一个合法的 Section schema 示例。每个属性的详细说明请参考 Content（内容）。

{% schema %}
{
  "name": "Slideshow",
  "tag": "section",
  "class": "slideshow",
  "limit": 1,
  "settings": [
    {
      "type": "text",
      "id": "title",
      "label": "Slideshow"
    }
  ],
  "max_blocks": 5,
  "blocks": [
    {
      "name": "Slide",
      "type": "slide",
      "settings": [
        {
          "type": "image_picker",
          "id": "image",
          "label": "Image"
        }
      ]
    }
  ],
  "presets": [
    {
      "name": "Slideshow",
      "settings": {
        "title": "Slideshow"
      },
      "blocks": [
        {
          "type": "slide"
        },
        {
          "type": "slide"
        }
      ]
    }
  ],
  "locales": {
    "en": {
      "title": "Slideshow"
    },
    "fr": {
      "title": "Diaporama"
    }
  },
  "enabled_on": {
    "templates": ["*"],
    "groups": ["footer"]
  }
}
{% endschema %}

内容（Content）

{% schema %} 里面可以包含以下属性：

name
tag
class
limit
settings
blocks
max_blocks
presets
default
locales

此外，还可以使用以下属性来控制 Section 的适用范围：

enabled_on：限定 Section 只能用于指定模板或分组
disabled_on：禁止 Section 用于指定模板或分组

注意

{% schema %} 是 Liquid 标签，但它不会输出内容，也不会解析内部的 Liquid 语法。
你还应该考虑让你的 Section 兼容 app blocks（应用区块），这样开发者可以让商家在不直接修改代码的情况下将应用内容添加到主题中。

各属性详细说明

name

name 属性定义了区块在主题编辑器中的标题。例如：

{% schema %}
{
  "name": "Slideshow"
}
{% endschema %}

效果：

tag

默认情况下，Shopify 渲染 Section 时会用 <div> 标签包裹，并加上唯一的 id：

<div id="shopify-section-[id]" class="shopify-section">
  // 区块内容
</div>

如果你不想使用 <div>，可以通过 tag 属性指定 HTML 标签。支持的值有：

article
aside
div
footer
header
section

示例：

{% schema %}
{
  "name": "Slideshow",
  "tag": "section"
}
{% endschema %}

生成：

<section id="shopify-section-[id]" class="shopify-section">
  // 区块内容
</section>

class

默认 Section 渲染时有 shopify-section 类名。你可以通过 class 属性额外添加类名：

{% schema %}
{
  "name": "Slideshow",
  "tag": "section",
  "class": "slideshow"
}
{% endschema %}

生成：

<section id="shopify-section-[id]" class="shopify-section slideshow">
  // 区块内容
</section>

limit

默认情况下，同一个 Section 可以在模板或分组中添加多次。
你可以通过 limit 限制只能添加 1 次或 2 次：

{% schema %}
{
  "name": "Slideshow",
  "tag": "section",
  "class": "slideshow",
  "limit": 1
}
{% endschema %}

settings

通过 settings 数组，你可以定义该 Section 支持哪些自定义设置。

示例：

{% schema %}
{
  "name": "Slideshow",
  "tag": "section",
  "class": "slideshow",
  "settings": [
    {
      "type": "text",
      "id": "header",
      "label": "Header"
    }
  ]
}
{% endschema %}

注意事项

每个设置的 id 必须是唯一的。
否则会导致错误。

如何访问 settings

可以通过 section 对象获取设置的值。

blocks

区块可以包含子模块（blocks），比如轮播图的每一张幻灯片。

每个 block 定义如下属性：

属性	描述	是否必填
`type`	Block 类型，自定义的标识符	是
`name`	Block 名称，出现在主题编辑器里	是
`limit`	限制这种 block 类型的数量	否
`settings`	这个 block 的设置项	否

示例：

{% schema %}
{
  "name": "Slideshow",
  "blocks": [
    {
      "name": "Slide",
      "type": "slide",
      "settings": [
        {
          "type": "image_picker",
          "id": "image",
          "label": "Image"
        }
      ]
    }
  ]
}
{% endschema %}

注意事项

每个 block 的 name 和 type 都要在同一个 section 内部唯一。
每个 setting 的 id 在 block 内部也必须唯一。

如何渲染 blocks

通过循环遍历 section.blocks 来渲染所有 block：

{% for block in section.blocks %}
  {% case block.type %}
    {% when 'slide' %}
      <div class="slide" {{ block.shopify_attributes }}>
        {{ block.settings.image | image_url: width: 2048 | image_tag }}
      </div>
    ...
  {% endcase %}
{% endfor %}

注意事项

不要依赖 block 的 id 固定值去写判断，因为 id 是动态生成的，随时可能变化。

错误示例：

{% for block in section.blocks %}
  {% if block.id == 'J6d9jV' %}
    <h1>{{ block.settings.heading }}</h1>
  {% endif %}
{% endfor %}

动态显示 block 标题

如果一个 block 的设置项有以下 id 名称之一，则在主题编辑器中，这个设置项的值会作为 block 的标题展示（按优先顺序）：

heading
title
text

如果没有，才使用 block 的 name。

示例：

"blocks": [
  {
    "name": "Announcement",
    "type": "announcement",
    "settings": [
      {
        "type": "text",
        "id": "heading",
        "default": "Welcome to our store",
        "label": "Heading"
      }
    ]
  }
]

效果是 sidebar 中标题显示为 Welcome to our store。

max_blocks

每个 Section 最多可以添加 50 个 block。
你可以通过 max_blocks 手动设置更低的上限。

示例：

{% schema %}
{
  "name": "Slideshow",
  "max_blocks": 5
}
{% endschema %}

静态区块（static blocks）不会占用这个数量限制。

presets

Presets 是 Section 的默认配置，用于让用户在编辑器里快速添加一个预设好的区块。

Presets 属性：

属性	描述	是否必填
`name`	预设的名称	是
`settings`	默认设置的值列表	否
`blocks`	默认包含哪些 blocks	否

示例：

{% schema %}
{
  "name": "Slideshow",
  "presets": [
    {
      "name": "Slideshow",
      "settings": {
        "title": "Slideshow"
      },
      "blocks": [
        {
          "type": "slide"
        },
        {
          "type": "slide"
        }
      ]
    }
  ]
}
{% endschema %}

default

default 属性用于为静态区块（static blocks）设置默认内容。

静态区块是指那些在代码中固定写死，而不是通过主题编辑器自由添加的 block。
default 会自动应用到模板中静态 block 上，以提供默认数据。

示例：

{% schema %}
{
  "name": "Slideshow",
  "blocks": [
    {
      "type": "slide",
      "name": "Slide",
      "settings": [
        {
          "type": "text",
          "id": "heading",
          "label": "Heading",
          "default": "Default heading"
        }
      ]
    }
  ],
  "default": {
    "blocks": {
      "static-slide": {
        "type": "slide",
        "settings": {
          "heading": "A default heading"
        }
      }
    }
  }
}
{% endschema %}

对应的静态 block 应该在 Section 的 Liquid 模板中这样写：

{% block 'slide' id: 'static-slide' %}
  <!-- 静态幻灯片内容 -->
{% endblock %}

注意事项

default 只会应用在静态 block 上，不影响动态 block。
default 的 key（例子里是 static-slide）必须和 id 保持一致。

locales

locales 属性用于给不同语言环境设置文本翻译。

它是一个对象，每个语言代码（比如 en、fr）下定义一组键值对。

示例：

{% schema %}
{
  "name": "Slideshow",
  "locales": {
    "en": {
      "title": "Slideshow"
    },
    "fr": {
      "title": "Diaporama"
    }
  }
}
{% endschema %}

这样在不同的语言环境下，区块的标题（title）就能显示对应翻译。

控制 Section 的可用范围

有时你希望某些 Section 只在特定页面、特定区域可见。
可以使用 enabled_on 或 disabled_on 来限制 Section 的适用范围。

enabled_on

enabled_on 限定只能在指定模板或分组里添加这个 Section。
格式：

"enabled_on": {
  "templates": ["template1", "template2"],
  "groups": ["header", "footer"]
}

支持的 templates：

使用模板文件名，比如 "product", "collection", "page.about"。
可以使用 "*" 通配符表示所有模板。

支持的 groups：

header
footer

示例：

{% schema %}
{
  "name": "Footer Banner",
  "enabled_on": {
    "templates": ["*"],
    "groups": ["footer"]
  }
}
{% endschema %}

表示这个 Section 只能添加到「Footer」区域。

disabled_on

disabled_on 和 enabled_on 相反，表示禁止在指定模板或分组里添加这个 Section。

示例：

{% schema %}
{
  "name": "Homepage Slideshow",
  "disabled_on": {
    "templates": ["product", "collection"]
  }
}
{% endschema %}

表示这个 Section 无法在商品页（product）和集合页（collection）中使用。

App blocks

如果你的 section 是 JSON template 或 section group 的一部分，那么你应该支持类型为 @app 的 block。 App blocks 允许应用开发者创建 block，让商家可以把应用内容添加到他们的主题里，而不需要直接编辑主题代码。

小结

Section 只能有一个 {% schema %} 标签，且必须是有效的 JSON。
settings 定义了可以自定义的选项，blocks 定义了子模块（比如幻灯片）。
presets 提供默认的区块布局，方便用户快速添加。
enabled_on 和 disabled_on 控制这个 Section 在主题编辑器中出现的位置。
记得用 locales 来做好国际化！