Cart items 区块

Cart items 区块是购物车中的商品行列表，渲染顾客添加的每个产品，包括其图片、标题、变体、价格、数量步进器和移除控件。它是必需的区块，也是承载购物车子区块（Product 行、Subscription upgrade 和 Custom code）的容器，为按行显示的子区块提供了挂载结构。

Cart items 区块，显示带产品图片、标题、变体、价格、数量步进器和移除控件的商品行

Product 行

Cart items 内部有一个 Product 子区块：即实际的商品行。它是锁定的并自动添加，因此每个 Cart items 区块始终恰好有一个无法移除的 Product 行；你可以围绕它重新排列其他子区块。它的设置控制每行价格的显示方式：

设置	控制内容	默认值
Strike-through price（划线价）	显示哪个价格为划线价：Compare-at 或折扣前价格中较高者、Compare-at 价格、折扣前价格或不显示划线价。	Compare-at 或折扣前价格中较高者
Strike-through price for subscriptions（订阅商品的划线价）	订阅商品行的同类选项，有两点不同：多了一个 Subscription compare-at price（订阅划线价）选项，且 Compare-at price 更名为 Product compare-at, then subscription compare-at。	Compare-at 或折扣前价格中较高者
Savings label（节省标签）	节省金额显示为金额、百分比还是隐藏。	金额
Bundle price（捆绑价格）	捆绑商品行显示价格的计算方式。Automatic（自动）显示捆绑中所有商品的总价（当其他商品免费时显示主商品价格）。Main item price only（仅主商品价格）只显示主（锚点）商品的价格。这仅是显示标签——Shopify 的购物车总额始终是权威数据。	自动
Savings text（节省文字）	节省标签文字。支持 `{{value}}` 令牌。	`Save {{value}}`

该行本身渲染产品图片（可用时链接到产品页面）、标题、变体、价格及任何划线的 compare-at 价格、数量步进器和移除按钮。捆绑商品行会显示其组成部分的展开列表。

文字样式

Product 行的设计设置中包含 Text（文字）部分。使用它来控制每个商品行中各个文字元素的排版。从选择器中选择一个文字元素以调整其设置：

设置	控制内容
Text color（文字颜色）	所选文字元素的颜色。
Font（字体）	Theme font（继承你主题的字体）或 Custom font（输入你的主题已加载的字体名称）。仅 Product title（产品标题）可用。
Size（字号）	以像素为单位的字号。
Weight（字重）	字重：Light、Regular、Medium、Semibold 或 Bold。
Line height（行高）	行高，以字号的倍数表示（例如 `1.4`）。
Letter spacing（字间距）	以像素为单位的字间距。负值会收紧文字。

可设置样式的文字元素按类别分组： Product（产品）

Product title（产品标题）— 每行的产品名称。也支持自定义字体族。
Variant（变体）— 变体标签（例如 Size: Medium）。
Subscription plan（订阅计划）— 显示在订阅商品行上的只读计划标签。

Pricing（价格）

Price（价格）— 该行的当前价格。
Compare-at price（划线价）— 划线的原价。
Savings（节省）— 节省标签（例如 Save $5.00）。仅支持字号和行高——粗体和颜色在上方的富文本编辑器中设置。

Bundle（捆绑）

Bundle toggle（捆绑切换）— 展开捆绑组成商品列表的展开标题。
Bundle item title（捆绑商品标题）— 捆绑内每个组成商品的标题。
Bundle item variant（捆绑商品变体）— 每个捆绑组成商品的变体标签。

任何字段留空都会保持该元素的默认值。

直接点击购物车预览中的某个文字元素会高亮它，并自动在面板中打开其控件。

折扣标签设计

Product 行的设计设置中包含 Discount tags（折扣标签）部分。使用它为每个商品行上显示的折扣标签胶囊设置样式：

设置	控制内容	默认值
Background color（背景颜色）	折扣标签胶囊的填充颜色。	`#F1F1F1`
Text color（文字颜色）	折扣标签胶囊内的文字颜色。	`#585858`
Border radius（圆角半径）	折扣标签胶囊的圆角程度。	`6px`

这些设置仅适用于 Cart items 区块中的商品行折扣标签。Summary 区块中的折扣码标签单独设置样式。

子区块及其定位方式

Cart items 是唯一承载子区块的区块。子区块在每行渲染一次，位于每个商品行内部，相对于固定的 Product 行定位：

排在 Product 行之前的子区块出现在每行商品内容的上方。
排在 Product 行之后的子区块出现在每行商品内容的下方。

因此，放置在 Product 行之后的 Subscription upgrade 会显示在每个符合条件的商品行下方，而不是在整个列表底部只显示一次。

行为

当购物车中没有商品时，抽屉会切换到空状态，此区块不显示。
购物车更改一次只执行一个。 当数量更新或移除操作正在进行时，该行的控件会被禁用以保持购物车一致性，更改完成后重新启用。
将某行数量降到 1 以下会将其移除。商店拒绝的数量（例如超出可用库存）会重新同步为最后一个有效值。
捆绑商品作为一个整体变化。 调整捆绑锚点行的数量会一次性缩放整个捆绑——如果某个子商品按每个锚点 3 件包含，将锚点从 1 调到 2 会使该子商品变为 6 件。移除锚点会同时移除捆绑的所有成员。
有些捆绑无法调整数量。 如果捆绑的任何子商品按小数比例包含（例如每个锚点 1.5 件），该捆绑的数量步进器会被锁定：+/− 按钮和数量字段都被禁用，且不接受输入的数量。该捆绑仍可移除。
订阅商品行显示其计划。 当某行有销售计划，且 Subscription upgrade 子区块被关闭或未添加时，Product 行会在变体下方显示只读的计划标签——例如 Delivers every month (save 30%)。当该子区块启用时，它会在自己的选择器中呈现计划，因此只读标签会被隐藏而不是重复显示。

位置与限制

区域： 主体。
最大数量： 每种购物车状态 1 个。
状态： 仅限有商品的购物车。
锁定且默认添加。 Cart items 无法移除或隐藏，只能重新定位。

自定义模板

支持通过其 Code 标签页使用自定义模板，用你的 JSX 替换此区块的内置标记。以下是它接收的 props。 Cart items 容器本身没有自定义模板。其内部的 Product 行有，而且它是购物车中最丰富的模板界面：你的模板每行渲染一次。

行内容

Prop	类型	用途
`title`	`string`	产品标题，纯文本。
`variantTitle`	`string \| null`	变体标签。单变体产品和原生捆绑为 `null`。
`url`	`string \| null`	产品页面 URL。当该行不应外链时为 `null`。
`imageUrl`	`string \| null`	行图片。产品无图片时为 `null`。
`quantity`	`number`	该行的当前数量。
`price`	`string`	行价格，已格式化。
`compareAtPrice`	`string \| null`	划线的”原价”，已格式化。无可划线内容时为 `null`。
`savingsHtml`	`string \| null`	经过净化的 HTML 格式节省标签。隐藏或无节省时为 `null`。
`discountTags`	`string[]`	该行折扣的名称，例如 `['Spring Sale']`。无折扣时为 `[]`。
`sellingPlanLabel`	`string \| null`	只读的订阅计划名称。当该行为一次性购买，或由 Subscription upgrade 子区块渲染计划 UI 时为 `null`。
`bundle`	`object \| null`	锚点行上的捆绑视图模型。否则为 `null`。
`productId`	`number`	Shopify 产品 ID。
`variantId`	`number`	Shopify 变体 ID。
`line`	`AftersellCartLine`	完整的购物车行，用于上述 props 未覆盖的内容。
`formatMoney`	`(cents: number) => string`	格式化以最小货币单位表示的金额。用于你从 `line` 读取的价格。

price 和 compareAtPrice 是格式化后的字符串；line 上的所有内容都以分为单位。 不要对 price 做算术运算。请基于 line.finalLinePrice 等字段计算，然后将结果传给 formatMoney。

数量与移除

Prop	类型	用途
`increment`	`() => void`	该行数量加一。
`decrement`	`() => void`	该行数量减一。
`remove`	`() => void`	完全移除该行。
`quantityInput`	`string`	受控数量 `<input>` 的当前值。为字符串，以便保留输入中间状态。
`onQuantityInput`	`(event: Event) => void`	该字段的 `onInput` 处理函数。
`commitQuantity`	`() => void`	应用输入的数量。绑定到 `onBlur`。
`onQuantityKeyDown`	`(event: KeyboardEvent) => void`	`onKeyDown` 处理函数，使按 Enter 键提交。
`busy`	`boolean`	任何购物车变更进行中时为 `true`。据此禁用你的控件。
`pending`	`'increment' \| 'decrement' \| 'remove' \| null`	当前正在执行的操作，用于显示针对性的加载动画。
`stepperLocked`	`boolean`	数量无法更改时为 `true`，原因是该行是捆绑锚点且某个子商品以小数比例包含。请隐藏或禁用步进器——设置此值时，内置处理函数已会拒绝更改。

function CustomTemplate(props) {
  return (
    <div className="cart-external-cart-items__row" style={{ display: 'flex', gap: '12px', opacity: props.busy ? 0.6 : 1 }}>
      {props.imageUrl && <img src={props.imageUrl} alt="" width={64} height={64} />}

      <div style={{ flex: 1 }}>
        {props.url ? <a href={props.url}>{props.title}</a> : <span>{props.title}</span>}
        {props.variantTitle && <div style={{ opacity: 0.6 }}>{props.variantTitle}</div>}
        {props.sellingPlanLabel && <div style={{ opacity: 0.6 }}>{props.sellingPlanLabel}</div>}

        {props.discountTags.map((tag) => (
          <span key={tag} style={{ fontSize: '11px', border: '1px solid', borderRadius: '4px', padding: '1px 5px' }}>
            {tag}
          </span>
        ))}

        {!props.stepperLocked && (
          <div style={{ display: 'flex', alignItems: 'center', gap: '6px', marginTop: '6px' }}>
            <button type="button" onClick={props.decrement} disabled={props.busy}>&minus;</button>
            <input
              value={props.quantityInput}
              onInput={props.onQuantityInput}
              onBlur={props.commitQuantity}
              onKeyDown={props.onQuantityKeyDown}
              size={2}
            />
            <button type="button" onClick={props.increment} disabled={props.busy}>+</button>
            <button type="button" onClick={props.remove} disabled={props.busy}>
              {props.pending === 'remove' ? 'Removing…' : 'Remove'}
            </button>
          </div>
        )}
      </div>

      <div style={{ textAlign: 'right' }}>
        <div>{props.price}</div>
        {props.compareAtPrice && <s style={{ opacity: 0.5 }}>{props.compareAtPrice}</s>}
        {props.savingsHtml && <div dangerouslySetInnerHTML={{ __html: props.savingsHtml }} />}
      </div>
    </div>
  );
}

渲染捆绑商品

在捆绑的锚点行上，bundle.children 保存其内容。子商品永远不会作为独立行出现，因此如果你不渲染它们，顾客将看不到捆绑中包含什么：

function CustomTemplate(props) {
  return (
    <div>
      <div>{props.title} {props.price}</div>

      {props.bundle && (
        <ul style={{ margin: '4px 0 0 12px', fontSize: '12px', opacity: 0.7 }}>
          {props.bundle.children.map((child, i) => (
            <li key={child.key ?? i}>{child.quantity} × {child.title}</li>
          ))}
        </ul>
      )}
    </div>
  );
}

对于 Shopify 原生捆绑的组成商品，子商品的 key 为 null，因此请如上所示回退到索引。

设计

通过设置面板中的 Design（设计）部分为此区块设置样式。这些是按区块的覆盖设置，叠加在你的全局设计之上，留空时回退到全局设计。什么是设计设置？在此了解更多：设计设置。

开始使用

主页

最佳实践

购后追加销售

购物车

结账追加销售（Shopify Plus）

感谢页面

产品页面追加销售

Rokt Thanks

策略

分析与跟踪

集成

Aftersell MCP

计费与账户

故障排除

Product 行

文字样式

折扣标签设计

子区块及其定位方式

行为

位置与限制

自定义模板

行内容

数量与移除

渲染捆绑商品

设计

​Product 行

​文字样式

​折扣标签设计

​子区块及其定位方式

​行为

​位置与限制

​自定义模板

​行内容

​数量与移除

​渲染捆绑商品

​设计

Product 行

文字样式

折扣标签设计

子区块及其定位方式

行为

位置与限制

自定义模板

行内容

数量与移除

渲染捆绑商品

设计