# Product List

[返回目录](../README.md)

`productList` 控制产品列表页。

```json
{
  "productList": {
    "categorySelection": "single",
    "filterPanelVariant": "boxed",
    "gridColumns": 3,
    "loadMorePrefixSvg": "<svg>...</svg>",
    "loadMoreSuffixSvg": "<svg>...</svg>",
    "pageSize": 24,
    "primaryFilter": {
      "type": "attribute",
      "code": "customized",
      "label": "Customized"
    },
    "showHeader": true,
    "showFooter": true,
    "showListTitle": false,
    "showPrimaryFilter": false,
    "title": "PRODUCTS"
  },
  "productCard": {
    "imageHoverScale": 1.06,
    "nameAlign": "center",
    "showCode": false
  }
}
```

## categoryselection

分类选择模式：

| 值 | 说明 |
| --- | --- |
| `"single"` | 单选分类 |
| `"multiple"` | 多选分类 |

## filterpanelvariant

筛选栏视觉变体。默认不配置，即使用 SDK 原始轻量样式。

| 值 | 说明 |
| --- | --- |
| `"default"` | 默认样式 |
| `"boxed"` | 带外框、加减号展开和 checkbox 选项的样式 |

## primaryfilter

左侧主筛选维度。默认不配置时等同于 `{ "type": "category" }`，SDK 会请求 `/tree` 并渲染分类树。

常见选择：

| 场景 | 配置 |
| --- | --- |
| 按后端分类树筛选 | 不配置，或配置 `{ "type": "category" }` |
| 按某个属性作为一级导航 | 配置 `{ "type": "attribute", "code": "customized" }` |
| Header 下拉也跟随该属性 | 配置属性主筛选后，Header 会优先使用 `/filter-options` 中该字段的 options |

当配置为属性主筛选时，SDK 使用 `/filter-options` 返回的对应字段选项渲染扁平筛选，不请求 `/tree`：

```json
{
  "productList": {
    "primaryFilter": {
      "type": "attribute",
      "code": "customized",
      "label": "Customized"
    }
  }
}
```

选中值会进入搜索请求：

```json
{
  "filters": [
    { "attribute_code": "customized", "operator": "in", "value": ["..."] }
  ]
}
```

同时，Header 中 `PRODUCTS` 的下拉项会优先使用该主筛选字段在 `/filter-options` 返回的枚举；如果枚举尚未加载，则短暂回退到 `navItems.children`。

如果 Header 下拉需要固定文案或兜底链接，可以同时配置 `navItems.children`；当接口枚举加载成功后，SDK 会用真实筛选值生成下拉项。

## showprimaryfilter

是否在左侧筛选栏展示主筛选区域。默认 `true`。

```json
{
  "productList": {
    "showPrimaryFilter": false
  }
}
```

隐藏后，左侧只显示普通 `filterFields`；当前主筛选值仍会显示在 breadcrumb。

## showlisttitle

是否显示列表标题和总数，例如 `2-IN-1 Pump Bottle / 9 items`。默认 `true`。

```json
{
  "productList": {
    "showListTitle": false
  }
}
```

## gridcolumns

产品卡片网格列数。默认 `4` 列。

```json
{
  "productList": {
    "gridColumns": 3
  }
}
```

适合需要放大产品图片的站点。例如 `3` 列会让同样宽度下的产品卡片和图片更大。

窄屏下 SDK 会自动降为 `2` 列，避免移动端卡片过窄。

## has3d

全局限制列表是否只查询有 3D 项目的产品。

```json
{
  "productList": {
    "has3d": true
  }
}
```

如果需要让用户在筛选栏里选择是否有 3D 预览，使用 [scope: has_3d](../filters/README.md#scope-has_3d)，不要固定写 `productList.has3d`。

## pagesize

每页产品数量，同时影响搜索请求 `limit`。

```json
{
  "productList": {
    "pageSize": 24
  }
}
```

图片较大的官网列表通常使用 `12`、`18` 或 `24`。如果首屏加载慢，优先降低 `pageSize`，再考虑图片资源优化。

## searchplacement

产品关键词搜索框展示位置。

| 值 | 说明 |
| --- | --- |
| `"list"` | 只显示在产品列表内容区，默认值。 |
| `"header"` | 显示在站点 Header。 |
| `"both"` | Header 和列表内容区都显示。 |
| `"none"` | 不显示搜索框。 |

```json
{
  "productList": {
    "searchPlacement": "header"
  }
}
```

## showheader

是否显示 SDK 内置 Header。

## showfooter

是否显示 SDK 内置 Footer。

## title

未选中分类时的列表标题。

如果 `showListTitle` 为 `false`，该标题不会显示在列表内容区，但仍可作为内部默认标题使用。

## loadmoreprefixsvg / loadmoresuffixsvg

`View More` 按钮前置 / 后置 SVG。SVG 字符串按可信 `siteConfig` 渲染，适合站点配置固定图标。

```json
{
  "productList": {
    "loadMorePrefixSvg": "<svg viewBox=\"0 0 24 24\">...</svg>",
    "loadMoreSuffixSvg": "<svg viewBox=\"0 0 24 24\">...</svg>"
  }
}
```

## productcard

`productCard` 是产品卡片的共享配置，产品列表和详情推荐区都会使用。

| 参数 | 说明 |
| --- | --- |
| `nameAlign` | 产品名称对齐方式：`"left"`、`"center"`、`"right"`，默认 `"left"`。 |
| `imageHoverScale` | 鼠标移入时图片放大比例，默认 `1.06`。 |
| `showCarousel` | 是否显示产品卡片缩略图轮播，默认 `false`。开启后使用接口返回的 `assets` 中 `asset_type: "carousel"` 的图片。 |
| `showCode` | 是否显示产品编码 / ID，默认 `true`。 |

常见配置：

```json
{
  "productCard": {
    "nameAlign": "center",
    "showCarousel": true,
    "showCode": false
  }
}
```

如果只想隐藏详情页标题区域的编码，使用 `productDetail.showProductCode`；如果列表卡片和推荐卡片都不显示编码，使用 `productCard.showCode: false`。

## 分类标题文案

分类筛选区标题使用静态文案 key：`list.categoryTitle`，默认中文为“分类”，英文为 `Category`。可以通过 `messages` 覆盖：

```json
{
  "messages": {
    "list.categoryTitle": "CATEGORY",
    "list.allCategory": "ALL"
  }
}
```