SHOPLINE Checkout UI 扩展

扩展（Extensions）
1 
仅限 Enterprise 客户使用。

1. 结账 UI 扩展概述

结账 UI 扩展允许应用开发人员构建自定义结账功能，商家可以在结账流程的特定扩展点安装和使用这些功能。

  • 扩展点类型：

  • 静态扩展点（Static Extension Points）：与核心结账功能（如联系信息、运输方式、订单摘要）相关联。如果核心功能不展示，则绑定的静态扩展点也不会呈现。例如：Checkout::Contact::RenderAfter（在联系表单模块下方）、Checkout::ShippingMethods::RenderBefore（在运输方式标题前）。

  • 动态扩展点（Dynamic Extension Points）：与核心结账功能无关，在每个结账步骤的核心功能之间呈现，且无论其他结账元素如何，动态扩展始终会显示。商家可通过结账编辑器将其放置在结账页、订单页和 Thank You 页中。例如：结账页的 Checkout::Dynamic::Render[Information1]（在联系表单模块上方）、感谢页/订单页的 Checkout::Dynamic::Render[OrderSummary1]（在商品列表上方）。

  • 注册方式：UI 扩展使用 render(extensionPoint, App) 来注册扩展点。

2. 扩展开发流程

开发流程主要包括：账号登录、创建扩展、连接扩展（可选）、开发扩展、预览扩展、发布扩展和上线使用。

  • 创建/开发：使用 SHOPLINE CLI 命令 sl extension create 创建扩展，并选择 Checkout UI Customizer 类型。

  • 目录结构：扩展结构主要包含 locales（多语言配置）、src（扩展源代码）和 shopline.ui.customizer.toml（配置文件）。

  • 预览/发布：使用 sl extension serve 进行本地预览，使用 sl extension push 推送扩展，然后在商家后台发布和安装应用，并通过结账编辑器添加和放置 UI 扩展。

  • 本地开发排障：确保代码中使用的扩展点包含在配置文件中。对于动态扩展点，可以通过 URL 的 placement-reference 参数指定渲染位置。

3. 配置文件 (shopline.ui.customizer.toml)

该文件自动生成，包含扩展名称、扩展点位置、扩展能力设置等定义。

  • 核心属性：

  • type：扩展类型，固定为 checkout_ui_customizer。

  • name：扩展的名称。

  • extension_points：扩展将渲染的预设点列表，必须包含 render 代码中指定的扩展点。

  • 能力（capabilities）：定义 UI 扩展的能力。

  • block_progress：布尔值，定义扩展是否具备阻断结账流程的能力（需商家在结账编辑器中勾选开启）。

  • network_access：布尔值，定义扩展是否具备访问网络的能力。

  • 商家配置项（settings）：定义一组用户配置字段，最终呈现在结账编辑器中供商家填写，扩展中可通过 props.settings.{key} 读取。支持的数据类型包括文本、数字、布尔值和日期等。

4. 标准 API 和全局钩子

Standard API（通过组件的 props 对象下发）和**全局钩子（Hooks）**用于扩展与应用程序的交互和获取信息。

  • 核心 API 示例：

  • interceptor：用于阻断结账流程并进行校验（需开启 block_progress 能力）。

  • request：基于 axios 的网络请求实例（需开启 network_access 能力）。

  • cost：当前结账费用的详细信息。

  • lines：商品行信息。

  • applyCheckoutLinesChange：更新商品行信息（仅结账页可用）。

  • i18n：用于根据当前本地化翻译内容。

  • storage：当前扩展的键值存储。

  • settings：访问商家配置项的值。

  • 核心 Hooks 示例：

  • useApi()：返回当前扩展点接收的完整 props 对象。

  • useCheckoutLineTarget()：获取当前商品行信息（仅在 Checkout::CheckoutLineDetails::RenderAfter 扩展点生效）。

  • useTotalAmount()：获取当前结账中商品总金额。

5. 安全和渲染原理

结账 UI 扩展通过安全可靠的方式自定义结账页面，不会影响结账或客户数据的安全。

  • 沙箱环境：扩展代码被隔离在 Web Worker 的沙箱环境运行，无法访问或操作结账页面的元素，无权访问页面的敏感信息。

  • 远程渲染：核心原理是将定义 UI 代码和渲染 UI 代码分离。扩展代码（Remote）在 Web Worker 中运行，生成 Virtual Dom Tree，通过 RPC 调用发送序列化指令给实际渲染环境（Host）。

6. UI 组件

扩展开发只能使用指定的 UI 组件和 API，不支持渲染原生 HTML 标签。组件的样式会跟随商家的店铺主题配置变化。

提供了以下常用 UI 组件及其属性说明：

  • 信息展示：Text（文本）、Badge（徽章）、Banner（横幅）、Image（图片）、ItemThumbnail（商品缩略图）、Divider（分隔符）、Tooltip（提示）。

  • 布局容器：View（通用容器）、Grid（网格布局）、GridItem（网格子容器）、InlineLayout（多列行内布局）、BlockStack（块级栈）、BlockLayout（多行块级布局）。

  • 表单/交互：Button（按钮）、Link（链接）、Pressable（点击容器）、TextField（文本输入）、PhoneField（电话输入）、Select（下拉选择）、Checkbox（复选框）、ChoiceList / Choice（选择列表/选项）、Stepper（步进器）。

  • 加载/骨架屏：Spinner（加载中）、SkeletonText（文本骨架屏）、SkeletonTextBlock（文本块骨架屏）、SkeletonImage（图片骨架屏）。

  • 样式辅助：StyleHelper（条件样式辅助工具，可根据视口大小等条件调整样式）。

详细文档可查看：