namyki/blog-code

Template

Fork 0

Files

Namyki 5c77d25b6d 111

2025-12-08 01:03:07 +08:00

6.3 KiB

Raw Blame History

相册功能使用说明

Mizuki 主题的相册功能采用自动扫描机制，只需创建文件夹、放置图片和配置文件即可，无需手动编写代码（外链相册则需要手动定义每张图片的 src 等信息）。

快速开始

创建一个相册只需 3 步：

在 public/images/albums/ （本说明文件所在目录）下创建一个文件夹（文件夹名即为相册 ID）
在文件夹中放置 cover.jpg（封面图）和其他照片
创建 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：

{
  "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"：

{
  "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)

{
  "layout": "grid",
  "columns": 3
}

适合尺寸统一的照片
支持 2-4 列
照片会被裁剪为正方形

瀑布流布局 (Masonry)

{
  "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 字段调整排序。

6.3 KiB Raw Blame History Unescape Escape