Shopify 应用区块开发：产品页接入与验收

要在 Shopify 产品页的指定位置加入可配置功能，可以用主题应用扩展（Theme app extension）中的应用区块（app block）。本文以“商家输入一段产品说明”为最小示例：开发者提供配置字段，商家在主题编辑器中添加、排序并保存，最后在同一主题和产品模板上检查结果。

先确定这段说明确实需要由应用提供；需求、数据权限与维护责任可参照定制 Shopify 插件的需求与发布 QA。本例只读取区块配置，不调用订单、客户或库存 API；它展示接入方法，不代表店铺已完成部署或业务效果测试。

先确认产品模板和目标区段支持应用区块

准备一个 Shopify 应用项目、具有应用开发权限的账号、含测试产品的开发店，以及支持应用区块的 Online Store 2.0 主题。按官方前提配置 Shopify CLI（3.0 或更高版本）、Ruby 与 Bundler 等开发依赖，并使用 JSON 模板的兼容主题；仅看到“在线商店”入口，还不足以证明目标区段能接收区块。参见官方开发前提。

目标区段或主题区块的 schema 必须允许 @app，并实际渲染应用区块。使用主题区块的实现可以通过 content_for 'blocks' 渲染；使用区段内定义区块的实现，需要在遍历区块时处理 @app 并渲染它。开发者应核对宿主主题的实现，商家可以查主题文档或询问主题开发者。技术条件见官方主题应用区块说明，编辑器支持条件见帮助中心。

先记下要编辑的主题、产品使用的模板及目标区段名称。应用安装后，应用区块不会自动加入模板；接下来的“添加区块”步骤决定它出现在哪里。这个行为由应用区块配置文档明确说明。

创建扩展并写入最小产品说明区块

在应用项目目录执行 shopify app generate extension，选择 Theme app extension 并命名扩展。生成后，在该扩展目录的 blocks/ 中新建 product-note.liquid。文件属于应用扩展，不是宿主主题的 sections/ 文件。目录与生成步骤分别见扩展目录结构和官方创建步骤。

{% if block.settings.message != blank %}
  <p>{{ block.settings.message | escape }}</p>
{% endif %}

{% schema %}
{
  "name": "t:blocks.note.name",
  "target": "section",
  "enabled_on": {
    "templates": ["product"]
  },
  "settings": [
    {
      "type": "text",
      "id": "message",
      "label": "t:blocks.note.message"
    }
  ]
}
{% endschema %}

target: "section" 定义应用区块；enabled_on 将本例限制在产品模板中。settings 里的 message 是商家可输入的文字，Liquid 通过 block.settings.message 读取它。schema 支持的属性见官方 schema 契约。

本例在字段为空时不输出段落；有内容时使用 escape，把输入中的 HTML 特殊字符转义。这样，商家输入的 <b>clarification</b> 会作为文字显示，而不是加粗标签。转义行为见Liquid escape 文档。

补齐编辑器标签，并进入开发预览

在同一扩展的 locales/en.default.schema.json 中加入以下键；文件已有内容时，合并键值并保留原有翻译。本例的区块名是 Product note，配置字段名是 Message。

{
  "blocks": {
    "note": {
      "name": "Product note",
      "message": "Message"
    }
  }
}

t: 引用的是编辑器 schema 翻译。这里翻译区块名和字段标签，产品页正文仍来自商家输入的 message。扩展的 schema locale 与前台 locale 用途不同，见扩展 locales 说明；引用格式见schema 翻译规则。

保持 JSON 严格合法，不加入注释或尾随逗号。在应用项目运行 shopify app build，处理构建检查报告；再运行 shopify app dev --theme 主题ID，指定准备好的开发店测试主题，用 Google Chrome 打开 CLI 提供的预览入口；当前主题应用扩展的开发预览仅支持该浏览器。官方教程说明，不指定主题时 CLI 会向开发店上传 Dawn；明确主题 ID 有助于确保后面的添加和检查落在预定主题上。步骤见开发预览与构建检查。

在主题编辑器添加、输入、排序并保存

开发预览按 CLI 提供的入口打开测试主题；已部署的应用则从 Shopify 后台的 Online Store 找到目标主题，点击 Edit theme。以下使用桌面编辑器，操作依据官方添加区块步骤。

1. 进入预定产品模板，选中支持应用区块的目标区段。
2. 点击 Add block，在 Apps 中选择本应用的 Product note。
3. exist Message 输入测试文字，例如“产品说明示例”。拖动区块，把它放到允许的位置。
4. 点击 Save，再打开这个主题的产品页预览。

如果需要把它作为模板中的独立区段添加，可走 Add section → Apps；Shopify 会把应用区块放入 Apps 包装区段。该入口同样需要保存，见官方模板添加步骤。

用保存后的预览完成验收

验收输入是测试主题、产品模板、产品和 Message 内容；完成结果是预览页在预定位置显示保存的文字。按以下顺序检查，并记录实际结果，而不是把构建成功当作前台可用。

1. 确认预览打开的是刚编辑的主题，产品使用的是刚配置的模板；在桌面和手机宽度检查文字、位置和换行。
2. 修改文字，保存并刷新预览，确认显示新内容。
3. 清空字段后保存，确认本例的说明段落不再输出；输入含尖括号的测试文字，确认它作为文字显示。
4. 移动区块并保存，确认位置变化；删除区块并保存，确认说明消失。随后按需要重新添加。

添加、移除、重排和配置属于官方建议测试范围。模板说明提醒，模板修改会影响使用它的所有页面。本例的文字来自区块配置，不会自动为每个产品生成不同说明。需要逐产品内容时，应另行设计资源设置或动态数据来源，并核对对应契约。

看不到区块时，从入口逐层排查

区段支持和模板入口依据官方帮助；产品模板限制依据schema 文档。更换主题后，应在新主题重新检查应用配置与位置，不能沿用旧主题的验收结论。