1275 字
6 分钟
相册功能使用说明
一、相册功能使用说明
Mizuki 主题的相册功能采用自动扫描机制，只需创建文件夹、放置图片和配置文件即可，无需手动编写代码（外链相册则需要手动定义每张图片的 src 等信息）。
1、快速开始
创建一个相册只需 3 步：
- 在
public/images/albums/（本说明文件所在目录）下创建一个文件夹（文件夹名即为相册 ID） - 在文件夹中放置
cover.jpg（封面图）和其他照片 - 创建
info.json配置文件
完成！相册会自动出现在相册列表页面。
2、目录结构
public/images/albums/├── my-travel-2024/ # 相册文件夹（文件夹名 = 相册ID）│ ├── info.json # 相册配置文件（必需）│ ├── cover.jpg # 封面图（必需）│ ├── photo1.jpg # 相册照片│ ├── photo2.jpg│ └── photo3.jpg├── daily-life/ # 另一个相册│ ├── info.json│ ├── cover.jpg│ └── ...└── README.md # 本说明文件3、配置文件说明
3.1本地图片模式
在相册文件夹中创建 info.json：
{ "title": "我的旅行相册", "description": "2024年夏天的美好回忆", "date": "2024-08-01", "location": "日本东京", "tags": ["旅行", "风景", "夏天"], "layout": "masonry", "columns": 3, "hidden": false}配置项说明：
| 字段 | 必需 | 说明 | 默认值 |
|---|---|---|---|
title | 是 | 相册标题 | 使用文件夹名 |
description | 否 | 相册描述 | 空 |
date | 否 | 相册日期（格式：YYYY-MM-DD） | 当前日期 |
location | 否 | 拍摄地点 | 空 |
tags | 否 | 标签数组 | [] |
layout | 否 | 布局方式：grid（网格）或 masonry（瀑布流） | grid |
columns | 否 | 列数（2-4） | 3 |
hidden | 否 | 是否隐藏相册 | false |
3.2外链图片模式
如果想使用外部图片链接（例如使用图床），设置 mode: "external"：
{ "mode": "external", "title": "外链相册示例", "description": "使用外部图片链接的相册", "date": "2024-08-28", "location": "网络", "tags": ["外链", "示例"], "layout": "masonry", "columns": 3, "cover": "https://example.com/cover.jpg", "photos": [ { "id": "photo-1", "src": "https://example.com/photo1.jpg", "alt": "图片描述", "title": "图片标题", "description": "详细描述", "tags": ["标签1"], "width": 1920, "height": 1280 } ]}外链模式额外字段：
| 字段 | 必需 | 说明 |
|---|---|---|
mode | 是 | 设置为 "external" 启用外链模式 |
cover | 是 | 封面图片 URL （仅外链模式需要） |
photos | 是 | 照片数组，每张照片包含 src、alt、title 等字段，详见下表 |
photos 数组中每张图片的字段说明（仅外链模式需要）：
| 字段 | 必需 | 说明 | 示例 |
|---|---|---|---|
id | 否 | 照片唯一标识符 | "photo-1" |
src | 是 | 照片 URL 地址 | "https://example.com/photo.jpg" |
thumbnail | 否 | 缩略图 URL（不提供则使用原图） | "https://example.com/thumb.jpg" |
alt | 否 | 图片替代文本（用于无障碍访问） | "美丽的日落" |
title | 否 | 照片标题 | "海边日落" |
description | 否 | 照片详细描述 | "2024年夏天在海边拍摄的日落" |
tags | 否 | 照片标签数组 | ["日落", "海边"] |
date | 否 | 拍摄日期（格式：YYYY-MM-DD） | "2024-08-01" |
location | 否 | 拍摄地点 | "冲绳海滩" |
width | 否 | 照片宽度（像素） | 1920 |
height | 否 | 照片高度（像素） | 1280 |
camera | 否 | 相机型号 | "Canon EOS R5" |
lens | 否 | 镜头型号 | "RF 24-70mm F2.8" |
settings | 否 | 拍摄参数（字符串） | "f/2.8, 1/500s, ISO 100" |
注意：
- 本地图片模式不需要配置
photos字段，系统会自动扫描文件夹中的所有图片文件- 外链模式必须手动配置
photos数组，至少需要提供src字段- 建议为外链照片提供
thumbnail缩略图以提升加载速度
4、图片格式建议
4.1、封面图片 (cover.jpg)
- 尺寸：800×600px（4:3 比例）
- 格式：JPG （外链模式可支持更多格式）
- 大小：建议 < 200KB
4.2、相册照片
- 格式：JPG、JPEG、PNG、WebP、GIF、SVG、AVIF
- 尺寸：建议最大宽度 1920px
- 优化：建议压缩后上传，提升加载速度
5、布局选项
5.1、网格布局 (Grid)
{ "layout": "grid", "columns": 3}- 适合尺寸统一的照片
- 支持 2-4 列
- 照片会被裁剪为正方形
5.2、瀑布流布局 (Masonry)
{ "layout": "masonry", "columns": 3}- 适合不同尺寸的照片
- 保持照片原始比例
- 自动排列，视觉效果更自然
6、示例相册
项目包含以下示例相册供参考：
6.1、AcgExample
- 本地图片模式示例
- 展示如何使用本地图片创建相册
- 瀑布流布局，3 列
6.2、ExternalExample
- 外链图片模式示例（默认隐藏）
- 展示如何使用外部图片链接
- 适合使用图床的场景
6.3、HiddenExample
- 隐藏相册示例
- 展示如何创建不在列表显示的相册
- 可通过直接访问 URL 查看
7、高级功能
7.1、文件名标签（实验性）
系统支持从文件名解析标签（格式：基本名_标签1_标签2.ext）：
photo_sunset_beach.jpg → 标签：sunset, beach7.2、隐藏相册
设置 "hidden": true 可以隐藏相册，但仍可通过 URL 直接访问：
访问：/albums/your-album-id/8、常见问题
Q: 为什么我的相册没有显示？
A: 检查是否存在 info.json 和 cover.jpg，以及 hidden 是否设置为 true。
Q: 可以使用其他图片格式吗？
A: 可以，支持 JPG、PNG、WebP、GIF、SVG、AVIF 等格式。
Q: 如何优化图片加载速度？
A: 建议使用 WebP 等压缩率较高的格式压缩图片大小。使用外链模式时设置缩略图。
Q: 如何更改相册排序？
A: 相册按时间顺序展示，可通过修改相册的 date 字段调整排序。
部分信息可能已经过时