动态数据源

Dynamic sources 允许商家将 input settings 连接到来自资源的数据，例如产品、集合、博客和页面，以及 metafields 和 metaobjects。

主题块可用的动态数据源

Theme blocks 是在主题级别定义的可重复使用块，可以嵌套。主题块的设置可以连接到以下来源的数据：

Source	Description
Template	与正在渲染的模板或页面关联的资源。
Section	作为 section schema 部分定义的 resource input setting，例如产品设置和集合设置。
Block	作为任何祖先块中定义的 resource input setting，例如产品设置和集合设置。
Liquid	明确通过 Liquid 的 `content_for` 标签传递给块的资源 drop。

访问最近的资源

主题块可以使用访问路径（如以下代码）访问动态数据源：

// 模板资源  
{{ product }}  
{{ collection }}  
// 区块设置  
{{ section.settings.featured_product }}  
// 块设置  
{{ block.settings.collection }}

主题块是可重复使用的，并且可以在各个区块和区块之间嵌套。因此，无法提前确定数据的来源。为了解决这个问题，可以使用 closest 访问路径来引用指定类型的最近资源。

closest 访问路径提供了一种方式，无论资源是来自模板、父级区块还是任何祖先块，都可以访问指定类型的最近资源。

注意

closest.<type> 仅可通过主题设置访问，并可作为这些设置的配置值。

示例

在此示例中，Image banner 区块包含一个 Product card 块，其中嵌套了 Media、Title 和 Price 块。它们连接到最近的产品，目前解析为 Product card 的产品设置，该设置为 Sunglasses。

如果从 Product card 中移除 Sunglasses 产品，连接到最近产品的嵌套块仍然指向 Product card 的产品设置，即使该设置为空。由于当前未设置最近的产品，嵌套块将显示占位符。

如果后续在 Product card 块中选择了 T-shirt 产品，其嵌套块将显示新的最近产品：T-shirt。

换句话说，连接到最近产品的设置会自动向上遍历其祖先链，按以下顺序获取最近产品的属性：

同一区块内的产品设置；
父级区块的产品设置；
当前区块的产品设置；
当前模板的产品。

在主题块预设中的使用

您可以在预设中将设置连接到特定类型的最近资源，从而访问最相关的资源（如产品、集合或页面）。

您可以配置 theme block preset settings，通过以下 Liquid 语法引用兼容资源类型的最近资源：{{closest.<type>}}。

当嵌套主题块连接到指定类型的最近资源时，最近资源的解析顺序基于以下规则：

指定类型的最近 Liquid 上下文设置器；
指定类型的最近祖先块设置；
指定类型的区块资源设置；
如果是指定类型，则为模板资源。

下表显示了每种资源类型的所有可能配置值：

Resource type	Configuration value
Product	`{{ closest.product }}`
Collection	`{{ closest.collection }}`
Article	`{{ closest.article }}`
Blog	`{{ closest.blog }}`
Page	`{{ closest.page }}`
Metaobject	`{{ closest.metaobject[<definition_type>] }}`

以下示例展示了一个价格块，其 product setting 设置为 closest.product。closest 键表示它能够从最近的祖先中访问最近的产品资源。

{{ block.settings.product.price | default: 1999 }}  
{% schema %}  
{  
  "name": "Product (price)",  
  "class": "price-block",  
  "settings": [{  
    "type": "product",  
    "id": "product",  
    "label": "Product"  
   }],  
  "presets": [{  
    "name": "Product (price)",  
    "settings": {  
      "product": "{{ closest.product }}"  
    }  
  }]  
}  
{% endschema %}

您可以在预设中配置主题块设置，指向特定资源类型的最近祖先，而无需指定具体位置。在祖先级别连接资源后，子块可以通过其设置从动态数据源访问可用资源的 properties。

在以下示例中，文本、价格和产品媒体块通过 {{ closest.product }} 访问最近的产品资源：

{% schema %}  
{  
  "name": "Card",  
  "blocks": [{"type": "@theme"}],  
  "presets": [  
    {  
      "name": "Product Card",  
      "blocks": [  
        {  
          "type": "group",  
          "blocks": [  
            {  
              "type": "text",  
              "settings": {  
                "text": "<p>{{ closest.product.title }}</p>"  
              }  
            },  
            {  
              "type": "price",  
              "settings": {  
                "product": "{{ closest.product }}"  
              }  
            },  
            {  
              "type": "product-medias",  
              "settings": {  
                "product": "{{ closest.product }}"  
              }  
            }  
          ]  
        }  
      ]  
    }  
  ]  
}  
{% endschema %}

预设插入到区块或区块后，数据以 JSON 格式存储如下：

{  
  "sections": {  
    "custom_section_1": {  
      "type": "custom-section",  
      "blocks": {  
        "group_1": {  
          "blocks": {  
            "text_1": {  
              "type": "text",  
              "settings": {  
                "text": "<p>{{ closest.product.title }}</p>"  
              }  
            },  
            "price_1": {  
              "type": "price",  
              "settings": {  
                "product": "{{ closest.product }}"  
              }  
            },  
            "product_medias_1": {  
              "type": "product-medias",  
              "settings": {  
                "product": "{{ closest.product }}"  
              }  
            }  
          },  
          "block_order": [  
            "text_1",  
            "price_1",  
            "product_medias_1"  
          ]  
        }  
      },  
      "block_order": ["group_1"]  
    }  
  },  
  "order": ["custom_section_1"]  
}

使用 closest 在 Liquid 中向下传递资源

主题块设置可以直接通过 content_for Liquid 标签访问在 Liquid 中设置的最近资源。资源可以通过参数直接传递到 content_for 标签，该参数指定资源的类型。

下表显示了哪些资源类型可以通过 Liquid 的 content_for 标签传递：

Resource type	Syntax
Product	`{% content_for "blocks", closest.product: <Product Drop> %}`
Collection	`{% content_for "blocks", closest.collection: <Collection Drop> %}`
Article	`{% content_for "blocks", closest.article: <ArticleDrop> %}`
Blog	`{% content_for "blocks", closest.blog: <BlogDrop> %}`
Page	`{% content_for "blocks", closest.page: <PageDrop> %}`
Metaobject	`{% content_for "blocks", closest.metaobject.<definition_type>: <MetaobjectDrop> %}`

用于渲染 static blocks 的 {% content_for "block" %} 标签也支持使用相同语法为上述所有资源类型传递上下文。

注意

如果资源类型不匹配以下参数之一，则会返回错误。

示例

在 Liquid 中，常见的用例是将资源传递给嵌套块（nested blocks），例如遍历集合中的产品时。我们需要将当前迭代的产品传递给 content_for 标签，以便嵌套块可以通过 {{ closest.product }} 访问产品资源。

设置

为了让商家更方便地自定义主题，你可以使用 JSON 创建设置，商家可以通过主题编辑器访问这些设置。

你可以在主题、区块（section）或块（block）层级提供设置。设置可以是固定的（如信息元素）或交互式的（如下拉菜单）。设置值可以是静态的，也可以使用动态源渲染上下文相关的值。

暴露设置可以让你的主题更具可定制性，从而更好地表达商家的品牌。它还能让主题更灵活，以应对商家的各种用例。

子类型

设置分为两类：

分类	描述
输入设置	可以存储值并由应用用户配置的设置。
侧边栏设置	无法存储值且不可由应用用户配置的设置。它们是信息元素，用于为你的输入设置提供详细说明和清晰度。

位置

你可以在以下位置创建设置：

config > settings_schema.json
使用区块的 {% schema %} 标签的 sections 文件夹中的区块文件

└── theme  
    ├── config  
    |   ├── settings_schema.json  
    |   ...  
    ├── sections  
    |   ├── main_product.liquid  
    |   ├── another_section_file.liquid  
    |   ...  
    ...

settings_schema.json

settings_schema.json 文件控制主题编辑器中 主题设置 区域的内容。此文件中的设置会转化为全局主题设置，可以通过 Liquid settings 对象访问。

区块 schema

区块的 {% schema %} 标签是创建区块设置和块设置的地方。这些设置可以通过 section 对象和 block 对象的 settings 属性分别访问。

Schema

设置以 JSON 的 settings 属性定义，并作为父级对象的一部分。该属性接受一个设置数组。输入设置和侧边栏设置都使用标准 schema 属性。你可以在以下部分找到这些属性的详细描述：

{  
  ...  
  "settings": [  
    {  
      "type": "header",  
      "content": "My settings"  
    },  
    {  
      "type": "text",  
      "id": "my_id",  
      "label": "My setting label",  
      "default": "Enter text here"  
    },  
    {  
      "type": "select",  
      "id": "layout_style",  
      "label": "type",  
      "options": [  
        {  
          "value": "flex",  
          "label": "Stack"  
        },  
        {  
          "value": "grid",  
          "label": "Grid"  
        }  
      ],  
      "default": "flex"  
    },  
    ...  
  }  
}

使用方法

在使用设置时，你需要熟悉以下内容：

访问设置值
检查设置值的格式
为设置使用动态源

访问设置

根据创建位置，你可以通过以下 Liquid 对象访问设置：

注意

settings 对象中的设置可以在 Liquid 主题资源中访问。

要访问特定设置，请将相关设置的 id 属性附加到要访问的对象上。

例如，如果你在每个 Liquid 对象中实现了以下设置：

{  
  "type": "text",  
  "id": "message",  
  "label": "Message",  
  "default": "Hello!"  
}

那么以下 Liquid 会生成以下输出：

// 设置  
消息: {{ settings.message }}  
// 区块  
消息: {{ section.settings.message }}  
// 块  
消息: {{ block.settings.message }}

// 设置  
消息: Hello!  
// 区块  
消息: Hello!  
// 块  
消息: Hello!

检查设置值的格式

引用设置时，始终检查值是否符合预期格式。任何没有自动默认值的设置可能没有值，这会转化为一个空字符串。

例如，如果你有一个 id 为 message 的设置，则根据值的不同，以下 Liquid 会生成以下输出：

// 没有值  
设置: {{ settings.message }}  
// 有值  
设置: {{ settings.message }}

// 没有值  
设置:  
// 有值  
设置: Message value

你可以使用 blank 运算符检查值是否为空字符串。例如：

{% unless settings.message == blank %}  
  {{ settings.message }}  
{% endunless %}

基于资源的设置

为了避免空字符串，请检查值是否符合预期格式。可能没有选择资源、所选资源不存在，或所选资源已被隐藏。

例如，如果你有以下 page 类型的设置：

{  
  "type": "page",  
  "id": "page",  
  "label": "Page"  
}

那么你可以像以下这样检查空值：

{% if settings.page != blank %}  
  {{ settings.page.title }}  
  {{ settings.page.content }}  
{% else %}  
  未选择页面，或选择了无效页面。  
{% endif %}

提示

基于资源的设置并不总是返回资源对象。要了解更多，请参考旧版基于资源的设置。

旧版基于资源的设置

过去，基于资源的设置会返回关联资源的 handle，你需要通过该 handle 在 Liquid 中访问实际对象。

例如，如果你有以下产品设置，则需要像以下这样访问产品对象：

{  
  "type": "product",  
  "id": "product",  
  "label": "Product"  
}

{% unless settings.product == blank %}  
  {% assign product = all_products[settings.product] %}  
  {% if product %}  
    {{ product.title }} - {{ product.price }}  
  {% else %}  
    未选择产品，或选择了无效产品。  
  {% endif %}  
{% endunless %}

动态源

包含在 JSON 模板中的区块和块的设置，商家可以根据设置类型选择连接一个或多个动态源到该设置。

了解更多关于动态源的信息。

平台控制的设置

在主题编辑器中，Shopify 在主题和区块层级暴露了一个自定义 CSS 设置。你不能在你的设置 schema 中添加或隐藏此设置。

商家使用此设置添加的任何自定义 CSS 都存储在 custom_css 属性中，要么在 JSON 模板的 section 属性中，要么在 settings_data.json 的 platform_customizations 对象中。

此设置旨在让用户在不编辑主题代码的情况下自定义商店的外观和感觉。作为主题开发者，你不应该添加此设置，或在设置后编辑其值。相反，你应该使用专用的 CSS 资源和 stylesheet Liquid 标签，并通过这些区域使用主题设置引入 CSS 的自定义选项。

翻译设置

你可以根据在线商店的活动语言翻译设置 schema 的各种属性。这些翻译存储在 schema 语言文件中。

Shopify 主题开发文档 - 帮助手册 - 教程

概览