> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aftersell.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Upsells 块

> Aftersell Cart 的 Upsells 块——在抽屉中展示由策略挑选的产品优惠。

> **Upsells** 块在 cart drawer 中展示产品优惠，由你选择的\*\*策略（Strategy）\*\*来挑选。当购物者打开购物车时，该块会根据当前购物车内容和你配置的任何定向规则，呈现你的策略返回的产品。<br /><br />在购物者打开购物车的那一刻呈现相关的产品优惠，利用根据购物车内容和定向规则挑选展示内容的策略，提升平均订单价值。

<Info>
  与始终展示你挑选的某一个产品的 [**Product add-on**](/zh/aftersell/cart/product-add-on-block) 块不同，Upsells 由一个决定展示内容的策略驱动。
</Info>

<Frame>
  <img src="https://mintcdn.com/aftersell/1Y3gBpUfxv16VGSW/images/aftersell/cart-upsells-block-strategy-picked-product-recommendations.png?fit=max&auto=format&n=1Y3gBpUfxv16VGSW&q=85&s=5ce00c7f12e1ddf32a0533eb700d22ee" alt="Upsells 块在 cart drawer 中展示由策略挑选的产品推荐" width="1228" height="510" data-path="images/aftersell/cart-upsells-block-strategy-picked-product-recommendations.png" />
</Frame>

<div id="behavior">
  ## 行为
</div>

* 产品根据购物者当前的购物车实时获取，因此优惠反映的是购物车中的实际内容。
* **当没有产品可展示时整个区域会隐藏**——没有关联策略、策略没有返回结果，或返回的产品都不可购买。购物者绝不会看到空的 Upsells 区域。
* 如果返回的优惠带有折扣，购物者会看到真实的划线价和折扣徽章，折扣会在结账时应用。

<div id="settings">
  ## 设置
</div>

| 设置                        | 控制的内容                                                              | 默认值                   |
| ------------------------- | ------------------------------------------------------------------ | --------------------- |
| **Title**                 | 优惠上方的富文本标题。支持加粗、斜体、对齐和颜色。                                          | `You may also like`   |
| **Add button text**       | 每个产品添加按钮上的文案。                                                      | `Add`                 |
| **Strategy**              | 决定展示哪些产品的策略。                                                       | 自动为你分配的 Shopify AI 策略 |
| **Layout**                | **Carousel** 或 **List**。                                           | Carousel              |
| **Maximum products**      | 最多展示多少个产品。接受 `1`–`12`。                                             | `4`                   |
| **Show compare-at price** | 是否显示划线的原价。                                                         | 开启                    |
| **Show product reviews**  | 是否在每个 upsell 卡片上显示星级评分和评论数。评分来自你的评论应用的产品 metafields，仅在存在有效评论数据时显示。 | 关闭                    |

<div id="supported-review-apps">
  ### 支持的评论应用
</div>

支持以下基于 metafield 的评论应用：Shopify Product Reviews、Junip、Okendo、Growave、Fera、Stamped、Loox、REVIEWS.io、Automizely Reviews、Judge.me、Ali Reviews、Trustoo、Rivo、Rivyo 和 Vitals。不支持 Yotpo，因为它使用单独的 API 而非产品 metafields。

<div id="design">
  ## 设计
</div>

Upsells 块在其 **Design** 面板中有块级设计覆盖设置。它们仅针对此块覆盖购物车的全局设计设置。留空则继承全局设置。

<div id="text-styling">
  ### 文字样式
</div>

Upsells 块的设计设置中包含 **Text**（文字）部分。使用它来控制每个 upsell 卡片上各个文字元素的排版。从选择器中选择一个文字元素以调整其设置：

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

可设置样式的文字元素按类别分组：

**Heading（标题）**

* **Heading**（标题）— upsell 卡片上方的部分标题（例如 *You may also like*）。也支持自定义字体族。粗体和颜色在上方的富文本编辑器中设置。

**Product（产品）**

* **Product title**（产品标题）— 每个 upsell 卡片上的产品名称。
* **Review count**（评论数）— 启用 **Show product reviews** 时显示的评论数。

**Pricing（价格）**

* **Price**（价格）— 每张卡片上的当前价格。
* **Compare-at price**（划线价）— 划线的原价。
* **Discount**（折扣） — 折扣标签（例如 *20% off*）。

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

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

<div id="tile-colors">
  ### 卡片颜色
</div>

| 设置                        | 控制的内容                | 默认值       |
| ------------------------- | -------------------- | --------- |
| **Tile background color** | 每个 upsell 产品卡片的背景填充。 | 透明        |
| **Tile border color**     | 每个 upsell 产品卡片的边框颜色。 | `#F6F6F7` |

<div id="reviews">
  ### 评论
</div>

启用 **Show product reviews** 后，你可以在 Design 面板的 **Reviews** 部分自定义星星颜色。

| 设置                   | 控制的内容       | 默认值       |
| -------------------- | ----------- | --------- |
| **Star color**       | 每颗星星的填充部分。  | `#FDCC0D` |
| **Empty star color** | 每颗星星的未填充部分。 | `#D1D5DB` |

<div id="placement-and-limits">
  ## 位置与限制
</div>

* \*\*区域：\*\*body 或 bottom。
* \*\*最大数量：\*\*每个购物车状态 1 个——非空购物车和空购物车各有一个。
* \*\*状态：\*\*非空和空购物车均可。
* 默认不添加。未锁定——你可以移除或隐藏它。

<div id="selecting-a-strategy">
  ## 选择策略
</div>

Upsells 块不会以空白状态出现：如果没有设置策略，Aftersell 会解析你商店的 Shopify AI 策略——如果还没有则会创建一个——并自动填入，因此该块开箱即用。打开 **Strategy** 选择器可以更换。选择器分两组：

**Quick start**

* **Create strategy from selected products**——直接挑选特定产品，系统会自动为你创建一个策略。
* **Create strategy from scratch**——打开策略编辑器，让你无需离开购物车编辑器即可构建规则。

**Strategies**

* **Shopify AI recommendations**——创建一个由 Shopify 自身推荐驱动的策略，之后出现在任何地方都命名为 **Shopify AI recommended products**。一旦你拥有一个，此条目就会消失，因为一家商店只需要一个 Shopify AI 策略。
* 你现有的策略，按名称列出。在搜索框中输入即可筛选。

选定策略后，其名称会出现在块内的策略行上。

<div id="managing-a-selected-strategy">
  ## 管理已选策略
</div>

关联策略后，策略行上会出现一个 **•••**（省略号）按钮。点击它打开操作菜单：

* **Edit strategy**——在新标签页中打开策略编辑器，因此你的购物车编辑器会话和任何未保存的更改都会保持原样。此选项对 Shopify AI 推荐策略不可用，该策略由系统自动管理，没有可编辑的规则。
* **Remove from upsell**——将策略从此块上解绑。策略本身不会被删除；它仍保留在你的策略列表中。

在新标签页中编辑策略不会影响购物车编辑器会话——你可以回到购物车编辑器标签页继续配置，不会丢失工作。

<div id="custom-template">
  ## 自定义模板
</div>

支持在其 Code 选项卡中使用[自定义模板](/zh/aftersell/cart/custom-templates)，用你的 JSX 替换此块的内置标记。以下是它接收的 props。

<div id="block-content">
  ### 块内容
</div>

| Prop            | 类型                     | 用途                                     |
| --------------- | ---------------------- | -------------------------------------- |
| `title`         | `string`               | 区域标题。                                  |
| `addButtonText` | `string`               | 加购按钮文案。                                |
| `layout`        | `'carousel' \| 'list'` | 横向滚动或换行排列。据此分支你的标记。                    |
| `upsells`       | `UpsellCard[]`         | 可直接展示的产品。参见下方[卡片结构](#the-upsell-card)。 |
| `isLoading`     | `boolean`              | upsell 产品仍在获取中时为 `true`。               |

<div id="adding-to-cart">
  ### 加入购物车
</div>

| Prop              | 类型                                               | 用途                               |
| ----------------- | ------------------------------------------------ | -------------------------------- |
| `selectVariant`   | `(productId: string, variantId: number) => void` | 为某个产品选择变体。                       |
| `handleAdd`       | `(productId: string) => void`                    | 将该产品选中的变体加入购物车。                  |
| `addingProductId` | `string \| null`                                 | 正在添加的产品，让你可以只禁用它的按钮。空闲时为 `null`。 |

<div id="carousel-controls">
  ### 轮播控件
</div>

仅在 `layout` 为 `'carousel'` 时相关。

| Prop           | 类型                                    | 用途                                          |
| -------------- | ------------------------------------- | ------------------------------------------- |
| `trackRef`     | `{ current: HTMLDivElement \| null }` | 用 `ref={props.trackRef}` 绑定到你的滚动容器，箭头才能滚动它。 |
| `atStart`      | `boolean`                             | 滚动轨道在起始边缘时为 `true`。禁用左箭头。                   |
| `atEnd`        | `boolean`                             | 滚动轨道在末尾边缘时为 `true`。禁用右箭头。                   |
| `scrollByCard` | `(direction: 1 \| -1) => void`        | 将轨道向左（`-1`）或向右（`1`）滚动一张卡片。                  |

<div id="the-upsell-card">
  ### upsell 卡片
</div>

`upsells` 中的每个条目：

| 字段                        | 类型                        | 用途                                                                                                                                                                          |
| ------------------------- | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `productId`               | `string`                  | 产品 GID。用作 React key 和加购目标。                                                                                                                                                  |
| `title`                   | `string`                  | 产品标题。                                                                                                                                                                       |
| `description`             | `string`                  | 纯文本描述。产品没有描述时为 `''`。                                                                                                                                                        |
| `url`                     | `string \| null`          | 产品页面 URL。不可用时为 `null`。                                                                                                                                                      |
| `imageUrl`                | `string \| null`          | 主图。产品没有时为 `null`。                                                                                                                                                           |
| `selectedVariantImageUrl` | `string \| null`          | 选中变体自己的图片。变体没有时为 `null`——回退到 `imageUrl`。                                                                                                                                    |
| `variantTitle`            | `string \| null`          | 选中变体的选项值（例如 `Medium / Blue`），已解析。变体没有真实标题时为 `null`——空白或 Shopify 的 `Default Title` 占位符。只有一个命名变体的产品仍会返回该名称，因此请用 `{upsell.variantTitle && …}` 来判断，而不要基于 `hasMultipleVariants`。 |
| `priceLabel`              | `string`                  | 要显示的价格，已格式化。有折扣时为促销价，否则为变体价格。                                                                                                                                               |
| `compareAtLabel`          | `string \| null`          | 划线的原价，已格式化。没有可划线的价格时为 `null`。                                                                                                                                               |
| `discountLabel`           | `string \| null`          | 行内折扣标签，如 `(20% off)`。无折扣时为 `null`。                                                                                                                                          |
| `review`                  | `object \| null`          | `{ rating, count, stars }`，其中 `stars` 是 5 个预渲染的图片 URL，已包含小数填充。将每个渲染为图片元素。评论关闭或产品没有评论时为 `null`。                                                                              |
| `options`                 | `Array<{ name, values }>` | 选项组，用于构建选择器或色板。                                                                                                                                                             |
| `variants`                | `array`                   | 变体组合。见下文。                                                                                                                                                                   |
| `selectedVariantId`       | `number`                  | 当前选中的变体。将其传给 `selectVariant`。                                                                                                                                               |
| `hasMultipleVariants`     | `boolean`                 | 是否需要渲染变体选择器。                                                                                                                                                                |
| `vendor`                  | `string`                  | 产品的供应商。                                                                                                                                                                     |
| `selectedVariantImageUrl` | `string \| null`          | 选中变体自己的图片。没有时为 `null`——回退到 `imageUrl`。                                                                                                                                      |

`variants` 中的每个条目包含 `id`、`title`、`price` 和 `compareAtPrice`（原始、未格式化，以货币主单位表示的字符串）、`availableForSale`、`imageUrl`、`sku` 和 `selectedOptions`（`[{ name, value }]`）。

<Warning>
  **可购买性是按组合而非按选项判断的。**`options` 给你要渲染的选项组，但某个选择是否可购买取决于 `variants` 中匹配的条目。请将购物者选择的组合与 `variants` 对应起来，并根据该条目的 `availableForSale` 做限制，而不要假设 `options` 中的每个值都可下单。
</Warning>

<Note>
  `priceLabel` 和 `compareAtLabel` 已格式化好可直接展示，而 `variants[].price` 和 `variants[].compareAtPrice` 是以货币主单位表示的原始字符串。不要混用两者：展示时用标签，原始值只用于比较。
</Note>

<div id="design-2">
  ## 设计
</div>

通过设置面板中的 **Design** 部分为此块设置样式。这些是块级覆盖设置，会叠加在你的全局设计之上，留空时回退到全局设计。

什么是设计设置？在这里了解更多：[设计设置](/zh/aftersell/cart/design-settings)。