Shopify Section 开发实战：构建高可复用的模块化组件

先判断问题出现在哪里

Section 是 Shopify 页面构成的最小独立单元（就像乐高积木）。

核心逻辑是：封装视图（HTML）、样式（CSS）、交互（JS）与配置项（Schema）。

一个优秀的 Section 必须是“高内聚、低耦合”的。它不应该依赖页面上的其他元素，无论商家把它拖拽到首页、产品页还是博客页，它都能完整渲染并正常工作。通过编写 {% schema %}，你赋予了商家在后台自定义这个区块外观和数据的能力。

实战步骤

步骤 1：构建基础文件结构

操作路径：在 sections/ 目录下新建 custom-banner.liquid

1. 一个标准的 Section 文件包含三部分：
2. HTML 骨架：使用 Liquid 变量占位。
   <div class="custom-banner"> <h2>{{ section.settings.title }}</h2> </div>
3. Schema 配置：定义后台的输入表单。
4. 样式与脚本：按需引入。
   {{ 'custom-banner.css' | asset_url | stylesheet_tag }}

步骤 2：编写 {% schema %} 配置项

操作路径：在文件底部添加 schema 标签

1. Schema 是一个严格的 JSON 对象。

   {% schema %}
   {
     "name": "自定义 Banner",
     "tag": "section",
     "class": "section-custom-banner",
     "settings": [
       {
         "type": "text",
         "id": "title",
         "label": "大标题",
         "default": "欢迎来到我们的商店"
       },
       {
         "type": "color",
         "id": "bg_color",
         "label": "背景颜色",
         "default": "#ffffff"
       }
     ],
     "presets": [
       {
         "name": "自定义 Banner"
       }
     ]
   }
   {% endschema %}

2. presets 很重要：只有配置了 presets，这个 Section 才会出现在后台“添加区块（Add Section）”的列表中！

步骤 3：在前端渲染 Settings 数据

操作路径：在 HTML 中调用 section.settings

1. 商家在后台填写的数据，会保存在 section.settings 对象中。
2. 渲染文本：<h2>{{ section.settings.title | escape }}</h2>（注意使用 escape 过滤器防止 XSS 攻击）。
3. 渲染动态内联样式：

   <div style="background-color: {{ section.settings.bg_color }};">
     ...
   </div>

常见误区与处理方法

误区一：在 Section 中写死了全局唯一的 CSS ID

规避方法：很多前端习惯在写样式时使用 ID 选择器，比如 <div id="hero-banner">，然后在 CSS 里写 #hero-banner { margin-top: 20px; }。在 Shopify 中这是致命的！因为商家可能会在同一个页面里添加两个相同的 Banner Section。如果 ID 重复，不仅违反 W3C 标准，还会导致 JavaScript 绑定事件时只对第一个 Section 生效。在 Section 中，必须使用 Shopify 提供的动态 ID：id="Banner-{{ section.id }}"。 确保页面上每个 Section 实例的 ID 都是绝对唯一的。

误区二：忘记处理图片未上传的“空状态 (Empty State)”

规避方法：你在 Schema 里定义了一个图片上传器（type: "image_picker"），前端代码写了 <img src="{{ section.settings.image | image_url }}">。当商家刚把这个 Section 拖到页面上，还没来得及上传图片时，前端会渲染出一个破裂的图片图标（404 错误）。这显得主题很不专业。必须使用 {% if %} 进行判空处理，并提供优雅的占位图（Placeholder）。

{% if section.settings.image != blank %}
  <img src="{{ section.settings.image | image_url: width: 800 }}">
{% else %}
  {{ 'lifestyle-1' | placeholder_svg_tag: 'placeholder-svg' }}
{% endif %}

误区三：JavaScript 事件在主题编辑器中失效

规避方法：你写了一个精美的轮播图 Section，在本地测试完整运行。但商家在 Shopify 后台编辑器里，修改了一下轮播图的标题，保存后发现轮播图卡死了，无法滑动。这是因为 Shopify 编辑器在保存时，会通过 Ajax 局部重新渲染这个 Section 的 HTML，导致你之前绑定的 JS 事件（如 addEventListener）全部丢失！必须监听 Shopify 编辑器的专属生命周期事件。 在你的 JS 代码中，添加对 shopify:section:load 事件的监听，在 Section 重新渲染后，重新初始化你的轮播图脚本。

常见问题

学习「Shopify Section 开发实战：构建高可复用的模块化组件」前需要什么基础？

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

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

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

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

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

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

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

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

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

下一步阅读

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