跳到主要内容

购物车商店 (wc/store/cart)

💡 购物车商店和结账商店有什么区别?

购物车商店 (wc/store/cart) 用于管理和检索关于购物车的的数据,包括商品、客户数据以及与优惠券相关的交互。

结账商店 (wc/store/checkout) 用于管理和检索与结账过程相关的数据,包括客户 ID、订单 ID 和结账状态。

概述

购物车商店提供了一组选择器和方法,用于管理和检索 WooCommerce Blocks 中与购物车相关的数据。它提供了从获取购物车详情到管理客户交互的功能,例如应用优惠券或更新配送信息。

使用方法

要使用此商店,您需要在任何引用它的模块中导入 cartStore StoreDescriptor。 假设 @woocommerce/block-data 已注册为指向 wc.wcBlocksData 的外部,您可以通过以下方式导入 StoreDescriptor

const { cartStore } = window.wc.wcBlocksData;

操作

setCartData

此操作用于在商店中设置购物车数据。

参数

  • cartData object: 当前的购物车数据,包含以下键:
    • coupons array: 购物车中的优惠券项。
    • shippingRates array: 购物车中的配送费率(参见 getShippingRates 选择器)。
    • shippingAddress object: 配送地址(参见 getCustomerData 选择器)。
    • billingAddress object: 账单地址(参见 getCustomerData 选择器)。
    • items array: 购物车中的商品。
    • itemsCount number: 购物车中商品的总数量。
    • itemsWeight number: 购物车中商品的总重量。
    • crossSells array: 推荐商品。
    • needsPayment boolean: 购物车是否需要支付。
    • needsShipping boolean: 购物车是否需要配送。
    • hasCalculatedShipping boolean: 购物车是否已计算出配送费。
    • fees array: 购物车中的费用。
    • totals object: 购物车中的总计(参见 getCartTotals 选择器)。
    • errors array: 购物车中的错误(参见 getCartErrors 选择器)。
    • paymentRequirements object: 购物车中的支付要求。
    • extensions object: 扩展数据。

示例

const { dispatch } = useDispatch( cartStore );
dispatch( setCartData( newCartData ) );

setErrorData

此操作用于在商店中设置错误数据。

参数

  • errorData object: 需要在商店中设置的错误数据。
    • code string: 错误代码。
    • message string: 错误消息。
    • data object: 额外的错误数据。 这是一个可选的对象,包含以下键:
      • status number: 错误状态。
      • params string: 错误参数。
      • message string: 错误消息。
      • cart object: 购物车数据。 这是一个可选的对象,包含以下键:
        • coupons array: 购物车中的优惠券项。
        • shippingRates array: 购物车配送费率(参见 getShippingRates 选择器)。
        • shippingAddress object: 配送地址(参见 getCustomerData 选择器)。
        • billingAddress object: 账单地址(参见 getCustomerData 选择器)。
        • items array: 购物车中的商品项。
        • itemsCount number: 购物车中商品的总数量。
        • itemsWeight number: 购物车中商品的总重量。
        • crossSells array: 推荐商品项。
        • needsPayment boolean: 购物车是否需要支付。
        • needsShipping boolean: 购物车是否需要配送。
        • hasCalculatedShipping boolean: 购物车是否已计算出配送费。
        • fees array: 购物车费用。
        • totals object: 购物车总额(参见 getCartTotals 选择器)。
        • errors array: 购物车错误(参见 getCartErrors 选择器)。
        • paymentRequirements object: 购物车支付要求。
        • extensions object: 扩展数据。

示例

const { dispatch } = useDispatch( cartStore );
dispatch( setErrorData( newErrorData ) );

receiveCartContents

此操作返回一个操作对象,用于使用提供的购物车数据更新商店。 它省略了客户的地址,以便仅接收购物车项和总额的更新。

参数

  • cartContents object: 购物车内容的 API 响应。
    • coupons array: 购物车中的优惠券项目。
    • shippingRates array: 购物车的配送费率(参见 getShippingRates 选择器)。
    • shippingAddress object: 配送地址(参见 getCustomerData 选择器)。
    • billingAddress object: 账单地址(参见 getCustomerData 选择器)。
    • items array: 购物车中的项目。
    • itemsCount number: 购物车中项目的总数。
    • itemsWeight number: 购物车中项目的总重量。
    • crossSells array: 推荐商品。
    • needsPayment boolean: 如果购物车需要支付。
    • needsShipping boolean: 如果购物车需要配送。
    • hasCalculatedShipping boolean: 如果购物车已计算出配送费。
    • fees array: 购物车中的费用。
    • totals object: 购物车总额(参见 getCartTotals 选择器)。
    • errors array: 购物车中的错误(参见 getCartErrors 选择器)。
    • paymentRequirements object: 购物车支付要求。
    • extensions object: 扩展数据。

返回值

  • object: 包含以下键的动作对象:
    • type string: 动作类型。
    • cartContents object: 购物车内容,包含以下键:
      • coupons array: 购物车中的优惠券项目。
      • shippingRates array: 购物车的配送费率(参见 getShippingRates 选择器)。
      • items array: 购物车中的项目。
      • itemsCount number: 购物车中项目的总数。
      • itemsWeight number: 购物车中项目的总重量。
      • crossSells array: 推荐商品。
      • needsPayment boolean: 如果购物车需要支付。
      • needsShipping boolean: 如果购物车需要配送。
      • hasCalculatedShipping boolean: 如果购物车已计算出配送费。
      • fees array: 购物车中的费用。
      • totals object: 购物车总额(参见 getCartTotals 选择器)。
      • errors array: 购物车中的错误(参见 getCartErrors 选择器)。
      • paymentRequirements object: 购物车支付要求。
      • extensions object: 扩展数据。

示例

const { dispatch } = useDispatch( cartStore );
dispatch( receiveCartContents( newCartContents ) );

receiveApplyingCoupon

此动作返回一个动作对象,用于跟踪何时应用优惠券。

参数

  • couponCode string: 正在应用的优惠券代码。

返回值

  • object: 包含以下键的动作对象:
    • type string: 动作类型。
    • couponCode string: 正在应用的优惠券代码。

示例

const { dispatch } = useDispatch( cartStore );
dispatch( receiveApplyingCoupon( couponCode ) );

receiveRemovingCoupon

此操作返回一个操作对象,用于跟踪优惠券的移除状态。

参数

  • couponCode string: 要移除的优惠券的代码。

返回值

  • object: 包含以下键的操作对象:
    • type string: 操作类型。
    • couponCode string: 要移除的优惠券的代码。

示例

const { dispatch } = useDispatch( cartStore );
dispatch( receiveRemovingCoupon( couponCode ) );

receiveCartItem

此操作用于更新购物车中的特定项目。

参数

  • cartResponseItem object: 购物车响应对象,包含以下键:
    • cartItem object: 购物车项目(请参阅 getCartItem 选择器)。

返回值

  • object: 包含以下键的操作对象:
    • type string: 操作类型。
    • cartItem object: 购物车项目(请参阅 getCartItem 选择器)。

示例

const { dispatch } = useDispatch( cartStore );
dispatch( receiveCartItem( CartResponseItem ) );

itemIsPendingQuantity

此操作返回一个操作对象,用于指示购物车中指定项目的数量是否正在更新。

参数

  • cartItemKey string: 购物车项目的键。
  • isPending boolean (默认值: true): 指示购物车项目数量是否正在更新。

返回值

  • object: 包含以下键的操作对象:
    • type string: 操作类型。
    • cartItemKey string: 购物车项目的键。
    • isPending boolean: 指示购物车项目数量是否正在更新。

示例

const { dispatch } = useDispatch( cartStore );
dispatch( itemIsPendingQuantity( cartItemKey, isPending ) );

itemIsPendingDelete

此操作返回一个操作对象,用于指示购物车中的指定项目是否正在被删除。

参数

  • cartItemKey string: 购物车项目的键。
  • isPending boolean (默认值: true): 指示购物车项目是否正在被删除。

返回值

  • object: 包含以下键的操作对象:
    • type string: 操作类型。
    • cartItemKey string: 购物车项目的键。
    • isPending boolean: 指示购物车项目是否正在被删除。

示例

const { dispatch } = useDispatch( cartStore );
dispatch( itemIsPendingDelete( cartItemKey, isPending ) );

setIsCartDataStale

此操作返回一个操作对象,用于指示购物车数据是否已过期。

参数

  • isCartDataStale boolean (默认值: true): 用于标记购物车数据是否过期的标志;如果 lastCartUpdate 时间戳比 wcSettings 中的时间戳更早,则为 true

返回值

  • object: 包含以下键的操作对象:
    • type string: 操作类型。
    • isCartDataStale boolean: 用于标记购物车数据是否过期的标志;如果 lastCartUpdate 时间戳比 wcSettings 中的时间戳更早,则为 true

Example

const { dispatch } = useDispatch( cartStore );
dispatch( setIsCartDataStale( isCartDataStale ) );

updatingCustomerData

此操作返回一个操作对象,用于指示客户数据(账单和/或配送地址)是否正在更新。

参数

  • isResolving boolean: 指示客户数据是否正在更新。

返回值

  • object: 包含以下键的操作对象:
    • type string: 操作类型。
    • isResolving boolean: 指示客户数据是否正在更新。

Example

const { dispatch } = useDispatch( cartStore );
dispatch( updatingCustomerData( isResolving ) );

shippingRatesBeingSelected

此操作返回一个操作对象,用于指示是否正在选择配送费率。

参数

  • isResolving boolean: 如果正在选择配送费率,则为 true

返回值

  • object: 包含以下键的操作对象:
    • type string: 操作类型。
    • isResolving boolean: 如果正在选择配送费率,则为 true

Example

const { dispatch } = useDispatch( cartStore );
dispatch( shippingRatesBeingSelected( isResolving ) );

applyExtensionCartUpdate

此操作用于向 /cart/extensions 端点发送 POST 请求,并将扩展提供的相关数据一同发送。

参数

  • args object: 请求的参数,包含以下键:
    • extensionId string: 扩展 ID。
    • data object: 要发送到端点的的数据,包含以下键:
      • key string: 扩展的键。
      • value string: 扩展的数值。
    • overwriteDirtyCustomerData boolean: 指示是否使用服务器返回的数据覆盖客户端的客户数据,即使该数据尚未推送到服务器。

Example

const { dispatch } = useDispatch( cartStore );
dispatch( applyExtensionCartUpdate( args ) );

applyCoupon

此操作用于将优惠券应用于购物车。

参数

  • couponCode string: 要应用的优惠券代码。

Example

const { dispatch } = useDispatch( cartStore );
dispatch( applyCoupon( couponCode ) );

removeCoupon

此操作用于从购物车中移除优惠券。

参数

  • couponCode string: 要移除的优惠券代码。

Example

const { dispatch } = useDispatch( cartStore );
dispatch( removeCoupon( couponCode ) );

addItemToCart

此操作用于将商品添加到购物车。

参数

  • productId number: 要添加到购物车的 产品 ID。
  • quantity number (默认值: 1): 要添加的商品数量。

Example

const { dispatch } = useDispatch( cartStore );
dispatch( addItemToCart( productId, quantity ) );

removeItemFromCart

此操作用于从购物车中移除商品。

参数

  • cartItemKey string: 需要更新的购物车项。

示例

const { dispatch } = useDispatch( cartStore );
dispatch( removeItemFromCart( cartItemKey ) );

changeCartItemQuantity

此操作用于更改购物车中某个商品的数量。

参数

  • cartItemKey string: 需要更新的购物车项。
  • quantity number: 商品的数量。

示例

const { dispatch } = useDispatch( cartStore );
dispatch( changeCartItemQuantity( cartItemKey, quantity ) );

selectShippingRate

此操作用于选择购物车中的配送方式。

参数

  • rateId string: 要选择的配送方式的 ID。
  • packageId number | string (默认: null): 将在选定的配送方式中选择的包裹的键。

示例

const { dispatch } = useDispatch( cartStore );
dispatch( selectShippingRate( rateId, packageId ) );

setBillingAddress

此操作用于在本地设置购物车的账单地址,而不是 updateCustomerData,后者会将数据发送到服务器。

参数

  • billingAddress object: 需要设置的账单地址。键如下:
    • first_name string: 名。
    • last_name string: 姓氏。
    • company string: 公司名称。
    • address_1 string: 地址行 1。
    • address_2 string: 地址行 2。
    • city string: 城市名称。
    • state string: 州/省名称。
    • postcode string: 邮政编码。
    • country string: 国家名称。

示例

const { dispatch } = useDispatch( cartStore );
dispatch( setBillingAddress( billingAddress ) );

setShippingAddress

此操作用于在本地设置购物车的配送地址,而不是 updateCustomerData,后者会将数据发送到服务器。

参数

  • shippingAddress object: 需要设置的配送地址。键如下:
    • first_name string: 名。
    • last_name string: 姓氏。
    • company string: 公司名称。
    • address_1 string: 地址行 1。
    • address_2 string: 地址行 2。
    • city string: 城市名称。
    • state string: 州/省名称。
    • postcode string: 邮政编码。
    • country string: 国家名称。

示例

const { dispatch } = useDispatch( cartStore );
dispatch( setShippingAddress( shippingAddress ) );

updateCustomerData

此操作用于更新客户的配送和/或账单地址,并返回一个更新后的购物车。

参数

  • customerData object: 客户的账单和配送地址。键如下:
    • shippingAddress object: 配送地址,包含以下键:
      • first_name string: 名。
      • last_name string: 姓氏。
      • company string: 公司名称。
      • address_1 string: 地址行 1。
      • address_2 string: 地址行 2。
      • city string: 城市名称。
      • state string: 州/省名称。
      • postcode string: 邮政编码。
      • country string: 国家名称。
    • billingAddress object: 账单地址(与配送地址具有相同的键)。
  • editing: boolean (默认值: true): 如果正在编辑地址,则我们不会从响应中更新商店中的客户数据。

示例

const { dispatch } = useDispatch( cartStore );
dispatch( updateCustomerData( customerData, editing ) );

选择器

getCartData

返回来自状态的购物车数据。

返回值

  • object: 当前的购物车数据,包含以下键:
    • coupons array: 购物车中的优惠券项。
    • shippingRates array: 购物车中的配送费率(参见 getShippingRates 选择器)。
    • shippingAddress object: 配送地址(参见 getCustomerData 选择器)。
    • billingAddress object: 账单地址。
    • items array: 购物车中的商品。
    • itemsCount number: 购物车中商品的总数量。
    • itemsWeight number: 购物车中商品的总重量。
    • crossSells array: 推荐商品。
    • needsPayment boolean: 购物车是否需要支付。
    • needsShipping boolean: 购物车是否需要配送。
    • hasCalculatedShipping boolean: 购物车是否已计算出配送费用。
    • fees array: 购物车中的费用。
    • totals object: 购物车总计(参见 getCartTotals 选择器)。
    • errors array: 购物车中的错误(参见 getCartErrors 选择器)。
    • paymentRequirements object: 购物车中的支付要求。
    • extensions object: 扩展数据。

示例

const store = select( cartStore );
const cartData = store.getCartData();

getCustomerData

返回来自状态的配送和账单地址。

返回值

  • object: 当前的配送和账单地址,包含以下键:
    • shippingAddress object: 配送地址,包含以下键:
      • first_name string: 名。
      • last_name string: 姓氏。
      • company string: 公司名称。
      • address_1 string: 地址行 1。
      • address_2 string: 地址行 2。
      • city string: 城市名称。
      • state string: 州/省名称。
      • postcode string: 邮政编码。
      • country string: 国家名称。
    • billingAddress object: 账单地址(包含与配送地址相同的键)。

示例

const store = select( cartStore );
const customerData = store.getCustomerData();

getShippingRates

从状态获取配送费率。

返回值

  • array: 配送费率。键如下:
    • id string: 配送费率 ID。
    • label string: 配送费率标签。
    • cost string: 配送费率费用。
    • package_id number: 配送费率包裹 ID。
    • meta_data array: 配送费率元数据。键如下:
      • id number: 配送费率元数据 ID。
      • key string: 配送费率元数据键。
      • value string: 配送费率元数据值。
    • taxes array: 配送费率税费。

示例

const store = select( cartStore );
const shippingRates = store.getShippingRates();

getNeedsShipping

查询购物车是否需要配送。

返回值

  • boolean: 如果购物车需要配送,则返回 true

示例

const store = select( cartStore );
const needsShipping = store.getNeedsShipping();

getHasCalculatedShipping

查询购物车配送费是否已计算。

返回值

  • boolean: 如果配送费已计算,则返回 true

示例

const store = select( cartStore );
const hasCalculatedShipping = store.getHasCalculatedShipping();

getCartTotals

从状态返回购物车总计。

返回值

  • object: 当前购物车总计信息,包含以下键:
    • _total_items_: string: 购物车中所有项目的总价,不包含折扣、税费或配送费。
    • _total_items_tax_: string: 所有项目之前的税费总额。
    • _total_fees_: string: 总交易手续费。
    • _total_fees_tax_: string: 总交易手续费的税费。
    • _total_discount_: string: 应用于购物车的总折扣。
    • _total_discount_tax_: string: 应用于总折扣金额的税费。
    • _total_shipping_: string: 总配送费用。
    • _total_shipping_tax_: string: 应用于总配送费用的税费。
    • _total_tax_: string: 应用于购物车的总税费。
    • _total_price_: string: 购物车总价,包含折扣、税费或配送费。
    • _tax_lines_: array of object: 税费明细,包含 name(名称)、price(价格)和 rate(税率)。
    • _currency_code_: string: 购物车的货币代码。
    • _currency_symbol_: string: 购物车的货币符号。
    • _currency_minor_unit_: integer: 购物车的货币最小单位。
    • _currency_decimal_separator_: string: 购物车的货币小数分隔符。
    • _currency_thousand_separator_: string: 购物车的货币千位分隔符。
    • _currency_prefix_: string: 购物车的货币前缀。
    • _currency_suffix_: string: 购物车的货币后缀。

示例

const store = select( cartStore );
const cartTotals = store.getCartTotals();

getCartMeta

从状态中获取购物车元数据。

返回值

  • object: 当前购物车元数据,包含以下键:
    • _updatingCustomerData_: boolean: 如果正在更新客户数据(账单和/或配送地址)。
    • _updatingSelectedRate_: boolean: 如果正在更新选定的税率。
    • _isCartDataStale_: boolean: 如果购物车数据已过期。
    • _applyingCoupon_: string: 正在应用的优惠券代码。
    • _removingCoupon_: string: 正在移除的优惠券代码。

示例

const store = select( cartStore );
const cartMeta = store.getCartMeta();

getCartErrors

如果购物车从 API 接收到面向用户的错误,则返回购物车错误。

返回值

  • array: 购物车错误,包含以下键:
    • _code_: string: 错误代码。
    • _message_: string: 错误消息。
    • _data_: object: API 响应数据。

示例

const store = select( cartStore );
const cartErrors = store.getCartErrors();

isApplyingCoupon

查询是否正在应用优惠券。

返回值

  • boolean: 如果正在应用优惠券,则返回 true

示例

const store = select( cartStore );
const isApplyingCoupon = store.isApplyingCoupon();

isCartDataStale

查询购物车数据是否已过期。

返回值

  • boolean: 如果购物车数据已过期,则返回 True

例子

const store = select( cartStore );
const isCartDataStale = store.isCartDataStale();

getCouponBeingApplied

返回正在应用的优惠券代码。

返回值

  • string: 正在应用的优惠券代码。

例子

const store = select( cartStore );
const couponBeingApplied = store.getCouponBeingApplied();

isRemovingCoupon

查询是否正在移除优惠券。

返回值

  • boolean: 如果正在移除优惠券,则返回 True

例子

const store = select( cartStore );
const isRemovingCoupon = store.isRemovingCoupon();

getCouponBeingRemoved

返回正在移除的优惠券代码。

返回值

  • string: 正在移除的优惠券代码。

例子

const store = select( cartStore );
const couponBeingRemoved = store.getCouponBeingRemoved();

getCartItem( cartItemKey )

从状态中返回一个购物车项目。

参数

  • cartItemKey string: 购物车项目的关键字。

返回结果

  • object: 购物车项目,包含以下键:
    • key string: 购物车项目的键。
    • id number: 购物车项目ID。
    • catalog_visibility string: 目录可见性。
    • quantity_limits object: 数量限制。
    • name string: 购物车项目名称。
    • summary string: 购物车项目摘要。
    • short_description string: 购物车项目简短描述。
    • description string: 购物车项目描述。
    • sku string: 购物车项目SKU。
    • low_stock_remaining null or number: 剩余库存。
    • backorders_allowed boolean: 指示是否允许延期交货。
    • show_backorder_badge boolean: 指示是否应显示延期交货标识。
    • sold_individually boolean: 指示该项目是否单独销售。
    • permalink string: 购物车项目的固定链接。
    • images array: 购物车项目图像。
    • variation array: 购物车项目变体。
    • prices object: 购物车项目价格,包含以下键:
      • currency_code string: 货币代码。
      • currency_symbol string: 货币符号。
      • currency_minor_unit number: 货币小数单位。
      • currency_decimal_separator string: 货币小数分隔符。
      • currency_thousand_separator string: 货币千位分隔符。
      • currency_prefix string: 货币前缀。
      • currency_suffix string: 货币后缀。
      • price string: 购物车项目价格。
      • regular_price string: 购物车项目常规价格。
      • sale_price string: 购物车项目促销价格。
      • price_range string: 购物车项目价格范围。
    • totals object: 购物车项目总计,包含以下键:
      • currency_code string: 货币代码。
      • currency_symbol string: 货币符号。
      • currency_minor_unit number: 货币小数单位。
      • currency_decimal_separator string: 货币小数分隔符。
      • currency_thousand_separator string: 货币千位分隔符。
      • currency_prefix string: 货币前缀。
      • currency_suffix string: 货币后缀。
      • line_subtotal string: 购物车项目小计。
      • line_subtotal_tax string: 购物车项目小计税额。
      • line_total string: 购物车项目总计。
      • line_total_tax string: 购物车项目总计税额。

示例

const store = select( cartStore );
const cartItem = store.getCartItem( cartItemKey );

isItemPendingQuantity( cartItemKey )

查询购物车项目是否处于待审数量状态。

参数

  • cartItemKey string: 购物车项目的键。

返回结果

  • boolean: 如果购物车项目处于待审数量状态,则返回 true

示例

const store = select( cartStore );
const isItemPendingQuantity = store.isItemPendingQuantity( cartItemKey );

isItemPendingDelete( cartItemKey )

查询购物车中的某个商品是否处于待审删除状态。

参数

  • cartItemKey 字符串: 购物车商品键。

返回值

  • 布尔值: 如果购物车中的商品处于待审删除状态,则返回 true

示例

const store = select( cartStore );
const isItemPendingDelete = store.isItemPendingDelete( cartItemKey );

isCustomerDataUpdating

查询客户数据是否正在更新。

返回值

  • 布尔值: 如果客户数据正在更新,则返回 true

示例

const store = select( cartStore );
const isCustomerDataUpdating = store.isCustomerDataUpdating();

isAddressFieldsForShippingRatesUpdating

查询影响配送费率的配送地址字段是否正在更新。 默认情况下,Store API 认为以下配送字段对于配送费率计算至关重要:statecountrypostcodecity

返回值

  • 布尔值: 如果影响配送费率的配送地址字段正在更新,则返回 true

示例

const store = select( cartStore );
const isAddressFieldsForShippingRatesUpdating = store.isAddressFieldsForShippingRatesUpdating();

hasPendingItemsOperations

查询是否存在任何待审的购物车操作(添加、更新数量或删除商品)。

返回值

  • 布尔值: 如果存在待审的购物车操作(添加产品、更新数量或删除商品),则返回 true

示例

const store = select( cartStore );
const hasPendingItemsOperations = store.hasPendingItemsOperations();

isShippingRateBeingSelected

查询是否正在选择配送费率。

返回值

  • 布尔值: 如果正在选择配送费率,则返回 true

示例

const store = select( cartStore );
const isShippingRateBeingSelected = store.isShippingRateBeingSelected();

getItemsPendingQuantityUpdate

获取正在更新数量的商品的商品键。

返回值

  • 字符串[]: 包含正在更新数量的商品的商品键的数组。

示例

const store = select( cartStore );
const itemsPendingQuantityUpdate = store.getItemsPendingQuantityUpdate();

getItemsPendingDelete

获取正在删除的商品的商品键。

返回值

  • 字符串[]: 包含正在删除的商品的商品键的数组。

示例

const store = select( cartStore );
const itemsPendingDelete = store.getItemsPendingDelete();