用途
Shopify Polaris Checkout Extensions 是一项面向 Shopify 开发者的技能,用于编写购物车(结账)流程中的自定义 UI 扩展。借助它,应用开发者可以构建商家能够安装到结账流程指定位置的自定义功能,覆盖商品信息、配送、支付、订单摘要以及 Shop Pay 等区域。
主要能力
该技能基于 2026-01 版本的 UI Framework,提供以下能力:
- 使用 Preact 入口(@shopify/ui-extensions/preact 与 preact 的 render)。
- 直接使用全局注册的 Polaris Web Components(如 s-banner、s-badge、s-button 等,无需导入)。
- 覆盖多种扩展目标,包括地址(purchase.address-autocomplete.*)、导航(purchase.checkout.actions.render-before)、区块(purchase.checkout.block.render、purchase.thank-you.block.render)、订单摘要、信息、配送、页眉页脚、支付、自提点与公告等。
- 可用 API 涵盖地址、分析、属性、买家身份、购物车行、结账令牌、费用、客户隐私、配送、折扣、扩展、礼品卡、本地化、元字段、订单、支付、Storefront API、会话令牌、设置、店铺与存储。
- 提供组件示例,如 s-button、s-banner、s-checkbox、s-text-field、s-stack、s-grid 等。
使用方式
该技能规定了一定的工作流程:
- 始终使用 Shopify CLI 脚手架创建新的结账 UI 扩展:
shopify app generate extension --template checkout_ui --name my-checkout-ui-extension
- 编写代码前,先调用搜索脚本获取组件与 API 上下文:
scripts/search_docs.mjs "<query>" --model YOUR_MODEL_NAME --client-name YOUR_CLIENT_NAME --client-version YOUR_CLIENT_VERSION
- 返回代码前必须调用验证脚本,并传入目标等参数:
scripts/validate.mjs --code '...' --model YOUR_MODEL_NAME --client-name YOUR_CLIENT_NAME --client-version YOUR_CLIENT_VERSION --artifact-id YOUR_ARTIFACT_ID --revision REVISION_NUMBER --target <extension-target>
若验证失败,需针对错误类型搜索、修复并重新验证,最多重试三次。
适用场景
适用于需要开发 Shopify 结账 UI 扩展的开发者,在结账流程的指定位置添加自定义界面与交互。
限制
- 代码中不得包含 HTML 注释(<!-- ... -->),验证器会将其视为无效自定义组件。
- 字符串关键字属性(如 padding、gap、direction、tone、variant、size、background、alignItems)必须使用字符串值,不能使用布尔简写。
- Web 组件属性使用 camelCase 命名,而非 kebab-case。
- 验证时 --target 为必填项,缺少会导致验证失败。
- 需注意脚本的隐私说明:搜索与验证脚本会向 Shopify 报告查询、验证结果、模型/客户端标识及代码等内容,可通过设置 OPT_OUT_INSTRUMENTATION=true 选择退出。