212 lines
6.3 KiB
Markdown
212 lines
6.3 KiB
Markdown
# 相册功能使用说明
|
||
|
||
Mizuki 主题的相册功能采用**自动扫描**机制，只需创建文件夹、放置图片和配置文件即可，无需手动编写代码（外链相册则需要手动定义每张图片的 `src` 等信息）。
|
||
|
||
## 快速开始
|
||
|
||
创建一个相册只需 3 步：
|
||
|
||
1. 在 `public/images/albums/` （本说明文件所在目录）下创建一个文件夹（文件夹名即为相册 ID）
|
||
2. 在文件夹中放置 `cover.jpg`（封面图）和其他照片
|
||
3. 创建 `info.json` 配置文件
|
||
|
||
完成！相册会自动出现在相册列表页面。
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
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 # 本说明文件
|
||
```
|
||
|
||
## 配置文件说明
|
||
|
||
### 本地图片模式
|
||
|
||
在相册文件夹中创建 `info.json`：
|
||
|
||
```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` |
|
||
|
||
### 外链图片模式
|
||
|
||
如果想使用外部图片链接（例如使用图床），设置 `mode: "external"`：
|
||
|
||
```json
|
||
{
|
||
"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` 缩略图以提升加载速度
|
||
|
||
## 图片格式建议
|
||
|
||
### 封面图片 (cover.jpg)
|
||
- **尺寸**：800×600px（4:3 比例）
|
||
- **格式**：JPG （外链模式可支持更多格式）
|
||
- **大小**：建议 < 200KB
|
||
|
||
### 相册照片
|
||
- **格式**：JPG、JPEG、PNG、WebP、GIF、SVG、AVIF
|
||
- **尺寸**：建议最大宽度 1920px
|
||
- **优化**：建议压缩后上传，提升加载速度
|
||
|
||
## 布局选项
|
||
|
||
### 网格布局 (Grid)
|
||
```json
|
||
{
|
||
"layout": "grid",
|
||
"columns": 3
|
||
}
|
||
```
|
||
- 适合尺寸统一的照片
|
||
- 支持 2-4 列
|
||
- 照片会被裁剪为正方形
|
||
|
||
### 瀑布流布局 (Masonry)
|
||
```json
|
||
{
|
||
"layout": "masonry",
|
||
"columns": 3
|
||
}
|
||
```
|
||
- 适合不同尺寸的照片
|
||
- 保持照片原始比例
|
||
- 自动排列，视觉效果更自然
|
||
|
||
## 示例相册
|
||
|
||
项目包含以下示例相册供参考：
|
||
|
||
### AcgExample
|
||
- **本地图片模式**示例
|
||
- 展示如何使用本地图片创建相册
|
||
- 瀑布流布局，3 列
|
||
|
||
### ExternalExample
|
||
- **外链图片模式**示例（默认隐藏）
|
||
- 展示如何使用外部图片链接
|
||
- 适合使用图床的场景
|
||
|
||
### HiddenExample
|
||
- **隐藏相册**示例
|
||
- 展示如何创建不在列表显示的相册
|
||
- 可通过直接访问 URL 查看
|
||
|
||
## 高级功能
|
||
|
||
### 文件名标签（实验性）
|
||
|
||
系统支持从文件名解析标签（格式：`基本名_标签1_标签2.ext`）：
|
||
|
||
```
|
||
photo_sunset_beach.jpg → 标签：sunset, beach
|
||
```
|
||
|
||
### 隐藏相册
|
||
|
||
设置 `"hidden": true` 可以隐藏相册，但仍可通过 URL 直接访问：
|
||
|
||
```
|
||
访问：/albums/your-album-id/
|
||
```
|
||
|
||
## 常见问题
|
||
|
||
**Q: 为什么我的相册没有显示？**
|
||
A: 检查是否存在 `info.json` 和 `cover.jpg`，以及 `hidden` 是否设置为 `true`。
|
||
|
||
**Q: 可以使用其他图片格式吗？**
|
||
A: 可以，支持 JPG、PNG、WebP、GIF、SVG、AVIF 等格式。
|
||
|
||
**Q: 如何优化图片加载速度？**
|
||
A: 建议使用 WebP 等压缩率较高的格式压缩图片大小。使用外链模式时设置缩略图。
|
||
|
||
**Q: 如何更改相册排序？**
|
||
A: 相册按时间顺序展示，可通过修改相册的 `date` 字段调整排序。
|