操作 - Aftersell & Upcart Docs

操作用于读取和更改购物车。它们位于 window.aftersell.cart.actions 下。

操作要在购物车就绪后运行，即在 ready() 或事件处理函数内部。

window.aftersell.cart.ready().then(() => {
  const state = window.aftersell.cart.actions.getCart();
  console.log(state.itemCount, 'items');
});

**在购物车加载之前，操作是桩函数。**每个操作会在控制台输出一条指明操作名称的警告，例如 cart.actions.addItem() called before the cart loaded，然后不做任何事。异步操作仍会 resolve 一个 Promise，所以 .then() 链会正常运行而不是抛出错误；getCart() 返回 null，formatMoney() 返回空字符串。过早调用不会破坏任何东西，但也不会发生任何事。当某个操作看似没有效果时，请留意控制台中的这条警告。

所有操作

操作	签名	返回值	作用
`open`	`open()`	无	打开抽屉。
`close`	`close()`	无	关闭抽屉。
`getCart`	`getCart()`	`AftersellCart \| null`	读取当前购物车。
`formatMoney`	`formatMoney(cents)`	`string`	格式化金额用于显示。
`addItem`	`addItem(variantId, quantity?)`	`Promise`	添加一个变体。
`removeItem`	`removeItem(key)`	`Promise`	移除一行。
`updateItemQuantity`	`updateItemQuantity(key, quantity)`	`Promise`	设置某行的数量。
`replaceLineVariant`	`replaceLineVariant(key, variantId)`	`Promise`	更换某行的变体。
`refresh`	`refresh()`	`Promise`	从 Shopify 重新获取购物车。
`visualRefresh`	`visualRefresh()`	无	重绘但不重新获取。

从 cart_updated 处理函数中调用操作可能导致循环。请先阅读两条规则。

抽屉

open 和 close

打开或关闭购物车抽屉。两者都是同步的，不接受参数。

// Open the drawer from your own cart link.
document.querySelector('#my-cart-link').addEventListener('click', (event) => {
  event.preventDefault();
  window.aftersell.cart.actions.open();
});

// Close it after the shopper does something in a custom block.
window.aftersell.cart.actions.close();

读取

getCart()

返回当前的购物车对象，在加载完成之前返回 null。结果是一个副本，所以修改它不会更改真实的购物车。

window.aftersell.cart.ready().then(() => {
  const state = window.aftersell.cart.actions.getCart();
  if (!state) return; // the initial load failed

  console.log(state.itemCount, 'items,', state.items.length, 'lines');
  console.log('Total:', window.aftersell.cart.actions.formatMoney(state.totalPrice));
});

由于它是快照，不要长期持有结果；每次需要最新数据时重新读取。在事件处理函数中，你已经通过载荷拿到了最新的购物车，所以在那里调用 getCart() 是多余的。

formatMoney(cents)

使用商店的货币格式对以最小货币单位表示的金额进行格式化。SDK 中的所有价格都以分为单位，这就是把它们转成可显示内容的方式。

window.aftersell.cart.actions.formatMoney(5779);  // "$57.79"
window.aftersell.cart.actions.formatMoney(0);     // "$0.00"

// Show the cart total in your own header element.
window.aftersell.cart.events.on('cart_updated', (state) => {
  document.querySelector('#header-total').textContent =
    window.aftersell.cart.actions.formatMoney(state.totalPrice);
});

用 configure({ money_format }) 覆盖格式。

更改购物车

商品操作通过 Shopify 的 key 而不是变体 ID 来标识行，因为购物车可以在多个带有不同属性的行中持有同一个变体。从 getCart().items[n].key 读取它。

addItem(variantId, quantity?)

向购物车添加一个变体。quantity 默认为 1。在购物车稳定后 resolve。

// Add one, then show the shopper.
window.aftersell.cart.actions.addItem(41720671830082).then(() => {
  window.aftersell.cart.actions.open();
});

// Add a specific quantity.
window.aftersell.cart.actions.addItem(41720671830082, 3);

添加已在购物车中的变体会增加该行的数量而不是创建第二行，前提是现有行没有行项目属性。带有属性的行是独立的行，所以你会得到新的一行。

removeItem(key)

完全移除一行。

// Remove any free line from the cart.
const gift = window.aftersell.cart.actions
  .getCart()
  .items.find((line) => line.finalLinePrice === 0);
if (gift) window.aftersell.cart.actions.removeItem(gift.key);

updateItemQuantity(key, quantity)

设置某行的数量。传入 0 会移除该行。

const line = window.aftersell.cart.actions.getCart().items[0];
if (line) window.aftersell.cart.actions.updateItemQuantity(line.key, 3);

// Cap a line at one unit.
window.aftersell.cart.events.on('cart_updated', (state) => {
  state.items.forEach((line) => {
    if (line.variantId === LIMITED_VARIANT_ID && line.quantity > 1) {
      window.aftersell.cart.actions.updateItemQuantity(line.key, 1);
    }
  });
});

第二个示例可以安全地从 cart_updated 中运行，因为 > 1 检查在第二次执行时为 false。参阅两条规则。

replaceLineVariant(key, variantId)

更换某行的变体，同时保留其数量和属性。适用于购物车内的尺码或口味切换器。

const line = window.aftersell.cart.actions.getCart().items[0];
window.aftersell.cart.actions.replaceLineVariant(line.key, 41720671862850);

更换时该行的销售计划会重置。订阅行会变成一次性购买，除非你重新应用计划。

更换是一次添加后跟一次移除，而不是原地编辑，所以结果是新的一行：它获得新的 key 并落在购物车末尾。之后请重新读取 getCart()，而不要重用你传入的 key。

刷新

refresh()

从 Shopify 重新获取购物车。当 SDK 之外的东西更改了购物车而抽屉没有察觉时使用它。

// After a raw Ajax API call of your own.
fetch('/cart/add.js', { method: 'POST', /* … */ })
  .then(() => window.aftersell.cart.actions.refresh())
  .then(() => { window.aftersell.cart.actions.open(); });

大多数时候你不需要它，因为 Aftersell 已经监听 Shopify 的标准购物车事件并自行重新获取。当自定义集成绕过了这些事件时才需要它。

visualRefresh()

重新运行渲染转换，但不从 Shopify 重新获取购物车。你很少需要它：注册（或注销）行转换、比较器、增强器或任一订阅 hook 都会自动触发一次。只有两个加入购物车 hook 不会，因为它们不改变屏幕上已有的任何内容。当转换所依赖的内容发生变化而购物车本身没变时使用它：

// A currency switcher changed the format: repaint prices already on screen.
window.myTheme.onCurrencyChange((currency) => {
  window.aftersell.cart.configure({ money_format: FORMATS[currency] });
  window.aftersell.cart.actions.visualRefresh();
});

注意事项和边界情况

**异步操作在变更稳定后 resolve。**等待一个操作可以让你在购物车确实更新后再安排后续工作。
**getCart() 返回副本。**修改它对真实购物车没有任何影响。
**没有折扣码操作。**已应用的折扣码可以在购物车上读取（discountCodes、totalDiscount）以及按行读取（discountAllocations）；购物者通过折扣码区块应用它们。
**没有购物车属性或备注操作。**属性可以在购物车对象上读取；购物者通过备注区块编写备注。
要隐藏一行而不是移除它，请使用 registerLineTransform。移除会改变购物者的总额；隐藏不会。

后续阅读

购物车对象：getCart() 返回的内容。
事件：何时运行这些操作。
Hooks：改变行的渲染方式而不是更改购物车。
使用案例：常见需求的完整解决方案。

开始使用

主页

最佳实践

购后追加销售

购物车

结账追加销售（Shopify Plus）

感谢页面

产品页面追加销售

Rokt Thanks

策略

分析与跟踪

集成

Aftersell MCP

计费与账户

故障排除

操作

所有操作

抽屉

open 和 close

读取

getCart()

formatMoney(cents)

更改购物车

addItem(variantId, quantity?)

removeItem(key)

updateItemQuantity(key, quantity)

replaceLineVariant(key, variantId)

刷新

refresh()

visualRefresh()

注意事项和边界情况

后续阅读

​所有操作

​抽屉

​open 和 close

​读取

​getCart()

​formatMoney(cents)

​更改购物车

​addItem(variantId, quantity?)

​removeItem(key)

​updateItemQuantity(key, quantity)

​replaceLineVariant(key, variantId)

​刷新

​refresh()

​visualRefresh()

​注意事项和边界情况

​后续阅读

所有操作

抽屉

open 和 close

读取

getCart()

formatMoney(cents)

更改购物车

addItem(variantId, quantity?)

removeItem(key)

updateItemQuantity(key, quantity)

replaceLineVariant(key, variantId)

刷新

refresh()

visualRefresh()

注意事项和边界情况

后续阅读