Shopify Block 开发指南：实现灵活的区块嵌套与排版

先判断问题出现在哪里

如果 Section 是页面的积木，那么 Block 就是 Section 内部的微型积木。

核心逻辑是：提供颗粒度更细的排版自由。

想象一个“图文介绍” Section。如果你把标题、副标题、按钮全写死在 Section 的 Settings 里，商家就无法改变它们的上下顺序，也无法决定隐藏副标题。通过引入 Blocks，你可以让标题、文本、按钮变成一个个独立的子模块，商家可以在这个 Section 内部自由拖拽排序、增加或删除这些元素。

实战步骤

步骤 1：在 Schema 中定义 Blocks

操作路径：在 section 的 {% schema %} 中添加 blocks 数组

1. Blocks 的定义方式与 Section Settings 非常相似，但它们被包裹在 blocks 数组中。

   "blocks": [
     {
       "type": "heading",
       "name": "标题区块",
       "limit": 1, // 限制该类型 Block 最多只能添加 1 个
       "settings": [
         {
           "type": "text",
           "id": "heading_text",
           "label": "标题文字"
         }
       ]
     },
     {
       "type": "button",
       "name": "按钮区块",
       "settings": [
         {
           "type": "url",
           "id": "btn_link",
           "label": "按钮链接"
         }
       ]
     }
   ]

步骤 2：在前端循环渲染 Blocks

操作路径：在 HTML 中使用 for 循环和 case 语句

1. 商家在后台添加的 Blocks 顺序，保存在 section.blocks 数组中。

   <div class="section-wrapper">
     {% for block in section.blocks %}
       {% case block.type %}
         {% when 'heading' %}
           <h2 {{ block.shopify_attributes }}>{{ block.settings.heading_text }}</h2>
         {% when 'button' %}
           <a href="{{ block.settings.btn_link }}" {{ block.shopify_attributes }}>点击这里</a>
       {% endcase %}
     {% endfor %}
   </div>

2. 核心关键：{{ block.shopify_attributes }} 需要加在每个 block 的最外层 HTML 标签上。它允许 Shopify 后台编辑器识别这个 DOM 元素，实现点击左侧菜单时，右侧预览区自动滚动并高亮选中该区块。

步骤 3：配置默认的 Blocks (Presets)

操作路径：在 presets 数组中预设 blocks

1. 当商家第一次把这个 Section 拖到页面上时，你希望它默认就带有一个标题和一个按钮，而不是空空如也。

   "presets": [
     {
       "name": "图文介绍",
       "blocks": [
         { "type": "heading" },
         { "type": "button" }
       ]
     }
   ]

常见误区与处理方法

误区一：忘记添加 {{ block.shopify_attributes }} 导致编辑器体验极差

规避方法：这是新手最容易遗漏的细节。如果你在渲染 Block 时没有加上这个属性，前端页面看起来完全正常。但是，当商家在 Shopify 后台编辑器里点击左侧的“按钮区块”时，右侧的预览画面不会有任何反应（正常情况下应该自动滚动到按钮位置并出现蓝色高亮边框）。这会让商家觉得你的主题“卡住了”或存在 Bug。铁律：每一个 {% case block.type %} 下渲染的最外层 HTML 标签，需要无条件带上 {{ block.shopify_attributes }}。

误区二：没有对 Block 数量进行限制，导致页面排版崩溃

规避方法：你设计了一个“三列服务优势”的 Section，使用 Blocks 来让商家添加优势说明。商家觉得很好用，一口气添加了 10 个 Block！结果前端的 Flexbox 或 Grid 布局直接被撑爆，文字挤成一团。在 Schema 中，需要对 Block 的数量进行严格的防御性限制。 可以在 Section 级别设置 "max_blocks": 3，或者在具体的 Block 类型中设置 "limit": 1（例如一个 Section 里只能有一个主标题）。不要考验商家的克制力，用代码锁死排版的边界。

误区三：在 Block 内部执行耗时的全局查询

规避方法：你在一个“推荐产品”的 Block 中，写了一段 {% for product in collections['all'].products %} 的代码去遍历全站所有产品。如果商家在页面上添加了 5 个这样的 Block，Shopify 服务器就会执行 5 次非常耗时的全站遍历，导致页面渲染超时（Liquid Timeout Error）。Block 应该只负责渲染自身携带的 settings 数据。 任何复杂的全局数据查询，应该在 Section 级别完成，然后将结果传递给 Block，或者直接让商家在 Block 设置中通过 product_picker 精准选择需要展示的商品。

常见问题

学习「Shopify Block 开发指南：实现灵活的区块嵌套与排版」前需要什么基础？

建议先熟悉 HTML、CSS、基础 JavaScript 和 Shopify 后台结构。涉及 Liquid、Section、Schema 或主题工作流的内容，可以边读边在测试主题里练习，不要直接改线上主题。

可以直接在正在使用的线上主题里操作吗？

不建议。主题开发和结构调整应先在复制主题、开发主题或本地环境中完成，确认移动端、产品页、购物车和关键模板正常后，再发布到线上主题。

修改主题前最应该备份什么？

至少保留当前主题副本，并用 Git 记录代码变化。如果文章涉及主题编辑器配置，还要注意模板 JSON 和 settings_data.json 这类配置文件是否需要同步。

遇到教程和后台界面不一致怎么办？

优先以当前 Shopify 后台、主题代码和官方文档为准。Shopify 后台和 CLI 会持续更新，旧截图可用于理解路径，但不能替代当前界面提示。

这类主题开发内容适合什么时候上线到正式店铺？

当改动已经在测试主题中完成移动端、桌面端、产品页、集合页、购物车和速度检查后，再安排上线。影响结账、价格、库存或应用兼容的改动要单独回归。

下一步阅读

• Shopify 主题开发
• 独立站诊断
• 上线检查清单