给 Shopify 主题加一个“卖点徽章”区块（section）

给 Shopify 主题加一个“卖点徽章”区块（section）：商家在主题编辑器里点“添加区块”，选 Shipping badges，然后添加 1–6 个徽章，每个徽章可以设置图标、标题和说明，还能调整每行显示几列。代码用官方 Shopify CLI 的 shopify theme check 检查过。

先看清成品

本机用 Shopify CLI 4.9.4 对一个最小主题执行 shopify theme check，结果是 5 files inspected with no offenses found。故意把翻译键写错后，它报了 TranslationKeyExists（见调试示例）。没有连接真实店铺（shopify theme dev / push 需要店铺和登录），区块在主题编辑器里的实际渲染效果没有看过。

注意：Shopify 的套餐价格、交易费和应用收费以官方价格页和你所在地区的条款为准，本文不列数字。只上架你有权销售的商品和有授权的图片；不要共享店铺员工账号，每个人用自己的员工账号登录。

做完之后你会得到什么？

需要准备哪些环境？

文件结构

28-shopify-A-src/theme/
├── sections/shipping-badges.liquid   # 本篇重点
├── assets/shipping-badges.css
├── locales/en.default.json
├── layout/theme.liquid               # 以下是让 theme check 能跑的最小主题
├── config/settings_schema.json
└── templates/index.json

第 1 步：区块代码

sections/shipping-badges.liquid：

{% comment %}
  卖点徽章区块：商家在主题编辑器里添加 1–6 个徽章（图标图片 + 标题 + 说明）。
{% endcomment %}
{{ 'shipping-badges.css' | asset_url | stylesheet_tag }}

<div class="badges page-width" style="--badge-columns: {{ section.settings.columns }};">
  {%- if section.settings.heading != blank -%}
    <h2 class="badges__heading">{{ section.settings.heading | escape }}</h2>
  {%- endif -%}
  <ul class="badges__list" role="list">
    {%- for block in section.blocks -%}
      <li class="badges__item" {{ block.shopify_attributes }}>
        {%- if block.settings.icon != blank -%}
          {{ block.settings.icon | image_url: width: 96 | image_tag: loading: 'lazy', width: 48, height: 48, alt: block.settings.title }}
        {%- endif -%}
        <h3 class="badges__title">{{ block.settings.title | escape }}</h3>
        {%- if block.settings.text != blank -%}
          <div class="badges__text">{{ block.settings.text }}</div>
        {%- endif -%}
      </li>
    {%- else -%}
      <li class="badges__item badges__item--empty">{{ 'sections.shipping_badges.empty' | t }}</li>
    {%- endfor -%}
  </ul>
</div>

{% schema %}
{
  "name": "Shipping badges",
  "tag": "section",
  "class": "section-shipping-badges",
  "max_blocks": 6,
  "settings": [
    { "type": "text", "id": "heading", "label": "Heading", "default": "Why shop with us" },
    { "type": "range", "id": "columns", "label": "Columns", "min": 2, "max": 4, "step": 1, "default": 3 }
  ],
  "blocks": [
    {
      "type": "badge",
      "name": "Badge",
      "settings": [
        { "type": "image_picker", "id": "icon", "label": "Icon" },
        { "type": "text", "id": "title", "label": "Title", "default": "Free returns" },
        { "type": "richtext", "id": "text", "label": "Text", "default": "<p>Within 30 days</p>" }
      ]
    }
  ],
  "presets": [
    { "name": "Shipping badges", "blocks": [ { "type": "badge" }, { "type": "badge" }, { "type": "badge" } ] }
  ]
}
{% endschema %}

要点：

• {{ block.shopify_attributes }} 让主题编辑器里点击徽章时能选中对应的块，不能省。
• presets 决定这个区块能不能出现在“添加区块”列表里，并且默认带 3 个徽章。
• 图片用 image_url + image_tag，Shopify 会生成合适的尺寸；alt 用的是徽章标题。
• 文本设置用 escape 输出；richtext 类型本身就是 HTML，直接输出。

第 2 步：样式和翻译

assets/shipping-badges.css：

.badges__list { display: grid; grid-template-columns: repeat(var(--badge-columns, 3), 1fr); gap: 1.5rem; list-style: none; padding: 0; }
.badges__item { text-align: center; }
.badges__title { margin: .5rem 0 .25rem; font-size: 1.1rem; }
@media (max-width: 749px) { .badges__list { grid-template-columns: 1fr 1fr; } }

locales/en.default.json（合并进主题已有的同名文件，不要整个替换）：

{"sections":{"shipping_badges":{"empty":"Add a badge block in the theme editor."}}}

第 3 步：检查

shopify theme check --path theme

本机输出：

5 files inspected with no offenses found.

第 4 步：在店铺里预览（本机未执行）

shopify theme dev --store your-store.myshopify.com

按 CLI 提示登录后，打开它给出的预览地址，在主题编辑器里点“添加区块”，选择 Shipping badges。确认没问题后，再用 shopify theme push --unpublished 推成一个新的未发布主题，不要直接覆盖线上主题。

检查结果：编辑器里能添加、删除、拖动徽章，改“Columns”后一行显示的数量随之变化。

调试示例

1. 翻译键拼错

把 sections.shipping_badges.empty 故意改成 empyt 再检查：

[error]: TranslationKeyExists
'sections.shipping_badges.empyt' does not have a matching entry in 'locales/en.default.json'
5 files inspected with 1 total offenses found across 1 files.

改回正确的键名后恢复为 0 个问题。

2. theme check 发现不了的错误

同一次测试里，还把 section.settings.heading 故意改成了 headng，theme check 没有报错。Liquid 读取不存在的设置只会得到空值，所以标题会悄悄消失。设置 ID 的拼写要在编辑器里实际预览一次才能确认。

常见问题

模板规则

• 一个区块对应一个 .liquid 文件和一个 CSS 文件，便于搬到其他主题。
• 所有能改的东西都放进 schema，不要在代码里写死文案。
• 每次修改后先运行 shopify theme check，再预览，最后推成未发布主题。

项目资源

Online Store 2.0 的区块就是“模板 + schema”：schema 写清楚了，商家就能自己改。theme check 能抓到翻译、语法这类错误，设置名拼错这种问题还得靠实际预览。