Ziyege双视图相册模块 for Typecho

子夜歌双视图相册 (Typecho)

一款优雅、高性能的 Typecho 相册模板，支持文章封面列表与图片详情双视图，集成 Masonry 瀑布流、Magnific Popup 灯箱、图片懒加载，并针对性能与安全进行了深度优化。新增缩略图生成、图片预加载、URL 编码、XSS 防护，并支持七牛云、又拍云、阿里云 OSS、缤纷云等主流云存储的实时图片裁剪。

在线演示：https://blog.ziyege.com/photos.html

✨ 功能特性

双视图切换
- 首页：展示指定分类下所有文章的封面卡片（第一张图片作为封面），卡片显示文章标题和图片数量。
- 详情页：点击卡片进入单篇文章，展示该文章所有图片，支持瀑布流布局与灯箱画廊。
图片处理优化
- 自动为封面图生成 400×300 缩略图，支持七牛云、又拍云、阿里云 OSS、缤纷云等主流云存储实时裁剪，大幅节省带宽。
- 首页前 4 张封面图预加载，首屏秒开。
- 图片 URL 自动编码（空格转 %20），避免特殊字符导致加载失败。
丝滑交互
- Masonry 瀑布流：图片自动排列，高度自适应，视觉整齐美观。
- Magnific Popup 灯箱：点击图片放大浏览，支持左右导航、键盘控制、标题显示。
- jQuery LazyLoad 懒加载：仅当图片进入视口时加载，提升页面速度。
- 悬停效果：卡片悬停时显示半透明遮罩及文章标题/图片数量。
安全可靠
- 所有输出均经过 htmlspecialchars 转义，有效防止 XSS 攻击。
- 严格遵循 Typecho 开发规范，代码结构清晰。
完全响应式
- 基于 Bootstrap 5，手机、平板、桌面均完美适配，边距随屏幕自动调整。
开箱即用
- 仅需修改一个分类 ID，即可将指定分类下的文章转为相册。
- 所有前端资源均从 CDN 加载，无需本地存放额外文件。

📦 安装方法

下载文件\
从 GitHub 仓库下载 ziyegephotos.php。
上传\
将文件上传至你的 Typecho 主题目录（例如 /usr/themes/你的主题/）。
创建独立页面\
在 Typecho 后台新建一个独立页面，并在“高级选项”中选择模板 “子夜歌双视图相册”。发布后即可访问该页面。
注意增加自定义字段 category_id ，填入你需要展示相册的分类id，提示：可在 Typecho 后台“管理”→“分类”中查看分类 ID。

⚙️ 进阶配置

1. 缩略图支持（云存储用户）

在 getThumbnailUrl 函数中（约第 24–70 行），已预设了七牛云、又拍云、阿里云 OSS 的缩略图参数。

2. 图片预加载数量

默认预加载前 4 张封面图，如需调整，修改 <head> 中的循环（约第 280 行）：

php

<?php for ($i = 0; $i < min(4, count($initialData)); $i++): ?>

将 4 改为你期望的数量（例如 6 或 8）。

3. 自定义样式

模板使用内联 CSS，你可以直接修改 <style> 标签中的样式，或通过主题的 custom.css 覆盖。卡片尺寸、悬停效果、边距等均可按需调整。

🚀 使用指南

首页模式

打开你创建的独立页面，即可看到按发布时间倒序排列的文章卡片。
每张卡片显示文章标题、图片数量，点击卡片进入该文章的详情页。

详情页模式

进入文章详情页后，所有图片以瀑布流网格展示。
点击任意图片，即可弹出灯箱画廊，左右滑动浏览全部图片，标题显示图片的 alt 文本及所属文章标题。
导航栏右侧提供“返回相册”按钮，点击返回首页。

分页说明

目前首页默认显示所有文章，未内置分页。若文章数量较多，建议自行添加分页逻辑或通过分类管理控制数量。

📌 注意事项

必须修改分类 ID，否则首页将不显示任何文章。
如果图片链接包含中文或特殊字符，请确保服务器已开启 UTF-8 支持，缩略图函数会自动编码空格。
由于使用了 jQuery LazyLoad，图片的 src 属性初始为透明占位图，真实地址存放在 data-original 中，不影响 SEO。
本模板依赖于 Bootstrap 5、jQuery、Masonry、imagesLoaded、Magnific Popup 等 CDN 资源，请确保你的网站能正常访问这些 CDN。
如果你使用缤纷云，建议在配置后通过浏览器直接访问生成的缩略图 URL，确认参数效果是否符合预期。

🤝 贡献与支持

项目 GitHub 地址：https://github.com/gxdng24/Typecho-photos-for-Ziyege
欢迎提交 Issue 或 Pull Request，共同改进模板。
如果你喜欢这个项目，请给一个 ⭐️ 支持作者！