update README.md

2026-05-19 17:25:43 +08:00
parent 31997e51c8
commit 5194d14fb0
57 changed files with 39100 additions and 0 deletions
@@ -0,0 +1,163 @@
+# 首页
+
+首页是访客进入站点后看到的第一个内容页面（Hero 区域下方），以文章卡片列表为核心展示形式。WarmIsland 提供了丰富的首页配置选项，涵盖卡片信息展示、摘要行数、加载方式以及各种文案自定义。
+
+## 配置项一览
+
+| 配置项 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `home_pinned_title` | 文本 | `置顶` | 置顶模块标题 |
+| `home_posts_title` | 文本 | `文章` | 文章模块标题 |
+| `home_card_show_visit` | 开关 | `true` | 文章卡片显示阅读量 |
+| `home_card_show_wordcount` | 开关 | `true` | 文章卡片显示字数 |
+| `home_card_show_category` | 开关 | `true` | 文章卡片显示分类 |
+| `home_card_show_tags` | 开关 | `true` | 文章卡片显示标签 |
+| `home_excerpt_lines` | 数字 | `3` | 文章简介显示行数 |
+| `home_post_loading` | 下拉 | `pagination` | 文章加载方式：`pagination` / `infinite_scroll` |
+| `home_label_newer` | 文本 | `较新` | 分页-较新标签 |
+| `home_label_older` | 文本 | `较旧` | 分页-较旧标签 |
+| `home_label_loading` | 文本 | `加载中...` | 无限滚动-加载中文案 |
+| `home_label_all_loaded` | 文本 | `已加载全部文章` | 无限滚动-全部加载文案 |
+| `home_label_no_posts` | 文本 | `暂无文章。` | 暂无文章文案 |
+| `home_label_post_count` | 文本 | `共 {total} 篇文章` | 文章数量文案（`{total}` 为占位符） |
+
+## 详细说明
+
+### 模块标题
+
+首页文章列表分为两个模块区域，各自拥有独立的标题：
+
+- **`home_pinned_title`** — 置顶文章区域的标题，默认为「置顶」。只有存在置顶文章时此区域才会显示。
+- **`home_posts_title`** — 普通文章区域的标题，默认为「文章」。
+
+```yaml
+# 英文站点示例
+home_pinned_title: "Pinned"
+home_posts_title: "Posts"
+```
+
+::: tip
+置顶文章需要在 Halo 后台编辑文章时手动设置置顶属性。置顶文章会显示在列表最前方的独立区域中，与普通文章区域以标题分隔。
+:::
+
+### 文章卡片信息展示
+
+通过四个开关控制文章卡片上显示的元信息：
+
+| 配置项 | 说明 |
+| --- | --- |
+| `home_card_show_visit` | 显示文章阅读量（依赖 Halo 统计功能） |
+| `home_card_show_wordcount` | 显示文章字数统计 |
+| `home_card_show_category` | 显示文章所属分类 |
+| `home_card_show_tags` | 显示文章标签列表 |
+
+::: tip
+关闭不需要的元信息可以让卡片更简洁，在移动端尤其有效。建议至少保留分类或标签中的一项，帮助访客快速了解文章主题。
+:::
+
+### 文章简介显示行数（home_excerpt_lines）
+
+控制文章卡片中摘要文本的最大显示行数。超出部分会被截断并显示省略号。
+
+- 设为 `0` 时不显示摘要
+- 设为 `2`–`3` 适合紧凑布局
+- 设为 `4`–`5` 适合需要更多预览内容的场景
+
+```yaml
+home_excerpt_lines: 3  # 默认，显示 3 行摘要
+```
+
+::: warning
+此设置使用 CSS `-webkit-line-clamp` 实现多行截断，在所有现代浏览器中均可正常工作。摘要内容来自 Halo 后台文章编辑时的「摘要」字段，如未填写则自动从正文提取。
+:::
+
+### 文章加载方式（home_post_loading）
+
+| 值 | 说明 |
+| --- | --- |
+| `pagination` | 传统分页，页面底部显示「较新/较旧」导航按钮（默认） |
+| `infinite_scroll` | 无限滚动，滚动到底部自动加载下一页文章 |
+
+#### 分页模式文案
+
+选择 `pagination` 模式时，可自定义分页按钮的文案：
+
+- **`home_label_newer`** — 指向较新文章的按钮文案，默认「较新」
+- **`home_label_older`** — 指向较旧文章的按钮文案，默认「较旧」
+
+#### 无限滚动模式文案
+
+选择 `infinite_scroll` 模式时，可自定义加载状态的文案：
+
+- **`home_label_loading`** — 正在加载时的提示文案，默认「加载中...」
+- **`home_label_all_loaded`** — 所有文章加载完毕后的提示文案，默认「已加载全部文章」
+
+```yaml
+# 英文站点示例
+home_post_loading: pagination
+home_label_newer: "Newer"
+home_label_older: "Older"
+
+# 或使用无限滚动
+home_post_loading: infinite_scroll
+home_label_loading: "Loading..."
+home_label_all_loaded: "All posts loaded"
+```
+
+### 暂无文章文案（home_label_no_posts）
+
+当站点没有任何已发布文章时，首页文章区域显示的提示文案。
+
+### 文章数量文案（home_label_post_count）
+
+显示在文章列表上方的文章总数统计文案。`{total}` 是占位符，会被替换为实际的文章数量。
+
+```yaml
+# 默认
+home_label_post_count: "共 {total} 篇文章"
+# 显示效果：共 12 篇文章
+
+# 英文示例
+home_label_post_count: "{total} posts in total"
+# 显示效果：12 posts in total
+```
+
+::: tip
+`{total}` 占位符是必须的，如果文案中不包含此占位符，文章数量将无法正确显示。
+:::
+
+## 页面布局结构
+
+首页的整体布局从上到下依次为：
+
+```
+┌─────────────────────────────┐
+│         Hero 首屏区域        │  ← 可选，参见 Hero 配置
+├─────────────────────────────┤
+│     置顶模块标题（置顶）      │  ← home_pinned_title
+│  ┌─────┐ ┌─────┐ ┌─────┐   │
+│  │置顶1 │ │置顶2 │ │置顶3 │   │  ← 置顶文章卡片
+│  └─────┘ └─────┘ └─────┘   │
+├─────────────────────────────┤
+│     文章模块标题（文章）      │  ← home_posts_title
+│  ┌─────┐ ┌─────┐ ┌─────┐   │
+│  │文章1 │ │文章2 │ │文章3 │   │  ← 普通文章卡片
+│  └─────┘ └─────┘ └─────┘   │
+│  ┌─────┐ ┌─────┐ ┌─────┐   │
+│  │文章4 │ │文章5 │ │文章6 │   │
+│  └─────┘ └─────┘ └─────┘   │
+├─────────────────────────────┤
+│     较新 ← → 较旧           │  ← 分页导航（或无限滚动）
+└─────────────────────────────┘
+```
+
+::: tip
+文章卡片在桌面端以多列网格排列，在平板和移动端自动调整为单列或双列布局，确保在各种屏幕尺寸下的阅读体验。
+:::
+
+## 相关页面
+
+- [Hero 首屏](/config/hero) — Hero 区域配置
+- [文章](/config/article) — 文章详情页配置
+- [样式设置](/config/style) — 容器宽度与动画效果配置
+- [首页页面](/pages/home) — 首页模板与结构说明