# CheckoutAPI 参考
> CheckoutAPI 参考：Shoplazza 结账扩展用它读取订单、监听买家选择的变化并驱动结账页界面。
`CheckoutAPI` 是结账页平台挂在 `window.CheckoutAPI` 上的全局对象，结账页和感谢页都有。它的方法按 `order`、`store`、`address` 等命名空间分组，扩展通过它读取订单和顾客已经做出的选择、监听这些数据的变化，以及驱动结账页的部分界面。本页列出的是结账页对外开放给应用的 CheckoutAPI 方法，口径来自平台的对外开放能力清单。方法签名里出现的类型，定义都在页尾的[类型定义](#类型定义)一节。
## 快速上手
`CheckoutAPI` 的方法按业务分成 15 个命名空间，调用形式统一是 `CheckoutAPI.<命名空间>.<方法>()`。下面这段代码打印一份结账页概况——当前步骤、订单、金额、商品行，用到 `step`、`store`、`summary` 三个命名空间。把它跑通，整份文档的用法就掌握了：之后需要什么数据，先找到管这块数据的命名空间，再到它的方法表里查方法名。
```javascript
const MOUNT_INTERVAL_MS = 100;
const MOUNT_MAX_ATTEMPTS = 50; // 100ms * 50 ≈ 5 秒
// CheckoutAPI 在结账页加载完成之后才挂到 window 上，
// 所以要轮询等待，不要直接读 window.CheckoutAPI。
function mount(cb, attempt = 0) {
if (window.CheckoutAPI) {
cb(window.CheckoutAPI);
return;
}
if (attempt >= MOUNT_MAX_ATTEMPTS) {
console.warn('CheckoutAPI 没有在预期时间内挂载');
return;
}
window.setTimeout(() => mount(cb, attempt + 1), MOUNT_INTERVAL_MS);
}
// 存成变量，之后才能用 api.store.removePricesChangeCb(onPricesChange) 取消。
const onPricesChange = (prices) => console.log('金额变了，现在总价', prices.totalPrice);
mount((api) => {
const order = api.store.getOrderInfo();
const prices = api.store.getPrices();
const products = api.summary.getProductList();
console.log('当前步骤：', api.step.getStep());
console.log('订单：', order.orderNo, order.status, order.currencyCode);
console.log('小计 / 总价：', prices.subtotalPrice, prices.totalPrice);
console.log('商品行：', products.length, products.map((p) => p.productTitle + ' x' + p.quantity));
api.store.onPricesChange(onPricesChange);
});
```
方法名的前缀说明了这是哪一类调用：
| 名字规律 | 含义 |
|---|---|
| `get*` / `is*` / `has*` | 同步读值，调用后立刻拿到返回值。 |
| `on*` / `remove*` | `on*` 注册回调，`remove*` 移除回调。两者成对使用，并且传同一个函数引用。 |
| `register*` / `unregister*` | 注册「改写器」。回调的返回值会被平台消费，返回错了整页崩溃。只在明确要改平台行为时用。 |
| `dispatch*` | 主动触发一次 UI 刷新。 |
| 返回 `Promise` | 会发请求或做校验，结果稍后才拿到。 |
:::caution 调用前必读
- **脚本刚开始跑的时候，`window` 上还没有 `CheckoutAPI`。** 平台要等结账页加载完成才把它挂上去，所以要像上面的例子那样轮询等待，不要一上来就读 `window.CheckoutAPI`。完整例子见 [场景三：API 调用与事件监听](/docs/app/extensions/checkout/extension-recipes#场景三api-调用与事件监听)。
- **`on*` 和 `remove*` 要配对。** 用 `on*` 注册的回调会一直留到页面卸载。把回调存成变量，不再需要时把**同一个函数引用**传给对应的 `remove*` 方法；写成内联箭头函数的回调永远取消不掉。
- **`register*` 是提供者，不是监听器。** 名字以 `register` 开头的方法，交给结账页的是一个**返回值会被平台消费**的回调。以 `registerUiShippingLinesChange` 为例，它决定页面渲染哪些物流方案：回调返回 `undefined`，页面读 `undefined.length` 就会整页崩到报错界面。只有确实要改平台行为时才注册，并且必须按签名要求返回对应类型的值。只想观察某个值、不想改动它，用对应的 `on*` 方法。
:::
## address
`address` 命名空间管收货地址和账单地址两张表单：字段值、界面据以渲染的 schema、校验，以及顾客保存过的地址簿；另外还提供国家列表和地址模板，用来判断某个国家的地址该收哪些字段。
### 收货地址
| 方法 | 用途 | 参数 | 返回 |
|---|---|---|---|
| `getShippingAddress` | 获取收货地址的字段值 | — | AddressValues |
| `getShippingAddressSchema` | 获取收货地址表单的 schema 配置列表，界面按这份配置渲染表单 | — | ExtendSchema[] |
| `onShippingSchemaChange` | 注册收货地址表单 schema 变更的回调，触发后界面要重新渲染表单 | cb: AddressChangeCb | `void` |
| `removeShippingSchemaChangeCb` | 删除收货地址表单 schema 变更的回调 | cb: AddressChangeCb | `void` |
| `onShippingAddressChange` | 注册收货地址字段值变化的回调 | cb: AddressValuesChangeCb | `void` |
| `removeShippingAddressChangeCb` | 删除收货地址字段值变化的回调 | cb: AddressValuesChangeCb | `void` |
| `onShippingAddressChangeByInput` | 注册收货地址字段值变化的回调，只有顾客在表单里手动改动才触发，代码改动不触发 | cb: AddressValuesChangeCb | `void` |
| `removeShippingAddressChangeByInput` | 删除只在顾客手动改动时触发的收货地址回调 | cb: AddressValuesChangeCb | `void` |
| `validateShippingAddress` | 校验收货地址，传 ids 时只校验指定字段 | `ids?: string[]`options?: ValidateOptions | Promise<ValidateResult[]> |
| `isSaveAddress` | 「保存到地址簿」是否已勾选 | — | `boolean` |
| `setIsSaveAddress` | 设置「保存到地址簿」的勾选状态 | `isSave: boolean` | `void` |
| `clearShippingAddress` | 清空收货地址 | — | `void` |
| `updateShippingAddress` | 更新收货地址 | address: Partial<ShippingAddress> | `void` |
| `getEmailSchema` | 获取邮箱输入框的 schema 配置 | config: ContactSchemaConfig | AddressItemEmailSchema | null |
| `getPhoneSchema` | 获取手机号输入框的 schema 配置 | config: ContactSchemaConfig | AddressItemGeneralPhoneSchema | AddressItemStringSchema | null |
| `getEmailOrPhoneSchema` | 获取「邮箱或手机号」输入框的 schema 配置 | — | AddressItemStringSchema | null |
| `validateContact` | 校验联系方式的输入 | options?: ValidateOptions | Promise<ValidateResult | undefined> |
| `getContactSchema` | 获取联系方式的 schema，汇总 getEmailSchema、getPhoneSchema 和 getEmailOrPhoneSchema 的结果 | — | AddressItemPhoneSchema | AddressItemStringSchema | AddressItemEmailSchema |
| `registerShippingAddressSchemaSort` | 注册收货地址表单的排序回调，用来调整字段顺序 | cb: SortSchemaCb | `void` |
| `registerShippingAddressSchemaChangeVisibility` | 注册非必填字段的显示控制回调，用来隐藏选填项 | cb: SchemaItemVisibilityCb | `void` |
| `registerShippingAddressSchemaChangeLabel` | 注册字段标签的改写回调，用来修改表单项的 label | cb: SchemaChangeLabelCb | `void` |
| `dispatchShippingAddressSchemaChange` | 手动通知界面重新渲染收货地址表单 | — | `void` |
| `expandShippingAddress` | 展开收货地址表单，reason 说明这次展开是怎么触发的 | reason?: AddressExpandReason | `void` |
| `formatPhone` | 按当前收货地址所属国家格式化电话号码 | `value: string` | `string` |
| `getCollapsibleShippingAddressSchema` | 获取折叠形态的收货地址 schema：未展开时隐藏联想字段，address 作为联想入口，并追加一个手动输入入口 | — | ExtendSchema[] |
| `getShippingAddressFocusIdPrefix` | 获取收货地址字段 focus id 的前缀，拼出完整 id 后可以定位到对应输入框 | — | `string` |
| `getSubmitShippingAddress` | 获取提交给平台的收货地址结构：字段是嵌套的，部分字段还带默认值处理 | — | ShippingAddress |
| `isFieldShow` | 判断当前地址模板下某个字段是否展示 | key: keyof AddressValues | `boolean` |
| `isShippingAddressExpanded` | 收货地址表单当前是否已展开 | — | `boolean` |
| `registerShippingAddressSchemaChangeDisable` | 注册收货地址字段的禁用回调，可以用来禁掉已经有值的字段 | cb: SchemaChangeDisableCB | `void` |
| `registerShippingAddressSchemaChangeValidateRule` | 注册收货地址表单的附加校验规则，在平台默认校验之上生效 | cb: SchemaChangeValidateRuleCB | `void` |
### 账单地址
| 方法 | 用途 | 参数 | 返回 |
|---|---|---|---|
| `getBillingAddress` | 获取账单地址 | — | AddressValues | ShippingAddress | undefined |
| `getBillingAddressSchema` | 获取账单地址表单的 schema 配置，界面按这份配置渲染表单 | — | AddressItemSchema[] |
| `onBillingSchemaChange` | 注册账单地址表单 schema 变更的回调，触发后界面要重新渲染表单 | cb: BillingAddressChangeCb | `void` |
| `removeBillingSchemaChangeCb` | 删除账单地址表单 schema 变更的回调 | cb: BillingAddressChangeCb | `void` |
| `validateBillingAddress` | 校验账单地址 | — | Promise<ValidateResult[]> |
| `onBillingAddressValuesChange` | 注册账单地址字段值变化的回调 | cb: BillingAddressValuesChangeCb | `void` |
| `removeBillingAddressValuesChange` | 删除账单地址字段值变化的回调 | cb: BillingAddressValuesChangeCb | `void` |
| `isUseShippingAsBillingAddress` | 账单地址是否复用收货地址；复用时账单地址表单会折叠起来，顾客不用填 | — | `boolean` |
| `setIsUseShippingAsBillingAddress` | 设置账单地址是否复用收货地址 | `isUse: boolean` | `void` |
| `onUseShippingAsBillingAddressChange` | 注册「账单地址复用收货地址」状态变化的回调 | cb: UseShippingAsBillingAddressCb | `void` |
| `removeUseShippingAsBillingAddressChange` | 删除「账单地址复用收货地址」状态变化的回调 | cb: UseShippingAsBillingAddressCb | `void` |
| `registerBillingAddressSchemaChangeLabel` | 注册账单地址字段标签的改写回调，用来修改表单项的 label | cb: SchemaChangeLabelCb | `void` |
| `setBillingAddress` | 设置账单地址的字段值 | address: AddressValues | `void` |
| `registerBillingAddressSchemaSort` | 注册账单地址表单的排序回调，用来对非礼品卡商品的账单地址字段重新排序 | cb: SortSchemaCb | `void` |
| `dispatchBillingAddressSchemaChange` | 手动触发账单地址表单结构变更的通知 | — | `void` |
### 地址簿
| 方法 | 用途 | 参数 | 返回 |
|---|---|---|---|
| `onChangeAddressBook` | 注册地址簿列表变化的回调，触发后要重新调用 getAddressBookList 取最新列表 | cb: AddressBookChangeCbs | `void` |
| `removeAddressBookChangeCb` | 删除地址簿列表变化的回调 | cb: AddressBookChangeCbs | `void` |
| `getAddressBookList` | 获取地址簿列表 | — | IAddressBookItem[] |
| `applyAddress` | 把地址簿里的某个地址填进收货地址 | `id: string``setBilling?: boolean` | `void` |
### 地址通用
| 方法 | 用途 | 参数 | 返回 |
|---|---|---|---|
| `getAddressTemplate` | 按国家、省州和预设取地址模板，模板决定这个国家的地址收哪些字段 | params: GetAddressTemplateParams | AddressTemplate |
| `getAllCountries` | 获取平台支持的全部国家 | — | AddressCountry[] |
| `getAvailableCountries` | 获取店铺开放的国家列表 | — | AddressCountry[] |
| `getDefaultAddressValues` | 获取一份空的地址字段值，可以拿来当表单初始值 | — | AddressValues |
| `getSchemaManager` | 创建地址表单的 schema 管理器，用它按当前地址值和地址模板生成并校验各个字段 | context: AddressSchemaManagerContextconfig: SchemaManagerConfig | AddressSchemaManager |
| `hasCountry` | 判断某个国家码是否在店铺开放的国家列表里 | `countryCode: string` | `boolean` |
| `isMiddleEastCountry` | 判断是否是需要特殊地址处理的中东国家 | `countryCode: string` | `boolean` |
| `isMultiLevelCountry` | 判断某个国家是否使用多级行政区地址 | `countryCode: string` | `boolean` |
## base
`base` 命名空间是结账页的基础设施：加载与 pending 状态、手机号格式化、多语言文案，以及每个原生模块当前是否展示。
### 加载与 pending 状态
| 方法 | 用途 | 参数 | 返回 |
|---|---|---|---|
| `getLoadingStatus` | 获取全局 loading 状态 | — | LoadingStatus |
| `onLoadingStatusChange` | 注册 loading 状态变化的回调 | cb: OnLoadingStatusChangeCallback | `void` |
| `removeLoadingStatusChangeCb` | 删除 loading 状态变化的回调 | cb: OnLoadingStatusChangeCallback | `void` |
| `setLoadingStatus` | 更新 loading 状态 | status: Partial<LoadingStatus> | `void` |
| `getPending` | 获取各个模块的 pending 状态 | — | Pending |
| `onPendingChange` | 注册 pending 状态变化的回调 | pending: OnSubmitPendingChangeCallback | `void` |
| `removePendingChangeCb` | 删除 pending 状态变化的回调 | cb: OnSubmitPendingChangeCallback | `void` |
| `resetAllPending` | 重置全部 pending 状态 | — | `void` |
| `setPricePending` | 设置价格计算的 pending 状态 | `pending: boolean` | `void` |
| `setPickupLocationPending` | 设置自提点列表的 pending 状态 | `pending: boolean` | `void` |
| `getPickupLocationPending` | 获取自提点列表的 pending 状态 | — | `boolean` |
| `setShippingLinesPending` | 设置物流方案列表的 pending 状态 | `pending: boolean` | `void` |
| `getShippingLinesPending` | 获取物流方案列表的 pending 状态 | — | `boolean` |
| `setPaymentPending` | 设置支付脚本加载的 pending 状态 | `pending: boolean` | `void` |
### 手机号格式化
| 方法 | 用途 | 参数 | 返回 |
|---|---|---|---|
| `getPhoneAreaList` | 获取电话区号列表 | — | Country[] |
| `getDefaultPhoneKey` | 获取默认的手机区号，先按 IP 定位取，取不到再按浏览器语言取 | — | `string` |
| `getPhoneArea` | 根据手机号判断它属于哪个国家或地区 | `phone: string``phoneKey?: string` | Country | undefined |
| `formatPhone` | 按国家格式化手机号 | `phone: string``countryCode: string` | `string` |
| `isValidPhone` | 判断手机号在指定国家下是否合法 | `phone: string``countryCode?: string` | `boolean` |
| `initPhone` | 初始化手机号和区号：先从订单上已有的号码解析出区号，再按这个区号把号码格式化成该国的标准写法 | `phone: string``_phoneAreaCode: string``isPhoneRequired: boolean` | InitPhoneResult | null |
### 多语言
| 方法 | 用途 | 参数 | 返回 |
|---|---|---|---|
| `getLocale` | 获取当前语言，例如 en | — | `string` |
| `formatMessage` | 按 key 取当前语言的文案，key 不存在时返回 defaultMessage；context 用来填文案里的占位符 | `id: string``defaultMessage?: string``context?: Record` | `string` |
| `formatPrice` | 把金额格式化成带货币符号的展示文案 | `price: number \| string``symbolStr?: string` | `string` |
| `isRtlLocale` | 当前语言是否从右往左排版，例如阿拉伯语 | — | `boolean` |
| `registerLocaleMap` | 注册扩展自己的多语言文案，按语言分组传入 | locales: LocaleMap | `void` |
| `getFullLocale` | 获取当前完整的语言标记，例如 en-US | — | Locale |
**用法**
先按语言注册自己的文案，再用 `formatMessage` 取回。嵌套的 key 会用点号打平，`audit2: { deep: … }` 要按 `'audit2.deep'` 取；`context` 用来填文案里的 `{占位符}`。
```javascript
CheckoutAPI.base.registerLocaleMap({
'en-US': { 'audit.greet': 'Hi {name}', audit2: { deep: 'deep {name}' } },
'zh-CN': { 'audit.greet': '你好 {name}', audit2: { deep: '深层 {name}' } },
});
CheckoutAPI.base.getLocale(); // 'en'
CheckoutAPI.base.getFullLocale(); // 'en-US'
CheckoutAPI.base.formatMessage('audit.greet', '', { name: 'Audit' }); // 'Hi Audit'
CheckoutAPI.base.formatMessage('audit2.deep', '', { name: 'Audit' }); // 'deep Audit'
// 不传 defaultMessage 时，key 不存在就原样返回 key
CheckoutAPI.base.formatMessage('probe.not_exist'); // 'probe.not_exist'
CheckoutAPI.base.formatMessage('probe.not_exist', 'FALLBACK TEXT'); // 'FALLBACK TEXT'
CheckoutAPI.base.formatPrice(10); // '$10.00'
CheckoutAPI.base.formatPrice('10.5'); // '$10.50'
CheckoutAPI.base.formatPrice(10, '€'); // '€10.00'
```
用哪一份文案由顾客当前语言决定：`getLocale()` 返回短格式，`getFullLocale()` 返回作为 map key 的完整标记。当前语言下没有这个 key 时，返回传入的 `defaultMessage`；没传 `defaultMessage` 就原样返回 key 本身。
### 展示状态
| 方法 | 用途 | 参数 | 返回 |
|---|---|---|---|
| `getSpecialInstructionVisible` | 备注输入框是否展示 | — | `boolean` |
| `getBillingVisible` | 账单地址是否展示 | — | `boolean` |
| `getVirtualBillingVisible` | 虚拟商品的账单地址是否展示 | — | `boolean` |
| `getBillingSelectorVisible` | 「账单地址复用收货地址」的选择框是否展示 | — | `boolean` |
| `getPickupAddressVisible` | 自提地址列表是否展示 | — | `boolean` |
| `getPickupInformationVisible` | 自提信息模块是否展示 | — | `boolean` |
| `getAddressCardVisible` | 已填信息卡片是否展示 | — | `boolean` |
| `getDeliveryMethodVisible` | 交付方式模块是否展示 | — | `boolean` |
| `getExpressCheckoutVisible` | 快捷支付是否展示 | — | `boolean` |
| `getDeliveryVisible` | 物流方案列表是否展示 | — | `boolean` |
| `getMobileCouponVisible` | 移动端的优惠码输入框是否展示 | — | `boolean` |
| `getSummaryCouponVisible` | 桌面端的优惠码输入框是否展示 | — | `boolean` |
| `getAddressBookVisible` | 地址簿是否展示 | — | `boolean` |
| `getShippingAddressVisible` | 收货地址是否展示 | — | `boolean` |
| `getContactInformationVisible` | 联系方式模块是否展示 | — | `boolean` |
| `setIsExpandedManually` | 记录顾客手动展开了已填信息卡片 | `val: boolean` | `void` |
| `getIsExpandedManually` | 顾客是否手动展开过已填信息卡片 | — | `boolean` |
| `getVisibleConfig` | 一次获取全部模块的展示状态 | — | VisibleConfig |
| `onVisibleConfigChange` | 注册展示状态变化的回调 | cb: VisibleConfigChangeCb | `void` |
| `removeVisibleConfigChangeCb` | 删除展示状态变化的回调 | cb: VisibleConfigChangeCb | `void` |
| `getShowDetails` | 平台下发的卡片收起配置 | — | ShowDetails |
| `getGiftCardBillingVisible` | 礼品卡订单的账单地址表单是否展示 | — | `boolean` |
## config
`config` 命名空间是只读的店铺和页面配置：主题、多市场、特性开关，以及当前打开的是结账页还是感谢页。
| 方法 | 用途 | 参数 | 返回 |
|---|---|---|---|
| `getFeatureConfig` | 获取结账页的特性开关配置 | — | CheckoutFeatures |
| `getThemeConfig` | 获取结账页的主题配置 | — | CheckoutThemeConfig |
| `getAppConfig` | 获取结账页的应用配置 | — | CheckoutAppConfig |
| `getMarketConfig` | 获取多市场配置 | — | MarketInfo |
| `getShopConfig` | 获取店铺配置 | — | ShopConfig |
| `getRootUrl` | 获取接口根地址 | — | `string` |
| `getPolicyTitles` | 获取页脚政策链接的标题列表 | — | `string[]` |
| `isThankyouPage` | 当前页是否是感谢页 | — | `boolean` |
| `isCheckoutPage` | 当前页是否是结账页 | — | `boolean` |
| `getCSettings` | 获取结账页的页面级设置 | — | CSettings |
| `isMobileLayout` | 当前是否采用移动端布局，窗口宽度小于 768px 时生效 | — | `boolean` |
| `onThemeConfigChange` | 注册主题配置变化的回调 | cb: ThemeConfigChangeCb | `void` |
| `removeThemeConfigChange` | 移除主题配置变化的回调 | cb: ThemeConfigChangeCb | `void` |
| `updateThemeConfig` | 更新主题配置 | config: Partial<CheckoutThemeConfig> | `void` |
## coupon
`coupon` 命名空间管顾客能用的优惠：领用的优惠券、手输的优惠码，以及礼品卡。它既能读当前生效的优惠、增删优惠码和礼品卡，也能改写礼品卡与优惠码 tag 的展示。
### 优惠券
| 方法 | 用途 | 参数 | 返回 |
|---|---|---|---|
| `applyCoupon` | 使用一张优惠券 | `code: string` | `Promise` |
| `cancelCoupon` | 取消一张已使用的优惠券 | `code: string` | `Promise` |
| `getAvailableCouponData` | 获取本单可用的优惠券列表 | — | CouponData |
| `getSelectedDiscountCoupon` | 获取当前生效的优惠券 | — | DiscountApplication | undefined |
| `getUnavailableCouponData` | 获取本单不可用的优惠券列表 | — | CouponData |
| `isShowDiscountCoupon` | 是否展示优惠券入口 | — | `boolean` |
| `onAvailableCouponDataChange` | 注册可用优惠券列表变化的回调 | cb: CouponListChangeCb | `void` |
| `onCouponChange` | 注册已用优惠券变化的回调 | cb: CouponChangeCb | `void` |
| `onUnavailableCouponDataChange` | 注册不可用优惠券列表变化的回调 | cb: CouponListChangeCb | `void` |
| `removeAvailableCouponDataChangeCb` | 移除可用优惠券列表变化的回调 | cb: CouponListChangeCb | `void` |
| `removeCouponChangeCb` | 移除已用优惠券变化的回调 | cb: CouponChangeCb | `void` |
| `removeUnavailableCouponDataChangeCb` | 移除不可用优惠券列表变化的回调 | cb: CouponListChangeCb | `void` |
| `requestCouponList` | 按可用状态拉取优惠券列表 | status: CouponAvailStatus | `Promise` |
### 礼品卡与优惠码
| 方法 | 用途 | 参数 | 返回 |
|---|---|---|---|
| `registerGiftCardTagChange` | 注册某一个优惠码或礼品卡 tag 的改写回调，用来定制这个 tag 的展示 | `id: string`cb: GiftCardTagChange | `void` |
| `getGiftCardTags` | 获取礼品卡和优惠码的 tag 列表 | — | GiftCardTagItem[] |
| `onDiscountChange` | 注册 tag 列表变化的回调 | cb: GiftCardTagsChangeCb | `void` |
| `removeDiscountChangeCb` | 删除 tag 列表变化的回调 | cb: GiftCardTagsChangeCb | `void` |
| `getGiftCards` | 获取本单已使用的礼品卡 | — | GiftCard[] |
| `getDiscountCodes` | 获取本单已使用的优惠码 | — | DiscountApplication[] |
| `getDiscountApplications` | 获取本单生效的全部优惠，包含优惠码和自动促销活动 | — | DiscountApplication[] |
| `applyGiftCardOrDiscountCode` | 使用一个优惠码或礼品卡；position 标明来源输入框，仅用于埋点 | `code: string``position?: 'coupon-pc' \| 'coupon-mobile'` | `Promise` |
| `cancelGiftCardOrDiscountCode` | 取消已使用的优惠码或礼品卡 | parasm: CancelCouponParams | `Promise` |
| `applyDiscount` | 批量使用优惠码 | `codes: string[]` | Promise<PriceResult | undefined> |
| `cancelDiscountCode` | 批量取消已使用的优惠码 | `codes: string[]` | Promise<PriceResult | undefined> |
| `isCurrentStepShowDiscountCode` | 按店铺配置判断当前步骤是否展示优惠码和礼品卡入口 | step?: CheckoutStep | `boolean` |
| `registerGiftCardTagsFilter` | 注册礼品卡与优惠码 tag 的过滤回调，决定哪些 tag 会展示 | cb: GiftCardTagsFilter | `void` |
## exception
`exception` 命名空间管结账过程中的业务异常：检查接口返回里的异常码、读取和清空已存的异常、监听提交错误，以及商品被剔除时的弹窗状态。
| 方法 | 用途 | 参数 | 返回 |
|---|---|---|---|
| `checkException` | 检查接口返回里有没有业务异常码：有就把异常信息存下来并返回 false，没有则返回 true。存下的信息可以用来弹窗或做其他提示 | exception?: ExceptNotification | `boolean` |
| `onExceptionChange` | 注册业务异常信息变化的回调，存入和清空都会触发 | cb: ExceptionChangeCbs | `void` |
| `removeExceptionChangeCb` | 删除业务异常信息变化的回调 | cb: ExceptionChangeCbs | `void` |
| `unsetException` | 清空当前存储的业务异常信息 | — | `void` |
| `getSubmitErrorInfo` | 获取当前提交相关的错误信息 | — | SubmitError | undefined |
| `setSubmitErrorInfo` | 设置提交相关的错误码。提交时平台已经设过一次，这里一般用来清空 | code: IExceptionCode | '' | `void` |
| `onSubmitErrorChange` | 注册提交错误变化的回调 | cb: SubmitErrorChangeCbs | `void` |
| `removeSubmitErrorChangeCb` | 删除提交错误变化的回调 | cb: SubmitErrorChangeCbs | `void` |
| `getExceptionInfo` | 获取存储的业务异常信息 | — | ExceptionInfo |
| `getException` | 获取当前存着的业务异常 | — | IException | undefined |
| `handleExceptionOk` | 执行业务异常弹窗上确认按钮的处理逻辑 | — | `Promise` |
## extension
`extension` 命名空间管的是扩展自身：注册扩展、读取某个点位上已注册的内容、监听扩展加载完成、查询和监听哪些原生模块被隐藏，以及拼出动态扩展点的真实名字。
| 方法 | 用途 | 参数 | 返回 |
|---|---|---|---|
| `generateRealDynamicPoint` | 把带 `{id}` 的动态点位模板拼成真实点位名 | point: ExtensionPoint`id?: string` | `string` |
| `getExtensionComponents` | 有id说明为动态点位 返回对应点位的 extension component信息，比getExtensionContent具有更全面的信息 | point: ExtensionPoint`id?: string` | ExtensionComponent[] |
| `getExtensionContent` | 有id说明为动态点位 返回对应点位的extension字符串，不存在则返回空 | point: ExtensionPoint`id?: string` | `string` |
| `getExtensionList` | 获取extension列表 | — | Extension[] |
| `getPlaceholderContent` | 返回对应点位的占位内容，ui层使用innerHtml插入这些内容 | point: ExtensionPoint | `string` |
| `isHideExtensionTarget` | 判断某个扩展目标是否隐藏，ui层根据这个决定要不要隐藏某个扩展组件 | target: ExtensionTarget | `boolean` |
| `onAllExtensionLoaded` | 注册所有 extension 加载完毕的回调 | cb: AllExtensionLoadedCb | `void` |
| `onExtensionLoad` | 注册一个回调，当某个点位的extension完成加载时执行回调 | cb: ExtensionLoadCb | `void` |
| `onHideExtensionTarget` | isHideExtensionTarget 发生变更 | cb: HideExtensionTargetCb | `void` |
| `registerExtension` | 注册一个扩展，extension开发者使用这个函数完成extension的注册 | params: RenderParams | `Promise` |
| `removeAllExtensionLoadedCb` | 注销所有 extension 加载完毕的回调 | cb: AllExtensionLoadedCb | `void` |
| `removeHideExtensionTarget` | 移除回调 | cb: HideExtensionTargetCb | `void` |
## order
`order` 命名空间管的是顾客下单途中做的选择：交付方式、物流方案、运输保障、小费、留言备注和提交动作，以及每次变更之后的价格刷新。
### 交付方式
| 方法 | 用途 | 参数 | 返回 |
|---|---|---|---|
| `getDeliveryMethodList` | 获取交付方式列表 | — | DeliveryMethodItem[] |
| `getSelectedDeliveryMethod` | 获取当前选中的交付方式 | — | DeliveryMethodItem |
| `updateDeliveryMethod` | 切换选中的交付方式，返回重算后的价格 | type: CheckoutBusinessType | Promise<PriceResult | undefined> |
| `onDeliveryMethodChange` | 注册交付方式发生变化的回调 | cb: DeliveryMethodChangeCb | `void` |
| `removeDeliveryMethodChangeCb` | 删除交付方式发生变化的回调 | cb: DeliveryMethodChangeCb | `void` |
| `onDeliveryMethodListChange` | 注册交付方式列表变化的回调 | cb: DeliveryListChangeCb | `void` |
| `removeDeliveryMethodListChange` | 移除交付方式列表变化的回调 | cb: DeliveryListChangeCb | `void` |
| `unregisterDeliveryMethodListChange` | 注销交付方式列表的改写回调 | cb: DeliveryMethodListChangeCb | `void` |
| `registerDeliveryMethodListChange` | 注册交付方式列表的改写回调，用于定制每一项的内容，例如隐藏图标或插入文案；回调必须返回一份完整的列表 | cb: DeliveryMethodListChangeCb | `void` |
### 商品行
| 方法 | 用途 | 参数 | 返回 |
|---|---|---|---|
| `addLineItems` | 新增 checkout 商品行，成功后自动调 /prices 重算并更新金额 | params: AddLineItemsInput | Promise<LineMutationResult> |
| `removeLineItems` | 移除 checkout 商品行，成功后自动调 /prices 重算并更新金额 | params: RemoveLineItemsInput | Promise<LineMutationResult> |
### 提交与校验
| 方法 | 用途 | 参数 | 返回 |
|---|---|---|---|
| `couldSubmit` | 当前是否允许提交，用于自定义提交按钮的禁用状态 | — | `boolean` |
| `onSubmitChange` | 注册提交状态发生变化的回调 | cb: SubmitChangeCb | `void` |
| `removeSubmitChangeCb` | 删除提交状态发生变化的回调 | cb: SubmitChangeCb | `void` |
| `preSaveAddress` | 把当前表单里填写的地址预存到订单 | — | `Promise` |
| `submitInformationAndNavigate` | 提交信息步并跳到下一步，过程中会跑表单校验和扩展校验；只有两页和三页布局会用到 | — | Promise<ValidateResult[] | undefined> |
| `registerBuyerJourneyIntercept` | 注册结算中断规则：回调返回 block 时弹窗拦下提交，返回 allow 则放行 | cb: BuyerJourneyInterceptCb | `void` |
| `addBeforeSubmitCb` | 添加一个地址提交前的校验回调，平台自带的两项是邮箱和地址 | cb: BeforeSubmitCb | `void` |
| `removeBeforeSubmitCb` | 移除地址提交前的校验回调 | cb: BeforeSubmitCb | `void` |
| `submitAddressAndShippingLines` | 提交地址和选中的物流方案 | — | Promise<Res<SubmitSuccessData>> |
| `submitShippingLinesAndNavigate` | 提交物流方案并跳到下一步，只有三页布局会用到 | — | Promise<ValidateResult[] | undefined> |
| `submitValidate` | 提交前的通用校验：按当前布局和所处步骤挑选要校验的项，并把焦点移到第一个不通过的输入框 | — | Promise<ValidateResult[]> |
| `unregisterBuyerJourneyIntercept` | 注销结算中断规则 | cb: BuyerJourneyInterceptCb | `void` |
### 小费
| 方法 | 用途 | 参数 | 返回 |
|---|---|---|---|
| `getTippingOptions` | 获取小费的预设档位列表 | — | TippingOption[] |
| `onTippingChange` | 注册小费发生变化的回调 | cb: TippingChangeCb | `void` |
| `removeTippingChangeCb` | 删除小费发生变化的回调 | cb: TippingChangeCb | `void` |
| `handleTipping` | 提交小费，type 区分选中预设档位（select）和顾客手动输入（input） | `value: number``type: 'select' \| 'input'` | `Promise` |
| `getTippingInfo` | 获取小费信息：是否支持和展示小费、货币符号、已收小费，以及扣除优惠（不含免邮券）后的商品小计 | — | TippingInfo |
### 物流
| 方法 | 用途 | 参数 | 返回 |
|---|---|---|---|
| `getShippingLines` | 获取当前地址可用的物流方案列表 | — | FormatShippingLineType[] |
| `getSelectedShippingLine` | 获取当前选中的物流方案，没有选中时返回 null | — | FormatShippingLineType | null |
| `updateSelectedShippingLine` | 切换选中的物流方案 | shippingLine: ShippingLineType | `Promise` |
| `shouldCalculateShippingLine` | 当前是否应该请求物流方案；三页布局在信息步返回 false | — | `boolean` |
| `onShippingChange` | 注册物流方案发生变化的回调 | cb: ShippingChangeCb | `void` |
| `removeShippingChangeCb` | 删除物流方案发生变化的回调 | cb: ShippingChangeCb | `void` |
| `isShippingMethodAutoSelect` | 店铺后台是否配置了自动选中物流方案 | — | `boolean` |
| `isSupportShippingLinesCollapse` | 物流方案列表是否支持折叠，只有单页和两页布局支持 | — | `boolean` |
| `getShippingPromptMessage` | 获取物流方案列表当前的提示文案，没有提示时返回 null | — | PromptMessage | null |
| `onShippingPromptMessageChange` | 注册物流方案列表提示文案发生变化的回调 | cb: ShippingPromptMessageChangeCb | `void` |
| `removeShippingPromptMessageChange` | 删除物流方案列表提示文案发生变化的回调 | cb: ShippingPromptMessageChangeCb | `void` |
| `dispatchShippingChange` | 手动触发一次物流方案变更的通知 | — | `void` |
| `getShippingLinesErrorInfo` | 获取物流方案列表的错误信息 | — | ShippingLinesErrorInfo |
| `getUiShippingLines` | 获取页面最终展示的物流方案列表，可能已经被扩展改写过 | — | FormatShippingLineType[] |
| `unregisterUiShippingLinesChange` | 注销物流方案列表的改写回调 | cb: UiShippingLinesChangeCb | `void` |
| `registerUiShippingLinesChange` | 注册物流方案列表的改写回调，决定页面最终展示哪些物流方案；回调必须返回一份完整的列表 | cb: UiShippingLinesChangeCb | `void` |
### 运输保障
| 方法 | 用途 | 参数 | 返回 |
|---|---|---|---|
| `getChargeQuotes` | 获取运输保障服务列表 | — | ChargeQuote[] |
| `onShippingProtectionChange` | 注册运输保障服务变化的回调 | cb: ShippingProtectionChangeCb | `void` |
| `removeShippingProtectionChangeCb` | 移除运输保障服务变化的回调 | cb: ShippingProtectionChangeCb | `void` |
| `switchShippingProtection` | 勾选或取消某一项运输保障服务 | `quoteId: string``selected: boolean` | Promise<SwitchShippingProtectionResult> |
### 留言备注
| 方法 | 用途 | 参数 | 返回 |
|---|---|---|---|
| `getSpecialInstructionNote` | 获取顾客填写的留言备注 | — | `string` |
| `updateSpecialInstructionNote` | 写入留言备注内容，saveToBackend 为 true 时同时保存到订单 | `note: string``saveToBackend?: boolean` | `Promise` |
| `onChangeSpecialInstruction` | 注册留言备注发生变化的回调 | `cb: (info: string) => void` | `void` |
| `removeSpecialInstructionChangeCb` | 删除留言备注发生变化的回调 | `cb: (info: string) => void` | `void` |
| `expendSpecialInstruction` | 展开留言备注输入框 | — | `void` |
| `isInstructionCollapse` | 留言备注输入框当前是否折叠 | — | `boolean` |
| `onInstructionCollapseChange` | 注册留言备注折叠状态发生变化的回调 | cb: IsSpecialInstructionCollapseChange | `void` |
| `removeInstructionCollapseChange` | 删除留言备注折叠状态发生变化的回调 | cb: IsSpecialInstructionCollapseChange | `void` |
### 自定义字段
| 方法 | 用途 | 参数 | 返回 |
|---|---|---|---|
| `getOrderCustomFields` | 获取当前订单已保存的自定义业务字段。读的是页面已加载的订单数据，直接返回结果，不发请求；订单没有字段时返回空对象 | — | `Record` |
| `updateOrderCustomFields` | 设置或删除当前订单的自定义业务字段。只在订单还可编辑时能用：感谢页、订单已取消、订单尚未创建时直接失败，不发请求 | params: UpdateOrderCustomFieldsInput | Promise<UpdateCustomFieldsResult> |
### 已填信息卡片
| 方法 | 用途 | 参数 | 返回 |
|---|---|---|---|
| `getCollapseInfo` | 获取已填信息卡片的内容：联系方式、收货地址、交付方式、物流方案，以及是否显示新建地址按钮 | — | CollapseInfo |
| `onCollapseInfoChange` | 注册已填信息卡片发生变化的回调 | cb: CollapseInfoChangeCb | `void` |
| `removeCollapseInfoChangeCb` | 删除已填信息卡片发生变化的回调 | cb: CollapseInfoChangeCb | `void` |
### 订单数据与价格更新
| 方法 | 用途 | 参数 | 返回 |
|---|---|---|---|
| `updateDataByPriceApi` | 重新请求价格接口并刷新页面上的价格数据 | params?: UpdateDataByPriceApiParams | Promise<PriceResult | undefined> |
| `updateDataByOrderAndPriceApi` | 并发请求订单详情接口和价格接口并刷新两份数据，常用于出错之后重新拉取 | params?: UpdateDataByPriceApiParams | Promise<UpdateDataByOrderAndPriceApiResult> |
| `updateDataByOrderApi` | 重新请求订单详情接口并刷新订单数据 | — | Promise<OrderResult | undefined> |
| `calculatePrice` | 按传入参数试算价格，只返回结果，不写回结账页的数据 | params?: UpdateDataByPriceApiParams | Promise<PriceResult | undefined> |
## payment
`payment` 命名空间管支付方式：有哪些可选、当前选中哪一个、发起支付，以及支付尝试、支付失败和支付完成时的回调。
| 方法 | 用途 | 参数 | 返回 |
|---|---|---|---|
| `paymentPay` | 顾客点击提交后发起支付 | — | `Promise` |
| `getPaymentLines` | 获取支付列表里的全部支付方式 | — | PaymentUpdateParams['paymentLines'] |
| `getSelectedPaymentLine` | 获取当前选中的支付方式 | — | PaymentLine | null | undefined |
| `onAfterPay` | 注册支付完成后的回调 | cb: AfterPayCb | `void` |
| `onPayAttempt` | 注册支付尝试的回调；它在表单校验之前触发，校验没过、支付其实没拉起也算一次尝试 | cb: PayAttemptCb | `void` |
| `onPayFailed` | 注册支付失败的处理回调，可以注册多个：触发时依次调用，取第一个有返回值的结果作为最终结果 | handler: PayFailedHandler | `void` |
| `removePayAttemptCb` | 移除支付尝试的回调 | cb: PayAttemptCb | `void` |
## pickup
`pickup` 命名空间管门店自提：自提点列表、顾客选中的自提点、取货信息表单，以及自提相关的校验。
| 方法 | 用途 | 参数 | 返回 |
|---|---|---|---|
| `getPickupLocations` | 获取自提点列表 | — | PickupLocation[] |
| `getPickupLocationValidateResult` | 获取自提点的校验结果 | — | ValidateResult | undefined |
| `onPickupLocationValidateResultChange` | 注册自提点校验结果变化的回调 | cb: ValidatePickupResultChangeCb | `void` |
| `removePickupLocationValidateResultChange` | 删除自提点校验结果变化的回调 | cb: ValidatePickupResultChangeCb | `void` |
| `validatePickupLocation` | 校验是否已经选了自提点 | — | Promise<ValidateResult | undefined> |
| `getSelectedPickupLocation` | 获取当前选中的自提点 | — | PickupLocation | undefined |
| `updatePickupLocation` | 切换选中的自提点，返回重算后的价格 | location: PickupLocation | Promise<PriceResult | undefined> |
| `onPickupLocationsChange` | 注册自提点列表变化的回调 | cb: PickupLocationsChangeCb | `void` |
| `removePickupLocationsChangeCb` | 删除自提点列表变化的回调 | cb: PickupLocationsChangeCb | `void` |
| `onSelectedPickupLocationChange` | 注册选中自提点变化的回调 | cb: SelectedPickupLocationChangeCb | `void` |
| `removeSelectedPickupLocationChangeCb` | 删除选中自提点变化的回调 | cb: SelectedPickupLocationChangeCb | `void` |
| `onPickupInformationChange` | 注册取货信息变化的回调 | cb: PickupInformationChangeCb | `void` |
| `removePickupInformationChangeCb` | 删除取货信息变化的回调 | cb: PickupInformationChangeCb | `void` |
| `getPickupInformationSchema` | 获取取货信息表单的 schema 配置 | — | AddressItemSchema[] |
| `validatePickupInfo` | 校验自提信息表单 | — | Promise<ValidateResult[]> |
## step
`step` 命名空间管结账的步骤：读取当前步骤、在步骤之间跳转、步骤导航栏的配置，以及跳出结账页去店铺的其他页面。
| 方法 | 用途 | 参数 | 返回 |
|---|---|---|---|
| `getStep` | 获取顾客当前所在的步骤 | — | CheckoutStep |
| `isInformationStep` | 当前是否在信息步 | — | `boolean` |
| `isShippingStep` | 当前是否在配送步；配送步只有三页布局的第二页才有 | — | `boolean` |
| `isPaymentStep` | 当前是否在支付步；支付步是三页和两页布局的最后一页 | — | `boolean` |
| `stepNavToInformation` | 跳转到信息步 | type?: EventType | `Promise` |
| `stepNavToShipping` | 跳转到配送步 | type?: EventType | `Promise` |
| `stepNavToPayment` | 跳转到支付步 | — | `Promise` |
| `stepNavToNext` | 跳转到下一步，布局和结算方式的差异由平台抹平 | — | `Promise` |
| `stepNavToPrevious` | 跳回上一步 | — | `void` |
| `hasShippingMethodStep` | 本单有没有配送步；没有选自提且不是虚拟商品才有 | — | `boolean` |
| `getNavigateLinks` | 获取步骤导航栏的配置 | — | NavigateLink[] |
| `onNavigateLinksChange` | 注册导航栏配置变化的回调 | cb: NavigateLinksChangeCb | `void` |
| `removeNavigateLinksChange` | 删除导航栏配置变化的回调 | cb: NavigateLinksChangeCb | `void` |
| `onStepChange` | 注册步骤变化的回调 | cb: StepChangeCb | `void` |
| `removeStepChangeCb` | 删除步骤变化的回调 | cb: StepChangeCb | `void` |
| `navigateClick` | 按导航栏点击的行为跳转到指定步骤 | id: CheckoutStep | `Promise` |
| `couldNavTo` | 导航栏能不能跳到指定步骤。导航栏只能往回跳，往前推进要靠提交当前步骤 | id: CheckoutStep | `boolean` |
| `stepNavTo` | 跳转到指定步骤 | id: CheckoutSteplocation?: EventType | `Promise` |
| `navToReferrerPage` | 跳回顾客进入结账页之前的那个页面 | — | `void` |
| `goToOrderInfoPage` | 跳转到订单详情页 | — | `void` |
| `goToHomePage` | 跳转到店铺首页 | — | `void` |
| `disableJump` | 禁止步骤跳转，可以指定只禁止哪几种跳转方式 | way?: JumpWay[] | `Promise` |
| `getReturnBtnText` | 获取返回按钮的文案，返回空字符串表示不展示这个按钮 | — | `string` |
| `goToThankyouPage` | 跳转到感谢页 | — | `void` |
| `isDisableJump` | 当前是否禁止步骤跳转 | — | `boolean` |
| `locationHref` | location.href统一用这个 | `url: string` | `void` |
| `stepNavToWithoutSubmit` | 跳到指定步骤，不提交当前步骤的数据 | id: CheckoutStep | `void` |
## store
`store` 命名空间是订单数据的所在地。订单本身、价格、业务类型和结账页布局都从这里读，数据刷新也在这里监听。
| 方法 | 用途 | 参数 | 返回 |
|---|---|---|---|
| `onPricesChange` | 注册价格发生变化的回调；回调触发时商品行的折后价可能仍是旧值，需要商品行数据时稍后再读 | cb: PricesChangeCb | `void` |
| `removePricesChangeCb` | 删除价格发生变化的回调 | cb: PricesChangeCb | `void` |
| `getOrderStatus` | 获取订单状态 | — | OrderStatus |
| `onOrderChange` | 注册订单数据刷新的回调，订单详情接口和价格接口写入新数据时触发。回调不带数据，要用对应的 get 方法去取 | cb: OnStoreDataChangeCb | `void` |
| `removeOrderChangeCb` | 删除订单数据刷新的回调 | cb: OnStoreDataChangeCb | `void` |
| `getPrices` | 获取订单的价格信息 | — | CheckoutPrices |
| `getOrderInfo` | 获取订单基础信息 | — | OrderInfo |
| `getOrderConfig` | 获取订单属性，例如结账页布局和订单业务类型 | — | OrderConfig |
| `getBusinessType` | 获取订单业务类型 | — | CheckoutBusinessType |
| `getCheckoutSettings` | 获取店铺的结账页设置 | — | CheckoutSettings |
| `getInstructionType` | 获取备注输入框的折叠配置 | — | InstructionType |
| `getCustomerAuthority` | 获取下单权限配置，login 表示只有登录顾客才能下单 | — | CustomerAuthority |
| `setBusinessType` | 设置订单业务类型，自提布局会用到 | type: CheckoutBusinessType | `void` |
| `onBusinessTypeChange` | 注册订单业务类型变化的回调 | cb: CheckoutBusinessTypeChangeCb | `void` |
| `removeBusinessTypeChangeCb` | 删除订单业务类型变化的回调 | cb: CheckoutBusinessTypeChangeCb | `void` |
| `getPageType` | 获取结账页布局类型，页面存续期间不会变 | — | CheckoutPageType |
| `isThreeStepPage` | 当前是否三页结账布局 | — | `boolean` |
| `isTwoStepPage` | 当前是否两页结账布局 | — | `boolean` |
| `isOneStepPage` | 当前是否单页结账布局 | — | `boolean` |
| `getContactType` | 获取店铺收集联系方式的配置 | — | ContactType |
| `getAddressSettings` | 获取地址表单配置 | — | CheckoutAddressSettings |
| `isPageTypeSupportFirstStepCollapse` | 当前布局是否支持在第一步把地址收成卡片，只有单页和两页布局支持 | — | `boolean` |
| `isStandardTemplate` | 当前是否物流配送结账模板 | — | `boolean` |
| `isVirtualTemplate` | 当前是否虚拟商品结账模板；订单里全是虚拟商品时才是 | — | `boolean` |
| `isStandardBusiness` | 订单业务类型是否为物流配送 | — | `boolean` |
| `isVirtualBusiness` | 订单业务类型是否为虚拟商品 | — | `boolean` |
| `isPickupTemplate` | 当前是否自提结账模板；商家配了自提点就是自提模板。顾客是不是真走自提要看 isSelectedPickup | — | `boolean` |
| `isSelectedPickup` | 本单是否走自提；自提模板且顾客选了自提才为 true | — | `boolean` |
| `isDirectPayment` | 订单是否由商家后台创建；这类订单会直接落到支付步 | — | `boolean` |
| `isShippingInInformationStep` | 物流方案是否展示在第一步。单页和两页布局把物流放在信息步，这决定了第一步要不要算运费 | — | `boolean` |
| `isCartOrder` | 订单是否从购物车下单 | — | `boolean` |
| `isBuyNowOrder` | 订单是否从商详页立即购买下单 | — | `boolean` |
| `getReferInfo` | 获取订单的来源信息 | — | ReferInfo |
| `getTaxLines` | 获取税费明细 | — | TaxLines |
| `isGiftCardOrder` | 判断是否礼品卡商品订单 | — | `boolean` |
| `isOrderIdEmpty` | 当前订单 id 是否为空 | — | `boolean` |
| `onPageTypeChange` | 注册结账页布局变化的回调 | cb: PageTypeChangeCb | `void` |
| `removePageTypeChange` | 移除结账页布局变化的回调 | cb: PageTypeChangeCb | `void` |
| `setOrderId` | 设置订单 id | `id: string` | `void` |
| `setPageType` | 设置结账页布局 | type: CheckoutPageType | `void` |
## summary
`summary` 命名空间管订单摘要那一列：商品行列表、价格明细，以及运费的展示文案。
| 方法 | 用途 | 参数 | 返回 |
|---|---|---|---|
| `getProductList` | 获取商品行列表，带 properties 自定义属性字段 | — | ProductItem[] |
| `onProductListChange` | 注册商品行列表变化的回调 | cb: ProductListChangeCb | `void` |
| `removeProductListChangeCb` | 删除商品行列表变化的回调 | cb: ProductListChangeCb | `void` |
| `getPriceList` | 获取平台算好的价格明细分组 | — | PriceGroupDetail[] |
| `onPriceListChange` | 注册价格明细变化的回调 | cb: PriceListChangeCb | `void` |
| `removePriceListChangeCb` | 删除价格明细变化的回调 | cb: PriceListChangeCb | `void` |
| `getShippingPriceDisplay` | 获取运费的展示文案 | — | `string` |
| `onShippingPriceDisplayChange` | 注册运费展示文案变化的回调 | cb: ShippingPriceDisplayChangeCb | `void` |
| `removeShippingPriceDisplayChange` | 删除运费展示文案变化的回调 | cb: ShippingPriceDisplayChangeCb | `void` |
| `registerUiProductListChange` | 注册商品行列表的改写回调，决定页面最终渲染哪些商品行；回调必须返回一份完整的列表 | cb: UiProductListChangeCb | `void` |
| `getGiftCardPrice` | 获取礼品卡的价格明细 | — | PriceGroupDetail | undefined |
| `dispatchPriceListChange` | 手动通知界面重新渲染价格明细 | — | `void` |
| `dispatchProductListChange` | 手动触发一次商品列表的界面刷新 | — | `void` |
| `getUiProductList` | 获取订单摘要最终展示的商品列表，可能已经被扩展改写过 | — | UIProduct[] |
| `unregisterUiProductListChange` | 注销商品列表的改写回调 | cb: UiProductListChangeCb | `void` |
## track
`track` 命名空间用来上报埋点事件。既有通用的 `track`，也有结账页各个环节的专用方法（进入结账、填地址、选物流、发起支付等），另外还能读取上报用的订单数据、给某个事件附加自定义字段。
| 方法 | 用途 | 参数 | 返回 |
|---|---|---|---|
| `track` | 上报一个埋点事件 | `event: string``data?: Record` | `void` |
| `getAssemblyOrder` | 获取埋点上报用的订单数据 | — | CheckoutOrder |
| `registerTrackExtraInfo` | 给某个埋点事件附加自定义字段，之后每次上报这个事件都会带上 | `eventName: string``data: Record` | `void` |
| `trackAddPaymentInfo` | 上报填写支付信息事件 | `extra?: Record` | `void` |
| `trackAddShippingMethod` | 上报选择物流方案事件 | — | `void` |
| `trackAddressFill` | 上报地址自动填充事件 | data: TrackAddressFillParams | `void` |
| `trackAddressFormExpand` | 上报地址表单展开事件 | reason: AddressExpandReason | `void` |
| `trackAioBeforePay` | 上报聚合支付发起前的事件 | — | `void` |
| `trackBeforePay` | 上报发起支付前的事件 | `extra?: Record` | `void` |
| `trackCompleteOrderClick` | 上报点击下单按钮事件 | — | `void` |
| `trackCompleteOrderError` | 上报下单失败事件 | `data: string` | `void` |
| `trackContinueToPayment` | 上报进入支付步骤事件 | — | `void` |
| `trackCouponChangeTab` | 上报优惠券面板切换 tab 的事件 | `status: string` | `void` |
| `trackEnterCheckout` | 上报进入结账页事件 | — | `void` |
| `trackGiftCard` | 上报礼品卡相关事件 | type: TrackGiftCardProps`info: Record` | `void` |
| `trackInitialAddressFill` | 上报地址首次填充事件 | — | `void` |
| `trackInitiateCheckout` | 上报发起结账事件 | — | `void` |
| `trackLogout` | 上报登出事件 | — | `void` |
| `trackPaymentRedirect` | 上报支付跳转事件，参数是跳转页的加载耗时 | `loadTime: number` | `void` |
| `trackShippingAddressSubmitErrors` | 上报收货地址提交失败事件 | `code: string` | `void` |
| `trackShippingMethodsCardExpose` | 上报物流方案卡片曝光事件 | — | `void` |
| `trackShippingMethodsRender` | 上报物流方案渲染成功事件 | — | `void` |
| `trackShippingMethodsRequest` | 上报物流方案拉取事件 | triggerSource: ShippingMethodsFetchTriggerSource | `void` |
| `trackSubmitAddress` | 上报提交地址事件 | options?: TrackSubmitAddressParams | `void` |
| `trackTipping` | 上报小费相关事件 | type: TrackTippingTypedata: TrackTippingData | `void` |
## user
`user` 命名空间管顾客是谁、怎么联系：登录状态、账号信息、结账页填写的邮箱和手机号，以及营销邮件订阅。
### 顾客信息
| 方法 | 用途 | 参数 | 返回 |
|---|---|---|---|
| `isLogin` | 顾客是否已登录 | — | `boolean` |
| `getIPAddress` | 获取顾客的 IP 地址信息 | — | CheckoutIpAddress |
| `doLogin` | 跳转到登录页；传入的参数会拼进登录后的返回地址 | `returnUrlSearchParams?: Record` | `void` |
| `doRegister` | 跳转到注册页 | — | `void` |
| `doLogout` | 登出当前顾客 | — | `Promise` |
| `getUserInfo` | 获取已登录顾客的账号信息 | — | UserInfo |
| `getCustomerInfo` | 获取提交订单时要带上的顾客信息 | — | CheckoutCustomerInfo |
| `updateCustomerInfo` | 更新提交订单时要带上的顾客信息 | data: Partial<CheckoutCustomerInfo> | `void` |
| `onUserInfoChange` | 注册顾客账号信息变化的回调 | cb: UserInfoChangeCb | `void` |
| `removeUserInfoChangeCb` | 删除顾客账号信息变化的回调 | cb: UserInfoChangeCb | `void` |
### 联系信息
| 方法 | 用途 | 参数 | 返回 |
|---|---|---|---|
| `getEmail` | 获取顾客填写的联系邮箱 | — | `string` |
| `getPhone` | 获取顾客填写的联系电话 | — | `string` |
| `getPhoneAreaCode` | 获取顾客填写的电话区号 | — | `string` |
| `getEmailOrPhone` | 店铺配置为收集「邮箱或手机号」时，获取顾客实际填的那一个 | — | `string` |
| `getContactInformation` | 获取联系信息：邮箱、手机号、区号，以及「邮箱或手机号」字段 | — | ContactInformation |
| `onContactInformationChange` | 注册联系信息变化的回调 | cb: ContactInformationChangeCb | `void` |
| `removeContactInformationChangeCb` | 删除联系信息变化的回调 | cb: ContactInformationChangeCb | `void` |
| `setNewsletter` | 设置营销邮件订阅的勾选状态 | val: NewsLetterStatus | `void` |
| `getNewsletter` | 获取营销邮件订阅的勾选状态 | — | NewsLetterStatus |
## utils
`utils` 命名空间提供结账页自带的弹窗和抽屉，外加三个原样透传的 lodash 函数。
| 方法 | 用途 | 参数 | 返回 |
|---|---|---|---|
| `debounce` | lodash 的 debounce，原样透传 | — | `unknown` |
| `get` | lodash 的 get，原样透传 | — | `unknown` |
| `throttle` | lodash 的 throttle，原样透传 | — | `unknown` |
| `createDialog` | 创建弹窗（模态确认框） | content: DialogContentoptions?: DialogOptions | IDialog |
| `createDrawer` | 创建抽屉式弹层（从屏幕边缘滑出） | content: DrawerContentoptions?: DrawerOptions | IDrawer |
**用法**
两个方法的第一个参数放内容和按钮文案，第二个可选参数放隐藏按钮、尺寸这类选项。`createDialog` 返回 `{ show, hide }`，`createDrawer` 返回 `{ show, hide, onClose, destroy, getId }`。顾客点确认后，`show()` 的 Promise 解析为 `true`。
```javascript
const dialog = CheckoutAPI.utils.createDialog({
content: '确认寄到这个地址？
',
footer: '预计 3 到 5 天送达
',
trueBtn: '确定',
falseBtn: '取消',
});
const confirmed = await dialog.show(); // 顾客点「确定」后为 true
const drawer = CheckoutAPI.utils.createDrawer({
content: '确认寄到这个地址？
',
footer: '预计 3 到 5 天送达
',
});
drawer.onClose((type) => {
// 顾客点确认时，type 是 'true_btn'
});
await drawer.show();
```
抽屉不传 `trueBtn` 和 `falseBtn` 时用默认的 Yes 和 No。弹窗关闭后节点仍留在 DOM 里，只是隐藏而不是移除，所以创建一次复用即可，不要每次点击都新建一个。
## utils.eventBus
`utils.eventBus` 是结账页内的事件总线，用来在同一个页面上的多个扩展之间传消息。事件名统一加上扩展 id 前缀，写成 `{extension-id}:{event}`，避免和别的扩展撞名。
| 方法 | 用途 | 参数 | 返回 |
|---|---|---|---|
| `emit` | 触发一个事件 | `name: string``...rest: any[]` | `void` |
| `on` | 注册事件监听 | `name: string``cb: Function` | `void` |
| `once` | 注册只触发一次的事件监听 | `name: string``cb: Function` | `void` |
| `off` | 移除事件监听 | `name: string``cb: Function` | `void` |
## 类型定义
上面方法表里出现的类型。`CountryCode` 来自 `libphonenumber-js` 包，这里不重复定义。
### AdditionalPrice {#type-additionalprice}
| 字段 | 类型 | 说明 |
|---|---|---|
| `name?` | `string` | 附加费的名称 |
| `price?` | `string` | 附加费的金额 |
### AdditionalProperty {#type-additionalproperty}
| 字段 | 类型 | 说明 |
|---|---|---|
| `id` | `string` | 字段名称，也是 extraInfo 里的 key |
| `name` | `string` | 字段的展示名称 |
| `inputType` | `1 \| 2 \| 3 \| 4` | 输入类型，对应界面上的输入控件 |
| `enable` | `1` | 是否启用 |
| `showType` | `'all' \| 'and' \| 'or'` | 展示条件：all 全部显示，and 全部规则命中才显示，or 任一规则命中就显示 |
| `showRules` | `Array<{ field: string; rules: string[]; }>` | 展示规则 |
| `require` | `0 \| 1` | 顾客是否必须填，`1` 表示必填 |
| `description` | `string` | 这个字段的说明 |
| `validates` | `Array<{ type: 'regex'; regexp: ''; }>` | 生效的校验规则 |
| `enums?` | `Array<{ name: string; value: string; }>` | 下拉类型的枚举值 |
### AdditionValues {#type-additionvalues}
| 字段 | 类型 | 说明 |
|---|---|---|
| `[key: string]` | `{ name: string; val: string; }` | 其他任意 key，按名字索引 |
### AddLineItemsInput {#type-addlineitemsinput}
| 字段 | 类型 | 说明 |
|---|---|---|
| `lineItems` | AddProductInput[] | 订单的商品行 |
| `mutationSource` | MutationSource | 你自己填的标记，说明这次改动是谁发起的 |
### AddProductInput {#type-addproductinput}
| 字段 | 类型 | 说明 |
|---|---|---|
| `variantId` | `string` | 规格 ID |
| `quantity` | `number` | 数量 |
| `properties?` | ProductProperties | 要写到新订单行上的自定义属性，JSON 字符串 |
### AddressBookChangeCbs {#type-addressbookchangecbs}
```typescript
export type AddressBookChangeCbs = () => void;
```
### AddressBookItem {#type-addressbookitem}
| 字段 | 类型 | 说明 |
|---|---|---|
| `address` | `string \| null` | 街道地址 |
| `address1` | `string \| null` | 街道地址第一行 |
| `area` | `string \| null` | 区 / 县 |
| `city` | `string \| null` | 城市 |
| `company` | `string \| null` | 公司名称 |
| `country` | `string \| null` | 国家 / 地区名称 |
| `countryCode` | `string \| null` | 国家 / 地区代码 |
| `createdAt` | `string \| null` | 这条记录的创建时间 |
| `email` | `string \| null` | 邮箱地址 |
| `firstName` | `string \| null` | 名 |
| `gender` | `string \| null` | 地址上记录的性别 |
| `id` | `string \| null` | 这一项的唯一 ID |
| `isDefault` | `boolean` | 是否为默认地址 |
| `lastName` | `string \| null` | 姓 |
| `phone` | `string \| null` | 手机号 |
| `phoneAreaCode` | `string \| null` | 手机号的国际电话区号 |
| `province` | `string \| null` | 省 / 州名称 |
| `provinceCode` | `string \| null` | 省 / 州代码 |
| `zip` | `string \| null` | 邮政编码 |
### AddressChangeByInputCb {#type-addresschangebyinputcb}
```typescript
export type AddressChangeByInputCb = (
changeValue: Partial,
fullAddress: AddressValues,
config: ChangeValuesConfig,
) => void;
```
### AddressChangeCb {#type-addresschangecb}
```typescript
export type AddressChangeCb = () => void;
```
### AddressCountry {#type-addresscountry}
| 字段 | 类型 | 说明 |
|---|---|---|
| `isoCode2` | `string` | 两位国家 / 地区代码 |
| `name` | `string` | 国家 / 地区名称 |
| `provinces` | AddressCountryProvince[] | 该国家 / 地区下的省 / 州列表 |
| `depth` | `number` | 这个国家 / 地区的地址层级数 |
| `code` | `string` | 两位国家 / 地区代码 |
| `preset` | `string` | |
| `format?` | AddressFormat | 地址格式模板 |
### AddressCountryProvince {#type-addresscountryprovince}
| 字段 | 类型 | 说明 |
|---|---|---|
| `cnName` | `string` | 中文名称 |
| `code` | `string` | 省 / 州代码 |
| `name` | `string` | 省 / 州名称 |
| `oldCode` | `string` | |
| `provinceId` | `string` | 省 / 州的 ID |
| `preset?` | `string` | |
| `format?` | AddressFormat | 这个字段的格式规则 |
### AddressExpandReason {#type-addressexpandreason}
| 取值 | 说明 |
|---|---|
| `'manual_click'` | 顾客点击展开了表单 |
| `'empty_fallback_click'` | 顾客点了折叠状态下的空表单 |
| `'auto_fill'` | 表单因为被自动填充而展开 |
| `'submit_validate'` | 为了显示校验报错而展开表单 |
| `'browser_fill'` | 浏览器自动填了表单 |
### AddressFormat {#type-addressformat}
| 字段 | 类型 | 说明 |
|---|---|---|
| `fields` | AddressFormatField[] | 这个模板包含的字段 |
| `[k: string]` | `any` | 其他任意 key，按名字索引 |
### AddressFormatField {#type-addressformatfield}
| 字段 | 类型 | 说明 |
|---|---|---|
| `id` | `string` | 这一项的唯一 ID |
| `label?` | `string` | 字段上方显示的标签 |
| `show?` | `0 \| 1` | 这一项是否显示 |
| `row?` | `number` | 这个字段在表单网格里所处的行 |
| `description?` | `string` | 这个字段的说明 |
| `[k: string]` | `any` | 其他任意 key，按名字索引 |
### AddressItemActionSchema {#type-addressitemactionschema}
| 字段 | 类型 | 说明 |
|---|---|---|
| `id` | `string` | 这一项的唯一 ID |
| `show` | `true` | 这一项是否显示 |
| `type` | FieldType.Action | 字段类型，固定为操作项 |
| `text` | `string` | 操作项的文字 |
| `row` | `number` | 这个字段在表单网格里所处的行 |
| `col` | `number` | 这个字段在表单网格里所处的列 |
| `style?` | `Record` | 加在元素上的行内样式 |
| `className?` | `string` | 加在元素上的 CSS class |
| `onClick()` | `void` | 顾客点击这一行时调用 |
### AddressItemCheckoutSchema {#type-addressitemcheckoutschema}
| 字段 | 类型 | 说明 |
|---|---|---|
| `id` | `string` | 这一项的唯一 ID |
| `type` | FieldType.Checkbox | 字段类型，固定为复选框 |
| `desc` | `string` | 复选框旁边的文案 |
| `show` | `true` | 这一项是否显示 |
| `value` | `boolean` | 复选框是否已勾选 |
| `row` | `number` | 这个字段在表单网格里所处的行 |
| `col` | `number` | 这个字段在表单网格里所处的列 |
| `changeValue(isCheck)` | `void` | 勾选或取消勾选这个复选框 |
### AddressItemEmailSchema {#type-addressitememailschema}
| 字段 | 类型 | 说明 |
|---|---|---|
| `type` | FieldType.Email | 字段类型，固定为邮箱 |
### AddressItemGeneralPhoneSchema {#type-addressitemgeneralphoneschema}
手机号字段的 schema。它还带有 `BaseAddressItemSchema` 和 `ValueInterface` 的全部字段，下面只列它自己的成员。
| 字段 | 类型 | 说明 |
|---|---|---|
| `type` | FieldType.Phone | 字段类型，固定为手机号 |
| `phoneInfo` | PhoneInfo | 手机号字段的区号和格式规则 |
| `maxLength?` | `number` | 允许输入的最大字符数 |
| `changePhone(value, format?, config?)` | `void` | 往字段里写一个新的手机号 |
| `changePhoneAreaCode(value)` | `void` | 往字段里写一个新的国际电话区号 |
### AddressItemPhoneSchema {#type-addressitemphoneschema}
手机号字段 schema 的别名，等价于 `AddressItemGeneralPhoneSchema`。
```typescript
export type AddressItemPhoneSchema = AddressItemGeneralPhoneSchema;
```
### AddressItemSchema {#type-addressitemschema}
地址表单里一个字段的 schema，按字段类型分成下拉、手机号、文本、邮箱四种。
```typescript
export type AddressItemSchema =
| AddressItemSelectSchema
| AddressItemPhoneSchema
| AddressItemStringSchema
| AddressItemEmailSchema;
```
### AddressItemSelectSchema {#type-addressitemselectschema}
| 字段 | 类型 | 说明 |
|---|---|---|
| `type` | FieldType.Enum | 字段类型，固定为下拉选择 |
| `selectType` | SelectType | 选项列表是固定的还是实时拉取，取值同 `SelectType` |
| `options` | OptionValue[] | 下拉列表里的选项 |
### AddressItemStringSchema {#type-addressitemstringschema}
| 字段 | 类型 | 说明 |
|---|---|---|
| `type` | FieldType.String | 字段类型，固定为文本 |
| `readOnly?` | `boolean` | 只读，禁止修改 |
| `format?` | `Array<[regexp: string, params: string[]]> \| string[]` | 值的格式化规则，例如巴西税号在失焦时会按规则重新排版 |
### AddressItemTitleSchema {#type-addressitemtitleschema}
| 字段 | 类型 | 说明 |
|---|---|---|
| `id` | `string` | 这一项的唯一 ID |
| `show` | `true` | 这一项是否显示 |
| `type` | FieldType.Title | 字段类型，固定为标题 |
| `title` | `string` | 标题文字 |
| `row` | `number` | 这个字段在表单网格里所处的行 |
| `col` | `number` | 这个字段在表单网格里所处的列 |
### AddressManagerConfig {#type-addressmanagerconfig}
| 字段 | 类型 | 说明 |
|---|---|---|
| `useAllCountry` | `boolean` | 是否列出所有国家 / 地区，而不只是可配送的那些 |
### AddressSchemaManager {#type-addressschemamanager}
地址表单的 schema 管理器，一个实例对应一张地址表单，负责取值、改值、拿字段 schema 和校验。
```typescript
class AddressSchemaManager {
getFieldType(key: keyof AddressValues);
updateContext(context: AddressSchemaManagerContext, config?: AddressManagerConfig);
onUpdateContext(cb: UpdateContextCb);
registerSchemaChange(field: keyof AddressValues, cb: AddSchemaChangeCbs);
onAddressChangeByInput(cb: AddressChangeByInputCb);
removeAddressChangeByInput(cb: AddressChangeByInputCb);
onAddressChange(cb: AddressValuesChangeCb);
removeAddressChange(cb: AddressValuesChangeCb);
onFieldsChange(cb: FieldsChangeCb);
getAddressValues();
changeValues(values: Partial, config?: ChangeValuesConfig);
onValuesChange(cb: AddressValuesChangeCb);
removeValuesChangeCb(cb: AddressValuesChangeCb);
dispatchAddressValuesChange(changeVal: Partial, options?: AddressValuesChangeOptions);
validateFields(fieldIds?: Array, config?: { updateUi?: boolean; onlyValidateExistValue?: boolean }): Promise;
onValidateResultChange(cb: ValidateResultChangeCb);
removeValidateResultChange(cb: ValidateResultChangeCb);
getCountries();
hasCountry(countryCode: string);
getProvinces();
isValidProvinceCode(code: string);
getAllSchema(): Array;
getCustomLabelById(id: string);
getCountryCodeSchema(): AddressItemSelectSchema | null;
getProvinceSchema(config?: { emptyHide: boolean }): AddressItemSelectSchema | AddressItemStringSchema | null;
getCitySchema(): AddressItemSelectSchema | AddressItemStringSchema | null;
getAreaSchema(): AddressItemSelectSchema | AddressItemStringSchema | null;
getAddressSchema(config?: { ignoreSettings?: boolean }): AddressItemSelectSchema | AddressItemStringSchema | null;
getAddress1Schema(config?: { ignoreSettings?: boolean }): AddressItemStringSchema | null;
getZipSchema(config?: { noUseSetting: boolean }): AddressItemStringSchema | null;
getFirstNameSchema(config?: { ignoreSettings?: boolean }): AddressItemStringSchema | null;
getLastNameSchema(config?: { ignoreSettings?: boolean }): AddressItemStringSchema | null;
getCompanySchema(config?: { ignoreSettings?: boolean }): AddressItemStringSchema | null;
getCustomizedFields(): Array;
getPhoneSchema(config: ContactSchemaConfig): AddressItemGeneralPhoneSchema | AddressItemStringSchema | null;
getEmailSchema(config: ContactSchemaConfig): AddressItemEmailSchema | null;
getEmailOrPhoneSchema(): AddressItemStringSchema | null;
getIdNumberSchema(): AddressItemStringSchema | null;
getCpfSchema(): AddressItemStringSchema | null;
formatPhone(value: string);
changePhone(value: string, format?: boolean, config?: ChangeValueConfig);
changePhoneAreaCode(code: string, setEmailOrPhone?: boolean);
changeEmailOrPhone(values: Partial, config?: ChangeValueConfig);
}
```
这个管理器自己持有内部状态，所以这里按源码列出、不转成表格。实例从 `CheckoutAPI.address` 上取，不要自己 new。
### AddressSchemaManagerContext {#type-addressschemamanagercontext}
| 字段 | 类型 | 说明 |
|---|---|---|
| `addressValues` | AddressValues | 地址表单当前的取值 |
| `addressTemplate` | AddressTemplate | 当前国家 / 地区的地址模板 |
### AddressTemplate {#type-addresstemplate}
| 字段 | 类型 | 说明 |
|---|---|---|
| `fields` | AddressTemplateField[] | 这个模板要收集的地址字段 |
| `stringify` | `string` | |
| `preset` | `string` | |
| `addressLevel` | `number` | 地址层级数 |
### AddressTemplateField {#type-addresstemplatefield}
| 字段 | 类型 | 说明 |
|---|---|---|
| `id` | `string` | 这一项的唯一 ID |
| `col` | `number` | 这个字段在表单网格里所处的列 |
| `row` | `number` | 这个字段在表单网格里所处的行 |
| `show` | `0 \| 1` | 这一项是否显示 |
| `format?` | `Array<[regexp: string, params: string[]]> \| string[]` | 取值需要匹配的格式规则 |
| `length?` | `number \| { min?: number; max?: number }` | 取值允许的长度 |
| `required` | `0 \| 1` | 顾客是否必须填这一项 |
| `type` | FieldType | 这一项的类型 |
| `label?` | `string` | 字段上方显示的标签 |
| `tips?` | `string` | 字段下方显示的提示文字 |
| `validate?` | AddressTemplateFieldValidate[] | 这个字段的校验规则 |
### AddressTemplateFieldValidate {#type-addresstemplatefieldvalidate}
| 字段 | 类型 | 说明 |
|---|---|---|
| `id` | `string` | 这一项的唯一 ID |
| `message` | `string` | 校验不通过时显示的文案 |
| `regexp` | `string` | 取值需要匹配的正则表达式 |
### AddressValues {#type-addressvalues}
| 字段 | 类型 | 说明 |
|---|---|---|
| `id?` | `string` | 地址 ID |
| `firstName` | `string` | 名 |
| `lastName` | `string` | 姓 |
| `countryCode` | `string` | 国家 / 地区代码 |
| `country` | `string` | 国家 / 地区名称 |
| `provinceCode` | `string` | 省 / 州代码 |
| `province` | `string` | 省 / 州名称 |
| `area` | `string` | 区 / 县 |
| `city` | `string` | 城市 |
| `address` | `string` | 详细地址 |
| `address1` | `string` | 详细地址第二行（门牌号、公寓号等） |
| `shortAddress?` | `string` | 短地址 |
| `zip` | `string` | 邮编 |
| `cpf?` | `string` | 税号 |
| `taxText?` | `string` | 税号名字 |
| `idNumber?` | `string` | 身份证号 |
| `idNumberText?` | `string` | 身份证号名字 |
| `company` | `string` | 公司名 |
| `latitude?` | `string` | 纬度 |
| `longitude?` | `string` | 经度 |
| `source?` | `string` | 当前这份地址取值的来源 |
| `tags?` | `string` | |
| `gender?` | `string` | 性别 |
| `phone` | `string` | 手机号 |
| `emailOrPhone` | `string` | 邮箱或手机号合并字段的值 |
| `email` | `string` | 邮箱 |
| `phoneAreaCode` | `string` | 手机区号 |
| `[key: string]` | `string \| undefined` | 其他任意 key，按名字索引 |
| `originId?` | `string` | 这个值来自哪条地址的 ID |
### AddressValuesChangeCb {#type-addressvalueschangecb}
```typescript
export type CommonAddressValuesChangeCb = (
changeValue: Partial,
fullAddress: AddressValues,
options?: AddressValuesChangeOptions,
) => void;
```
### AddressValuesChangeOptions {#type-addressvalueschangeoptions}
| 字段 | 类型 | 说明 |
|---|---|---|
| `apiAutoFilled?` | `boolean` | 这个值是接口自动填的，不是顾客填的 |
| `changeByInput?` | `boolean` | 这次变化是否由顾客输入引起 |
### AddSchemaChangeCbs {#type-addschemachangecbs}
```typescript
type AddSchemaChangeCbs = (item: AddressItemSchema) => AddressItemSchema;
```
### AfterPayCb {#type-afterpaycb}
```typescript
export type AfterPayCb = (res: AfterPayParams) => void;
```
### AfterPayParams {#type-afterpayparams}
一次支付尝试的结果：支付请求走通时是 `PayResponse` 再加一个 `loadTime`，抛异常时是 `Error`，没有结果可报时是 `undefined`。
```typescript
export type AfterPayParams =
| (PayResponse & {
loadTime: number;
})
| Error
| undefined;
```
### AllExtensionLoadedCb {#type-allextensionloadedcb}
```typescript
export type AllExtensionLoadedCb = () => void;
```
### AlreadyPaymentLines {#type-alreadypaymentlines}
这笔订单上已经收到的支付记录数组，下面是数组里一项的字段。
| 字段 | 类型 | 说明 |
|---|---|---|
| `creditCardNumber` | `string` | 这次支付使用的卡号 |
| `extraInfo` | `{ name: string; channel: string; method: string; lastCharacters: string; realPaidTotal: string; }` | 这笔支付的附加信息 |
| `paidTotal` | `string` | 这笔支付收到的金额 |
### AppliedGiftCard {#type-appliedgiftcard}
| 字段 | 类型 | 说明 |
|---|---|---|
| `id` | `string` | 这一项的唯一 ID |
| `lastCharacters` | `string` | 礼品卡卡号的末几位 |
| `amountUsed` | `string` | 礼品卡已抵扣的金额 |
| `realAmountCurrency` | `string` | 礼品卡本身的币种 |
| `realSymbol` | `string` | 礼品卡本身币种的符号 |
| `realAmountUsed` | `string` | 按礼品卡本身币种计的已用金额 |
### BannerConfig {#type-bannerconfig}
| 字段 | 类型 | 说明 |
|---|---|---|
| `checkoutPcImage` | `string` | 桌面端使用的 Banner 图片 |
| `checkoutMobileImage` | `string` | 移动端使用的 Banner 图片 |
| `checkoutImageHeight` | `'normal' \| 'large' \| 'small'` | Banner 图片的高度档位 |
| `checkoutAlignment` | `'top' \| 'center' \| 'bottom'` | Banner 的垂直对齐方式 |
| `checkoutIsFullWidth` | `boolean` | Banner 是否通栏铺满页面宽度 |
| `checkoutShowBottomMargin` | `boolean` | Banner 下方是否留出下边距 |
### BaseAddressItemSchema {#type-baseaddressitemschema}
| 字段 | 类型 | 说明 |
|---|---|---|
| `id` | `string` | 这一项的唯一 ID |
| `row` | `number` | 这个字段在表单网格里所处的行 |
| `col` | `number` | 这个字段在表单网格里所处的列 |
| `show` | `boolean` | 这一项是否显示 |
| `label` | `string` | 字段上方显示的标签 |
| `eventBus` | EventBus | 这个字段自带的事件总线 |
| `description?` | `string` | 这个字段的说明 |
| `max?` | `number` | 允许的最大值 |
| `min?` | `number` | 允许的最小值 |
| `tips?` | `string` | 字段下方显示的提示文字 |
| `autocomplete?` | `string` | 写在输入框 `autocomplete` 属性上的值 |
| `required` | `boolean` | 顾客是否必须填这一项 |
| `readonly?` | `boolean` | 只读会禁止修改 |
| `htmlAttr?` | `Record` | 加在输入框上的额外 HTML 属性 |
| `fieldType?` | `'standard' \| 'custom'` | 标准属性和自定义添加属性 |
| `focusId?` | `string` | 要聚焦的输入框 ID |
| `nameId?` | `string` | 写在输入框 `name` 属性上的值 |
| `placeType?` | PlaceType | 地址自动补全要匹配的地点类型 |
| `validateFn(updateUi?)` | Promise<ValidateResult | undefined> | 校验字段当前的值 |
| `validateByValue?` | (val: string) => ValidateResult | undefined | 校验你传进来的值，不改动字段本身 |
| `validateResult?` | ValidateResult | 上一次校验的结果 |
| `onValidateResultChange(cb)` | `void` | 注册校验结果变化时的回调 |
| `removeValidateResultChange(cb)` | `void` | 取消一个校验结果变化回调 |
### BasePriceDetail {#type-basepricedetail}
| 字段 | 类型 | 说明 |
|---|---|---|
| `key?` | `string` | 这一行明细的标识 |
| `dataRobot?` | `string` | |
| `title?` | `string` | 这一行的标题 |
| `titleLangId?` | `string` | 标题的翻译 key |
| `subTitle?` | `string` | 这一行的副标题 |
| `subTitleLangId?` | `string` | 副标题的翻译 key |
| `originPrice?` | `string` | 折扣前的金额 |
| `price?` | `string` | 这一行的金额 |
| `originalValue?` | `string` | 这一行未格式化的原始值 |
| `value?` | `string` | 这一项的取值 |
| `desc?` | `string` | 这一行附带的说明文字 |
| `descLangId?` | `string` | 说明文字的翻译 key |
| `icon?` | `string` | 这一行显示的图标 |
| `isShow?` | `boolean` | 这一行是否显示 |
| `tooltip?` | `string` | 这一行的悬浮提示文字 |
### BaseResponse {#type-baseresponse}
| 字段 | 类型 | 说明 |
|---|---|---|
| `ok` | `boolean` | 这次请求是否成功 |
| `config` | ReqConfig | 随这次请求或这笔订单带上的配置 |
### BeforeSubmitCb {#type-beforesubmitcb}
```typescript
export type BeforeSubmitCb = (params: BeforeSubmitCbParams) => Promise;
```
### BeforeSubmitCbParams {#type-beforesubmitcbparams}
| 字段 | 类型 | 说明 |
|---|---|---|
| `pageType` | CheckoutPageType | 结账页布局，取值同 `CheckoutPageType` |
| `step` | CheckoutStep | 对应的结账步骤 |
### BillingAddress {#type-billingaddress}
| 字段 | 类型 | 说明 |
|---|---|---|
| `id?` | `string` | 这一项的唯一 ID |
| `firstName` | `string` | 名 |
| `lastName` | `string` | 姓 |
| `email` | `string` | 邮箱地址 |
| `emailOrPhone` | `string` | 顾客填的那一项，邮箱或手机号 |
| `phone` | `string` | 手机号 |
| `phoneAreaCode` | `string` | 手机号的国际电话区号 |
| `countryCode` | `string` | 国家 / 地区代码 |
| `country` | `string` | 国家 / 地区名称 |
| `provinceCode` | `string` | 省 / 州代码 |
| `province` | `string` | 省 / 州名称 |
| `area` | `string` | 区 / 县 |
| `city` | `string` | 城市 |
| `address` | `string` | 街道地址 |
| `address1` | `string` | 街道地址第一行 |
| `zip` | `string` | 邮政编码 |
| `company` | `string` | 公司名称 |
### BillingAddressChangeCb {#type-billingaddresschangecb}
```typescript
export type BillingAddressChangeCb = () => void;
```
### BillingAddressValuesChangeCb {#type-billingaddressvalueschangecb}
```typescript
export type BillingAddressValuesChangeCb = (values: Partial) => void;
```
### BuyerJourneyInterceptCb {#type-buyerjourneyinterceptcb}
```typescript
export type BuyerJourneyInterceptCb = () => BuyerJourneyInterceptCbReturn;
```
### BuyerJourneyInterceptCbReturn {#type-buyerjourneyinterceptcbreturn}
| 字段 | 类型 | 说明 |
|---|---|---|
| `behavior` | `'block' \| 'allow'` | 拦下顾客还是让他继续 |
| `pointId` | `string` | 拦截来自哪个扩展点的 ID |
| `hideTrueBtn?` | `boolean` | 隐藏弹窗的确认按钮 |
| `hideFalseBtn?` | `boolean` | 隐藏弹窗的取消按钮 |
### CancelCouponParams {#type-cancelcouponparams}
```typescript
export type CancelCouponParams =
| {
code: string;
discountCodeType: DiscountCodeType.DISCOUNT_CODE;
}
| {
id: string;
discountCodeType: DiscountCodeType.GIFT_CARD;
};
```
### CardInfo {#type-cardinfo}
| 字段 | 类型 | 说明 |
|---|---|---|
| `cardFirstName` | `string` | 持卡人名 |
| `cardLastName` | `string` | 持卡人姓 |
| `cardDate` | `string` | 卡片有效期 |
| `cardCode` | `string` | 卡片上的安全码 |
| `cardNumber` | `string` | 卡号 |
| `instalmentsPlans` | `string` | 卡片上选择的分期方案 |
### Cards {#type-cards}
| 字段 | 类型 | 说明 |
|---|---|---|
| `supportCards` | Array<PlayCardCards> | 这个支付方式支持的卡种 |
### ChangedLineItem {#type-changedlineitem}
| 字段 | 类型 | 说明 |
|---|---|---|
| `id` | `string` | 这一项的唯一 ID |
| `productId` | `string` | 商品 ID |
| `variantId` | `string` | 规格 ID |
| `quantity` | `number` | 数量 |
| `originalQuantity` | `number` | 改动之前的数量 |
| `image` | `{ src: string; }` | 商品图片 |
| `productTitle` | `string` | 商品标题 |
| `options` | `Array<{ name: string; value: string }>` | 这一项可选的取值 |
| `properties` | `string` | 挂在这一行上的自定义属性 |
| `reason` | `\| 'line_item_sold_out' \| 'line_item_shortage' \| 'line_item_off_line' \| 'line_item_not_exist' \| 'line_item_mismatch_wholesale_conditions'` | 这一行发生变化的原因 |
### ChangeValueConfig {#type-changevalueconfig}
| 字段 | 类型 | 说明 |
|---|---|---|
| `format?` | `boolean` | 写入时是否顺便格式化这个值 |
| `changeByInput?` | `boolean` | 这次变化是否由顾客输入引起 |
### ChangeValuesConfig {#type-changevaluesconfig}
| 字段 | 类型 | 说明 |
|---|---|---|
| `ignoreValidate?` | `boolean` | 这次改动是否跳过校验 |
| `dispatchUpdate?` | `boolean` | 改完之后是否触发界面刷新 |
| `changeByInput?` | `boolean` | 这次变化是否由顾客输入引起 |
| `changeByUserInput?` | `boolean` | 用户手动输入 |
| `apiAutoFilled?` | `boolean` | 地址联想等 API 自动填充，UI 高亮提示 |
| `onlyValidateExistValue?` | `boolean` | 是否只校验已经有值的字段 |
### ChargeQuote {#type-chargequote}
| 字段 | 类型 | 说明 |
|---|---|---|
| `quoteId` | `string` | 报价 ID |
| `feeTitle` | `string` | 费用名称 |
| `fee` | `string` | 费用金额 |
| `feeValue` | `string` | 格式化后的费用文本 |
| `currency` | `string` | 货币代码 |
| `selected` | `boolean` | 是否已选中 |
| `available` | `boolean` | 是否可选 |
| `providerIcon` | `string` | 服务商图标 |
| `providerName` | `string` | 服务商名称 |
| `title` | `string` | 标题 |
| `description` | `string` | 描述 |
| `tooltip` | `string` | 提示文案 |
| `lineItems` | `Array<{ lineItemId: string; quantity: number; fee: string }>` | 这份报价覆盖的订单行 |
### CheckoutAddressSettings {#type-checkoutaddresssettings}
| 字段 | 类型 | 说明 |
|---|---|---|
| `name` | NameSetting | 姓名字段的设置 |
| `nameRequirement` | NmeRequirementSetting | 姓名字段的必填要求 |
| `contactDetails` | ContactDetailsSetting | 联系方式字段的设置 |
| `phone` | SimplesSetting | 手机号字段的设置 |
| `email` | SimplesSetting | 邮箱字段的设置 |
| `company` | SimplesSetting | 公司字段的设置 |
| `address` | SimplesSetting | 详细地址字段的设置 |
| `address1` | SimplesSetting | 详细地址第二行字段的设置 |
### CheckoutAppConfig {#type-checkoutappconfig}
| 字段 | 类型 | 说明 |
|---|---|---|
| `namespace` | `string` | 应用的命名空间 |
| `routes` | `{ root: string; }` | 应用路由的基础路径 |
| `currencySymbol` | `string` | 货币符号 |
| `localeRtl` | `boolean` | 当前语言是否从右往左排版 |
| `locale` | `string` | 当前语言 |
| `favicon?` | `string` | 站点图标 |
| `siteKey` | `string \| null` | 人机验证服务的 site key |
| `cdnDomain` | `string` | CDN 域名 |
| `imageDomain` | `string` | 图片域名 |
| `currencySymbolPos` | `string` | 货币符号放在金额前面还是后面 |
| `moneyFormat` | `string` | 金额格式 |
| `paymentSettings` | `{ paypalExpressEnabled: boolean; }` | 支付相关配置 |
| `market` | MarketInfo | 市场信息 |
### CheckoutBusinessType {#type-checkoutbusinesstype}
结账类型：普通商品、虚拟商品、门店自提。
| 成员 | 值 | 说明 |
|---|---|---|
| `STANDARD` | `0` | 普通实物商品 |
| `VIRTUAL_PRODUCT` | `1` | 虚拟商品，不需要配送 |
| `PICKUP` | `2` | 门店自提 |
### CheckoutBusinessTypeChangeCb {#type-checkoutbusinesstypechangecb}
```typescript
export type CheckoutBusinessTypeChangeCb = (type: CheckoutBusinessType) => void;
```
### CheckoutCustomerInfo {#type-checkoutcustomerinfo}
| 字段 | 类型 | 说明 |
|---|---|---|
| `email` | `string` | 邮箱 |
| `phone` | `string` | 手机号 |
| `emailOrPhone` | `string` | 邮箱或手机号合并字段的值 |
| `firstName` | `string` | 名 |
| `lastName` | `string` | 姓 |
| `newsletter` | `0 \| 1` | 是否订阅营销邮件，1 订阅、0 不订阅 |
| `note` | `null \| string` | 顾客备注 |
| `saveAddress` | `0 \| 1` | 是否把地址存进地址簿，1 存、0 不存 |
### CheckoutFeatures {#type-checkoutfeatures}
结账页的功能开关表，key 是功能名，值是这个功能开没开。
```typescript
export type CheckoutFeatures = Record;
```
### checkoutFontfamily {#type-checkoutfontfamily}
| 字段 | 类型 | 说明 |
|---|---|---|
| `family` | `string` | 字体族名称 |
| `fallbackFamilies` | `string` | 兜底字体族 |
| `style` | `string` | 字形 |
| `weight` | `string` | 字重 |
| `fontFace` | `string` | 这个字体对应的 `@font-face` 规则 |
### CheckoutIpAddress {#type-checkoutipaddress}
| 字段 | 类型 | 说明 |
|---|---|---|
| `countryCode` | `string` | 国家 / 地区代码 |
| `provinceName` | `string` | 省 / 州名称 |
| `countryName` | `string` | 国家 / 地区名称 |
| `city` | `string` | 城市 |
| `ip` | `string` | IP 地址 |
### CheckoutMenuPolicyLink {#type-checkoutmenupolicylink}
| 字段 | 类型 | 说明 |
|---|---|---|
| `id` | `number` | 这一项的唯一 ID |
| `title` | `string` | 只有三种内置政策才有值 |
| `type` | `string` | 菜单类型：三种内置政策为 policy，商家自定义的为 web |
| `url` | `string` | 内置政策为固定值：退款政策 refund_policy、隐私政策 privacy_policy、服务条款 service_policy； 自定义菜单为商家填写的链接，留空表示只展示文字、不跳转 |
### CheckoutOrder {#type-checkoutorder}
| 字段 | 类型 | 说明 |
|---|---|---|
| `failCode` | `string \| null` | 失败码，没失败时为空 |
| `id` | `string` | 订单 ID |
| `orderNo` | `string` | 订单号 |
| `status` | `string` | 订单状态 |
| `checkoutStatus` | `string` | 结账状态 |
| `financialStatus` | `string` | 支付状态 |
| `fulfillmentStatus` | `string` | 履约状态 |
| `postSaleStatus?` | `string \| null` | 售后状态 |
| `emailStatus?` | `string` | 订单确认邮件的状态 |
| `note?` | `string \| null` | 订单备注 |
| `customerNote` | `string` | 顾客备注 |
| `appliedGiftCards` | Array<AppliedGiftCard> | 已使用的礼品卡 |
| `alreadyPaymentLines` | AlreadyPaymentLines | 已完成的支付记录 |
| `cancelReason` | `string \| null` | 取消原因 |
| `currencyCode` | `string` | 货币代码 |
| `currencySymbol` | `string` | 货币符号 |
| `discountApplications` | Array<DiscountApplication> | 订单上生效的优惠 |
| `lineItems` | Array<LineItem> | 订单行 |
| `shippingAddress` | ShippingAddress | 收货地址 |
| `billingAddress` | BillingAddress | 账单地址 |
| `pickupLocation?` | PickupLocation | 自提点 |
| `subTotal` | `string` | 商品小计 |
| `shippingTotal?` | `string` | 运费合计 |
| `taxTotal?` | `string` | 税费合计 |
| `discountTotal?` | `string` | 优惠合计 |
| `totalTipReceived` | `string` | 小费合计 |
| `discountShippingPrice` | `string` | 运费优惠金额 |
| `total` | `string` | 订单总额 |
| `giftCardPrice` | `string` | 礼品卡抵扣金额 |
| `paymentDue` | `string` | 实付金额 |
| `paidTotal` | `string` | 已支付金额 |
| `prices` | CheckoutPrices | 价格明细 |
| `lineItemDiscountTotal` | `string` | 商品行优惠合计 |
| `codeDiscountTotal` | `string` | 优惠码优惠合计 |
| `shippingLine` | ShippingLineType | null | 当前选中的物流方案 |
| `config` | `{ checkoutBusinessType: number; checkoutTemplateType: number; pageType: 'single' \| 'three_step' \| 'two_step'; marketSetting: { marketId?: string; }; productTaxIncluded?: boolean; }` | 随这次请求或这笔订单带上的配置 |
| `customer` | Customer | 顾客信息 |
| `referInfo` | ReferInfo | 来源信息 |
| `paymentLine?` | PaymentLine | 当前选中的支付方式 |
| `paymentLines` | Array<PaymentLine> | 可选的支付方式列表 |
| `discountSubTotal?` | `string` | 商品折扣后的小计 |
| `shippingTaxTotal?` | `string` | 运费税合计 |
| `allTaxTotal?` | `string` | 全部税费合计 |
| `paymentDiscountTotal?` | `string` | 支付优惠 |
| `prePaymentAmount?` | `string` | 不含支付优惠的 paymentDue，用于判断是否需要刷新支付方式列表 |
| `additionalPrices?` | AdditionalPrice[] | 附加费用 |
| `checkoutPriceList` | PriceGroupDetail[] | 价格明细分组 |
| `taxLines` | TaxLines | 税费明细 |
| `checkoutId?` | `string` | 结账单 ID |
| `checkoutUrl?` | `string` | 结账页地址 |
| `createTime?` | `string` | 创建时间 |
| `identifierExtra?` | `string` | |
| `installmentFee?` | `string` | 分期手续费 |
| `orderKey?` | `string` | |
| `orderStatusUrl?` | `string` | 订单状态页地址 |
| `orderToken?` | `string` | 标识这次结账会话的 token |
| `orderType?` | `number` | 订单类型 |
| `refund?` | `string` | 退款金额 |
| `shippingAddressEditable?` | `boolean` | 收货地址是否还能改 |
| `shippingTaxType?` | `number` | 运费税的计算方式 |
| `taxType?` | `number` | 订单税费的计算方式 |
| `updatedTime?` | `string` | 更新时间 |
| `yetPayment?` | `string` | |
| `customFields?` | `Record` | 订单的自定义业务字段 |
### CheckoutPageType {#type-checkoutpagetype}
结账页布局：单页、两页、三页。
| 成员 | 值 | 说明 |
|---|---|---|
| `SINGLE` | `'single'` | 单页结账 |
| `THREE_STEP` | `'three_step'` | 三页结账 |
| `TWO_STEP` | `'two_step'` | 两页结账 |
### CheckoutPrices {#type-checkoutprices}
下面所有价格字段都是字符串，金额以**主单位**表示，例如 `"10.99"` 表示 10.99 美元，**不是**最小单位（不是 `"1099"` 分）。做计算时用 `Decimal.js` 之类的库，避免 JavaScript 浮点误差。
| 字段 | 类型 | 说明 |
|---|---|---|
| `subtotalPrice` | `string` | 商品小计 |
| `shippingPrice` | `string` | 运费 |
| `taxPrice` | `string` | 税费 |
| `discountCodePrice` | `string` | 优惠码优惠金额 |
| `discountPrice` | `string` | 优惠合计 |
| `totalPrice` | `string` | 订单总额 |
| `discountLineItemPrice` | `string` | 商品行优惠金额 |
| `totalTipReceived` | `string` | 小费合计 |
| `discountShippingPrice` | `string` | 运费优惠金额 |
| `giftCardPrice` | `string` | 礼品卡抵扣金额 |
| `paymentDue` | `string` | 实付金额 |
| `paidTotal` | `string` | 已支付金额 |
| `discountSubTotal?` | `string` | 商品折扣后的小计 |
| `shippingTaxTotal?` | `string` | 运费税合计 |
| `allTaxTotal?` | `string` | 全部税费合计 |
| `paymentDiscountTotal?` | `string` | 支付优惠 |
| `prePaymentAmount?` | `string` | 不含支付优惠的 paymentDue，用于判断是否需要刷新支付方式列表 |
| `additionalPrices?` | AdditionalPrice[] | 附加费用 |
| `chargeQuotes?` | ChargeQuote[] | 运输保障服务 |
### CheckoutSettings {#type-checkoutsettings}
| 字段 | 类型 | 说明 |
|---|---|---|
| `customerAuthority` | `'all' \| 'login'` | 谁可以结账：all 所有人，login 只有登录顾客 |
| `discountShowV2` | `string[]` | |
| `reductionShow` | `{ single: string[]; twoStep: string[]; threeStep: string[]; }` | 各结账布局下分别显示哪些折扣行 |
| `orderTimeout` | `number` | 订单超时时间 |
| `shippingCpf` | ShippingCpf | 配送环节用到的 CPF 字段设置 |
| `zipCheckV2` | `string` | |
| `zipCheckConfigV2` | `Record` | 各国家 / 地区的邮编校验配置 |
| `zipFormatCheck` | SwitchSetting | 是否校验邮编格式 |
| `doorplateFormatCheck` | SwitchSetting | 是否校验门牌号格式 |
| `forcedZipCheck` | `CountryCode[]` | 强制校验邮编的国家 / 地区 |
| `instruction` | `string` | 订单备注框的展示方式，取值同 `InstructionType` |
| `autoComplete` | SwitchSetting | 是否开启地址自动补全 |
| `autoCompleteCollapseMode?` | SwitchSetting | 地址被自动补全填好之后是否折叠表单 |
| `identificationInfo` | { default: IdentificationConfig; } | 身份证件的配置，按国家 / 地区索引 |
| `shippingMethodDisplayStyle` | `'auto_select' \| 'manual_select'` | 物流方案怎么选中：auto_select 自动选中，manual_select 顾客手动选 |
| `additionalProperties` | AdditionalProperty[] | 商家自定义的附加字段 |
### CheckoutStep {#type-checkoutstep}
结账步骤：填联系方式、选配送方式、选支付方式。
| 取值 | 说明 |
|---|---|
| `'contact_information'` | 填联系方式和地址的那一步 |
| `'shipping_method'` | 选配送方式的那一步 |
| `'payment_method'` | 选支付方式的那一步 |
### CheckoutThemeConfig {#type-checkoutthemeconfig}
结账页的主题配置，把 `ThemeStyleConfig`、`LogoConfig`、`MenuPolicyConfig`、`BannerConfig`、`PluginConfig`、`InteractionConfig` 六组配置的字段合并成一个对象。
| 字段 | 类型 | 说明 |
|---|---|---|
| `checkoutRecommendImageLink` | `'' \| { url: string; type: string }` | 广告位跳转链接 |
| `checkoutRecommendImage` | `string` | 广告位图片 |
| `checkoutPaymentBackgroundImage` | `string` | 付款区域背景图 |
| `checkoutPaymentBackgroundColor` | `string` | 付款区域背景色，同时配了背景图时以图片为准 |
| `checkoutInputBackgroundColor` | `string` | 输入框背景色 |
| `checkoutOrderBackgroundImage` | `string` | 订单摘要背景图 |
| `checkoutOrderBackgroundColor` | `string` | 订单摘要背景色，同时配了背景图时以图片为准 |
| `checkoutHeadingFontfamily` | checkoutFontfamily | 标题字体 |
| `checkoutBodyFontfamily` | checkoutFontfamily | 正文字体 |
| `checkoutButtonFontfamily` | checkoutFontfamily | 按钮字体 |
| `checkoutButtonBackgroundColor` | `string` | 按钮背景色，也是页脚返回链接的文字颜色 |
| `checkoutButtonText` | `string` | 按钮文字颜色 |
| `checkoutErrorColor` | `string` | 报错提示的文字颜色 |
| `checkoutFocusColor` | `string` | 输入框聚焦时的高亮颜色 |
| `checkoutBorderRadius` | `string` | 页面统一使用的圆角大小 |
| `checkoutBorderColor` | `string` | 左侧表单区域 |
| `checkoutTextMainColor` | `string` | 页面主文字颜色 |
| `checkoutTextSubColor` | `string` | 页面次文字颜色 |
| `checkoutEmptyBgColor` | `string` | 空白区域的背景色 |
| `checkoutBlockBorderColor` | `string` | 左侧卡片内部，包含输入框、物流方案卡片等 |
| `checkoutBlockTextMainColor` | `string` | 卡片内的主文字颜色 |
| `checkoutBlockTextSubColor` | `string` | 卡片内的次文字颜色 |
| `checkoutSummaryBorderColor` | `string` | 右侧订单摘要区域 |
| `checkoutSummaryTextMainColor` | `string` | 订单摘要的主文字颜色 |
| `checkoutSummaryTextSubColor` | `string` | 订单摘要的次文字颜色 |
| `checkoutSummaryBlockBorderColor` | `string` | 右侧卡片内部 |
| `checkoutSummaryBlockTextMainColor` | `string` | 订单摘要里卡片的主文字颜色 |
| `checkoutSummaryBlockTextSubColor` | `string` | 订单摘要里卡片的次文字颜色 |
| `checkoutLogoImage` | `string` | 结账页的 Logo 图片 |
| `checkoutLogoSize` | `'large' \| 'medium' \| 'small'` | Logo 的尺寸档位 |
| `checkoutLogoPosition` | `string` | Logo 的位置 |
| `checkoutMenuPolicyLink1?` | '' | CheckoutMenuPolicyLink | 第一个政策菜单项的链接目标 |
| `checkoutMenuPolicyLink2?` | '' | CheckoutMenuPolicyLink | 第二个政策菜单项的链接目标 |
| `checkoutMenuPolicyLink3?` | '' | CheckoutMenuPolicyLink | 第三个政策菜单项的链接目标 |
| `checkoutMenuPolicyText1?` | `string` | 第一个政策菜单项的文案 |
| `checkoutMenuPolicyText2?` | `string` | 第二个政策菜单项的文案 |
| `checkoutMenuPolicyText3?` | `string` | 第三个政策菜单项的文案 |
| `checkoutMenuAlignment` | `string` | 政策菜单的对齐方式 |
| `blocks` | Array<{ type: string; settings: { checkoutMenuPolicyText: string; checkoutMenuPolicyLink: CheckoutMenuPolicyLink; }; key: string; }> | 新版数据格式，上面六个字段是旧格式；两者同时存在时以 blocks 为准 |
| `checkoutPcImage` | `string` | 桌面端使用的 Banner 图片 |
| `checkoutMobileImage` | `string` | 移动端使用的 Banner 图片 |
| `checkoutImageHeight` | `'normal' \| 'large' \| 'small'` | Banner 图片的高度档位 |
| `checkoutAlignment` | `'top' \| 'center' \| 'bottom'` | Banner 的垂直对齐方式 |
| `checkoutIsFullWidth` | `boolean` | Banner 是否通栏铺满页面宽度 |
| `checkoutShowBottomMargin` | `boolean` | Banner 下方是否留出下边距 |
| `plugins` | `{ appserval: { servalBg1Color: string; servalBg2Color: string; servalDiscountColor: string; servalHeadingColor: string; showNewCustomerExclusiveTag: boolean; exclusiveForNewUsers: false; }; }` | 结账页插件的配置 |
| `checkoutPaymentIconShow` | `boolean` | 是否显示支付方式图标 |
| `checkoutMobileOrderSummaryCollapse` | `boolean` | 移动端订单摘要是否默认折叠 |
| `checkoutMobileDiscountBoxLocation` | `'orderSummaryAndPaymentMethod' \| 'orderSummary' \| 'paymentMethod'` | 移动端折扣码输入框放在哪里 |
### CloseType {#type-closetype}
| 取值 | 说明 |
|---|---|
| `'close_icon'` | 顾客点了关闭图标 |
| `'true_btn'` | 顾客点了确认按钮 |
| `'false_btn'` | 顾客点了取消按钮 |
| `'hide_fn'` | 你的代码调了 `hide()` |
### CollapseInfo {#type-collapseinfo}
| 字段 | 类型 | 说明 |
|---|---|---|
| `contact` | `string` | 折叠态里显示的联系方式 |
| `delivery` | `string` | 折叠态里显示的配送方式 |
| `addressInfo` | `string` | 折叠态里显示的地址 |
| `addressInfoTitle` | `string` | 折叠态地址那一行的标题 |
| `showNewBtn` | `boolean` | 是否显示新建收货地址按钮 |
### CollapseInfoChangeCb {#type-collapseinfochangecb}
```typescript
export type CollapseInfoChangeCb = () => void;
```
### CommonAddressValuesChangeCb {#type-commonaddressvalueschangecb}
```typescript
export type CommonAddressValuesChangeCb = (
changeValue: Partial,
fullAddress: AddressValues,
options?: AddressValuesChangeOptions,
) => void;
```
### ContactDetailsSetting {#type-contactdetailssetting}
| 取值 | 说明 |
|---|---|
| `'single'` | 只收一个联系方式字段 |
| `'multiple'` | 收多个联系方式字段 |
### ContactInformation {#type-contactinformation}
| 字段 | 类型 | 说明 |
|---|---|---|
| `email` | `string` | 邮箱 |
| `phone` | `string` | 手机号 |
| `emailOrPhone` | `string` | 邮箱或手机号合并字段的值 |
| `phoneAreaCode` | `string` | 手机区号 |
### ContactInformationChangeCb {#type-contactinformationchangecb}
```typescript
export type ContactInformationChangeCb = (contactInformation: Partial) => void;
```
### ContactSchemaConfig {#type-contactschemaconfig}
| 字段 | 类型 | 说明 |
|---|---|---|
| `type` | `'address' \| 'contact'` | 这一项的类型 |
| `showWhenOptional?` | `boolean` | 这个字段可选时是否仍然显示 |
### ContactType {#type-contacttype}
联系方式的收集方式：只收邮箱、只收手机号，或者两者填一个。
| 成员 | 值 | 说明 |
|---|---|---|
| `ONLY_EMAIL` | `'only_email'` | 只收邮箱 |
| `ONLY_PHONE` | `'only_phone'` | 只收手机号 |
| `EMAIL_OR_PHONE` | `'email_or_phone'` | 邮箱和手机号填一个就行 |
### Country {#type-country}
| 字段 | 类型 | 说明 |
|---|---|---|
| `cnName` | `string` | 中文名称 |
| `name` | `string` | 国家 / 地区名称 |
| `flag` | `string` | 国旗 |
| `phoneCode` | `string` | 电话区号 |
| `phoneKey` | `string` | 这个国家 / 地区区号的 key |
| `isoCode2` | `string` | 两位国家 / 地区代码 |
### CouponAvailStatus {#type-couponavailstatus}
| 成员 | 值 | 说明 |
|---|---|---|
| `AVAILABLE` | `'available'` | 这张券在当前订单上可用 |
| `UNAVAILABLE` | `'unavailable'` | 这张券在当前订单上不可用 |
### CouponChangeCb {#type-couponchangecb}
```typescript
export type CouponChangeCb = () => void;
```
### CouponData {#type-coupondata}
| 字段 | 类型 | 说明 |
|---|---|---|
| `page` | `number` | 当前页码 |
| `limit` | `number` | 每页条数 |
| `data` | CouponItem[] | 这一页的优惠券 |
| `total` | `number` | 总条数 |
### CouponItem {#type-couponitem}
| 字段 | 类型 | 说明 |
|---|---|---|
| `id` | `string` | 这一项的唯一 ID |
| `code` | `string` | 券码 |
| `title` | `string` | 券的名称 |
| `discountText` | `string` | 描述这张券优惠内容的文案 |
| `prerequisiteText` | `string` | 使用这张券需要满足的条件文案 |
| `createdAt` | `string` | 这条记录的创建时间 |
| `expiredAt` | `string` | 券的过期时间 |
| `isFirstOrder` | `boolean` | 这张券是否只对首单有效 |
### CouponListChangeCb {#type-couponlistchangecb}
```typescript
export type CouponListChangeCb = (data: CouponData) => void;
```
### CSettings {#type-csettings}
| 字段 | 类型 | 说明 |
|---|---|---|
| `locale` | `string` | 当前语言 |
| `localeRtl` | `boolean` | 当前语言是否从右往左排版 |
| `cdnDomain` | `string` | CDN 域名 |
| `customer` | `{ customerId: string; customerEmail: string; customerPhone: string; }` | 顾客信息 |
| `imageDomain` | `string` | 图片域名 |
| `paymentSettings` | `{ paypalExpressEnabled: true; expressCheckoutConfig: { expressAccountInfos: {}; expressChannels: string[]; expressThemeConfigs: {}; }; }` | 支付相关配置 |
| `saServerUrl` | `string` | 埋点事件上报的服务端地址 |
| `saWebUrl` | `string` | 加载埋点脚本的地址 |
| `currencyCode` | `string` | 货币代码 |
| `currencySymbol` | `string` | 货币符号 |
| `currencySymbolPos` | `string` | 货币符号放在金额前面还是后面 |
| `theme` | `{ themeVersionId: string; merchantThemeName: string; updatedAt: string; }` | 主题信息 |
| `meta` | `{ page: { templateName: string; templateType: number; }; }` | 结账页前端的页面元信息 |
| `moneyFormat` | `string` | 金额格式 |
| `slug` | `string` | |
| `clientSentryDsn` | `string` | 前端上报错误用的 Sentry DSN |
| `environment` | `string` | 前端运行所处的环境 |
| `region` | `string` | 区域代码 |
| `storePlan` | `string` | 店铺套餐 |
| `storeTrial` | `boolean` | 店铺是否在试用期 |
| `passwordEnabled` | `boolean` | 店铺是否开启了密码访问 |
| `namespace` | `string` | 结账页前端的命名空间 |
| `siteKey` | `null` | 人机验证服务的 site key |
| `routes` | `{ root: string; }` | 应用路由的基础路径 |
| `market` | `{ marketId: string; }` | 市场信息 |
| `shop` | `{ customerId: string; finance: string; financeSymbol: string; cdnDomain: string; shopName: string; themeId: string; shopId: string; shopEnv: string; defaultImg: string; templateName: string; templateType: string; favicon: string; formLang: {}; contactEmail: string; serviceEmail: string; timeZone: string; }` | 店铺信息 |
### Customer {#type-customer}
| 字段 | 类型 | 说明 |
|---|---|---|
| `id` | `string` | 顾客记录的 ID |
| `firstName` | `string` | 名 |
| `lastName` | `string` | 姓 |
| `email` | `string` | 邮箱地址 |
| `phone` | `string \| null` | 手机号 |
| `name` | `string` | 顾客的全名 |
| `orderCount` | `number` | 这位顾客下过的订单数 |
| `customerId` | `string` | 顾客 ID |
| `createAt` | `string` | 顾客资料的创建时间 |
| `registeredAt` | `string` | 顾客的注册时间 |
| `registered` | `string` | 这位顾客是否已注册店铺账号 |
| `subscribed` | `boolean` | 顾客是否订阅了营销邮件 |
### CustomerAuthority {#type-customerauthority}
谁可以结账：all 所有人，login 只有登录顾客。
| 取值 | 说明 |
|---|---|
| `'all'` | 所有人都能结账 |
| `'login'` | 只有登录顾客能结账 |
### DayConfigOfPickupTime {#type-dayconfigofpickuptime}
| 字段 | 类型 | 说明 |
|---|---|---|
| `day?` | `number` | 1-7 |
| `state?` | `number` | 0 休息，1 营业 |
| `start?` | `string` | 时间段的开始时间 |
| `end?` | `string` | 时间段的结束时间 |
### DeliveryListChangeCb {#type-deliverylistchangecb}
```typescript
export type DeliveryListChangeCb = () => void;
```
### DeliveryMethodChangeCb {#type-deliverymethodchangecb}
```typescript
export type DeliveryMethodChangeCb = (id: DeliveryMethodItem) => void;
```
### DeliveryMethodItem {#type-deliverymethoditem}
| 字段 | 类型 | 说明 |
|---|---|---|
| `iconType` | `string` | 这个配送方式用哪个图标 |
| `checkoutBusinessType` | CheckoutBusinessType | 对应的结账类型 |
| `text` | `string` | 展示文案 |
### DeliveryMethodListChangeCb {#type-deliverymethodlistchangecb}
```typescript
export type DeliveryMethodListChangeCb = (items: DeliveryMethodItem[]) => DeliveryMethodItem[];
```
### DialogContent {#type-dialogcontent}
| 字段 | 类型 | 说明 |
|---|---|---|
| `content` | `string` | 弹窗或抽屉的正文内容 |
| `footer?` | `string` | 弹窗或抽屉的底部内容 |
| `trueBtn?` | `string` | 确认按钮的文案 |
| `falseBtn?` | `string` | 取消按钮的文案 |
### DialogOptions {#type-dialogoptions}
| 字段 | 类型 | 说明 |
|---|---|---|
| `hideTrueBtn?` | `boolean` | 隐藏弹窗的确认按钮 |
| `hideFalseBtn?` | `boolean` | 隐藏弹窗的取消按钮 |
| `closeThroughResolve?` | `boolean` | 点击close icon 时返回resolve状态？； 默认为false，返回reject |
| `maskBlur?` | `boolean` | 蒙层是否启用模糊滤镜，默认为 false |
| `style?` | `{ width?: number; height?: number; maxHeight?: number; maxWidth?: number; backgroundColor?: string; }` | 加在元素上的行内样式 |
### DiscountApplication {#type-discountapplication}
| 字段 | 类型 | 说明 |
|---|---|---|
| `type` | `string` | 优惠类型 |
| `code` | `string` | 优惠码 |
| `status` | `string` | 优惠状态 |
| `message` | `string` | 提示文案 |
| `discountId` | `string` | 优惠 ID |
| `discountAmount` | `string` | 该商品优惠金额 eg. "2.00" |
| `discountMessage` | `string` | 这个折扣附带的提示文案 |
| `entitledProductList` | `Array<{ productId: string; variantId: string; price: string; quantity: number; compareAtPrice: string; inventoryTracking: boolean; inventoryQuantity: number; spu: string; }>` | 参与这个优惠的商品 |
| `valueType` | `string` | 折扣是固定金额还是百分比 |
| `targetType` | `string` | 折扣作用在什么上，比如商品或运费 |
| `targetSelection` | `string` | 折扣挑中哪些商品 |
| `title` | `string` | 优惠名称 |
| `value` | `string` | eg. "20" |
| `discountType` | `string` | 折扣的种类 |
| `allocationMethod` | `string` | 折扣在订单行之间的分摊方式 |
| `isFreeGift` | `boolean` | 是不是赠品优惠 |
| `totalDiscountAmount` | `string` | 活动总优惠金额 eg. "2" |
| `subType` | `string` | 折扣的细分类型 |
| `icon` | `string` | url |
| `labelText` | `string` | 标签文案 |
| `labelFontColor` | `string` | 标签文字颜色 |
| `labelBackgroundColor` | `string` | 标签背景色 |
### DiscountCodeType {#type-discountcodetype}
| 成员 | 值 | 说明 |
|---|---|---|
| `DISCOUNT_CODE` | `'discountCode'` | 这个码是折扣码 |
| `GIFT_CARD` | `'giftCard'` | 这个码是礼品卡 |
### DiscountTypeEnum {#type-discounttypeenum}
| 成员 | 值 | 说明 |
|---|---|---|
| `AUTOMATIC` | `'automatic'` | 自动优惠，不用输码就生效 |
| `DISCOUNT_REBATE` | `'discount_rebate'` | 满减优惠 |
| `DISCOUNT_CODE` | `'discount_code'` | 顾客手动输入的折扣码 |
| `DISCOUNT_COUPON` | `'discount_coupon'` | 顾客持有的优惠券 |
| `GIFT_CARD` | `'gift_card'` | 礼品卡 |
### DrawerContent {#type-drawercontent}
| 字段 | 类型 | 说明 |
|---|---|---|
| `content` | `string` | 弹窗或抽屉的正文内容 |
| `footer?` | `string` | 弹窗或抽屉的底部内容 |
| `trueBtn?` | `string` | 确认按钮的文案 |
| `falseBtn?` | `string` | 取消按钮的文案 |
### DrawerOptions {#type-draweroptions}
| 字段 | 类型 | 说明 |
|---|---|---|
| `hideTrueBtn?` | `boolean` | 隐藏弹窗的确认按钮 |
| `hideFalseBtn?` | `boolean` | 隐藏弹窗的取消按钮 |
| `maskBlur?` | `boolean` | 蒙层是否启用模糊滤镜，默认为 false |
| `style?` | `{ width?: number; height?: number; maxHeight?: number; maxWidth?: number; backgroundColor?: string; }` | 加在元素上的行内样式 |
### DynamicExtensionPoint {#type-dynamicextensionpoint}
```typescript
enum DynamicExtensionPoint {
// 每个动态扩展点模板一个成员，完整清单见扩展点页面
PRODUCT_RENDER_AFTER = 'Checkout::Product-{id}::RenderAfter',
SHIPPING_LINE_RENDER_AFTER = 'Checkout::ShippingLine-{id}::RenderAfter',
// ...
}
```
### EventBus {#type-eventbus}
一个小型的发布 / 订阅总线，每个地址字段的 `eventBus` 属性上挂着一个。
| 字段 | 类型 | 说明 |
|---|---|---|
| `eventMap` | `Map>` | 按事件名分组的回调集合 |
| `onceCbMap` | `Map` | 一次性回调的包装函数，按原函数索引 |
| `emit(name, ...rest)` | — | 触发一个事件，通知所有监听这个名字的回调 |
| `on(name, cb)` | — | 在一个事件名上注册回调 |
| `once(name, cb)` | — | 注册一个只触发一次的回调 |
| `off(name, cb)` | — | 把某个回调从一个事件名上移除 |
### EventType {#type-eventtype}
| 取值 | 说明 |
|---|---|
| `'change'` | 页面上某个值变了 |
| `'return'` | 顾客返回上一步 |
| `'navigate'` | 页面跳转到别处 |
### ExceptionChangeCbs {#type-exceptionchangecbs}
```typescript
export type ExceptionChangeCbs = (tags?: IException) => void;
```
### ExceptionInfo {#type-exceptioninfo}
| 字段 | 类型 | 说明 |
|---|---|---|
| `code` | `string` | 错误码 |
| `message?` | `string` | 错误信息 |
| `title?` | `string` | 标题 |
| `content?` | `string` | 正文 |
| `footer?` | `string` | 底部文案 |
| `backStep?` | `string` | 顾客会被退回到的那一步 |
| `invalidLineItems?` | Array<InvalidLineItem> | 已失效的订单行 |
| `changedLineItems?` | Array<ChangedLineItem> | 发生了变化的订单行 |
### ExceptNotification {#type-exceptnotification}
| 字段 | 类型 | 说明 |
|---|---|---|
| `code` | `string` | 异常的错误码 |
| `message?` | `string` | 异常的错误信息 |
| `nextAction?` | NextAction | 页面接下来该做什么 |
| `invalidLineItems?` | Array<InvalidLineItem> | 已经不再有效的订单行 |
| `kickLineItems?` | Array<KickLineItem> | 已经被踢出订单的订单行 |
| `thirdPartyErrorDetails?` | `Record[]` | 第三方返回的原始错误详情 |
### ExtendSchema {#type-extendschema}
地址表单里一项的 schema，除了普通字段，还包括勾选项、标题和操作项。
```typescript
export type ExtendSchema =
| AddressItemSchema
| AddressItemCheckoutSchema
| AddressItemTitleSchema
| AddressItemActionSchema;
```
### Extension {#type-extension}
| 字段 | 类型 | 说明 |
|---|---|---|
| `components` | ExtensionComponent[] | 这个扩展的组件列表 |
| `name` | `string` | 扩展名称 |
| `name_en` | `string` | 扩展的英文名称 |
| `desc` | `string` | 扩展描述 |
| `desc_en` | `string` | 扩展的英文描述 |
| `deleteTargets` | `string[]` | 这个扩展要隐藏的原生模块 |
| `placeholder` | `Record` | 占位文案，按字段 ID 索引 |
### ExtensionComponent {#type-extensioncomponent}
| 字段 | 类型 | 说明 |
|---|---|---|
| `extensionId` | `string` | 扩展 ID |
| `content` | `string` | 渲染出来的 HTML 内容 |
| `point` | `string` | 渲染到哪个扩展点 |
### ExtensionList {#type-extensionlist}
| 字段 | 类型 | 说明 |
|---|---|---|
| `extensionId` | `string` | 扩展 ID |
| `resourceUrl` | `string` | 加载扩展脚本的 URL |
| `fields?` | `string` | 扩展声明的字段 |
| `name?` | `string` | 扩展的名称 |
| `name_en?` | `string` | 英文名称 |
| `desc?` | `string` | 扩展的说明 |
| `desc_en?` | `string` | 英文说明 |
### ExtensionLoadCb {#type-extensionloadcb}
```typescript
export type ExtensionLoadCb = (point: ExtensionPoint) => void;
```
### ExtensionPoint {#type-extensionpoint}
```typescript
export type ExtensionPoint = StaticExtensionPoint | DynamicExtensionPoint;
```
### ExtensionTarget {#type-extensiontarget}
```typescript
enum ExtensionTarget {
// 每个可隐藏的原生模块一个成员，完整清单见结账扩展参考页
shippingList = 'shippingList',
couponDrawer = 'couponDrawer',
// ...
}
```
### FailPriceResult {#type-failpriceresult}
| 字段 | 类型 | 说明 |
|---|---|---|
| `data` | `null` | 结果的数据体 |
| `message` | `string` | 错误信息 |
| `state` | `string` | 结果状态，成功时为 `success` |
### FieldFnValidate {#type-fieldfnvalidate}
| 字段 | 类型 | 说明 |
|---|---|---|
| `id` | `string` | 这条校验规则的 ID |
| `message` | `string` | 校验不通过时显示的文案 |
| `validate(value)` | `boolean` | 返回这个值是否通过校验 |
### FieldRegExpValidate {#type-fieldregexpvalidate}
| 字段 | 类型 | 说明 |
|---|---|---|
| `id` | `string` | 这一项的唯一 ID |
| `message` | `string` | 校验不通过时显示的文案 |
| `regexp` | `string` | 取值需要匹配的正则表达式 |
### FieldsChangeCb {#type-fieldschangecb}
```typescript
export type FieldsChangeCb = (fields?: Array) => void;
```
### FieldType {#type-fieldtype}
| 成员 | 值 | 说明 |
|---|---|---|
| `String` | `0` | 普通文本字段 |
| `Number` | `1` | 数字字段 |
| `Enum` | `2` | 固定选项字段 |
| `Bool` | `3` | 布尔字段 |
| `Phone` | `101` | 手机号字段 |
| `Email` | `102` | 邮箱字段 |
| `Checkbox` | `103` | 勾选框 |
| `Title` | `104` | 标题行，不是输入项 |
| `Action` | `105` | 操作行，比如一个链接或按钮，不是输入项 |
### FieldValidate {#type-fieldvalidate}
```typescript
export type FieldValidate = FieldRegExpValidate | FieldFnValidate;
```
### FormatShippingLineType {#type-formatshippinglinetype}
| 字段 | 类型 | 说明 |
|---|---|---|
| `formatDiscountShippingPrice` | `string` | 带货币符号的优惠后运费 |
| `formatShippingPrice` | `string` | 带货币符号的运费 |
| `isFree` | `boolean` | 是不是免运费 |
### GetAddressTemplateParams {#type-getaddresstemplateparams}
| 字段 | 类型 | 说明 |
|---|---|---|
| `countryCode` | `string` | 国家 / 地区代码 |
| `provinceCode` | `string` | 省 / 州代码 |
### GiftCard {#type-giftcard}
| 字段 | 类型 | 说明 |
|---|---|---|
| `type` | DiscountCodeType | 码的类型 |
| `code` | `string` | 礼品卡码 |
| `id` | `string` | 礼品卡 ID |
| `title` | `string` | 礼品卡名称 |
| `lastCharacters?` | `string` | 卡号后几位 |
| `amountUsed?` | `string` | 已抵扣金额 |
| `realAmountCurrency?` | `string` | 礼品卡本身的币种 |
| `realSymbol?` | `string` | 礼品卡本身币种的符号 |
| `realAmountUsed?` | `string` | 按礼品卡本身币种计的已用金额 |
### GiftCardTagChange {#type-giftcardtagchange}
```typescript
export type GiftCardTagChange = (item: GiftCardTagItem) => GiftCardTagItem;
```
### GiftCardTagItem {#type-giftcardtagitem}
| 字段 | 类型 | 说明 |
|---|---|---|
| `disable?` | `boolean` | 是否禁用 |
| `hideIcon?` | `boolean` | 是否隐藏图标 |
### GiftCardTagsChangeCb {#type-giftcardtagschangecb}
```typescript
export type GiftCardTagsChangeCb = (tags: GiftCardTagItem[]) => void;
```
### GiftCardTagsFilter {#type-giftcardtagsfilter}
```typescript
export type GiftCardTagsFilter = (tags: GiftCardTagItem[]) => GiftCardTagItem[];
```
### HideExtensionTargetCb {#type-hideextensiontargetcb}
```typescript
export type HideExtensionTargetCb = () => void;
```
### HttpCompleteResponse {#type-httpcompleteresponse}
| 字段 | 类型 | 说明 |
|---|---|---|
| `status` | `number` | HTTP 状态码 |
| `statusText` | `string` | HTTP 状态描述 |
| `headers` | `Record` | 请求头或响应头 |
| `data` | `Payload` | 响应的数据体 |
### HttpFailResponse {#type-httpfailresponse}
| 字段 | 类型 | 说明 |
|---|---|---|
| `ok` | `false` | 这次请求是否成功 |
### HttpSuccessResponse {#type-httpsuccessresponse}
| 字段 | 类型 | 说明 |
|---|---|---|
| `ok` | `true` | 这次请求是否成功 |
### IAddressBookItem {#type-iaddressbookitem}
| 字段 | 类型 | 说明 |
|---|---|---|
| `showEmail` | `boolean` | 是否展示邮箱 |
| `showPhone` | `boolean` | 是否展示手机号 |
### IdentificationConfig {#type-identificationconfig}
| 字段 | 类型 | 说明 |
|---|---|---|
| `countries?` | `Record \| null` | 这份配置覆盖的国家 / 地区 |
| `isFilled` | `boolean` | 顾客是否已经填了这个字段 |
| `formatCheck` | `boolean` | 是否校验取值的格式 |
| `rules` | `Array<{ countryCode: string; provinceCode?: string; name: string; regexp: string; exampleVal: string; }>` | 生效的规则，每个国家 / 地区一条 |
### IDialog {#type-idialog}
| 字段 | 类型 | 说明 |
|---|---|---|
| `show()` | `Promise` | 这一项是否显示 |
| `hide()` | `void` | 关闭弹窗或抽屉 |
### IDrawer {#type-idrawer}
| 字段 | 类型 | 说明 |
|---|---|---|
| `show()` | `Promise` | 这一项是否显示 |
| `hide()` | `void` | 关闭弹窗或抽屉 |
| `onClose(cb)` | `void` | 注册抽屉关闭时的回调 |
| `destroy()` | `void` | 关闭抽屉并销毁它 |
### IException {#type-iexception}
| 字段 | 类型 | 说明 |
|---|---|---|
| `code` | `string` | 错误码 |
| `message?` | `string` | 错误信息 |
| `invalidLineItems?` | Array<InvalidLineItem> | 已失效的订单行 |
| `changedLineItems?` | Array<ChangedLineItem> | 发生了变化的订单行 |
| `kickLineItems?` | Array<KickLineItem | (Omit<KickLineItem, 'properties'> & { properties: Record<string, string> })> | 被移出订单的行 |
| `nextAction?` | NextAction | 页面接下来该做什么 |
| `thirdPartyErrorDetails?` | ThirdPartyErrorDetails | 第三方返回的错误详情 |
### IExceptionCode {#type-iexceptioncode}
| 取值 | 说明 |
|---|---|
| `'30002'` | 平台错误码 30002 |
| `'30003'` | 平台错误码 30003 |
| `'30005'` | 平台错误码 30005 |
| `'line_items_variant_not_exist'` | 订单里某个规格已经不存在 |
| `'price_shipline_changed'` | 运费变了 |
| `'price_tax_changed'` | 税费变了 |
| `'price_shipping_tax_changed'` | 运费税变了 |
| `'checkout_address_invalid'` | 订单上的地址不合法 |
| `'shipping_not_available'` | 这个地址没有可用的配送方式 |
| `'payment_method_invalid'` | 选中的支付方式不能用 |
| `'80009'` | 平台错误码 80009 |
| `'discount_code_expired'` | 折扣码已过期 |
| `'discount_code_times_limit'` | 折扣码使用次数已用完 |
| `'shipping_line_changed'` | 配送方式变了 |
| `'shipping_line_changed_refresh'` | 配送方式变了，页面需要刷新 |
| `'gift_card_disabled'` | 礼品卡已停用 |
| `'gift_card_no_funds'` | 礼品卡余额已用完 |
| `'total_price_changed'` | 订单总价变了 |
| `'pickup_changed'` | 自提点变了 |
| `'pay_cod_limit'` | 订单超出货到付款的限额 |
| `'pay_ip_limit'` | 支付被 IP 限制拦下 |
| `'price_shipline_changed_true'` | 运费变了，且新值已经生效 |
| `'system_busy'` | 平台繁忙，稍后重试 |
### InitPhoneResult {#type-initphoneresult}
这是文档为便于引用起的名字，源码中是内联类型。
| 字段 | 类型 | 说明 |
|---|---|---|
| `phoneAreaCode` | `string` | 手机号的国际电话区号 |
| `phone` | `string` | 手机号 |
### InstructionType {#type-instructiontype}
订单备注框的展示方式：展开、折叠、隐藏。
| 成员 | 值 | 说明 |
|---|---|---|
| `UNFOLD` | `'unfold'` | 订单备注框默认展开 |
| `FOLD` | `'fold'` | 订单备注框默认折叠 |
| `HIDDEN` | `'hidden'` | 不显示订单备注框 |
### InteractionConfig {#type-interactionconfig}
| 字段 | 类型 | 说明 |
|---|---|---|
| `checkoutPaymentIconShow` | `boolean` | 是否显示支付方式图标 |
| `checkoutMobileOrderSummaryCollapse` | `boolean` | 移动端订单摘要是否默认折叠 |
| `checkoutMobileDiscountBoxLocation` | `'orderSummaryAndPaymentMethod' \| 'orderSummary' \| 'paymentMethod'` | 移动端折扣码输入框放在哪里 |
### InvalidLineItem {#type-invalidlineitem}
| 字段 | 类型 | 说明 |
|---|---|---|
| `productTitle` | `string` | 商品标题 |
| `image` | `{ src: string; }` | 商品图片 |
| `options` | `Array<{ name: string; value: string \| number; }>` | 这一项可选的取值 |
### isShowCountries {#type-isshowcountries}
| 字段 | 类型 | 说明 |
|---|---|---|
| `[key: string]` | `{ countryCodes?: string; countries?: { [key: string]: string[] }; isFilled: boolean; title: string; formatCheck?: boolean; }` | 其他任意 key，按名字索引 |
### IsSpecialInstructionCollapseChange {#type-isspecialinstructioncollapsechange}
```typescript
export type IsSpecialInstructionCollapseChange = (isCollapse: boolean) => void;
```
### JumpWay {#type-jumpway}
| 取值 | 说明 |
|---|---|
| `'a'` | 走 `<a>` 链接跳转 |
| `'window.open'` | 用 `window.open` 开新窗口 |
| `'history'` | 写一条 history 记录，页面不重新加载 |
| `'hash'` | 只改 URL 的 hash 部分 |
| `'location'` | 给 `location` 赋值，页面会重新加载 |
### KickLineItem {#type-kicklineitem}
| 字段 | 类型 | 说明 |
|---|---|---|
| `id` | `string` | 这一项的唯一 ID |
| `productId` | `string` | 商品 ID |
| `variantId` | `string` | 规格 ID |
| `quantity` | `number` | 调整后剩余的数量 |
| `originalQuantity` | `number` | 调整前的数量 |
| `url` | `string` | 商品图片 URL |
| `name` | `string` | 商品名称，不支持多语言，请改用 productTitle |
| `options` | `Array<{ name: string; value: any }>` | 这一项可选的取值 |
| `productTitle?` | `string` | 商品名称，支持多语言 |
| `properties` | `string` | 挂在这一行上的自定义属性 |
### LineItem {#type-lineitem}
| 字段 | 类型 | 说明 |
|---|---|---|
| `id` | `string` | 订单行 ID |
| `productTitle` | `string` | 商品名称 |
| `productId` | `string` | 商品 ID |
| `productHandle` | `string` | 商品 handle |
| `variantId` | `string` | 变体 ID |
| `variantTitle` | `string` | 变体名称 |
| `quantity` | `number` | 数量 |
| `fulfillmentStatus` | `string` | 履约状态 |
| `note` | `string` | 备注 |
| `image` | `{ path: string; src: string; }` | 商品图 |
| `compareAtPrice` | `string` | 划线价 |
| `price` | `string` | 单价 |
| `linePrice` | `string` | 这一行的金额 |
| `total` | `string` | 这一行的合计 |
| `sku` | `string` | SKU |
| `weight` | `string` | 重量 |
| `weightUnit` | `string` | 重量单位 |
| `taxable` | `boolean` | 是否计税 |
| `requiresShipping` | `boolean` | 是否需要配送 |
| `options` | `Array<{ name: string; value: string }>` | 变体选项 |
| `vendor` | `string` | 供应商 |
| `productUrl` | `string` | 商品页地址 |
| `properties` | `string` | 自定义属性 |
| `discountApplications` | Array<DiscountApplication> | 这一行生效的优惠 |
| `finalPrice?` | `string` | 所有商品优惠后的单价 eg. "9.00" |
| `finalLinePrice?` | `string` | 所有商品优惠后的单价 x 数量 eg. "18.00" |
| `discountTotal?` | `string` | 商品优惠总金额，discount_application 的汇总 eg. "2.00" |
| `isFreeGift?` | `boolean` | 是不是赠品 |
| `type?` | `string` | 这一项的类型 |
### LineMutationErrorCode {#type-linemutationerrorcode}
| 取值 | 说明 |
|---|---|
| `'bundled_product_requires_real_item'` | 加了组合商品，但没有它依附的实物商品 |
| `'checkout_token_missing'` | 页面上取不到结账 token |
| `'checkout_token_invalid'` | 结账 token 无效 |
### LineMutationResult {#type-linemutationresult}
| 字段 | 类型 | 说明 |
|---|---|---|
| `state` | `'success' \| string` | 结果状态，成功时为 `success` |
| `data?` | LineMutationResultData | 结果的数据体 |
| `code?` | LineMutationErrorCode | string | 失败时的错误码 |
| `message?` | `string` | 错误信息 |
### LineMutationResultData {#type-linemutationresultdata}
| 字段 | 类型 | 说明 |
|---|---|---|
| `orderId` | `string` | 订单 ID |
| `lineItems` | LineItem[] | 订单的商品行 |
| `priceDirty` | `boolean` | 为 true 表示价格已过期、需要重新计算 |
| `lineItemsVersion` | `number` | 订单行的版本号，每次改动递增 |
| `shippingReselectRequired?` | `boolean` | 仅当「是否需要物流」翻转时为 true |
| `paymentReselectRequired?` | `boolean` | 顾客是否需要重新选一次支付方式 |
### LoadingStatus {#type-loadingstatus}
| 字段 | 类型 | 说明 |
|---|---|---|
| `globalLoading` | `boolean` | 整页是不是在加载中 |
### Locale {#type-locale}
结账页支持的语言标记。
| 取值 | 说明 |
|---|---|
| `'ar-SA'` | 阿拉伯语（沙特阿拉伯） |
| `'de-DE'` | 德语（德国） |
| `'en-US'` | 英语（美国） |
| `'es-ES'` | 西班牙语（西班牙） |
| `'fr-FR'` | 法语（法国） |
| `'id-ID'` | 印尼语（印度尼西亚） |
| `'it-IT'` | 意大利语（意大利） |
| `'ja-JP'` | 日语（日本） |
| `'ko-KR'` | 韩语（韩国） |
| `'nl-NL'` | 荷兰语（荷兰） |
| `'pl-PL'` | 波兰语（波兰） |
| `'pt-PT'` | 葡萄牙语（葡萄牙） |
| `'ru-RU'` | 俄语（俄罗斯） |
| `'th-TH'` | 泰语（泰国） |
| `'zh-CN'` | 简体中文（中国大陆） |
| `'zh-TW'` | 繁体中文（台湾） |
### LocaleMap {#type-localemap}
| 字段 | 类型 | 说明 |
|---|---|---|
| `'en-US'` | `Record` | 每个语言一项，值是该语言下的文案 |
| `[k in Locale]` | `Record` | 每个语言一项，值是该语言下的文案 |
### LogoConfig {#type-logoconfig}
| 字段 | 类型 | 说明 |
|---|---|---|
| `checkoutLogoImage` | `string` | 结账页的 Logo 图片 |
| `checkoutLogoSize` | `'large' \| 'medium' \| 'small'` | Logo 的尺寸档位 |
| `checkoutLogoPosition` | `string` | Logo 的位置 |
### MarketInfo {#type-marketinfo}
| 字段 | 类型 | 说明 |
|---|---|---|
| `marketId` | `string` | 市场 ID |
| `marketPriceSetting` | MarketPriceSetting | 这个市场的价格设置 |
### MarketPriceSetting {#type-marketpricesetting}
| 字段 | 类型 | 说明 |
|---|---|---|
| `local_currency_enabled` | `boolean` | 是否按本地币种展示价格 |
| `custom_rate_enabled` | `boolean` | 是否使用自定义汇率 |
| `custom_rate` | `number` | 手动汇率 USD -> CNY 主市场货币 -> 市场基本货币 |
| `rate` | `number` | 自动汇率 USD -> HKD 主市场货币 -> 市场基本货币/本地货币 |
| `back_rate` | `number` | 反向自动汇率 HKD -> USD 市场基本货币/本地货币 -> 主市场货币 |
| `actual_rate` | `number` | 生效转换汇率 USD -> HKD 主市场货币 -> 市场基本货币/本地货币 |
| `base_to_local` | `number` | CNY -> HKD 市场基本货币 -> 本地货币 |
| `local_to_base` | `number` | HKD -> CNY 本地货币 -> 市场基本货币 |
| `adjust` | `number` | 价格调整 |
| `price_round_enabled` | `true` | 换算后的价格是否取整 |
### MenuPolicyConfig {#type-menupolicyconfig}
| 字段 | 类型 | 说明 |
|---|---|---|
| `checkoutMenuPolicyLink1?` | '' | CheckoutMenuPolicyLink | 第一个政策菜单项的链接目标 |
| `checkoutMenuPolicyLink2?` | '' | CheckoutMenuPolicyLink | 第二个政策菜单项的链接目标 |
| `checkoutMenuPolicyLink3?` | '' | CheckoutMenuPolicyLink | 第三个政策菜单项的链接目标 |
| `checkoutMenuPolicyText1?` | `string` | 第一个政策菜单项的文案 |
| `checkoutMenuPolicyText2?` | `string` | 第二个政策菜单项的文案 |
| `checkoutMenuPolicyText3?` | `string` | 第三个政策菜单项的文案 |
| `checkoutMenuAlignment` | `string` | 政策菜单的对齐方式 |
| `blocks` | Array<{ type: string; settings: { checkoutMenuPolicyText: string; checkoutMenuPolicyLink: CheckoutMenuPolicyLink; }; key: string; }> | 新版数据格式，上面六个字段是旧格式；两者同时存在时以 blocks 为准 |
### MutationSource {#type-mutationsource}
```typescript
export type MutationSource = string;
```
### NameSetting {#type-namesetting}
| 取值 | 说明 |
|---|---|
| `'separate'` | 姓和名分成两个输入框 |
| `'normal'` | 姓名合成一个输入框 |
### NavigateLink {#type-navigatelink}
| 字段 | 类型 | 说明 |
|---|---|---|
| `id` | CheckoutStep | 这个链接指向的结账步骤 |
| `title` | `'information' \| 'shipping' \| 'payment'` | 埋点用 |
| `text` | `string` | 链接文案 |
### NavigateLinksChangeCb {#type-navigatelinkschangecb}
```typescript
export type NavigateLinksChangeCb = () => void;
```
### NewsLetterStatus {#type-newsletterstatus}
营销邮件的订阅状态：未订阅、已订阅。
| 成员 | 值 | 说明 |
|---|---|---|
| `NO_SUBSCRIPTION` | `0` | 未订阅营销邮件 |
| `SUBSCRIBED` | `1` | 已订阅营销邮件 |
### NextAction {#type-nextaction}
| 字段 | 类型 | 说明 |
|---|---|---|
| `redirectToUrl` | `{ url: string; }` | 要把顾客跳转到的 URL |
| `type` | `'redirect_to_url'` | 这一项的类型 |
### NmeRequirementSetting {#type-nmerequirementsetting}
| 取值 | 说明 |
|---|---|
| `'both'` | 姓和名都必填 |
| `'last_name'` | 只有姓必填 |
### OnCloseCb {#type-onclosecb}
```typescript
export type OnCloseCb = (type: CloseType) => void;
```
### OnLoadingStatusChangeCallback {#type-onloadingstatuschangecallback}
```typescript
export type OnLoadingStatusChangeCallback = (status: LoadingStatus) => void;
```
### OnPayFailedPayload {#type-onpayfailedpayload}
| 字段 | 类型 | 说明 |
|---|---|---|
| `sysCodeGroup` | `string \| null` | |
| `paymentKey` | `string` | 标识支付方式的 key |
### OnPayFailedResult {#type-onpayfailedresult}
| 字段 | 类型 | 说明 |
|---|---|---|
| `handled` | `boolean` | 你的回调是否已经自己处理了这次失败 |
### OnStoreDataChangeCb {#type-onstoredatachangecb}
```typescript
export type OnStoreDataChangeCb = () => void;
```
### OnSubmitPendingChangeCallback {#type-onsubmitpendingchangecallback}
```typescript
export type OnSubmitPendingChangeCallback = (val: Pending, change: Partial) => void;
```
### OptionValue {#type-optionvalue}
| 字段 | 类型 | 说明 |
|---|---|---|
| `name` | `string` | 选项的名称 |
| `code` | `C` | 这一项的代码 |
| `alternateNames?` | `string[]` | 这个选项的其他别名 |
### OrderConfig {#type-orderconfig}
订单上的配置信息，取自 `CheckoutOrder` 的 `config` 字段。
| 字段 | 类型 | 说明 |
|---|---|---|
| `checkoutBusinessType` | `number` | 这笔订单的结账类型，取值同 `CheckoutBusinessType` |
| `checkoutTemplateType` | `number` | 结账页使用的模板类型 |
| `pageType` | `'single' \| 'three_step' \| 'two_step'` | 结账页布局，取值同 `CheckoutPageType` |
| `marketSetting` | `{ marketId?: string; }` | 这笔订单归属的市场 |
| `productTaxIncluded?` | `boolean` | 商品价格是否已含税 |
### OrderInfo {#type-orderinfo}
| 字段 | 类型 | 说明 |
|---|---|---|
| `currencyCode` | `string` | 结账货币，例如 USD |
| `currencySymbol` | `string` | 货币符号，例如 $ |
| `alreadyPaymentLines` | AlreadyPaymentLines | 已支付明细 |
| `failCode` | `string \| null` | 失败码，没失败时为空 |
| `id` | `string` | 订单 ID |
| `status` | OrderStatus | 订单状态 |
| `checkoutStatus` | `string` | 结账状态 |
| `financialStatus` | `string` | 支付状态 |
| `orderNo` | `string` | 订单号 |
| `cancelReason` | `string \| null` | 取消原因 |
| `orderType?` | `number` | 订单类型：1 = 礼品卡商品订单，0 = 其他订单（标准商品、虚拟商品等） |
| `exceptionError?` | `string` | 下面两个字段只有感谢页才有 |
| `exceptionErrorMessage?` | `string` | 异常信息 |
| `additionalPrices?` | AdditionalPrice[] | 附加费用 |
| `customFields?` | `Record` | 订单的自定义业务字段 |
### OrderResult {#type-orderresult}
| 字段 | 类型 | 说明 |
|---|---|---|
| `data?` | OrderResultData | 响应的数据体 |
| `state` | `string` | 结果状态，成功时为 `success` |
| `errors` | `string[]` | 错误信息列表 |
### OrderResultData {#type-orderresultdata}
| 字段 | 类型 | 说明 |
|---|---|---|
| `exceptNotification` | ExceptNotification | 平台报出的异常信息 |
| `addressSettings` | CheckoutAddressSettings | 店铺的地址表单设置 |
| `checkoutSettings` | CheckoutSettings | 店铺的结账设置 |
| `customerInfo` | CheckoutCustomerInfo | 顾客填写的联系信息 |
| `ipAddress` | CheckoutIpAddress | 下单来源的 IP 地址信息 |
| `order` | CheckoutOrder | 订单本身 |
| `paymentSettings` | PaymentSettings | 店铺的支付设置 |
| `showDetails` | ShowDetails | 页面上哪些区块显示 |
| `step` | CheckoutStep | 对应的结账步骤 |
### OrderStatus {#type-orderstatus}
订单状态。
| 取值 | 说明 |
|---|---|
| `'opened'` | 订单已创建但还没提交 |
| `'placed'` | 订单已提交 |
| `'cancelled'` | 订单已取消 |
| `'finished'` | 订单已完成 |
### PageTypeChangeCb {#type-pagetypechangecb}
```typescript
export type PageTypeChangeCb = (type: CheckoutPageType) => void;
```
### PayAttemptCb {#type-payattemptcb}
```typescript
export type PayAttemptCb = () => void;
```
### PayFailedHandler {#type-payfailedhandler}
```typescript
export type PayFailedHandler = (payload: OnPayFailedPayload) => Promise;
```
### PaymentIconResource {#type-paymenticonresource}
| 字段 | 类型 | 说明 |
|---|---|---|
| `paymentKey` | `string` | 标识支付方式的 key |
| `icon` | `string` | 这一行显示的图标 |
### PaymentLine {#type-paymentline}
| 字段 | 类型 | 说明 |
|---|---|---|
| `failCode?` | `string \| null` | 失败码，没失败时为空 |
| `available` | `boolean \| string` | 这个支付方式是否可用 |
| `createdAt` | `string` | 创建时间 |
| `desc` | `string` | 描述 |
| `id` | `string` | 支付方式 ID |
| `name` | `string` | 支付方式名称 |
| `paymentChannel` | `string` | 支付渠道 |
| `paymentMethod` | `string` | 支付方式 |
| `publicKey` | `any` | |
| `status` | `string` | 状态 |
| `storeId` | `string` | 店铺 ID |
| `tips` | `string` | 提示文案 |
| `updatedAt` | `string` | 更新时间 |
| `supportTip?` | `boolean` | 是否支持小费 |
| `paypalClassicMode?` | `boolean` | 是否走 PayPal 的经典流程 |
| `channel` | `string` | 支付渠道 |
| `method` | `string` | 支付方式 |
| `fePay?` | `boolean` | 这笔支付是否在前端完成 |
| `failReason?` | `string` | 失败原因 |
| `paymentKey?` | `string` | 标识支付方式的 key |
| `discounts?` | `Record[]` | 绑定在这个支付方式上的优惠 |
### PaymentLinesSource {#type-paymentlinessource}
| 取值 | 说明 |
|---|---|
| `'destroy'` | 上一条支付记录被销毁 |
| `'verificationError'` | 支付校验失败 |
| `'api'` | 支付记录来自一次接口返回 |
### PaymentResources {#type-paymentresources}
| 字段 | 类型 | 说明 |
|---|---|---|
| `[key: string]` | Cards | 其他任意 key，按名字索引 |
### PaymentSettings {#type-paymentsettings}
| 字段 | 类型 | 说明 |
|---|---|---|
| `supportChannels` | `string[]` | 店铺已开启的支付渠道 |
| `paymentResources` | PaymentResources | 支付方式需要的静态资源 |
| `paymentIconResources?` | PaymentIconResource[] | 可用支付方式的图标资源 |
| `paypalExpressEnabled` | `string` | PayPal Express 是否开启 |
### PaymentUpdateParams {#type-paymentupdateparams}
| 字段 | 类型 | 说明 |
|---|---|---|
| `paymentLine` | PaymentLine | 当前选中的支付方式 |
| `paymentLines` | Array<PaymentLine> | 可选的支付方式列表 |
| `paymentButton` | `boolean` | 是否显示支付按钮 |
| `paymentReady` | `boolean` | 支付方式是否已经可以提交 |
| `cardInfo` | Partial<CardInfo> | 银行卡信息 |
| `source?` | PaymentLinesSource | 这次支付更新由什么触发，取值同 `PaymentLinesSource` |
| `paymentFeatures?` | `{ useCustomPaymentButton: boolean; useBillingAddress: boolean; }` | 这个支付方式需要哪些支付能力 |
### PayResponse {#type-payresponse}
```typescript
export type PayResponse = (
| {
data: {
exceptNotification: ExceptNotification;
result?:
| {
redirectType: 'newwindow' | 'redirect' | 'iframe';
redirectUrl: string;
}
| {
redirectType: 'form';
form: string;
};
};
state: 'success';
}
| {
data: null;
state: 'pay_failed';
}
) & {
errors: string[];
message: string;
};
```
### Pending {#type-pending}
| 字段 | 类型 | 说明 |
|---|---|---|
| `price` | `boolean` | 价格接口调用中 |
| `shippingLines` | `boolean` | 物流方案列表加载中 |
| `payment` | `boolean` | 支付脚本加载中，不是支付方式列表 |
| `pickupLocation` | `boolean` | 自提点列表加载中 |
### PhoneInfo {#type-phoneinfo}
| 字段 | 类型 | 说明 |
|---|---|---|
| `phone` | `string` | 手机号 |
| `phoneAreaCode` | `string` | 手机号的国际电话区号 |
### PickupInformationChangeCb {#type-pickupinformationchangecb}
```typescript
export type PickupInformationChangeCb = (pickupInformation?: string) => void;
```
### PickupLocation {#type-pickuplocation}
| 字段 | 类型 | 说明 |
|---|---|---|
| `deliveryMethod?` | `number` | 1 快递，2 本地配送，3 到店自提 |
| `businessTimeType?` | `number` | 字段不存在默认为 1, 1 统一的时间，2 按天设置 |
| `id?` | `string` | 自提点 ID |
| `name?` | `string` | 自提点名称 |
| `desc?` | `string` | 自提点描述 |
| `shippingPrice?` | `string` | 这个自提点的费用 |
| `supportCod?` | `number` | 0 不支持，1 支持 |
| `locationId?` | `string` | 关联的位置 ID |
| `country?` | `string` | 国家 / 地区名称 |
| `countryCode?` | `string` | 国家 / 地区代码 |
| `province?` | `string` | 省 / 州名称 |
| `provinceCode?` | `string` | 省 / 州代码 |
| `city?` | `string` | 城市 |
| `address?` | `string` | 详细地址 |
| `address1?` | `string` | 详细地址第二行（门牌号、公寓号等） |
| `company?` | `string` | 公司名 |
| `zip?` | `string` | 邮编 |
| `timeZone?` | `string` | 时区 |
| `timeDaySetting?` | DayConfigOfPickupTime[] | 每天可自提的时间段 |
| `timeRemark?` | `string` | 自提时间的备注 |
| `businessStart?` | `string` | 自提点营业开始时间 |
| `businessEnd?` | `string` | 自提点营业结束时间 |
| `timeLag?` | `string` | 预计提货时间（单位h） |
| `estimatedTimeEnd?` | `string` | 预计提货时间 （前端使用） |
| `estimatedTimeUnit?` | `string` | 预计提货时间单位（前端使用、多语言前端控制），枚举 h、d |
| `pickupAt?` | `string` | 顾客选的自提时间 |
| `lastSelected?` | `boolean` | 是否为上次选中的自提点 |
| `formattedPickAt?` | `string` | 自提时间，以自提点时区为准，是按 YYYY-MM-DD HH:mm:ss 格式化后的时间 |
### PickupLocationsChangeCb {#type-pickuplocationschangecb}
```typescript
export type PickupLocationsChangeCb = (locations?: PickupLocation[]) => void;
```
### PlaceType {#type-placetype}
```typescript
export type PlaceType =
| {
types: Array;
stringify?: string;
}
| Array;
```
### PlayCardCards {#type-playcardcards}
| 字段 | 类型 | 说明 |
|---|---|---|
| `cardName` | `string` | 卡种的显示名称 |
| `cardType` | `string` | 卡种，比如 Visa、Mastercard |
| `countryCnName?` | `string` | 国家 / 地区的中文名 |
| `countryCode?` | `string` | 国家 / 地区代码 |
| `countryEnName?` | `string` | 国家 / 地区的英文名 |
| `icon` | `string` | 这一行显示的图标 |
| `name?` | `string` | 这一项的名称 |
| `pmId?` | `string` | |
### PluginConfig {#type-pluginconfig}
| 字段 | 类型 | 说明 |
|---|---|---|
| `plugins` | `{ appserval: { servalBg1Color: string; servalBg2Color: string; servalDiscountColor: string; servalHeadingColor: string; showNewCustomerExclusiveTag: boolean; exclusiveForNewUsers: false; }; }` | 结账页插件的配置 |
### PriceDetail {#type-pricedetail}
金额明细里的一行，字段是 `BasePriceDetail` 的全部字段，再加一个 id 和一组可选的子行。
| 字段 | 类型 | 说明 |
|---|---|---|
| `key?` | `string` | 这一行明细的标识 |
| `dataRobot?` | `string` | |
| `title?` | `string` | 这一行的标题 |
| `titleLangId?` | `string` | 标题的翻译 key |
| `subTitle?` | `string` | 这一行的副标题 |
| `subTitleLangId?` | `string` | 副标题的翻译 key |
| `originPrice?` | `string` | 折扣前的金额 |
| `price?` | `string` | 这一行的金额 |
| `originalValue?` | `string` | 这一行未格式化的原始值 |
| `value?` | `string` | 这一项的取值 |
| `desc?` | `string` | 这一行附带的说明文字 |
| `descLangId?` | `string` | 说明文字的翻译 key |
| `icon?` | `string` | 这一行显示的图标 |
| `isShow?` | `boolean` | 这一行是否显示 |
| `tooltip?` | `string` | 这一行的悬浮提示文字 |
| `subList?` | SubPriceDetail[] | 这一行下面的子行 |
| `id` | `string` | 这一项的唯一 ID |
### PriceGroupDetail {#type-pricegroupdetail}
| 字段 | 类型 | 说明 |
|---|---|---|
| `key` | PriceGroupDetailKey | 分组标识 |
| `list?` | PriceDetail[] | 这一组下的价格条目 |
| `desc?` | `string` | 描述 |
| `descLangId?` | `string` | 说明文字的翻译 key |
### PriceGroupDetailKey {#type-pricegroupdetailkey}
| 取值 | 说明 |
|---|---|
| `'tax_total'` | 税费合计 |
| `'shipping_tax_total'` | 运费税 |
| `'sub_total'` | 商品小计 |
| `'shipping_total'` | 运费合计 |
| `'discount_coupon_total'` | 优惠券折扣合计 |
| `'discount_flash_sale_total'` | 闪购折扣合计 |
| `'discount_applications'` | 逐条列出的已应用折扣 |
| `'total_tip_received'` | 小费合计 |
| `'gift_card'` | 礼品卡 |
| `'payment_discount_total'` | 支付方式折扣合计 |
| `'additional_price'` | 运费险 |
| `'charge_quotes'` | 这笔订单报出的附加费 |
### PriceListChangeCb {#type-pricelistchangecb}
```typescript
export type PriceListChangeCb = (newPriceList: PriceGroupDetail[]) => void;
```
### PriceParams {#type-priceparams}
| 字段 | 类型 | 说明 |
|---|---|---|
| `reductions?` | `Array<{ code: string }>` | 要应用的折扣码，按码给出 |
| `discountApplications?` | `Array<{ code: string; discountId: string; _delete: 1; }>` | 逐条列出的已应用折扣 |
| `calculateShippingLine` | `boolean` | 这次是否要重新计算运费 |
| `totalTipReceived` | `string` | 订单上的小费合计 |
| `appliedGiftCards?` | `Record` | 这笔订单上已使用的礼品卡 |
| `type?` | DiscountTypeEnum | 这次要应用的折扣种类，取值同 `DiscountTypeEnum` |
| `step?` | `string` | 对应的结账步骤 |
| `paymentLine?` | PaymentLine | null | 订单上选中的支付方式 |
| `config` | { checkoutBusinessType: CheckoutBusinessType; } | 随这次请求或这笔订单带上的配置 |
### PriceResult {#type-priceresult}
```typescript
export type PriceResult = SuccessPriceResult | FailPriceResult;
```
### PriceResultData {#type-priceresultdata}
| 字段 | 类型 | 说明 |
|---|---|---|
| `exceptNotification` | ExceptNotification | 平台报出的异常信息 |
| `discountApplications` | CheckoutOrder['discountApplications'] | 逐条列出的已应用折扣 |
| `lineItems` | CheckoutOrder['lineItems'] | 订单的商品行 |
| `prices` | CheckoutPrices | 订单的金额明细 |
| `shippingInfo` | { requiresShipping: boolean; shippingLine: ShippingLineType; shippingLines: Array<ShippingLineType>; } | 配送方式，以及这笔单是否需要配送 |
| `appliedGiftCards` | Array<AppliedGiftCard> | 这笔订单上已使用的礼品卡 |
| `alreadyPaymentLines` | AlreadyPaymentLines | 这笔订单上已经收到的支付记录 |
| `pickupLocations` | PickupLocation[] | 可选的自提点列表 |
| `pickupLocation` | PickupLocation | 订单上选中的自提点 |
| `checkoutPriceList?` | PriceGroupDetail[] | 价格明细分组 |
| `taxLines?` | TaxLines | 这笔订单算出的税费明细 |
### PricesChangeCb {#type-priceschangecb}
```typescript
export type PricesChangeCb = (prices: CheckoutPrices) => void;
```
### ProductItem {#type-productitem}
派生自 `LineItem`，字段完全相同，只是 `properties` 换成了键值对对象（`Record`），不再是字符串。
| 字段 | 类型 | 说明 |
|---|---|---|
| `id` | `string` | 这一项的唯一 ID |
| `productTitle` | `string` | 商品标题 |
| `productId` | `string` | 商品 ID |
| `productHandle` | `string` | 商品的 URL handle |
| `variantId` | `string` | 规格 ID |
| `variantTitle` | `string` | 规格标题 |
| `quantity` | `number` | 数量 |
| `fulfillmentStatus` | `string` | 这一行的发货状态 |
| `note` | `string` | 挂在这一行上的备注 |
| `image` | `{ path: string; src: string; }` | 商品图片 |
| `compareAtPrice` | `string` | 规格的原价（划线价） |
| `price` | `string` | 这一行的金额 |
| `linePrice` | `string` | 这一行的单价乘数量 |
| `total` | `string` | 这一行的合计金额 |
| `sku` | `string` | 规格的 SKU |
| `weight` | `string` | 商品重量 |
| `weightUnit` | `string` | 重量使用的单位 |
| `taxable` | `boolean` | 这一行是否计税 |
| `requiresShipping` | `boolean` | 这一行是否需要配送 |
| `options` | `Array<{ name: string; value: string }>` | 这一项可选的取值 |
| `vendor` | `string` | 商品的供应商 |
| `productUrl` | `string` | 商品在店铺前台的路径 |
| `discountApplications` | Array<DiscountApplication> | 逐条列出的已应用折扣 |
| `finalPrice?` | `string` | 所有商品优惠后的单价 eg. "9.00" |
| `finalLinePrice?` | `string` | 所有商品优惠后的单价 x 数量 eg. "18.00" |
| `discountTotal?` | `string` | 商品优惠总金额，discount_application 的汇总 eg. "2.00" |
| `isFreeGift?` | `boolean` | 这一行是否为赠品 |
| `type?` | `string` | 订单行的类型标记 |
| `properties` | `Record` | 挂在这一行上的自定义属性 |
### ProductListChangeCb {#type-productlistchangecb}
```typescript
export type ProductListChangeCb = (newProductList: ProductItem[]) => void;
```
### ProductProperties {#type-productproperties}
| 字段 | 类型 | 说明 |
|---|---|---|
| `_shoplazza_bundled_product?` | `boolean` | 捆绑商品，不能独立成单 |
| `_shoplazza_exclude_calculation?` | `boolean` | 独立于所有计算之外，仅最终总价加回 |
| `[key: string]` | `any` | 其他任意 key，按名字索引 |
### PromptMessage {#type-promptmessage}
| 字段 | 类型 | 说明 |
|---|---|---|
| `type` | `string` | 提示类型 |
| `dataRobot` | `string` | |
| `errorMessage?` | `string` | 错误信息 |
| `locales` | `string[]` | 这条文案覆盖的语言 |
### ReferInfo {#type-referinfo}
| 字段 | 类型 | 说明 |
|---|---|---|
| `clientId` | `string` | 应用的 client id |
| `country` | `string` | 国家 / 地区 |
| `domain` | `string` | 域名 |
| `fbc` | `string` | |
| `fbp` | `string` | |
| `ip` | `string` | IP 地址 |
| `source` | `'buy_now' \| 'back' \| 'cart'` | 顾客从哪里进入结账：buy_now 立即购买、back 返回、cart 购物车 |
| `userAgent` | `string` | 浏览器 User-Agent |
| `payMethod?` | `string` | 支付方式 |
| `note?` | `string` | 备注 |
### RemoveLineItemsInput {#type-removelineitemsinput}
| 字段 | 类型 | 说明 |
|---|---|---|
| `lineItemIds` | `string[]` | 要操作的订单行 ID 列表 |
| `mutationSource` | MutationSource | 你自己填的标记，说明这次改动是谁发起的 |
### RenderParams {#type-renderparams}
| 字段 | 类型 | 说明 |
|---|---|---|
| `id` | `string` | 这一项的唯一 ID |
| `extensionPoint` | ExtensionPoint | 内容渲染在哪个扩展点上 |
| `component` | `Promise \| string` | 扩展要渲染的 HTML，也可以是解析出 HTML 的 promise |
### ReqConfig {#type-reqconfig}
| 字段 | 类型 | 说明 |
|---|---|---|
| `url` | `string` | 请求地址 |
| `method?` | `RequestInit['method']` | HTTP 请求方法 |
| `headers?` | `Record` | 请求头或响应头 |
| `params?` | `Record \| URLSearchParams` | 请求的查询参数 |
| `data?` | `Record \| string` | 结果的数据体 |
| `timeout?` | `number` | 请求超时时间，单位毫秒 |
| `withCredentials?` | `boolean` | 请求是否带上 cookie |
| `responseType?` | `'json'` | 响应按什么格式解析 |
| `xsrfCookieName?` | `string` | 读取 XSRF token 的 cookie 名 |
| `xsrfHeaderName?` | `string` | 发送 XSRF token 的请求头名 |
### Res {#type-res}
```typescript
export type Res, ErrorPayload = Record & { state: string | '' }> =
| HttpSuccessResponse
| HttpFailResponse;
```
### SaleTaxLine {#type-saletaxline}
| 字段 | 类型 | 说明 |
|---|---|---|
| `key?` | `string` | 这条税费的标识 |
| `price?` | `string` | 这一行的金额 |
### SchemaChangeDisableCB {#type-schemachangedisablecb}
```typescript
export type SchemaChangeDisableCB = () => Record;
```
### SchemaChangeLabelCb {#type-schemachangelabelcb}
```typescript
export type SchemaChangeLabelCb = () => Record;
```
### SchemaChangeValidateRule {#type-schemachangevalidaterule}
| 字段 | 类型 | 说明 |
|---|---|---|
| `[k: string]` | SchemaChangeValidateRuleValue | 其他任意 key，按名字索引 |
### SchemaChangeValidateRuleCB {#type-schemachangevalidaterulecb}
```typescript
export type SchemaChangeValidateRuleCB = () => SchemaChangeValidateRule;
```
### SchemaChangeValidateRuleValue {#type-schemachangevalidaterulevalue}
| 字段 | 类型 | 说明 |
|---|---|---|
| `required` | `true` | 顾客是否必须填这一项 |
| `validates` | FieldValidate[] | 生效的校验规则 |
### SchemaItemVisibilityCb {#type-schemaitemvisibilitycb}
```typescript
export type SchemaItemVisibilityCb = () => Record;
```
### SchemaManagerConfig {#type-schemamanagerconfig}
| 字段 | 类型 | 说明 |
|---|---|---|
| `focusIdPrefix` | `string` | 生成 focus id 时统一加的前缀 |
### SchemaManagerConfigFn {#type-schemamanagerconfigfn}
| 字段 | 类型 | 说明 |
|---|---|---|
| `getAddressVisible()` | `boolean` | 返回地址表单当前是否可见 |
| `getCustomLabels?` | `() => Record` | 返回商家自定义的字段标签，按字段 ID 索引 |
| `getCustomValidateRules?` | () => SchemaChangeValidateRule | 返回要额外应用的校验规则 |
| `getAddressExpanded?` | `() => boolean` | 地址表单当前是否已展开；不提供时视为已展开 |
| `expandAddress?` | `(reason: 'manual_click' \| 'empty_fallback_click' \| 'auto_fill') => void` | 展开地址表单 |
### SelectedPickupLocationChangeCb {#type-selectedpickuplocationchangecb}
```typescript
export type SelectedPickupLocationChangeCb = (location?: PickupLocation) => void;
```
### SelectType {#type-selecttype}
| 取值 | 说明 |
|---|---|
| `'static'` | 选项列表是固定的 |
| `'dynamic'` | 选项列表随顾客输入实时拉取 |
### ShippingAddress {#type-shippingaddress}
| 字段 | 类型 | 说明 |
|---|---|---|
| `phoneCountryCode?` | `string` | 手机号所属的国家 / 地区代码 |
| `id?` | `string` | 地址 ID |
| `firstName` | `string` | 名 |
| `lastName` | `string` | 姓 |
| `email` | `string` | 邮箱 |
| `phone` | `string` | 手机号 |
| `countryCode` | `string` | 国家 / 地区代码 |
| `country` | `string` | 国家 / 地区名称 |
| `provinceCode` | `string` | 省 / 州代码 |
| `province` | `string` | 省 / 州名称 |
| `area` | `string` | 区 / 县 |
| `city` | `string` | 城市 |
| `address` | `string` | 详细地址 |
| `address1` | `string` | 详细地址第二行（门牌号、公寓号等） |
| `zip` | `string` | 邮编 |
| `extraInfo` | { cpf?: string; taxText?: string; idNumber?: string; idNumberText?: string; addition?: AdditionValues; shortAddress?: string; } | 额外的地址字段，比如税号和证件号 |
| `company` | `string` | 公司名 |
| `emailOrPhone` | `string` | 邮箱或手机号合并字段的值 |
| `phoneAreaCode` | `string` | 手机区号 |
| `latitude?` | `string` | 纬度 |
| `longitude?` | `string` | 经度 |
### ShippingChangeCb {#type-shippingchangecb}
```typescript
export type ShippingChangeCb = () => void;
```
### ShippingCpf {#type-shippingcpf}
| 字段 | 类型 | 说明 |
|---|---|---|
| `isShow` | `boolean` | 这一行是否显示 |
| `configInfo` | `{ configBr: { length: string; type: string; }; configDefault: { length: string; type: string; }; }` | CPF 字段的分国家配置 |
| `countries` | `any[]` | 这份配置覆盖的国家 / 地区 |
| `isShowCountries` | isShowCountries | 哪些国家 / 地区显示 CPF 字段 |
### ShippingLinesErrorInfo {#type-shippinglineserrorinfo}
| 字段 | 类型 | 说明 |
|---|---|---|
| `message?` | `string` | 错误信息 |
### ShippingLineType {#type-shippinglinetype}
| 字段 | 类型 | 说明 |
|---|---|---|
| `createdAt?` | `string` | 创建时间 |
| `desc?` | `string` | 描述 |
| `id` | `string \| number` | 物流方案 ID |
| `name?` | `string` | 物流方案名称 |
| `rateAdditionalAmount?` | `string` | 每增加一个计费单位收多少 |
| `rateAdditionalRange?` | `string` | 一个附加计费单位的大小 |
| `rateAdditionalUnit?` | `string` | 附加计费所用的单位 |
| `rateAmount?` | `string` | 基础运费金额 |
| `rateFirstRange?` | `string` | 首个计费单位的大小 |
| `rateFirstUnit?` | `string` | 首段计费所用的单位 |
| `rateType?` | `string` | 运费的计算方式 |
| `ruleRangeInfinite?` | `number` | 计费区间是否没有上限 |
| `ruleRangeMax?` | `string` | 计费区间的上限 |
| `ruleRangeMin?` | `string` | 计费区间的下限 |
| `ruleRangeUnit?` | `string` | 计费区间使用的单位 |
| `ruleType?` | `string` | 计费区间按什么衡量，比如重量或金额 |
| `shippingId?` | `string` | 配送方式的 ID |
| `shippingPrice?` | `number \| string` | 运费 |
| `storeId?` | `number` | 店铺 ID |
| `supportCod?` | `number` | 是否支持货到付款 |
| `selected?` | `boolean` | 是否已选中 |
| `discountShippingPrice` | `number \| string` | 优惠后的运费 |
### ShippingMethodsFetchTriggerSource {#type-shippingmethodsfetchtriggersource}
| 取值 | 说明 |
|---|---|
| `'init'` | 页面首次加载 |
| `'address_change'` | 物流地址变了 |
| `'shipping_method_switch'` | 顾客换了配送方式 |
| `'tipping_change'` | 小费变了 |
| `'charge_quote_change'` | 附加费项变了 |
| `'billing_address_change'` | 账单地址变了 |
| `'step_change'` | 顾客切换了步骤 |
| `'delivery_method_change'` | 顾客在配送和自提之间切换 |
| `'pickup_location_change'` | 顾客换了自提点 |
| `'coupon_apply'` | 用上了一张券或折扣码 |
| `'coupon_cancel'` | 取消了一张券或折扣码 |
| `'gift_card_remove'` | 移除了一张礼品卡 |
| `'payment_change'` | 顾客换了支付方式 |
| `'payment_cancel'` | 顾客取消了支付 |
| `'submit_retry'` | 顾客重新提交了订单 |
| `'exception_recovery'` | 页面从异常中恢复 |
| `'other'` | 其他触发来源 |
### ShippingPriceDisplayChangeCb {#type-shippingpricedisplaychangecb}
```typescript
export type ShippingPriceDisplayChangeCb = () => void;
```
### ShippingPromptMessageChangeCb {#type-shippingpromptmessagechangecb}
```typescript
export type ShippingPromptMessageChangeCb = () => void;
```
### ShippingProtectionChangeCb {#type-shippingprotectionchangecb}
```typescript
export type ShippingProtectionChangeCb = () => void;
```
### ShopConfig {#type-shopconfig}
| 字段 | 类型 | 说明 |
|---|---|---|
| `contactEmail` | `string` | 联系邮箱 |
| `defaultImg` | `string` | 商品没有图时用的占位图 |
| `shopName` | `string` | 店铺名称 |
| `shopId` | `string` | 店铺 ID |
| `favicon` | `string` | 站点图标 |
| `finance` | `string` | 店铺的币种代码 |
| `customerId` | `string` | 顾客 ID |
| `financeSymbol` | `string` | 店铺的币种符号 |
| `serviceEmail` | `string` | 客服邮箱 |
| `cdnDomain` | `string` | CDN 域名 |
| `[key: string]` | `any` | 其他任意 key，按名字索引 |
### ShowDetails {#type-showdetails}
| 字段 | 类型 | 说明 |
|---|---|---|
| `isAddressAvailable?` | `boolean` | 地址是否可用 |
### SimplesSetting {#type-simplessetting}
| 取值 | 说明 |
|---|---|
| `'hidden'` | 不显示这个字段 |
| `'optional'` | 显示这个字段，可以不填 |
| `'required'` | 显示这个字段，必须填 |
### SortSchemaCb {#type-sortschemacb}
```typescript
export type SortSchemaCb = (items: SortSchemaItem[]) => SortSchemaItem[];
```
### SortSchemaItem {#type-sortschemaitem}
| 字段 | 类型 | 说明 |
|---|---|---|
| `id` | `string` | 这一项的唯一 ID |
| `row` | `number` | 这个字段在表单网格里所处的行 |
### StaticExtensionPoint {#type-staticextensionpoint}
```typescript
enum StaticExtensionPoint {
// 每个静态扩展点一个成员，完整清单见扩展点页面
PAGE_BEFORE = 'Checkout::RenderBefore',
MAIN_AFTER = 'Checkout::Main::RenderAfter',
// ...
}
```
### StepChangeCb {#type-stepchangecb}
```typescript
export type StepChangeCb = () => void;
```
### SubmitChangeCb {#type-submitchangecb}
```typescript
export type SubmitChangeCb = () => void;
```
### SubmitError {#type-submiterror}
| 字段 | 类型 | 说明 |
|---|---|---|
| `code` | `string` | 错误码 |
| `message` | `string` | 错误信息 |
### SubmitErrorChangeCbs {#type-submiterrorchangecbs}
```typescript
export type SubmitErrorChangeCbs = (tags: { code: string; message: string }) => void;
```
### SubmitSuccessData {#type-submitsuccessdata}
| 字段 | 类型 | 说明 |
|---|---|---|
| `data?` | { exceptNotification: ExceptNotification; result: Record<string, any>; } | 结果的数据体 |
| `state` | `string` | 结果状态，成功时为 `success` |
| `errors` | `string[]` | 错误信息列表 |
### SubPriceDetail {#type-subpricedetail}
金额明细某一行下面的子行，取 `BasePriceDetail` 的 `key`、`price`、`value`、`title`、`titleLangId`、`tooltip` 六个字段。
| 字段 | 类型 | 说明 |
|---|---|---|
| `key?` | `string` | 这一行明细的标识 |
| `title?` | `string` | 这一行的标题 |
| `titleLangId?` | `string` | 标题的翻译 key |
| `price?` | `string` | 这一行的金额 |
| `value?` | `string` | 这一项的取值 |
| `tooltip?` | `string` | 这一行的悬浮提示文字 |
### SuccessPriceResult {#type-successpriceresult}
| 字段 | 类型 | 说明 |
|---|---|---|
| `data` | PriceResultData | 结果的数据体 |
| `message` | `string` | 提示文案 |
| `state` | `'success'` | 结果状态，成功时为 `success` |
### Suggestion {#type-suggestion}
| 字段 | 类型 | 说明 |
|---|---|---|
| `text` | `string` | 这一行显示的文字 |
| `id` | `string` | 这一项的唯一 ID |
| `prefix?` | `string` | 建议项里匹配文字之前的部分 |
| `suffix?` | `string` | 建议项里匹配文字之后的部分 |
### SuggestionChangeCb {#type-suggestionchangecb}
```typescript
export type SuggestionChangeCb = (sugs: Suggestion[], status?: SuggestionSearchStatus) => void;
```
### SuggestionSchema {#type-suggestionschema}
| 字段 | 类型 | 说明 |
|---|---|---|
| `suggestions?` | Array<Suggestion> | 推荐列表 |
| `onSuggestionsChange?(cb)` | `void` | 注册建议列表变化时的回调 |
| `removeSuggestionChangeCb?(cb)` | `void` | 取消一个建议列表变化回调 |
| `onSelectSuggestion?(item)` | `void` | 选中某一个推荐项 |
| `prefixIcon?` | `string` | 输入框前置图标（Icon 的 type） |
### SuggestionSearchStatus {#type-suggestionsearchstatus}
| 取值 | 说明 |
|---|---|
| `'idle'` | 没有正在进行的搜索 |
| `'empty'` | 搜索完成，没有结果 |
### SwitchSetting {#type-switchsetting}
| 取值 | 说明 |
|---|---|
| `'disabled'` | 关 |
| `'enabled'` | 开 |
### SwitchShippingProtectionResult {#type-switchshippingprotectionresult}
| 字段 | 类型 | 说明 |
|---|---|---|
| `success` | `boolean` | 这次调用是否成功 |
| `message` | `string` | 提示文案 |
| `data` | `any` | 结果的数据体 |
### TaxLines {#type-taxlines}
| 字段 | 类型 | 说明 |
|---|---|---|
| `salesTaxLines?` | SaleTaxLine[] | 销售税明细 |
### ThemeConfigChangeCb {#type-themeconfigchangecb}
```typescript
export type ThemeConfigChangeCb = () => void;
```
### ThemeStyleConfig {#type-themestyleconfig}
| 字段 | 类型 | 说明 |
|---|---|---|
| `checkoutRecommendImageLink` | `'' \| { url: string; type: string }` | 广告位跳转链接 |
| `checkoutRecommendImage` | `string` | 广告位图片 |
| `checkoutPaymentBackgroundImage` | `string` | 付款区域背景图 |
| `checkoutPaymentBackgroundColor` | `string` | 付款区域背景色，同时配了背景图时以图片为准 |
| `checkoutInputBackgroundColor` | `string` | 输入框背景色 |
| `checkoutOrderBackgroundImage` | `string` | 订单摘要背景图 |
| `checkoutOrderBackgroundColor` | `string` | 订单摘要背景色，同时配了背景图时以图片为准 |
| `checkoutHeadingFontfamily` | checkoutFontfamily | 标题字体 |
| `checkoutBodyFontfamily` | checkoutFontfamily | 正文字体 |
| `checkoutButtonFontfamily` | checkoutFontfamily | 按钮字体 |
| `checkoutButtonBackgroundColor` | `string` | 按钮背景色，也是页脚返回链接的文字颜色 |
| `checkoutButtonText` | `string` | 按钮文字颜色 |
| `checkoutErrorColor` | `string` | 报错提示的文字颜色 |
| `checkoutFocusColor` | `string` | 输入框聚焦时的高亮颜色 |
| `checkoutBorderRadius` | `string` | 页面统一使用的圆角大小 |
| `checkoutBorderColor` | `string` | 左侧表单区域 |
| `checkoutTextMainColor` | `string` | 页面主文字颜色 |
| `checkoutTextSubColor` | `string` | 页面次文字颜色 |
| `checkoutEmptyBgColor` | `string` | 空白区域的背景色 |
| `checkoutBlockBorderColor` | `string` | 左侧卡片内部，包含输入框、物流方案卡片等 |
| `checkoutBlockTextMainColor` | `string` | 卡片内的主文字颜色 |
| `checkoutBlockTextSubColor` | `string` | 卡片内的次文字颜色 |
| `checkoutSummaryBorderColor` | `string` | 右侧订单摘要区域 |
| `checkoutSummaryTextMainColor` | `string` | 订单摘要的主文字颜色 |
| `checkoutSummaryTextSubColor` | `string` | 订单摘要的次文字颜色 |
| `checkoutSummaryBlockBorderColor` | `string` | 右侧卡片内部 |
| `checkoutSummaryBlockTextMainColor` | `string` | 订单摘要里卡片的主文字颜色 |
| `checkoutSummaryBlockTextSubColor` | `string` | 订单摘要里卡片的次文字颜色 |
### ThirdPartyErrorDetails {#type-thirdpartyerrordetails}
```typescript
export type ThirdPartyErrorDetails = Record[];
```
### TippingChangeCb {#type-tippingchangecb}
```typescript
export type TippingChangeCb = () => void;
```
### TippingInfo {#type-tippinginfo}
| 字段 | 类型 | 说明 |
|---|---|---|
| `productTotalPrice` | `number` | 商品总额 |
| `isShowTipping` | `boolean` | 是否展示小费模块 |
| `isSupportTipping` | `boolean` | 是否支持小费 |
| `currencySymbol` | `string` | 货币符号 |
| `totalTipReceived` | `string` | 小费合计 |
### TippingOption {#type-tippingoption}
| 字段 | 类型 | 说明 |
|---|---|---|
| `percent` | `number \| 'none' \| 'custom'` | 比例；none 是不给小费，custom 是顾客手动输入 |
| `value` | `number` | 金额 |
| `formatValue` | `string` | 带货币符号的金额 |
### TipSchema {#type-tipschema}
| 字段 | 类型 | 说明 |
|---|---|---|
| `tip?` | `string` | 小费金额 |
| `tipChangeEvent?` | `string` | |
### TrackAddressFillParams {#type-trackaddressfillparams}
这是文档为便于引用起的名字，源码中是内联类型。
| 字段 | 类型 | 说明 |
|---|---|---|
| `data` | Partial<AddressBookItem> | 结果的数据体 |
| `fillType` | `number` | |
### TrackGiftCardProps {#type-trackgiftcardprops}
| 取值 | 说明 |
|---|---|
| `'checkout_coupon_apply_begin'` | 顾客开始使用礼品卡 |
| `'checkout_coupon_close_begin'` | 顾客开始关闭礼品卡输入区 |
| `'checkout_coupon_fail'` | 礼品卡使用失败 |
### TrackSubmitAddressParams {#type-tracksubmitaddressparams}
这是文档为便于引用起的名字，源码中是内联类型。
| 字段 | 类型 | 说明 |
|---|---|---|
| `skipSetShippingAddress?` | `boolean` | 是否跳过设置物流地址这一步 |
### TrackTippingData {#type-tracktippingdata}
| 字段 | 类型 | 说明 |
|---|---|---|
| `total?` | `string` | 随事件上报的小费金额 |
| `rate?` | `number` | 顾客选择的小费比例 |
| `keyword?` | `string` | |
### TrackTippingType {#type-tracktippingtype}
| 取值 | 说明 |
|---|---|
| `'checkout_tipping_add_tip'` | 顾客加了小费 |
| `'checkout_tipping_select'` | 顾客选了一个小费金额 |
| `'checkout_tipping_visible'` | 小费模块出现在视野里 |
| `'checkout_tipping_focus'` | 顾客聚焦到小费输入框 |
### UIProduct {#type-uiproduct}
| 字段 | 类型 | 说明 |
|---|---|---|
| `id` | `string` | 这一项的唯一 ID |
| `variantId` | `string` | 变体 ID |
| `productTitle` | `string` | 商品名称 |
| `properties` | ProductItem['properties'] | 自定义属性 |
| `discountApplications` | ProductItem['discountApplications'] | 这一行生效的优惠 |
| `options` | ProductItem['options'] | 变体选项 |
| `isFreeGift` | `boolean` | 是不是赠品 |
| `quantity` | ProductItem['quantity'] | 数量 |
| `linePrice` | ProductItem['linePrice'] | 这一行的金额 |
| `discountTotal?` | ProductItem['discountTotal'] | 这一行的优惠合计 |
| `finalLinePrice?` | ProductItem['finalLinePrice'] | 优惠后这一行的金额 |
| `compareAtPrice` | ProductItem['compareAtPrice'] | 划线价 |
| `price` | ProductItem['price'] | 单价 |
| `coverUrl` | `string` | 封面图地址 |
### UiProductListChangeCb {#type-uiproductlistchangecb}
```typescript
export type UiProductListChangeCb = (product: UIProduct[]) => UIProduct[];
```
### UiShippingLinesChangeCb {#type-uishippinglineschangecb}
```typescript
export type UiShippingLinesChangeCb = (lines: FormatShippingLineType[]) => FormatShippingLineType[];
```
### UpdateContextCb {#type-updatecontextcb}
```typescript
type UpdateContextCb = (context: AddressSchemaManagerContext) => void;
```
### UpdateCustomFieldsResult {#type-updatecustomfieldsresult}
| 字段 | 类型 | 说明 |
|---|---|---|
| `state` | `'success' \| string` | 结果状态，成功时为 `success`；方法不抛异常，失败只通过这个字段告知 |
| `message?` | `string` | 失败时的错误信息，例如两个参数都为空、订单不可编辑、字段总长度超出上限 |
### UpdateDataByOrderAndPriceApiResult {#type-updatedatabyorderandpriceapiresult}
这是文档为便于引用起的名字，源码中是内联类型。
| 字段 | 类型 | 说明 |
|---|---|---|
| `price?` | PriceResult | 这一行的金额 |
| `order?` | OrderResult | 订单本身 |
### UpdateDataByPriceApiParams {#type-updatedatabypriceapiparams}
`PriceParams` 的字段，在这里全部是可选的，只传你要改的那些。
| 字段 | 类型 | 说明 |
|---|---|---|
| `reductions?` | `Array<{ code: string }>` | 要应用的折扣码，按码给出 |
| `discountApplications?` | `Array<{ code: string; discountId: string; _delete: 1; }>` | 逐条列出的已应用折扣 |
| `calculateShippingLine?` | `boolean` | 这次是否要重新计算运费 |
| `totalTipReceived?` | `string` | 订单上的小费合计 |
| `appliedGiftCards?` | `Record` | 这笔订单上已使用的礼品卡 |
| `type?` | DiscountTypeEnum | 这一项的类型 |
| `step?` | `string` | 对应的结账步骤 |
| `paymentLine?` | PaymentLine | null | 订单上选中的支付方式 |
| `config?` | { checkoutBusinessType: CheckoutBusinessType; } | 随这次请求或这笔订单带上的配置 |
### UpdateOrderCustomFieldsInput {#type-updateordercustomfieldsinput}
| 字段 | 类型 | 说明 |
|---|---|---|
| `customFields?` | `Record` | 要设置的字段，合并到订单已有的字段上，没提到的字段不受影响；同名 key 直接覆盖。key 不能为空字符串，也不能为 `*`。值只能是字符串，对象和数组需自行 `JSON.stringify` 后传入 |
| `deleteCustomFields?` | `string[]` | 要删除的 key；传 `['*']` 删除全部字段 |
### UserInfo {#type-userinfo}
顾客信息，`Customer` 的字段在这里全部是可选的。
| 字段 | 类型 | 说明 |
|---|---|---|
| `id?` | `string` | 这一项的唯一 ID |
| `firstName?` | `string` | 名 |
| `lastName?` | `string` | 姓 |
| `email?` | `string` | 邮箱地址 |
| `phone?` | `string \| null` | 手机号 |
| `name?` | `string` | 这一项的名称 |
| `orderCount?` | `number` | 这位顾客下过的订单数 |
| `customerId?` | `string` | 顾客 ID |
| `createAt?` | `string` | 顾客资料的创建时间 |
| `registeredAt?` | `string` | 顾客的注册时间 |
| `registered?` | `string` | 这位顾客是否已注册店铺账号 |
| `subscribed?` | `boolean` | 顾客是否订阅了营销邮件 |
### UserInfoChangeCb {#type-userinfochangecb}
```typescript
export type UserInfoChangeCb = (d: UserInfo) => void;
```
### UseShippingAsBillingAddressCb {#type-useshippingasbillingaddresscb}
```typescript
export type UseShippingAsBillingAddressCb = (val: boolean) => void;
```
### ValidateOptions {#type-validateoptions}
| 字段 | 类型 | 说明 |
|---|---|---|
| `updateUi?` | `boolean` | 校验结果是否显示到界面上 |
### ValidatePickupResultChangeCb {#type-validatepickupresultchangecb}
```typescript
export type ValidatePickupResultChangeCb = (result: ValidateResult | undefined) => void;
```
### ValidateResult {#type-validateresult}
| 字段 | 类型 | 说明 |
|---|---|---|
| `fieldId` | `string` | 字段 ID |
| `focusId` | `string` | 要聚焦的输入框 ID |
| `id` | `string` | 这一项的唯一 ID |
| `message` | `string` | 校验提示文案 |
### ValidateResultChangeCb {#type-validateresultchangecb}
```typescript
export type ValidateResultChangeCb = (fieldId: string, result: ValidateResult | undefined) => void;
```
### ValueInterface {#type-valueinterface}
| 字段 | 类型 | 说明 |
|---|---|---|
| `value` | `string` | 这一项的取值 |
| `onBlur?` | `(val: string) => void` | 输入框失焦时调用 |
| `changeValues` | (values: Partial<AddressValues>, config?: ChangeValueConfig) => void | 往地址表单里写入新的值 |
| `onValuesChange(cb)` | `void` | 注册字段取值变化时的回调 |
| `removeValuesChangeCb(cb)` | `void` | 取消一个取值变化回调 |
### VisibleConfig {#type-visibleconfig}
| 字段 | 类型 | 说明 |
|---|---|---|
| `billing` | `boolean` | 账单地址模块是否展示 |
| `virtualProductBilling` | `boolean` | 虚拟商品的账单地址模块是否展示 |
| `billingSelector` | `boolean` | 账单地址选择器是否展示 |
| `addressCard` | `boolean` | 地址卡片是否展示 |
| `deliveryMethod` | `boolean` | 配送方式模块是否展示 |
| `specialInstruction` | `boolean` | 订单备注模块是否展示 |
| `pickupInformation` | `boolean` | 自提信息模块是否展示 |
| `pickupAddress` | `boolean` | 自提地址是否展示 |
| `expressCheckout` | `boolean` | 快捷支付模块是否展示 |
| `delivery` | `boolean` | 配送模块是否展示 |
| `mobileCoupon` | `boolean` | 移动端优惠码模块是否展示 |
| `summaryCoupon` | `boolean` | 订单摘要里的优惠码模块是否展示 |
| `addressBook` | `boolean` | 地址簿是否展示 |
| `shippingAddress` | `boolean` | 收货地址模块是否展示 |
| `contactInformation` | `boolean` | 联系方式模块是否展示 |
### VisibleConfigChangeCb {#type-visibleconfigchangecb}
```typescript
export type VisibleConfigChangeCb = (visibleConfig: VisibleConfig) => void;
```