跳到主要内容

Checkout Extension 开发指南

概述​

Checkout Extension 允许开发者在店铺结账页面中注入自定义内容和业务逻辑，无需修改主题代码。

使用 shoplazza app 指令开发的 Checkout Extension 支持以下两类能力：

  • 在指定扩展点插入自定义内容：在结账页面的固定位置渲染自定义 HTML，例如在联系信息上方显示提示横幅、在支付模块下方添加说明文本等。

  • 读取 checkout 数据并响应变化：通过 CheckoutAPI 获取订单、商品、价格、地址、用户等信息，并监听其变化执行自定义逻辑。

开发方式说明​

  • 在空目录中开发：生成的扩展仅供自己店铺使用，无法发布给其他商家。

  • 在已有 app 项目中开发：将扩展作为 app 的一部分发布，其他商家可安装使用。完整 App 开发教程请参考：App 开发指南

你将学到什么​

  • 如何用 CLI 初始化并创建一个 Checkout Extension

  • 如何选择扩展点，把自定义内容渲染到结账页指定位置

  • 如何用 extend + HTML 模板写出一个最小可预览的扩展

前置条件​

  • 已安装 shoplazza-cli

  • 拥有 Shoplazza 开发者账号

  • 已有 shoplazza app 项目，或在空目录中开发

开发流程​

第一步：初始化​

在 app 项目根目录（或空目录）执行：

shoplazza app init --name "my-app"

该命令会创建一个名为 my-app 的应用，并在当前目录下生成同名项目子目录。

第二步：创建 Checkout Extension​

进入生成的 app 目录后执行：

shoplazza app extension create --type checkout --name my-checkout

该命令会在 extensions/ 目录下创建一个名为 my-checkout 的结账扩展。目录结构如下：

my-app/
└── extensions/
    └── my-checkout/
        ├── shoplazza.extension.toml   # 扩展配置文件
        ├── package.json
        └── src/
            ├── index.js               # 扩展入口
            ├── index.html             # 主 HTML 模板
            ├── style.html             # 样式
            ├── content.html           # 页面内容
            └── script.html            # 脚本逻辑

在 src/ 目录下进行扩展开发。

第三步：启动预览​

开发完成后，在 app 目录中执行：

shoplazza app dev

扩展会自动发布到绑定的店铺，在店铺主题编辑「结账页编辑器」中即可查看效果。

扩展点速览​

扩展点决定自定义内容插入到结账页的具体位置，在 extend() 的 extensionPoint 字段中指定。常用扩展点：

扩展点位置说明
Checkout::RenderBefore页面头部之前
Checkout::ContactInformation::RenderAfter联系信息模块之后
Checkout::Summary::RenderBefore订单摘要之前
Checkout::SectionPayment::RenderBefore支付模块之前

全部扩展点见 Checkout extension 参考。

一个最小 UI 示例​

从 shoplazza-extension-ui 引入 extend，指定一个扩展点并传入 HTML 字符串，即可在结账页渲染内容：

import { extend } from 'shoplazza-extension-ui';

extend({
  extensionPoint: 'Checkout::RenderBefore',
  component: '<div style="padding:12px;background:#f5f5f5;">Hello, Shoplazza!</div>',
});

内容较复杂时可拆分到 src/style.html / src/content.html / src/script.html 并在 src/index.html 组装。extend 函数签名、HTML 模板机制与完整 CheckoutAPI，见 Checkout extension 参考。

别漏写分号

JS 文件每条语句末尾必须加分号。若漏写分号，dev 运行时会报错并提示 extend 必须写在文件顶部，这是解析失败导致的误导性报错，并非 extend 位置问题。

预览与发布​

在 app 目录中执行：

shoplazza app dev

扩展自动发布到绑定店铺后，打开店铺后台「结账页编辑器」即可查看效果。

如果需要其他商家也可以使用本扩展，需要首先完成 app 开发，并进行发布：

shoplazza app deploy

其他商家在安装 app 后，即可在店铺主题编辑的结账页查看效果。

下一步​

排障​

extend 报错说它必须写在文件顶部​

问题： dev 运行时报错，提示 extend 必须写在文件顶部，但它其实已经在顶部了。

原因： 文件别处缺了分号导致解析失败，错误被误报成 extend 的位置问题。

解决： 确保每条语句都以分号结尾（参见上文最小示例中的提示）。

window.CheckoutAPI 是 undefined​

问题： 直接读取 window.CheckoutAPI 返回 undefined。

原因： CheckoutAPI 只有在结账页完全加载后才挂载。

解决： 调用前先等待挂载——用 setTimeout/setInterval 轮询（最多约 5 秒）。挂载写法 mount 参见场景教程的场景二。