购物车商店 (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: 扩展数据。
- coupons
示例
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: 扩展数据。
- coupons
- status
- code
示例
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: 扩展数据。
- coupons
返回值
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: 扩展数据。
- coupons
- type
示例
const { dispatch } = useDispatch( cartStore );
dispatch( receiveCartContents( newCartContents ) );
receiveApplyingCoupon
此动作返回一个动作对象,用于跟踪何时应用优惠券。
参数
- couponCode
string: 正在应用的优惠券代码。
返回值
object: 包含以下键的动作对象:- type
string: 动作类型。 - couponCode
string: 正在应用的优惠券代码。
- type
示例
const { dispatch } = useDispatch( cartStore );
dispatch( receiveApplyingCoupon( couponCode ) );
receiveRemovingCoupon
此操作返回一个操作对象,用于跟踪优惠券的移除状态。
参数
- couponCode
string: 要移除的优惠券的代码。
返回值
object: 包含以下键的操作对象:- type
string: 操作类型。 - couponCode
string: 要移除的优惠券的代码。
- type
示例
const { dispatch } = useDispatch( cartStore );
dispatch( receiveRemovingCoupon( couponCode ) );
receiveCartItem
此操作用于更新购物车中的特定项目。
参数
- cartResponseItem
object: 购物车响应对象,包含以下键:- cartItem
object: 购物车项目(请参阅getCartItem选择器)。
- cartItem
返回值
object: 包含以下键的操作对象:- type
string: 操作类型。 - cartItem
object: 购物车项目(请参阅getCartItem选择器)。
- type
示例
const { dispatch } = useDispatch( cartStore );
dispatch( receiveCartItem( CartResponseItem ) );
itemIsPendingQuantity
此操作返回一个操作对象,用于指示购物车中指定项目的数量是否正在更新。
参数
- cartItemKey
string: 购物车项目的键。 - isPending
boolean(默认值:true): 指示购物车项目数量是否正在更新。
返回值
object: 包含以下键的操作对象:- type
string: 操作类型。 - cartItemKey
string: 购物车项目的键。 - isPending
boolean: 指示购物车项目数量是否正在更新。
- type
示例
const { dispatch } = useDispatch( cartStore );
dispatch( itemIsPendingQuantity( cartItemKey, isPending ) );
itemIsPendingDelete
此操作返回一个操作对象,用于指示购物车中的指定项目是否正在被删除。
参数
- cartItemKey
string: 购物车项目的键。 - isPending
boolean(默认值:true): 指示购物车项目是否正在被删除。
返回值
object: 包含以下键的操作对象:- type
string: 操作类型。 - cartItemKey
string: 购物车项目的键。 - isPending
boolean: 指示购物车项目是否正在被删除。
- type
示例
const { dispatch } = useDispatch( cartStore );
dispatch( itemIsPendingDelete( cartItemKey, isPending ) );
setIsCartDataStale
此操作返回一个操作对象,用于指示购物车数据是否已过期。
参数
- isCartDataStale
boolean(默认值:true): 用于标记购物车数据是否过期的标志;如果lastCartUpdate时间戳比wcSettings中的时间戳更早,则为true。
返回值
object: 包含以下键的操作对象:- type
string: 操作类型。 - isCartDataStale
boolean: 用于标记购物车数据是否过期的标志;如果lastCartUpdate时间戳比wcSettings中的时间戳更早,则为true。
- type
Example
const { dispatch } = useDispatch( cartStore );
dispatch( setIsCartDataStale( isCartDataStale ) );
updatingCustomerData
此操作返回一个操作对象,用于指示客户数据(账单和/或配送地址)是否正在更新。
参数
- isResolving
boolean: 指示客户数据是否正在更新。
返回值
object: 包含以下键的操作对象:- type
string: 操作类型。 - isResolving
boolean: 指示客户数据是否正在更新。
- type
Example
const { dispatch } = useDispatch( cartStore );
dispatch( updatingCustomerData( isResolving ) );
shippingRatesBeingSelected
此操作返回一个操作对象,用于指示是否正在选择配送费率。
参数
- isResolving
boolean: 如果正在选择配送费率,则为true。
返回值
object: 包含以下键的操作对象:- type
string: 操作类型。 - isResolving
boolean: 如果正在选择配送费率,则为true。
- type
Example
const { dispatch } = useDispatch( cartStore );
dispatch( shippingRatesBeingSelected( isResolving ) );
applyExtensionCartUpdate
此操作用于向 /cart/extensions 端点发送 POST 请求,并将扩展提供的相关数据一同发送。
参数
- args
object: 请求的参数,包含以下键:- extensionId
string: 扩展 ID。 - data
object: 要发送到端点的的数据,包含以下键:- key
string: 扩展的键。 - value
string: 扩展的数值。
- key
- overwriteDirtyCustomerData
boolean: 指示是否使用服务器返回的数据覆盖客户端的客户数据,即使该数据尚未推送到服务器。
- extensionId
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: 国家名称。
- first_name
示例
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: 国家名称。
- first_name
示例
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: 国家名称。
- first_name
- billingAddress
object: 账单地址(与配送地址具有相同的键)。
- shippingAddress
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: 扩展数据。
- coupons
示例
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: 国家名称。
- first_name
- billingAddress
object: 账单地址(包含与配送地址相同的键)。
- shippingAddress
示例
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: 配送费率元数据值。
- id
- taxes
array: 配送费率税费。
- id
示例
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_:arrayof 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
nullornumber: 剩余库存。 - 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: 购物车项目价格范围。
- currency_code
- 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: 购物车项目总计税额。
- currency_code
- key
示例
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();