# 首页模块 (Homepage Modules) 配置规范

[[toc]]

源的 `homepageModules` 字段允许开发者声明该源在首页展示的内容模块。这些模块通过 JSON
数组进行定义，支持高度自定义的布局和数据来源。

## 1. 数据结构 (Data Structure)

`homepageModules` 是一个包含多个模块定义对象的 JSON 数组。

### 模块通用字段

| 字段               | 类型       | 必须 | 说明                                         |
|:-----------------|:---------|:---|:-------------------------------------------|
| **key**          | `String` | 是  | 模块唯一标识。建议使用 `[a-z0-9_]` 字符。用于保存用户的排序/显隐设置。 |
| **type**         | `Enum`   | 是  | 模块类型。定义了渲染方式和交互逻辑。                         |
| **title**        | `String` | 是  | 模块默认标题。用户可在本地自定义覆盖。                        |
| **kindTitle**    | `String` | 否  | 用于匹配源「发现」规则中的分类标题。匹配成功后自动继承其 URL 和规则。      |
| **url**          | `String` | 否  | 显式指定数据接口 URL。优先级高于 `kindTitle`。支持变量替换。     |
| **args**         | `String` | 否  | 附加参数。在 `buttonGroup` 类型中为 JSON 数组字符串。      |
| **layoutConfig** | `Object` | 否  | 布局配置对象，用于调整列数、行数、图标等。                      |

## 2. 模块类型 (Module Types)

### 列表与轮播类

| 类型        | 描述    | 特点                    |
|:----------|:------|:----------------------|
| `banner`  | 横滑轮播图 | 适合展示高权重的精品推荐，使用大图封面   |
| `ranking` | 排行榜列表 | 垂直列表展示，带排名序号          |
| `card`    | 推荐卡片  | 横向滑动的卡片流，同时显示封面、标题及简介 |

### 网格类

| 类型             | 描述    | 特点               |
|:---------------|:------|:-----------------|
| `grid`         | 标准网格  | 最常用的展示形式，支持自定义行列 |
| `gridRanking`  | 网格排行榜 | 多行多列的排行展示，横向翻页   |
| `infiniteGrid` | 无限网格  | 垂直滚动的网格流，无限加载    |
| `waterfall`    | 错位瀑布流 | 垂直错位排列的书架流，无限加载  |

### 功能类

| 类型            | 描述    | 特点                                         |
|:--------------|:------|:-------------------------------------------|
| `buttonGroup` | 快捷按钮组 | 渲染为一组圆形/图标按钮，支持自动填充宽度与自动分列。通常用于放置常用分类或功能入口 |

## 3. 布局配置 (LayoutConfig)

通过 `layoutConfig` 对象，可以精细化控制模块的表现。

| 属性        | 类型       | 适用类型                                | 默认值 | 说明                                      |
|:----------|:---------|:------------------------------------|:----|:----------------------------------------|
| `columns` | `Int`    | `grid`, `waterfall`, `infiniteGrid` | 3   | 每行显示的列数                                 |
| `icon`    | `String` | `buttonGroup`                       | -   | 按钮组的默认统一图标 URL                          |
| `icons`   | `Object` | `buttonGroup`                       | -   | 图标映射表。例：`{"排行": "http://path/to/icon"}` |

## 4. 数据绑定逻辑 (Data Binding)

1. **自动匹配**：如果提供了 `kindTitle`，系统会遍历源 `exploreKinds()` 返回的列表。如果某个分类的
   `title` 与之完全一致，该模块将自动使用该分类的 `url`。
2. **静态指定**：如果提供了 `url`，系统将直接请求该 URL。
3. **降级逻辑**：若 `kindTitle` 未匹配且无 `url`，模块将回退至源的主 `exploreUrl`。

## 5. 完整 JSON 示例

```json
[
  {
    "key": "top_banner",
    "type": "banner",
    "title": "精品强推",
    "kindTitle": "首页推荐"
  },
  {
    "key": "quick_nav",
    "type": "buttonGroup",
    "title": "分类导航",
    "args": "[\"武侠\", \"仙侠\", \"都市\", \"历史\"]",
    "layoutConfig": {
      "icon": "https://example.com/icons/default.png",
      "icons": {
        "武侠": "https://example.com/icons/wuxia.png"
      }
    }
  },
  {
    "key": "hot_rank",
    "type": "ranking",
    "title": "热门榜单",
    "kindTitle": "排行榜",
    "layoutConfig": {
      "rows": 5
    }
  },
  {
    "key": "explore_waterfall",
    "type": "waterfall",
    "title": "发现更多",
    "kindTitle": "全部",
    "layoutConfig": {
      "columns": 2
    }
  }
]
```