164 lines
6.7 KiB
Markdown
164 lines
6.7 KiB
Markdown
# 首页
|
||
|
||
首页是访客进入站点后看到的第一个内容页面（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) — 首页模板与结构说明
|