[{"value":"使用扩展 API","id":"使用扩展-api","hLevel":2,"level":1},{"value":"应用场景示例","id":"应用场景示例","hLevel":2,"level":1,"children":[{"value":"使用全局 React 对象","id":"使用全局-react-对象","hLevel":3,"level":2},{"value":"访问特性","id":"访问特性","hLevel":3,"level":2},{"value":"翻译字符串","id":"翻译字符串","hLevel":3,"level":2},{"value":"访问结账编辑器设置","id":"访问结账编辑器设置","hLevel":3,"level":2},{"value":"Hooks 调用","id":"hooks-调用","hLevel":3,"level":2},{"value":"阻止进度并在扩展程序中显示错误","id":"阻止进度并在扩展程序中显示错误","hLevel":3,"level":2}]}]

概述

结账扩展接口覆盖数据处理、用户界面交互与分析等核心场景。借助这些 API，你可以快速构建复杂的自定义结账应用，并实现高效集成。

使用扩展 API

扩展 APIs 通过组件的 props 对象下发。有关每个扩展 API 的详细使用说明，参考其对应的 API 文档。

应用场景示例

你可以通过如下应用场景示例了解如何通过 JavaScript (JS) 使用扩展 API。

使用全局 React 对象

React 对象可以在全局中访问，如 React.useState 或 React.useEffect 等。

注意

勿直接使用 useState 或 useEffect。

访问特性

你可以通过 props.{feature} 来访问对应的特性字段。在下面的例子中，通过 props.shop 获取当前的店铺信息对象，随后使用 Text 组件渲染出当前的店铺名称 shop.name。

render('Checkout::Dynamic::Render', (props) => {
  const { shop } = props;
  
  return <Text>Shop name: {shop.name}</Text>
});

翻译字符串

多语言翻译存储在扩展开发目录下的 locales/{lang}.json 中，其中 lang 表示对应的语言。以 {lang}.deafult.json 结尾的文件，lang 则会作为默认语言，例如 en.default.json 对应 en 作为默认语言。

在扩展运行时会优先采用用户偏好的语种，若该语种不存在，则会采用默认语言。你可以使用 props.i18n.translate(key) 来渲染 key 对应的多语言文案。

/* 请参阅下面 locales/en.default.json 文件代码内容以获取此示例的翻译键和值 */
render('Checkout::Dynamic::Render', (props) => {
  const { i18n } = props;
  return <Text>{i18n.translate("welcome", { name: "tony" })}</Text>;
});

// locales/en.default.json
{
  "welcome": "Welcome to our store {{name}}!"
}

访问结账编辑器设置

假设你在结账编辑器中定义的商家配置如下：

type = "checkout_ui_customizer"
name = "my-checkout-customizer"
extension_points = [
  'Checkout::Dynamic::Render'
]
[settings]
  [[settings.fields]]
  key = "banner_title"
  type = "single_line_text_field"
  name = "Banner title"
  description = "Enter a title for the banner."
    [[settings.fields.validations]]
    name = "min"
    value = "5"
    [[settings.fields.validations]]
    name = "max"
    value = "20"

你可以在扩展程序中通过 props.settings.{key} 检索商家配置对应 key 的值。

render('Checkout::Dynamic::Render', (props) => {
  const { settings } = props;
  
  return <Banner title={settings.banner_title}></Banner>;
});

Hooks 调用

获取完整 API

你可以在扩展程序中通过 useApi 钩子获取对应拓展点的完整 API，适用于深层嵌套的组件。

render('Checkout::Dynamic::Render', () => {
  const { settings } = useApi();
  
  return <Banner title={settings.banner_title}></Banner>;
});

获取当前商品行信息

你可以在扩展程序中通过 useCheckoutLineTarget 钩子获取当前商品行信息，适用于深层嵌套的组件。

注意

仅对 checkout line 扩展点生效，如 Checkout::CheckoutLineDetails::RenderAfter。

render('Checkout::CheckoutLineDetails::RenderAfter', () => {
  const { variantId } = useCheckoutLineTarget();
  
  return <Banner title={variantId}></Banner>;
});

阻止进度并在扩展程序中显示错误

使用 Interceptor 拦截并阻止买家结账，同时在扩展程序中显示错误消息。

在下面例子中，当用户成单的时候，会调用 interceptor.validate 中的回调方法进行校验。在校验过程中，若发现总金额大于 5000 的时候，用户可以成单，否则校验失败并显示 The total amount must be greater than 5000。

render(
  'Checkout::Dynamic::Render',
  (props) => {
    const { interceptor, cost } = props;
    const [isValid, setIsValid] = React.useState(false);
    React.useEffect(() => {
      const interceptorHandle = interceptor.validate(() => {
        const success = cost.totalAmount > 5000;
        setIsValid(success);
        return { success };
      });
      return () => {
        interceptorHandle.unsubscribe();
      };
    }, []);
    return isValid ? null : <Banner>The total amount must be greater than 5000</Banner>;
  }
)