数据与实现基础
先确定模块读什么、由谁维护,再选择 Liquid 或 Headless。
可编辑模块与 Section 合同
把设计稿中的标题、正文和目标拆成明确设置;布局由 Section 负责,共用片段用 Snippet,页面组合由模板安排。先验证一份真实数据,再扩大复用。
数据与依赖
- heading:text;body:richtext;destination:url。
- 同页用 section.id 区分标题与控件。
交互逻辑
- 有链接时显示按钮;目标缺失时不生成空链接。
- 商家调整内容时,布局和语义仍成立。
示例代码 · sections/ww-intro.liquid
<section class="ww-intro" aria-labelledby="Intro-{{ section.id }}">
<h2 id="Intro-{{ section.id }}">{{ section.settings.heading | escape }}</h2>
<div>{{ section.settings.body }}</div>
{% if section.settings.destination != blank %}
<a href="{{ section.settings.destination | escape }}">
{{ section.settings.link_label | escape }}
</a>
{% endif %}
</section>
{% schema %}
{
"name": "WW introduction",
"settings": [
{"type":"text","id":"heading","label":"Heading","default":"Explore the collection"},
{"type":"richtext","id":"body","label":"Introduction"},
{"type":"url","id":"destination","label":"Destination"},
{"type":"text","id":"link_label","label":"Link label","default":"Explore"}
],
"presets":[{"name":"WW introduction"}]
}
{% endschema %}
验收检查
- 在主题编辑器增加两份模块,检查重复 ID。
- 核对空正文、长标题、手机及键盘顺序。
此示例可作为独立 Section;其他片段须按各自说明放入已有模板。文案应进入项目语言文件。
同一模块怎样迁到 Headless
沿用字段和购买状态合同,把 Liquid 对象读取替换为服务端 Storefront 查询。保留真实框架负责的路由、渲染和构建,按已安装 Hydrogen 版本连接商务能力。
数据与依赖
- handle 来自当前商品路由;country/language 来自市场上下文。
- 查询只取该模块所需事实。
交互逻辑
- 找不到商品时返回真实 404。
- 有下一页时继续分页,不把前十项当全量。
示例代码 · queries/product.graphql
query ProductFacts($handle: String!, $country: CountryCode!, $language: LanguageCode!)
@inContext(country: $country, language: $language) {
product(handle: $handle) {
id
title
description
variants(first: 10) {
nodes {
id
title
availableForSale
price { amount currencyCode }
}
pageInfo { hasNextPage endCursor }
}
}
}
验收检查
- 同一型号核首屏 HTML、市场切换与购物车。
- 核框架版本、锁文件和缓存隔离。
示例是查询文档,不含认证或请求适配器。私有凭据留在服务端;Hydrogen 2026-10 与旧版按各自文档接入。
先理解,再整合,最后验证
- 选择模块,确认数据和输入输出。
- 将片段接入当前主题或框架。
- 用真实变体、市场和失败恢复场景验收。
示例按 Shopify Online Store 2.0 主题编写;Headless 使用单独的数据与版本边界。代码片段需接实际字段、主题和语言文件。
架构参考
示例由 WESWOO 编写,结合 Shopify 官方文档和固定版本的仓库参考。采用仓库代码时应保留适用许可。
Shopify/dawn · 许可commit 3e9ee2281dc4 · Shopify 集成主题的限定许可;参考架构,不复制仓库实现。
Shopify/hydrogen · 许可commit 9e358a2462ba · MIT;采用实质代码时保留版权与许可。
依据核对 2026-11-12