# 图库

图库是 WarmIsland 主题支持的照片展示模块，提供多种布局样式和分组功能，适合摄影师、设计师或任何需要展示图片集合的用户。

## 配置项一览

| 配置项 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `photos_page_title` | 文本 | `图库` | 页面标题 |
| `photos_style` | 下拉 | `masonry` | 展示样式：`masonry` / `grid` / `carousel` |
| `photos_columns` | 数字 | `3` | 列数 |
| `photos_show_ungrouped` | 开关 | `false` | 显示未分组图片 |
| `photos_show_group_title` | 开关 | `true` | 显示分组标题 |

## 前置依赖

::: danger
图库功能依赖 Halo 的 **PluginPhotos** 插件。如果未安装此插件，图库页面将无法正常工作。

安装方式：Halo 后台 → **插件** → **安装** → 搜索「Photos」→ 安装并启用。
:::

## 详细说明

### 页面标题（photos_page_title）

图库页面的标题，显示在页面顶部。

```yaml
photos_page_title: "图库"       # 默认
photos_page_title: "相册"       # 替代方案
photos_page_title: "Gallery"    # 英文站点
```

### 展示样式（photos_style）

| 值 | 说明 |
| --- | --- |
| `masonry` | 瀑布流样式，图片按原始比例错落排列，充分利用空间（默认） |
| `grid` | 网格样式，图片统一裁剪为正方形或固定比例，整齐划一 |
| `carousel` | 轮播样式，图片以轮播方式逐张展示，适合精选照片 |

::: tip
`masonry` 样式适合图片尺寸差异较大的场景（如混合横竖版照片）；`grid` 样式适合图片尺寸统一的场景（如统一裁剪的摄影作品）；`carousel` 样式适合精选少量优质照片展示。
:::

### 列数（photos_columns）

控制网格和瀑布流布局中的图片列数。默认为 3 列。

- 桌面端按设定列数显示
- 平板端自动缩减列数
- 移动端固定为 1–2 列

```yaml
photos_columns: 3  # 默认，3 列
photos_columns: 4  # 更紧凑的布局
photos_columns: 2  # 更宽松的布局
```

::: tip
列数选择建议：2 列适合大图展示，3 列是通用平衡选择，4 列及以上适合缩略图式浏览。
:::

### 显示未分组图片（photos_show_ungrouped）

开启后，「全部」视图中会显示未分配到任何分组的图片。未分组图片区域的标题为「全部」。

关闭时，未分组的图片仅在「全部」视图中以合并方式展示，不单独标注分组。

### 显示分组标题（photos_show_group_title）

控制「全部」视图中是否显示各分组的标题。

- **开启**（默认）— 每个分组的图片前会显示分组名称作为分隔标题
- **关闭** — 所有图片合并展示，不显示分组标题

::: tip
如果分组较多且每个分组图片较少，建议关闭分组标题以获得更流畅的浏览体验。如果分组清晰且每个分组图片较多，建议开启以帮助访客快速定位。
:::

## 内置功能

### 分组导航

图库页面顶部显示分组导航标签，访客可以按分组筛选查看图片。点击「全部」查看所有图片，点击具体分组名称只查看该分组的图片。

### 图片灯箱

所有图片支持点击放大查看，基于 LightGallery 实现：

- 点击图片弹出灯箱查看大图
- 支持左右切换浏览同组图片
- 支持缩放、全屏等操作
- 按 `Esc` 或点击背景关闭灯箱

## 相关页面

- [瞬间](/config/moments) — 瞬间页面配置
- [样式设置](/config/style) — 圆角与容器宽度配置
- [图库页面](/pages/photos) — 图库模板与结构说明