title: "购物车商店 (wc/store/cart)" post_status: publish comment_status: open taxonomy: category: - woocommerce post_tag: - Data Store - Reference - Block Development

购物车商店 (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 认为以下配送字段对于配送费率计算至关重要：state、country、postcode 和 city。

返回值

• 布尔值: 如果影响配送费率的配送地址字段正在更新，则返回 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();