Shopify Checkout UI Extensions

news2025/3/31 2:47:27

结账界面的UI扩展允许应用开发者构建自定义功能，商家可以在结账流程的定义点安装，包括产品信息、运输、支付、订单摘要和Shop Pay。

Shopify官方在去年2024年使用结账扩展取代了checkout.liquid，并将于2025年8月28日彻底停用checkout.liquid。

步骤1：初始化shopify app和checkout ui extension

npm init @shopify/app@latest
cd your-app
npm run shopify app generate extension

步骤2：配置checkout extension的`shopify.extension.toml文件`

Configuration

当创建一个扩展checkout ui扩展时，shopify.extension.toml 文件会自动生成在扩展目录中。该文件包含了扩展的配置信息，其中包括扩展名称、扩展目标、元字段、功能以及设置定义。

配置扩展点

Checkout-ui-extensions targets

checkout ui可配置多个扩展点，每个扩展点出现在结账的不同的位置（UI出现的位置）

可配置多个

api_version = "2025-01"

[[extensions]]
type = "ui_extension"
name = "My checkout extension"
handle = "checkout-ui"

  [[extensions.targeting]]
  target = "purchase.checkout.block.render"
  module = "./Checkout.jsx"

  [[extensions.targeting]]
  target = "purchase.checkout.payment-method-list.render-after"
  module = "./Payment.jsx"

扩展点展示UI出现的位置，构建UI请遵循

Checkout-ui-extensions components

只能使用官方提供好的UI组件库

配置API访问权限

Checkout-ui-extensions apis

不同的API对于权限的要求不同，不敏感数据是不需要访问权限的

敏感数据如用户的身份信息就需要访问权限

要想请求敏感数据请按照如下操作进行编辑后台配置

如下配置

选择需要使用到的用户信息提交表单即可，如果不确定直接全选一步到位就好了，在配置过后，配置入口将不再出现。

定义扩展的“能力”

Configuration

Property	Description
api_access	允许您的扩展程序查询 Storefront API。
network_access	允许扩展访问外部网络，如fetch访问接口
block_progress	允许阻止买家结账，当配置了此配置，需在checkout配置后台选择开启此app的阻止结账的功能按钮
collect_buyer_consent	允许您的扩展程序收集买家对特定政策（例如短信营销）的同意。

# ...

[extensions.capabilities]
api_access = true
network_access = true
block_progress = true

[extensions.capabilities.collect_buyer_consent]
sms_marketing = true
customer_privacy = true

# ...

开启了network_access，需开启app配置后台的“access network”才可生效。

配置自定义表单

Configuration

这个类似于shopify liquid schema settings，配置代码不同，使用方式类似，可以自定义文案等。

[settings]
  [[settings.fields]]
  key = "banner_title"
  type = "single_line_text_field"
  name = "Banner title"
  description = "Enter a title for the banner"

步骤3：代码编写

需要具有React的代码编写能力

import {
  reactExtension,
  BlockStack,
  InlineStack,
  Button,
  Image,
  Text,
} from '@shopify/ui-extensions-react/checkout';

export default reactExtension(
  'purchase.checkout.block.render',
  () => <Extension />,
);

function Extension() {
  return (
    <InlineStack>
      <Image source="/url/for/image" />
      <BlockStack>
        <Text size="large">Heading</Text>
        <Text size="small">Description</Text>
      </BlockStack>
      <Button
        onPress={() => {
          console.log('button was pressed');
        }}
      >
        Button
      </Button>
    </InlineStack>
  );
}