# FilterFields

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

`filterFields` 配置产品列表和侧边栏筛选。它决定页面展示哪些筛选项、选项如何显示，以及请求参数如何生成。

把业务需求转换成配置时，先判断筛选值应该发到哪里：

| 需求 | 推荐配置 |
| --- | --- |
| 按产品属性筛选，如容量、材质、形状 | `scope` 不填或填 `"attribute"`，`target` 使用接口属性 code |
| 按推荐类型筛选，如 Best Sellers / New In | `scope: "recommend_type"` |
| 按是否有 3D 模型筛选 | `scope: "has_3d"` |
| 固定几个前端选项，不依赖后端枚举 | 配置 `options` |
| 只在后端有选项时展示 | 配置 `hideWhenNoOptions: true` |

```json
{
  "filterFields": [
    {
      "source": "has_3d",
      "scope": "has_3d",
      "label": "3D PREVIEW",
      "component": "select",
      "options": [
        { "label": "With 3D Preview", "value": "true" },
        { "label": "Without 3D Preview", "value": "false" }
      ]
    },
    {
      "source": "capacity",
      "target": "capacity",
      "label": "CAPACITY",
      "component": "range",
      "hideUnit": true
    }
  ]
}
```

## source

筛选字段的唯一 key。比如 `capacity`、`has_3d`。

## target

接口属性 code。默认通过 `attributeMappings[source]` 解析；仍无映射则使用 `source`。

`scope: "has_3d"` 和 `scope: "recommend_type"` 通常不需要 `target`。

## label

筛选项标题。

## scope

决定请求发送位置。

| 值 | 请求位置 | 适用场景 |
| --- | --- | --- |
| `"attribute"` | `filters` | 接口属性筛选，默认值 |
| `"recommend_type"` | `recommend_types` | 推荐类型，如 Best Sellers / New In |
| `"has_3d"` | 顶层 `has_3d` | 是否有 3D 预览 |

## scope-has_3d

用于是否有 3D 预览。推荐搭配 `component: "select"`，保持单选。

```json
{
  "source": "has_3d",
  "scope": "has_3d",
  "label": "3D PREVIEW",
  "component": "select",
  "options": [
    { "label": "With 3D Preview", "value": "true" },
    { "label": "Without 3D Preview", "value": "false" }
  ]
}
```

选中后请求体：

```json
{
  "has_3d": true
}
```

不会进入 `filters`，也不需要配置 `enumWhitelist.attributeValues.has_3d`。

## component

| 值 | 说明 |
| --- | --- |
| `"select"` | 单选，再点已选项可取消 |
| `"multi_select"` | 多选 |
| `"range"` | 数值区间 |
| `"boolean"` | 布尔字段 |

## operator

不填时按 `component` 推断。

| component | 默认 operator |
| --- | --- |
| `range` | `between` |
| `multi_select` | `in` |
| 其他 | `eq` |

## options

静态选项。不依赖 `/filter-options`。

适合前端固定选项，例如推荐类型、是否有 3D、或业务上固定的排除项：

```json
{
  "source": "collections",
  "scope": "recommend_type",
  "label": "Collections",
  "component": "multi_select",
  "options": [
    { "label": "Best Sellers", "value": "hot_sale" },
    { "label": "New In", "value": "new_arrival" }
  ]
}
```

如果不配置 `options`，SDK 会尝试从 `/filter-options` 找到 `target` 对应字段，并使用接口返回的 options。

## hideunit

数值筛选是否隐藏单位。用于容量筛选时隐藏 `ml/g`：

```json
{
  "source": "capacity",
  "target": "capacity",
  "component": "range",
  "hideUnit": true
}
```

## hidewhennooptions

当后端没有返回该字段 options 时隐藏筛选项，也不会发送该字段。

## sort

排序权重，越小越靠前。

## filterdisplay

顶层字段，控制筛选项展示策略：

| 值 | 说明 |
| --- | --- |
| `"configured"` | 只展示 `filterFields` 配置的筛选项 |
| `"all"` | 展示 `/filter-options` 返回的全部可筛选属性，并用 `filterFields` 覆盖配置 |

## filterpresets

数值筛选固定区间 chips。key 使用接口属性 code。

```json
{
  "filterPresets": {
    "capacity": [
      { "label": "5-14ML", "min": 5, "max": 14 },
      { "label": "51ML+", "min": 51 }
    ]
  }
}
```

## 示例：属性筛选

```json
{
  "filterFields": [
    {
      "source": "capacity",
      "target": "capacity",
      "label": "CAPACITY",
      "component": "range",
      "hideUnit": true
    },
    {
      "source": "material",
      "target": "material",
      "label": "MATERIAL",
      "component": "multi_select",
      "hideWhenNoOptions": true
    }
  ]
}
```

生成的属性筛选会进入搜索请求的 `filters`。

## 示例：推荐类型筛选

```json
{
  "filterFields": [
    {
      "source": "collections",
      "scope": "recommend_type",
      "label": "Collections",
      "component": "multi_select",
      "options": [
        { "label": "Best Sellers", "value": "hot_sale" },
        { "label": "New In", "value": "new_arrival" }
      ]
    }
  ]
}
```

选中值会进入搜索请求的 `recommend_types`，不会进入属性 `filters`。