CheckoutAPI 参考

CheckoutAPI 是结账页平台挂在 window.CheckoutAPI 上的全局对象，结账页和感谢页都有。它的方法按 order、store、address 等命名空间分组，扩展通过它读取订单和顾客已经做出的选择、监听这些数据的变化，以及驱动结账页的部分界面。本页列出的是结账页对外开放给应用的 CheckoutAPI 方法，口径来自平台的对外开放能力清单。方法签名里出现的类型，定义都在页尾的类型定义一节。

快速上手

CheckoutAPI 的方法按业务分成 15 个命名空间，调用形式统一是 CheckoutAPI.<命名空间>.<方法>()。下面这段代码打印一份结账页概况——当前步骤、订单、金额、商品行，用到 step、store、summary 三个命名空间。把它跑通，整份文档的用法就掌握了：之后需要什么数据，先找到管这块数据的命名空间，再到它的方法表里查方法名。

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	会发请求或做校验，结果稍后才拿到。

调用前必读

• 脚本刚开始跑的时候，window 上还没有 CheckoutAPI。 平台要等结账页加载完成才把它挂上去，所以要像上面的例子那样轮询等待，不要一上来就读 window.CheckoutAPI。完整例子见 场景三：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: AddressSchemaManagerContext config: 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, string | number>	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 用来填文案里的 {占位符}。

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<any>
cancelCoupon	取消一张已使用的优惠券	code: string	Promise<any>
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<void>

礼品卡与优惠码

方法	用途	参数	返回
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<any>
cancelGiftCardOrDiscountCode	取消已使用的优惠码或礼品卡	parasm: CancelCouponParams	Promise<any>
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<boolean>

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<void>
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<void>
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<any>
getTippingInfo	获取小费信息：是否支持和展示小费、货币符号、已收小费，以及扣除优惠（不含免邮券）后的商品小计	—	TippingInfo

物流

方法	用途	参数	返回
getShippingLines	获取当前地址可用的物流方案列表	—	FormatShippingLineType[]
getSelectedShippingLine	获取当前选中的物流方案，没有选中时返回 null	—	FormatShippingLineType | null
updateSelectedShippingLine	切换选中的物流方案	shippingLine: ShippingLineType	Promise<void>
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<any>
onChangeSpecialInstruction	注册留言备注发生变化的回调	cb: (info: string) => void	void
removeSpecialInstructionChangeCb	删除留言备注发生变化的回调	cb: (info: string) => void	void
expendSpecialInstruction	展开留言备注输入框	—	void
isInstructionCollapse	留言备注输入框当前是否折叠	—	boolean
onInstructionCollapseChange	注册留言备注折叠状态发生变化的回调	cb: IsSpecialInstructionCollapseChange	void
removeInstructionCollapseChange	删除留言备注折叠状态发生变化的回调	cb: IsSpecialInstructionCollapseChange	void

已填信息卡片

方法	用途	参数	返回
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<void>
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<void>
stepNavToShipping	跳转到配送步	type?: EventType	Promise<void>
stepNavToPayment	跳转到支付步	—	Promise<void>
stepNavToNext	跳转到下一步，布局和结算方式的差异由平台抹平	—	Promise<void>
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<void>
couldNavTo	导航栏能不能跳到指定步骤。导航栏只能往回跳，往前推进要靠提交当前步骤	id: CheckoutStep	boolean
stepNavTo	跳转到指定步骤	id: CheckoutStep location?: EventType	Promise<any>
navToReferrerPage	跳回顾客进入结账页之前的那个页面	—	void
goToOrderInfoPage	跳转到订单详情页	—	void
goToHomePage	跳转到店铺首页	—	void
disableJump	禁止步骤跳转，可以指定只禁止哪几种跳转方式	way?: JumpWay[]	Promise<void>
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<string, any>	void
getAssemblyOrder	获取埋点上报用的订单数据	—	CheckoutOrder
registerTrackExtraInfo	给某个埋点事件附加自定义字段，之后每次上报这个事件都会带上	eventName: string data: Record<string, unknown>	void
trackAddPaymentInfo	上报填写支付信息事件	extra?: Record<string, any>	void
trackAddShippingMethod	上报选择物流方案事件	—	void
trackAddressFill	上报地址自动填充事件	data: TrackAddressFillParams	void
trackAddressFormExpand	上报地址表单展开事件	reason: AddressExpandReason	void
trackAioBeforePay	上报聚合支付发起前的事件	—	void
trackBeforePay	上报发起支付前的事件	extra?: Record<string, any>	void
trackCompleteOrderClick	上报点击下单按钮事件	—	void
trackCompleteOrderError	上报下单失败事件	data: string	void
trackContinueToPayment	上报进入支付步骤事件	—	void
trackCouponChangeTab	上报优惠券面板切换 tab 的事件	status: string	void
trackEnterCheckout	上报进入结账页事件	—	void
trackGiftCard	上报礼品卡相关事件	type: TrackGiftCardProps info: Record<string, string | number>	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: TrackTippingType data: TrackTippingData	void

user

user 命名空间管顾客是谁、怎么联系：登录状态、账号信息、结账页填写的邮箱和手机号，以及营销邮件订阅。

顾客信息

方法	用途	参数	返回
isLogin	顾客是否已登录	—	boolean
getIPAddress	获取顾客的 IP 地址信息	—	CheckoutIpAddress
doLogin	跳转到登录页；传入的参数会拼进登录后的返回地址	returnUrlSearchParams?: Record<string, string>	void
doRegister	跳转到注册页	—	void
doLogout	登出当前顾客	—	Promise<void>
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: DialogContent options?: DialogOptions	IDialog
createDrawer	创建抽屉式弹层（从屏幕边缘滑出）	content: DrawerContent options?: DrawerOptions	IDrawer

用法

两个方法的第一个参数放内容和按钮文案，第二个可选参数放隐藏按钮、尺寸这类选项。createDialog 返回 { show, hide }，createDrawer 返回 { show, hide, onClose, destroy, getId }。顾客点确认后，show() 的 Promise 解析为 true。

const dialog = CheckoutAPI.utils.createDialog({
  content: '<div>确认寄到这个地址？</div>',
  footer: '<div>预计 3 到 5 天送达</div>',
  trueBtn: '确定',
  falseBtn: '取消',
});
const confirmed = await dialog.show();  // 顾客点「确定」后为 true

const drawer = CheckoutAPI.utils.createDrawer({
  content: '<div style="height:200px">确认寄到这个地址？</div>',
  footer: '<div>预计 3 到 5 天送达</div>',
});
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

字段	类型	说明
name?	string	附加费的名称
price?	string	附加费的金额

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

字段	类型	说明
[key: string]	{ name: string; val: string; }	其他任意 key，按名字索引

AddLineItemsInput

字段	类型	说明
lineItems	AddProductInput[]	订单的商品行
mutationSource	MutationSource	你自己填的标记，说明这次改动是谁发起的

AddProductInput

字段	类型	说明
variantId	string	规格 ID
quantity	number	数量
properties?	ProductProperties	要写到新订单行上的自定义属性，JSON 字符串

AddressBookChangeCbs

export type AddressBookChangeCbs = () => void;

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

export type AddressChangeByInputCb = (
  changeValue: Partial<AddressValues>,
  fullAddress: AddressValues,
  config: ChangeValuesConfig,
) => void;

AddressChangeCb

export type AddressChangeCb = () => void;

AddressCountry

字段	类型	说明
isoCode2	string	两位国家 / 地区代码
name	string	国家 / 地区名称
provinces	AddressCountryProvince[]	该国家 / 地区下的省 / 州列表
depth	number	这个国家 / 地区的地址层级数
code	string	两位国家 / 地区代码
preset	string
format?	AddressFormat	地址格式模板

AddressCountryProvince

字段	类型	说明
cnName	string	中文名称
code	string	省 / 州代码
name	string	省 / 州名称
oldCode	string
provinceId	string	省 / 州的 ID
preset?	string
format?	AddressFormat	这个字段的格式规则

AddressExpandReason

取值	说明
'manual_click'	顾客点击展开了表单
'empty_fallback_click'	顾客点了折叠状态下的空表单
'auto_fill'	表单因为被自动填充而展开
'submit_validate'	为了显示校验报错而展开表单
'browser_fill'	浏览器自动填了表单

AddressFormat

字段	类型	说明
fields	AddressFormatField[]	这个模板包含的字段
[k: string]	any	其他任意 key，按名字索引

AddressFormatField

字段	类型	说明
id	string	这一项的唯一 ID
label?	string	字段上方显示的标签
show?	0 | 1	这一项是否显示
row?	number	这个字段在表单网格里所处的行
description?	string	这个字段的说明
[k: string]	any	其他任意 key，按名字索引

AddressItemActionSchema

字段	类型	说明
id	string	这一项的唯一 ID
show	true	这一项是否显示
type	FieldType.Action	字段类型，固定为操作项
text	string	操作项的文字
row	number	这个字段在表单网格里所处的行
col	number	这个字段在表单网格里所处的列
style?	Record<string, string | number>	加在元素上的行内样式
className?	string	加在元素上的 CSS class
onClick()	void	顾客点击这一行时调用

AddressItemCheckoutSchema

字段	类型	说明
id	string	这一项的唯一 ID
type	FieldType.Checkbox	字段类型，固定为复选框
desc	string	复选框旁边的文案
show	true	这一项是否显示
value	boolean	复选框是否已勾选
row	number	这个字段在表单网格里所处的行
col	number	这个字段在表单网格里所处的列
changeValue(isCheck)	void	勾选或取消勾选这个复选框

AddressItemEmailSchema

字段	类型	说明
type	FieldType.Email	字段类型，固定为邮箱

AddressItemGeneralPhoneSchema

手机号字段的 schema。它还带有 BaseAddressItemSchema 和 ValueInterface 的全部字段，下面只列它自己的成员。

字段	类型	说明
type	FieldType.Phone	字段类型，固定为手机号
phoneInfo	PhoneInfo	手机号字段的区号和格式规则
maxLength?	number	允许输入的最大字符数
changePhone(value, format?, config?)	void	往字段里写一个新的手机号
changePhoneAreaCode(value)	void	往字段里写一个新的国际电话区号

AddressItemPhoneSchema

手机号字段 schema 的别名，等价于 AddressItemGeneralPhoneSchema。

export type AddressItemPhoneSchema = AddressItemGeneralPhoneSchema;

AddressItemSchema

地址表单里一个字段的 schema，按字段类型分成下拉、手机号、文本、邮箱四种。

export type AddressItemSchema =
  | AddressItemSelectSchema
  | AddressItemPhoneSchema
  | AddressItemStringSchema
  | AddressItemEmailSchema;

AddressItemSelectSchema

字段	类型	说明
type	FieldType.Enum	字段类型，固定为下拉选择
selectType	SelectType	选项列表是固定的还是实时拉取，取值同 SelectType
options	OptionValue[]	下拉列表里的选项

AddressItemStringSchema

字段	类型	说明
type	FieldType.String	字段类型，固定为文本
readOnly?	boolean	只读，禁止修改
format?	Array<[regexp: string, params: string[]]> | string[]	值的格式化规则，例如巴西税号在失焦时会按规则重新排版

AddressItemTitleSchema

字段	类型	说明
id	string	这一项的唯一 ID
show	true	这一项是否显示
type	FieldType.Title	字段类型，固定为标题
title	string	标题文字
row	number	这个字段在表单网格里所处的行
col	number	这个字段在表单网格里所处的列

AddressManagerConfig

字段	类型	说明
useAllCountry	boolean	是否列出所有国家 / 地区，而不只是可配送的那些

AddressSchemaManager

地址表单的 schema 管理器，一个实例对应一张地址表单，负责取值、改值、拿字段 schema 和校验。

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<AddressValues>, config?: ChangeValuesConfig);
  onValuesChange(cb: AddressValuesChangeCb);
  removeValuesChangeCb(cb: AddressValuesChangeCb);
  dispatchAddressValuesChange(changeVal: Partial<AddressValues>, options?: AddressValuesChangeOptions);
  validateFields(fieldIds?: Array<keyof AddressValues>, config?: { updateUi?: boolean; onlyValidateExistValue?: boolean }): Promise<ValidateResult[]>;
  onValidateResultChange(cb: ValidateResultChangeCb);
  removeValidateResultChange(cb: ValidateResultChangeCb);
  getCountries();
  hasCountry(countryCode: string);
  getProvinces();
  isValidProvinceCode(code: string);
  getAllSchema(): Array<AddressItemSchema>;
  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<AddressItemStringSchema | AddressItemPhoneSchema | AddressItemEmailSchema | AddressItemSelectSchema>;
  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<AddressValues>, config?: ChangeValueConfig);
}

这个管理器自己持有内部状态，所以这里按源码列出、不转成表格。实例从 CheckoutAPI.address 上取，不要自己 new。

AddressSchemaManagerContext

字段	类型	说明
addressValues	AddressValues	地址表单当前的取值
addressTemplate	AddressTemplate	当前国家 / 地区的地址模板

AddressTemplate

字段	类型	说明
fields	AddressTemplateField[]	这个模板要收集的地址字段
stringify	string
preset	string
addressLevel	number	地址层级数

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

字段	类型	说明
id	string	这一项的唯一 ID
message	string	校验不通过时显示的文案
regexp	string	取值需要匹配的正则表达式

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

export type CommonAddressValuesChangeCb = (
  changeValue: Partial<AddressValues>,
  fullAddress: AddressValues,
  options?: AddressValuesChangeOptions,
) => void;

AddressValuesChangeOptions

字段	类型	说明
apiAutoFilled?	boolean	这个值是接口自动填的，不是顾客填的
changeByInput?	boolean	这次变化是否由顾客输入引起

AddSchemaChangeCbs

type AddSchemaChangeCbs = (item: AddressItemSchema) => AddressItemSchema;

AfterPayCb

export type AfterPayCb = (res: AfterPayParams) => void;

AfterPayParams

一次支付尝试的结果：支付请求走通时是 PayResponse 再加一个 loadTime，抛异常时是 Error，没有结果可报时是 undefined。

export type AfterPayParams =
  | (PayResponse & {
      loadTime: number;
    })
  | Error
  | undefined;

AllExtensionLoadedCb

export type AllExtensionLoadedCb = () => void;

AlreadyPaymentLines

这笔订单上已经收到的支付记录数组，下面是数组里一项的字段。

字段	类型	说明
creditCardNumber	string	这次支付使用的卡号
extraInfo	{ name: string; channel: string; method: string; lastCharacters: string; realPaidTotal: string; }	这笔支付的附加信息
paidTotal	string	这笔支付收到的金额

AppliedGiftCard

字段	类型	说明
id	string	这一项的唯一 ID
lastCharacters	string	礼品卡卡号的末几位
amountUsed	string	礼品卡已抵扣的金额
realAmountCurrency	string	礼品卡本身的币种
realSymbol	string	礼品卡本身币种的符号
realAmountUsed	string	按礼品卡本身币种计的已用金额

BannerConfig

字段	类型	说明
checkoutPcImage	string	桌面端使用的 Banner 图片
checkoutMobileImage	string	移动端使用的 Banner 图片
checkoutImageHeight	'normal' | 'large' | 'small'	Banner 图片的高度档位
checkoutAlignment	'top' | 'center' | 'bottom'	Banner 的垂直对齐方式
checkoutIsFullWidth	boolean	Banner 是否通栏铺满页面宽度
checkoutShowBottomMargin	boolean	Banner 下方是否留出下边距

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<string, string | number>	加在输入框上的额外 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

字段	类型	说明
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

字段	类型	说明
ok	boolean	这次请求是否成功
config	ReqConfig	随这次请求或这笔订单带上的配置

BeforeSubmitCb

export type BeforeSubmitCb = (params: BeforeSubmitCbParams) => Promise<boolean>;

BeforeSubmitCbParams

字段	类型	说明
pageType	CheckoutPageType	结账页布局，取值同 CheckoutPageType
step	CheckoutStep	对应的结账步骤

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

export type BillingAddressChangeCb = () => void;

BillingAddressValuesChangeCb

export type BillingAddressValuesChangeCb = (values: Partial<AddressValues>) => void;

BuyerJourneyInterceptCb

export type BuyerJourneyInterceptCb = () => BuyerJourneyInterceptCbReturn;

BuyerJourneyInterceptCbReturn

字段	类型	说明
behavior	'block' | 'allow'	拦下顾客还是让他继续
pointId	string	拦截来自哪个扩展点的 ID
hideTrueBtn?	boolean	隐藏弹窗的确认按钮
hideFalseBtn?	boolean	隐藏弹窗的取消按钮

CancelCouponParams

export type CancelCouponParams =
  | {
      code: string;
      discountCodeType: DiscountCodeType.DISCOUNT_CODE;
    }
  | {
      id: string;
      discountCodeType: DiscountCodeType.GIFT_CARD;
    };

CardInfo

字段	类型	说明
cardFirstName	string	持卡人名
cardLastName	string	持卡人姓
cardDate	string	卡片有效期
cardCode	string	卡片上的安全码
cardNumber	string	卡号
instalmentsPlans	string	卡片上选择的分期方案

Cards

字段	类型	说明
supportCards	Array<PlayCardCards>	这个支付方式支持的卡种

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

字段	类型	说明
format?	boolean	写入时是否顺便格式化这个值
changeByInput?	boolean	这次变化是否由顾客输入引起

ChangeValuesConfig

字段	类型	说明
ignoreValidate?	boolean	这次改动是否跳过校验
dispatchUpdate?	boolean	改完之后是否触发界面刷新
changeByInput?	boolean	这次变化是否由顾客输入引起
changeByUserInput?	boolean	用户手动输入
apiAutoFilled?	boolean	地址联想等 API 自动填充，UI 高亮提示
onlyValidateExistValue?	boolean	是否只校验已经有值的字段

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

字段	类型	说明
name	NameSetting	姓名字段的设置
nameRequirement	NmeRequirementSetting	姓名字段的必填要求
contactDetails	ContactDetailsSetting	联系方式字段的设置
phone	SimplesSetting	手机号字段的设置
email	SimplesSetting	邮箱字段的设置
company	SimplesSetting	公司字段的设置
address	SimplesSetting	详细地址字段的设置
address1	SimplesSetting	详细地址第二行字段的设置

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

结账类型：普通商品、虚拟商品、门店自提。

成员	值	说明
STANDARD	0	普通实物商品
VIRTUAL_PRODUCT	1	虚拟商品，不需要配送
PICKUP	2	门店自提

CheckoutBusinessTypeChangeCb

export type CheckoutBusinessTypeChangeCb = (type: CheckoutBusinessType) => void;

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

结账页的功能开关表，key 是功能名，值是这个功能开没开。

export type CheckoutFeatures = Record<string, boolean>;

checkoutFontfamily

字段	类型	说明
family	string	字体族名称
fallbackFamilies	string	兜底字体族
style	string	字形
weight	string	字重
fontFace	string	这个字体对应的 @font-face 规则

CheckoutIpAddress

字段	类型	说明
countryCode	string	国家 / 地区代码
provinceName	string	省 / 州名称
countryName	string	国家 / 地区名称
city	string	城市
ip	string	IP 地址

CheckoutMenuPolicyLink

字段	类型	说明
id	number	这一项的唯一 ID
title	string	只有三种内置政策才有值
type	string	菜单类型：三种内置政策为 policy，商家自定义的为 web
url	string	内置政策为固定值：退款政策 refund_policy、隐私政策 privacy_policy、服务条款 service_policy； 自定义菜单为商家填写的链接，留空表示只展示文字、不跳转

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

CheckoutPageType

结账页布局：单页、两页、三页。

成员	值	说明
SINGLE	'single'	单页结账
THREE_STEP	'three_step'	三页结账
TWO_STEP	'two_step'	两页结账

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

字段	类型	说明
customerAuthority	'all' | 'login'	谁可以结账：all 所有人，login 只有登录顾客
discountShowV2	string[]
reductionShow	{ single: string[]; twoStep: string[]; threeStep: string[]; }	各结账布局下分别显示哪些折扣行
orderTimeout	number	订单超时时间
shippingCpf	ShippingCpf	配送环节用到的 CPF 字段设置
zipCheckV2	string
zipCheckConfigV2	Record<CountryCode, number>	各国家 / 地区的邮编校验配置
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

结账步骤：填联系方式、选配送方式、选支付方式。

取值	说明
'contact_information'	填联系方式和地址的那一步
'shipping_method'	选配送方式的那一步
'payment_method'	选支付方式的那一步

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

取值	说明
'close_icon'	顾客点了关闭图标
'true_btn'	顾客点了确认按钮
'false_btn'	顾客点了取消按钮
'hide_fn'	你的代码调了 hide()

CollapseInfo

字段	类型	说明
contact	string	折叠态里显示的联系方式
delivery	string	折叠态里显示的配送方式
addressInfo	string	折叠态里显示的地址
addressInfoTitle	string	折叠态地址那一行的标题
showNewBtn	boolean	是否显示新建收货地址按钮

CollapseInfoChangeCb

export type CollapseInfoChangeCb = () => void;

CommonAddressValuesChangeCb

export type CommonAddressValuesChangeCb = (
  changeValue: Partial<AddressValues>,
  fullAddress: AddressValues,
  options?: AddressValuesChangeOptions,
) => void;

ContactDetailsSetting

取值	说明
'single'	只收一个联系方式字段
'multiple'	收多个联系方式字段

ContactInformation

字段	类型	说明
email	string	邮箱
phone	string	手机号
emailOrPhone	string	邮箱或手机号合并字段的值
phoneAreaCode	string	手机区号

ContactInformationChangeCb

export type ContactInformationChangeCb = (contactInformation: Partial<ContactInformation>) => void;

ContactSchemaConfig

字段	类型	说明
type	'address' | 'contact'	这一项的类型
showWhenOptional?	boolean	这个字段可选时是否仍然显示

ContactType

联系方式的收集方式：只收邮箱、只收手机号，或者两者填一个。

成员	值	说明
ONLY_EMAIL	'only_email'	只收邮箱
ONLY_PHONE	'only_phone'	只收手机号
EMAIL_OR_PHONE	'email_or_phone'	邮箱和手机号填一个就行

Country

字段	类型	说明
cnName	string	中文名称
name	string	国家 / 地区名称
flag	string	国旗
phoneCode	string	电话区号
phoneKey	string	这个国家 / 地区区号的 key
isoCode2	string	两位国家 / 地区代码

CouponAvailStatus

成员	值	说明
AVAILABLE	'available'	这张券在当前订单上可用
UNAVAILABLE	'unavailable'	这张券在当前订单上不可用

CouponChangeCb

export type CouponChangeCb = () => void;

CouponData

字段	类型	说明
page	number	当前页码
limit	number	每页条数
data	CouponItem[]	这一页的优惠券
total	number	总条数

CouponItem

字段	类型	说明
id	string	这一项的唯一 ID
code	string	券码
title	string	券的名称
discountText	string	描述这张券优惠内容的文案
prerequisiteText	string	使用这张券需要满足的条件文案
createdAt	string	这条记录的创建时间
expiredAt	string	券的过期时间
isFirstOrder	boolean	这张券是否只对首单有效

CouponListChangeCb

export type CouponListChangeCb = (data: CouponData) => void;

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

字段	类型	说明
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

谁可以结账：all 所有人，login 只有登录顾客。

取值	说明
'all'	所有人都能结账
'login'	只有登录顾客能结账

DayConfigOfPickupTime

字段	类型	说明
day?	number	1-7
state?	number	0 休息，1 营业
start?	string	时间段的开始时间
end?	string	时间段的结束时间

DeliveryListChangeCb

export type DeliveryListChangeCb = () => void;

DeliveryMethodChangeCb

export type DeliveryMethodChangeCb = (id: DeliveryMethodItem) => void;

DeliveryMethodItem

字段	类型	说明
iconType	string	这个配送方式用哪个图标
checkoutBusinessType	CheckoutBusinessType	对应的结账类型
text	string	展示文案

DeliveryMethodListChangeCb

export type DeliveryMethodListChangeCb = (items: DeliveryMethodItem[]) => DeliveryMethodItem[];

DialogContent

字段	类型	说明
content	string	弹窗或抽屉的正文内容
footer?	string	弹窗或抽屉的底部内容
trueBtn?	string	确认按钮的文案
falseBtn?	string	取消按钮的文案

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	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

成员	值	说明
DISCOUNT_CODE	'discountCode'	这个码是折扣码
GIFT_CARD	'giftCard'	这个码是礼品卡

DiscountTypeEnum

成员	值	说明
AUTOMATIC	'automatic'	自动优惠，不用输码就生效
DISCOUNT_REBATE	'discount_rebate'	满减优惠
DISCOUNT_CODE	'discount_code'	顾客手动输入的折扣码
DISCOUNT_COUPON	'discount_coupon'	顾客持有的优惠券
GIFT_CARD	'gift_card'	礼品卡

DrawerContent

字段	类型	说明
content	string	弹窗或抽屉的正文内容
footer?	string	弹窗或抽屉的底部内容
trueBtn?	string	确认按钮的文案
falseBtn?	string	取消按钮的文案

DrawerOptions

字段	类型	说明
hideTrueBtn?	boolean	隐藏弹窗的确认按钮
hideFalseBtn?	boolean	隐藏弹窗的取消按钮
maskBlur?	boolean	蒙层是否启用模糊滤镜，默认为 false
style?	{ width?: number; height?: number; maxHeight?: number; maxWidth?: number; backgroundColor?: string; }	加在元素上的行内样式

DynamicExtensionPoint

enum DynamicExtensionPoint {
  // 每个动态扩展点模板一个成员，完整清单见扩展点页面
  PRODUCT_RENDER_AFTER = 'Checkout::Product-{id}::RenderAfter',
  SHIPPING_LINE_RENDER_AFTER = 'Checkout::ShippingLine-{id}::RenderAfter',
  // ...
}

EventBus

一个小型的发布 / 订阅总线，每个地址字段的 eventBus 属性上挂着一个。

字段	类型	说明
eventMap	Map<string, Set<Function>>	按事件名分组的回调集合
onceCbMap	Map<Function, Function>	一次性回调的包装函数，按原函数索引
emit(name, ...rest)	—	触发一个事件，通知所有监听这个名字的回调
on(name, cb)	—	在一个事件名上注册回调
once(name, cb)	—	注册一个只触发一次的回调
off(name, cb)	—	把某个回调从一个事件名上移除

EventType

取值	说明
'change'	页面上某个值变了
'return'	顾客返回上一步
'navigate'	页面跳转到别处

ExceptionChangeCbs

export type ExceptionChangeCbs = (tags?: IException) => void;

ExceptionInfo

字段	类型	说明
code	string	错误码
message?	string	错误信息
title?	string	标题
content?	string	正文
footer?	string	底部文案
backStep?	string	顾客会被退回到的那一步
invalidLineItems?	Array<InvalidLineItem>	已失效的订单行
changedLineItems?	Array<ChangedLineItem>	发生了变化的订单行

ExceptNotification

字段	类型	说明
code	string	异常的错误码
message?	string	异常的错误信息
nextAction?	NextAction	页面接下来该做什么
invalidLineItems?	Array<InvalidLineItem>	已经不再有效的订单行
kickLineItems?	Array<KickLineItem>	已经被踢出订单的订单行
thirdPartyErrorDetails?	Record<string, unknown>[]	第三方返回的原始错误详情

ExtendSchema

地址表单里一项的 schema，除了普通字段，还包括勾选项、标题和操作项。

export type ExtendSchema =
  | AddressItemSchema
  | AddressItemCheckoutSchema
  | AddressItemTitleSchema
  | AddressItemActionSchema;

Extension

字段	类型	说明
components	ExtensionComponent[]	这个扩展的组件列表
name	string	扩展名称
name_en	string	扩展的英文名称
desc	string	扩展描述
desc_en	string	扩展的英文描述
deleteTargets	string[]	这个扩展要隐藏的原生模块
placeholder	Record<string, string>	占位文案，按字段 ID 索引

ExtensionComponent

字段	类型	说明
extensionId	string	扩展 ID
content	string	渲染出来的 HTML 内容
point	string	渲染到哪个扩展点

ExtensionList

字段	类型	说明
extensionId	string	扩展 ID
resourceUrl	string	加载扩展脚本的 URL
fields?	string	扩展声明的字段
name?	string	扩展的名称
name_en?	string	英文名称
desc?	string	扩展的说明
desc_en?	string	英文说明

ExtensionLoadCb

export type ExtensionLoadCb = (point: ExtensionPoint) => void;

ExtensionPoint

export type ExtensionPoint = StaticExtensionPoint | DynamicExtensionPoint;

ExtensionTarget

enum ExtensionTarget {
  // 每个可隐藏的原生模块一个成员，完整清单见结账扩展参考页
  shippingList = 'shippingList',
  couponDrawer = 'couponDrawer',
  // ...
}

FailPriceResult

字段	类型	说明
data	null	结果的数据体
message	string	错误信息
state	string	结果状态，成功时为 success

FieldFnValidate

字段	类型	说明
id	string	这条校验规则的 ID
message	string	校验不通过时显示的文案
validate(value)	boolean	返回这个值是否通过校验

FieldRegExpValidate

字段	类型	说明
id	string	这一项的唯一 ID
message	string	校验不通过时显示的文案
regexp	string	取值需要匹配的正则表达式

FieldsChangeCb

export type FieldsChangeCb = (fields?: Array<keyof AddressValues>) => void;

FieldType

成员	值	说明
String	0	普通文本字段
Number	1	数字字段
Enum	2	固定选项字段
Bool	3	布尔字段
Phone	101	手机号字段
Email	102	邮箱字段
Checkbox	103	勾选框
Title	104	标题行，不是输入项
Action	105	操作行，比如一个链接或按钮，不是输入项

FieldValidate

export type FieldValidate = FieldRegExpValidate | FieldFnValidate;

FormatShippingLineType

字段	类型	说明
formatDiscountShippingPrice	string	带货币符号的优惠后运费
formatShippingPrice	string	带货币符号的运费
isFree	boolean	是不是免运费

GetAddressTemplateParams

字段	类型	说明
countryCode	string	国家 / 地区代码
provinceCode	string	省 / 州代码

GiftCard

字段	类型	说明
type	DiscountCodeType	码的类型
code	string	礼品卡码
id	string	礼品卡 ID
title	string	礼品卡名称
lastCharacters?	string	卡号后几位
amountUsed?	string	已抵扣金额
realAmountCurrency?	string	礼品卡本身的币种
realSymbol?	string	礼品卡本身币种的符号
realAmountUsed?	string	按礼品卡本身币种计的已用金额

GiftCardTagChange

export type GiftCardTagChange = (item: GiftCardTagItem) => GiftCardTagItem;

GiftCardTagItem

字段	类型	说明
disable?	boolean	是否禁用
hideIcon?	boolean	是否隐藏图标

GiftCardTagsChangeCb

export type GiftCardTagsChangeCb = (tags: GiftCardTagItem[]) => void;

GiftCardTagsFilter

export type GiftCardTagsFilter = (tags: GiftCardTagItem[]) => GiftCardTagItem[];

HideExtensionTargetCb

export type HideExtensionTargetCb = () => void;

HttpCompleteResponse

字段	类型	说明
status	number	HTTP 状态码
statusText	string	HTTP 状态描述
headers	Record<string, string>	请求头或响应头
data	Payload	响应的数据体

HttpFailResponse

字段	类型	说明
ok	false	这次请求是否成功

HttpSuccessResponse

字段	类型	说明
ok	true	这次请求是否成功

IAddressBookItem

字段	类型	说明
showEmail	boolean	是否展示邮箱
showPhone	boolean	是否展示手机号

IdentificationConfig

字段	类型	说明
countries?	Record<string, string[]> | null	这份配置覆盖的国家 / 地区
isFilled	boolean	顾客是否已经填了这个字段
formatCheck	boolean	是否校验取值的格式
rules	Array<{ countryCode: string; provinceCode?: string; name: string; regexp: string; exampleVal: string; }>	生效的规则，每个国家 / 地区一条

IDialog

字段	类型	说明
show()	Promise<boolean>	这一项是否显示
hide()	void	关闭弹窗或抽屉

IDrawer

字段	类型	说明
show()	Promise<boolean>	这一项是否显示
hide()	void	关闭弹窗或抽屉
onClose(cb)	void	注册抽屉关闭时的回调
destroy()	void	关闭抽屉并销毁它

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

取值	说明
'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

这是文档为便于引用起的名字，源码中是内联类型。

字段	类型	说明
phoneAreaCode	string	手机号的国际电话区号
phone	string	手机号

InstructionType

订单备注框的展示方式：展开、折叠、隐藏。

成员	值	说明
UNFOLD	'unfold'	订单备注框默认展开
FOLD	'fold'	订单备注框默认折叠
HIDDEN	'hidden'	不显示订单备注框

InteractionConfig

字段	类型	说明
checkoutPaymentIconShow	boolean	是否显示支付方式图标
checkoutMobileOrderSummaryCollapse	boolean	移动端订单摘要是否默认折叠
checkoutMobileDiscountBoxLocation	'orderSummaryAndPaymentMethod' | 'orderSummary' | 'paymentMethod'	移动端折扣码输入框放在哪里

InvalidLineItem

字段	类型	说明
productTitle	string	商品标题
image	{ src: string; }	商品图片
options	Array<{ name: string; value: string | number; }>	这一项可选的取值

isShowCountries

字段	类型	说明
[key: string]	{ countryCodes?: string; countries?: { [key: string]: string[] }; isFilled: boolean; title: string; formatCheck?: boolean; }	其他任意 key，按名字索引

IsSpecialInstructionCollapseChange

export type IsSpecialInstructionCollapseChange = (isCollapse: boolean) => void;

JumpWay

取值	说明
'a'	走 <a> 链接跳转
'window.open'	用 window.open 开新窗口
'history'	写一条 history 记录，页面不重新加载
'hash'	只改 URL 的 hash 部分
'location'	给 location 赋值，页面会重新加载

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

字段	类型	说明
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

取值	说明
'bundled_product_requires_real_item'	加了组合商品，但没有它依附的实物商品
'checkout_token_missing'	页面上取不到结账 token
'checkout_token_invalid'	结账 token 无效

LineMutationResult

字段	类型	说明
state	'success' | string	结果状态，成功时为 success
data?	LineMutationResultData	结果的数据体
code?	LineMutationErrorCode | string	失败时的错误码
message?	string	错误信息

LineMutationResultData

字段	类型	说明
orderId	string	订单 ID
lineItems	LineItem[]	订单的商品行
priceDirty	boolean	为 true 表示价格已过期、需要重新计算
lineItemsVersion	number	订单行的版本号，每次改动递增
shippingReselectRequired?	boolean	仅当「是否需要物流」翻转时为 true
paymentReselectRequired?	boolean	顾客是否需要重新选一次支付方式

LoadingStatus

字段	类型	说明
globalLoading	boolean	整页是不是在加载中

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

字段	类型	说明
'en-US'	Record<string, string>	每个语言一项，值是该语言下的文案
[k in Locale]	Record<string, string>	每个语言一项，值是该语言下的文案

LogoConfig

字段	类型	说明
checkoutLogoImage	string	结账页的 Logo 图片
checkoutLogoSize	'large' | 'medium' | 'small'	Logo 的尺寸档位
checkoutLogoPosition	string	Logo 的位置

MarketInfo

字段	类型	说明
marketId	string	市场 ID
marketPriceSetting	MarketPriceSetting	这个市场的价格设置

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

字段	类型	说明
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

export type MutationSource = string;

NameSetting

取值	说明
'separate'	姓和名分成两个输入框
'normal'	姓名合成一个输入框

NavigateLink

字段	类型	说明
id	CheckoutStep	这个链接指向的结账步骤
title	'information' | 'shipping' | 'payment'	埋点用
text	string	链接文案

NavigateLinksChangeCb

export type NavigateLinksChangeCb = () => void;

NewsLetterStatus

营销邮件的订阅状态：未订阅、已订阅。

成员	值	说明
NO_SUBSCRIPTION	0	未订阅营销邮件
SUBSCRIBED	1	已订阅营销邮件

NextAction

字段	类型	说明
redirectToUrl	{ url: string; }	要把顾客跳转到的 URL
type	'redirect_to_url'	这一项的类型

NmeRequirementSetting

取值	说明
'both'	姓和名都必填
'last_name'	只有姓必填

OnCloseCb

export type OnCloseCb = (type: CloseType) => void;

OnLoadingStatusChangeCallback

export type OnLoadingStatusChangeCallback = (status: LoadingStatus) => void;

OnPayFailedPayload

字段	类型	说明
sysCodeGroup	string | null
paymentKey	string	标识支付方式的 key

OnPayFailedResult

字段	类型	说明
handled	boolean	你的回调是否已经自己处理了这次失败

OnStoreDataChangeCb

export type OnStoreDataChangeCb = () => void;

OnSubmitPendingChangeCallback

export type OnSubmitPendingChangeCallback = (val: Pending, change: Partial<Pending>) => void;

OptionValue

字段	类型	说明
name	string	选项的名称
code	C	这一项的代码
alternateNames?	string[]	这个选项的其他别名

OrderConfig

订单上的配置信息，取自 CheckoutOrder 的 config 字段。

字段	类型	说明
checkoutBusinessType	number	这笔订单的结账类型，取值同 CheckoutBusinessType
checkoutTemplateType	number	结账页使用的模板类型
pageType	'single' | 'three_step' | 'two_step'	结账页布局，取值同 CheckoutPageType
marketSetting	{ marketId?: string; }	这笔订单归属的市场
productTaxIncluded?	boolean	商品价格是否已含税

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[]	附加费用

OrderResult

字段	类型	说明
data?	OrderResultData	响应的数据体
state	string	结果状态，成功时为 success
errors	string[]	错误信息列表

OrderResultData

字段	类型	说明
exceptNotification	ExceptNotification	平台报出的异常信息
addressSettings	CheckoutAddressSettings	店铺的地址表单设置
checkoutSettings	CheckoutSettings	店铺的结账设置
customerInfo	CheckoutCustomerInfo	顾客填写的联系信息
ipAddress	CheckoutIpAddress	下单来源的 IP 地址信息
order	CheckoutOrder	订单本身
paymentSettings	PaymentSettings	店铺的支付设置
showDetails	ShowDetails	页面上哪些区块显示
step	CheckoutStep	对应的结账步骤

OrderStatus

订单状态。

取值	说明
'opened'	订单已创建但还没提交
'placed'	订单已提交
'cancelled'	订单已取消
'finished'	订单已完成

PageTypeChangeCb

export type PageTypeChangeCb = (type: CheckoutPageType) => void;

PayAttemptCb

export type PayAttemptCb = () => void;

PayFailedHandler

export type PayFailedHandler = (payload: OnPayFailedPayload) => Promise<OnPayFailedResult>;

PaymentIconResource

字段	类型	说明
paymentKey	string	标识支付方式的 key
icon	string	这一行显示的图标

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<string, unknown>[]	绑定在这个支付方式上的优惠

PaymentLinesSource

取值	说明
'destroy'	上一条支付记录被销毁
'verificationError'	支付校验失败
'api'	支付记录来自一次接口返回

PaymentResources

字段	类型	说明
[key: string]	Cards	其他任意 key，按名字索引

PaymentSettings

字段	类型	说明
supportChannels	string[]	店铺已开启的支付渠道
paymentResources	PaymentResources	支付方式需要的静态资源
paymentIconResources?	PaymentIconResource[]	可用支付方式的图标资源
paypalExpressEnabled	string	PayPal Express 是否开启

PaymentUpdateParams

字段	类型	说明
paymentLine	PaymentLine	当前选中的支付方式
paymentLines	Array<PaymentLine>	可选的支付方式列表
paymentButton	boolean	是否显示支付按钮
paymentReady	boolean	支付方式是否已经可以提交
cardInfo	Partial<CardInfo>	银行卡信息
source?	PaymentLinesSource	这次支付更新由什么触发，取值同 PaymentLinesSource
paymentFeatures?	{ useCustomPaymentButton: boolean; useBillingAddress: boolean; }	这个支付方式需要哪些支付能力

PayResponse

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

字段	类型	说明
price	boolean	价格接口调用中
shippingLines	boolean	物流方案列表加载中
payment	boolean	支付脚本加载中，不是支付方式列表
pickupLocation	boolean	自提点列表加载中

PhoneInfo

字段	类型	说明
phone	string	手机号
phoneAreaCode	string	手机号的国际电话区号

PickupInformationChangeCb

export type PickupInformationChangeCb = (pickupInformation?: string) => void;

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

export type PickupLocationsChangeCb = (locations?: PickupLocation[]) => void;

PlaceType

export type PlaceType =
  | {
      types: Array<string>;
      stringify?: string;
    }
  | Array<string>;

PlayCardCards

字段	类型	说明
cardName	string	卡种的显示名称
cardType	string	卡种，比如 Visa、Mastercard
countryCnName?	string	国家 / 地区的中文名
countryCode?	string	国家 / 地区代码
countryEnName?	string	国家 / 地区的英文名
icon	string	这一行显示的图标
name?	string	这一项的名称
pmId?	string

PluginConfig

字段	类型	说明
plugins	{ appserval: { servalBg1Color: string; servalBg2Color: string; servalDiscountColor: string; servalHeadingColor: string; showNewCustomerExclusiveTag: boolean; exclusiveForNewUsers: false; }; }	结账页插件的配置

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

字段	类型	说明
key	PriceGroupDetailKey	分组标识
list?	PriceDetail[]	这一组下的价格条目
desc?	string	描述
descLangId?	string	说明文字的翻译 key

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

export type PriceListChangeCb = (newPriceList: PriceGroupDetail[]) => void;

PriceParams

字段	类型	说明
reductions?	Array<{ code: string }>	要应用的折扣码，按码给出
discountApplications?	Array<{ code: string; discountId: string; _delete: 1; }>	逐条列出的已应用折扣
calculateShippingLine	boolean	这次是否要重新计算运费
totalTipReceived	string	订单上的小费合计
appliedGiftCards?	Record<string, { id: string; _delete: 1 }>	这笔订单上已使用的礼品卡
type?	DiscountTypeEnum	这次要应用的折扣种类，取值同 DiscountTypeEnum
step?	string	对应的结账步骤
paymentLine?	PaymentLine | null	订单上选中的支付方式
config	{ checkoutBusinessType: CheckoutBusinessType; }	随这次请求或这笔订单带上的配置

PriceResult

export type PriceResult = SuccessPriceResult | FailPriceResult;

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

export type PricesChangeCb = (prices: CheckoutPrices) => void;

ProductItem

派生自 LineItem，字段完全相同，只是 properties 换成了键值对对象（Record<string, string>），不再是字符串。

字段	类型	说明
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<string, string>	挂在这一行上的自定义属性

ProductListChangeCb

export type ProductListChangeCb = (newProductList: ProductItem[]) => void;

ProductProperties

字段	类型	说明
_shoplazza_bundled_product?	boolean	捆绑商品，不能独立成单
_shoplazza_exclude_calculation?	boolean	独立于所有计算之外，仅最终总价加回
[key: string]	any	其他任意 key，按名字索引

PromptMessage

字段	类型	说明
type	string	提示类型
dataRobot	string
errorMessage?	string	错误信息
locales	string[]	这条文案覆盖的语言

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

字段	类型	说明
lineItemIds	string[]	要操作的订单行 ID 列表
mutationSource	MutationSource	你自己填的标记，说明这次改动是谁发起的

RenderParams

字段	类型	说明
id	string	这一项的唯一 ID
extensionPoint	ExtensionPoint	内容渲染在哪个扩展点上
component	Promise<string> | string	扩展要渲染的 HTML，也可以是解析出 HTML 的 promise

ReqConfig

字段	类型	说明
url	string	请求地址
method?	RequestInit['method']	HTTP 请求方法
headers?	Record<string, string>	请求头或响应头
params?	Record<string, any> | URLSearchParams	请求的查询参数
data?	Record<string, any> | string	结果的数据体
timeout?	number	请求超时时间，单位毫秒
withCredentials?	boolean	请求是否带上 cookie
responseType?	'json'	响应按什么格式解析
xsrfCookieName?	string	读取 XSRF token 的 cookie 名
xsrfHeaderName?	string	发送 XSRF token 的请求头名

Res

export type Res<Shape = Record<string, any>, ErrorPayload = Record<string, any> & { state: string | '' }> =
  | HttpSuccessResponse<Shape>
  | HttpFailResponse<ErrorPayload>;

SaleTaxLine

字段	类型	说明
key?	string	这条税费的标识
price?	string	这一行的金额

SchemaChangeDisableCB

export type SchemaChangeDisableCB = () => Record<string, boolean>;

SchemaChangeLabelCb

export type SchemaChangeLabelCb = () => Record<string, string>;

SchemaChangeValidateRule

字段	类型	说明
[k: string]	SchemaChangeValidateRuleValue	其他任意 key，按名字索引

SchemaChangeValidateRuleCB

export type SchemaChangeValidateRuleCB = () => SchemaChangeValidateRule;

SchemaChangeValidateRuleValue

字段	类型	说明
required	true	顾客是否必须填这一项
validates	FieldValidate[]	生效的校验规则

SchemaItemVisibilityCb

export type SchemaItemVisibilityCb = () => Record<string, boolean>;

SchemaManagerConfig

字段	类型	说明
focusIdPrefix	string	生成 focus id 时统一加的前缀

SchemaManagerConfigFn

字段	类型	说明
getAddressVisible()	boolean	返回地址表单当前是否可见
getCustomLabels?	() => Record<string, string>	返回商家自定义的字段标签，按字段 ID 索引
getCustomValidateRules?	() => SchemaChangeValidateRule	返回要额外应用的校验规则
getAddressExpanded?	() => boolean	地址表单当前是否已展开；不提供时视为已展开
expandAddress?	(reason: 'manual_click' | 'empty_fallback_click' | 'auto_fill') => void	展开地址表单

SelectedPickupLocationChangeCb

export type SelectedPickupLocationChangeCb = (location?: PickupLocation) => void;

SelectType

取值	说明
'static'	选项列表是固定的
'dynamic'	选项列表随顾客输入实时拉取

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

export type ShippingChangeCb = () => void;

ShippingCpf

字段	类型	说明
isShow	boolean	这一行是否显示
configInfo	{ configBr: { length: string; type: string; }; configDefault: { length: string; type: string; }; }	CPF 字段的分国家配置
countries	any[]	这份配置覆盖的国家 / 地区
isShowCountries	isShowCountries	哪些国家 / 地区显示 CPF 字段

ShippingLinesErrorInfo

字段	类型	说明
message?	string	错误信息

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

取值	说明
'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

export type ShippingPriceDisplayChangeCb = () => void;

ShippingPromptMessageChangeCb

export type ShippingPromptMessageChangeCb = () => void;

ShippingProtectionChangeCb

export type ShippingProtectionChangeCb = () => void;

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

字段	类型	说明
isAddressAvailable?	boolean	地址是否可用

SimplesSetting

取值	说明
'hidden'	不显示这个字段
'optional'	显示这个字段，可以不填
'required'	显示这个字段，必须填

SortSchemaCb

export type SortSchemaCb = (items: SortSchemaItem[]) => SortSchemaItem[];

SortSchemaItem

字段	类型	说明
id	string	这一项的唯一 ID
row	number	这个字段在表单网格里所处的行

StaticExtensionPoint

enum StaticExtensionPoint {
  // 每个静态扩展点一个成员，完整清单见扩展点页面
  PAGE_BEFORE = 'Checkout::RenderBefore',
  MAIN_AFTER = 'Checkout::Main::RenderAfter',
  // ...
}

StepChangeCb

export type StepChangeCb = () => void;

SubmitChangeCb

export type SubmitChangeCb = () => void;

SubmitError

字段	类型	说明
code	string	错误码
message	string	错误信息

SubmitErrorChangeCbs

export type SubmitErrorChangeCbs = (tags: { code: string; message: string }) => void;

SubmitSuccessData

字段	类型	说明
data?	{ exceptNotification: ExceptNotification; result: Record<string, any>; }	结果的数据体
state	string	结果状态，成功时为 success
errors	string[]	错误信息列表

SubPriceDetail

金额明细某一行下面的子行，取 BasePriceDetail 的 key、price、value、title、titleLangId、tooltip 六个字段。

字段	类型	说明
key?	string	这一行明细的标识
title?	string	这一行的标题
titleLangId?	string	标题的翻译 key
price?	string	这一行的金额
value?	string	这一项的取值
tooltip?	string	这一行的悬浮提示文字

SuccessPriceResult

字段	类型	说明
data	PriceResultData	结果的数据体
message	string	提示文案
state	'success'	结果状态，成功时为 success

Suggestion

字段	类型	说明
text	string	这一行显示的文字
id	string	这一项的唯一 ID
prefix?	string	建议项里匹配文字之前的部分
suffix?	string	建议项里匹配文字之后的部分

SuggestionChangeCb

export type SuggestionChangeCb = (sugs: Suggestion[], status?: SuggestionSearchStatus) => void;

SuggestionSchema

字段	类型	说明
suggestions?	Array<Suggestion>	推荐列表
onSuggestionsChange?(cb)	void	注册建议列表变化时的回调
removeSuggestionChangeCb?(cb)	void	取消一个建议列表变化回调
onSelectSuggestion?(item)	void	选中某一个推荐项
prefixIcon?	string	输入框前置图标（Icon 的 type）

SuggestionSearchStatus

取值	说明
'idle'	没有正在进行的搜索
'empty'	搜索完成，没有结果

SwitchSetting

取值	说明
'disabled'	关
'enabled'	开

SwitchShippingProtectionResult

字段	类型	说明
success	boolean	这次调用是否成功
message	string	提示文案
data	any	结果的数据体

TaxLines

字段	类型	说明
salesTaxLines?	SaleTaxLine[]	销售税明细

ThemeConfigChangeCb

export type ThemeConfigChangeCb = () => void;

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

export type ThirdPartyErrorDetails = Record<string, unknown>[];

TippingChangeCb

export type TippingChangeCb = () => void;

TippingInfo

字段	类型	说明
productTotalPrice	number	商品总额
isShowTipping	boolean	是否展示小费模块
isSupportTipping	boolean	是否支持小费
currencySymbol	string	货币符号
totalTipReceived	string	小费合计

TippingOption

字段	类型	说明
percent	number | 'none' | 'custom'	比例；none 是不给小费，custom 是顾客手动输入
value	number	金额
formatValue	string	带货币符号的金额

TipSchema

字段	类型	说明
tip?	string	小费金额
tipChangeEvent?	string

TrackAddressFillParams

这是文档为便于引用起的名字，源码中是内联类型。

字段	类型	说明
data	Partial<AddressBookItem>	结果的数据体
fillType	number

TrackGiftCardProps

取值	说明
'checkout_coupon_apply_begin'	顾客开始使用礼品卡
'checkout_coupon_close_begin'	顾客开始关闭礼品卡输入区
'checkout_coupon_fail'	礼品卡使用失败

TrackSubmitAddressParams

这是文档为便于引用起的名字，源码中是内联类型。

字段	类型	说明
skipSetShippingAddress?	boolean	是否跳过设置物流地址这一步

TrackTippingData

字段	类型	说明
total?	string	随事件上报的小费金额
rate?	number	顾客选择的小费比例
keyword?	string

TrackTippingType

取值	说明
'checkout_tipping_add_tip'	顾客加了小费
'checkout_tipping_select'	顾客选了一个小费金额
'checkout_tipping_visible'	小费模块出现在视野里
'checkout_tipping_focus'	顾客聚焦到小费输入框

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

export type UiProductListChangeCb = (product: UIProduct[]) => UIProduct[];

UiShippingLinesChangeCb

export type UiShippingLinesChangeCb = (lines: FormatShippingLineType[]) => FormatShippingLineType[];

UpdateContextCb

type UpdateContextCb = (context: AddressSchemaManagerContext) => void;

UpdateDataByOrderAndPriceApiResult

这是文档为便于引用起的名字，源码中是内联类型。

字段	类型	说明
price?	PriceResult	这一行的金额
order?	OrderResult	订单本身

UpdateDataByPriceApiParams

PriceParams 的字段，在这里全部是可选的，只传你要改的那些。

字段	类型	说明
reductions?	Array<{ code: string }>	要应用的折扣码，按码给出
discountApplications?	Array<{ code: string; discountId: string; _delete: 1; }>	逐条列出的已应用折扣
calculateShippingLine?	boolean	这次是否要重新计算运费
totalTipReceived?	string	订单上的小费合计
appliedGiftCards?	Record<string, { id: string; _delete: 1 }>	这笔订单上已使用的礼品卡
type?	DiscountTypeEnum	这一项的类型
step?	string	对应的结账步骤
paymentLine?	PaymentLine | null	订单上选中的支付方式
config?	{ checkoutBusinessType: CheckoutBusinessType; }	随这次请求或这笔订单带上的配置

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

export type UserInfoChangeCb = (d: UserInfo) => void;

UseShippingAsBillingAddressCb

export type UseShippingAsBillingAddressCb = (val: boolean) => void;

ValidateOptions

字段	类型	说明
updateUi?	boolean	校验结果是否显示到界面上

ValidatePickupResultChangeCb

export type ValidatePickupResultChangeCb = (result: ValidateResult | undefined) => void;

ValidateResult

字段	类型	说明
fieldId	string	字段 ID
focusId	string	要聚焦的输入框 ID
id	string	这一项的唯一 ID
message	string	校验提示文案

ValidateResultChangeCb

export type ValidateResultChangeCb = (fieldId: string, result: ValidateResult | undefined) => void;

ValueInterface

字段	类型	说明
value	string	这一项的取值
onBlur?	(val: string) => void	输入框失焦时调用
changeValues	(values: Partial<AddressValues>, config?: ChangeValueConfig) => void	往地址表单里写入新的值
onValuesChange(cb)	void	注册字段取值变化时的回调
removeValuesChangeCb(cb)	void	取消一个取值变化回调

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

export type VisibleConfigChangeCb = (visibleConfig: VisibleConfig) => void;