开发概述#

商城主题是普通 Halo 主题的一部分。你可以在现有主题的 templates/shop/ 中添加商城页面，也可以开发以商城为主的完整主题。主题负责商品展示和顾客交互，商品、订单、支付与履约由 Halo 商城版提供。

本系列以 Halo 商城版 2.27 为基线。首次开发主题时，请先了解主题目录结构、主题配置和 Thymeleaf。

#页面如何渲染

Halo 商城版内置了 shop-templates 提供的商城模板。访问商城时，优先使用当前主题中的同名模板；主题未提供的模板继续使用内置版本。

内置模板采用两种方式组合渲染：

• Thymeleaf：在服务器端输出商品列表、商品详情正文和订单详情，便于展示内容和搜索引擎读取公开商品页面。
• Web Components：在浏览器中处理购买规格、购物车、结算和支付等交互。内置组件由 Svelte 编译，使用这些组件的主题不需要采用 Svelte。

商品详情同时包含服务端商品内容和浏览器端购买组件。订单详情是 Thymeleaf 页面，不需要寻找一个 shop-page-order 组件。

#选择开发方式

通常可以先复用内置模板，再逐页替换确有定制需求的部分。未覆盖的模块能够继续使用 Halo 升级带来的更新；复制进主题的模板和 UI 源码则需要自行同步。

#版本与参考资料

shop-templates 的 main 是开发分支，可能包含 Halo 商城版暂未发布的功能。开发前从分支列表选择与目标 Halo 商城版对应的 release 分支，不要将最新版源码与旧版后端直接混用。

• 基础示例主题：复用内置模板。
• 二次开发示例主题：在主题中集成商城 UI 源码。
• Halo 商城版 2.27 RESTful API：查询请求字段、响应模型与接口分组。
• 版本差异：查看本系列涉及的重要模板和 API 变化。

接下来按照快速开始完成第一个页面。