照片墙插件 (WP Photo Wall)

一个极简风格的照片墙 WordPress 插件，带有强大的后台管理和极致的前端性能优化。

页面预览

✨ 特性

• 极简设计: 采用极简风格的 UI 设计，清爽、现代。
• 强大的后台管理:
  • 支持从 WordPress 媒体库添加本地图片。
  • 支持添加外部链接图片（兼容 CDN 带参数的 URL）。
  • 分组管理：创建多个分组，通过拖拽或批量选择移动图片到目标分组。
  • 分组排序：拖动分组标题左侧抓手图标，即可调整分组在前台的展示顺序。
  • 批量操作：支持批量移动分组、批量从照片墙移除、从媒体库永久删除。
  • 孤儿图片清理：从照片墙或顶部轮播移除媒体库图片时，若该图片已不被插件任何位置引用，自动从媒体库永久删除，避免孤儿文件堆积（可在设置中开关，默认开启）。
• 极致性能优化:
  • 后台: 缩略图由 PHP 端一次性预加载，消除 N+1 AJAX 请求；批量 DOM 更新。
  • 前台:
    • 异步解码 (decoding="async")：防止大图解码阻塞主线程。
    • 智能可见性 (content-visibility)：只渲染视口内的图片，极大降低内存占用。
    • 懒加载 (loading="lazy")：提升首屏加载速度。
    • 滚动节流：滚动时自动禁用 hover 动画，提升移动端流畅度。
    • 淡入动画：图片加载时带有错落的淡入效果，视觉体验流畅优雅。
• 响应式布局: 自动适应桌面、平板和手机。
• 内置灯箱 (Lightbox): 自带轻量级灯箱效果，支持键盘左右切换、焦点陷阱。
• 顶部海报轮播 (Banner Carousel): 在每个 [photo_wall] 顶部展示手动选图组成的自动轮播，支持本地媒体库与外部链接，可配置轮播间隔、滑动过渡、悬停暂停、点击进灯箱。

📁 项目结构

photo-wall/
├── wp-photo-wall.php          # 主入口文件（精简加载器）
├── includes/
│   ├── i18n.php               # 多语言翻译定义
│   ├── data.php               # 数据操作与校验
│   ├── ajax.php               # AJAX 请求处理
│   ├── frontend.php           # 前端渲染与短代码
│   └── slides.php             # 顶部轮播数据层与渲染
├── admin/
│   ├── admin-page.php         # 后台页面模板
│   ├── admin-slides.php       # 后台轮播管理模板
│   ├── admin-script.js        # 后台交互逻辑
│   └── admin-style.css        # 后台样式
├── public/
│   ├── shortcode.php          # 短代码输出模板
│   ├── gallery-script.js      # 前台交互（灯箱、无限滚动）
│   ├── gallery-style.css      # 前台样式
│   ├── slider-script.js       # 前台轮播交互（自动播放、滑动、悬停暂停）
│   └── slider-style.css       # 前台轮播样式
├── uninstall.php              # 卸载清理
└── README.md

📥 安装

1. 下载插件压缩包（photo-wall-2.3.0.zip）。
2. 在 WordPress 后台 → 插件 → 安装插件。
3. 点击 上传插件，选择 zip 文件并安装。
4. 启用插件。

🚀 使用方法

1. 添加图片

在 WordPress 后台侧边栏找到 "照片墙" 菜单。

• 点击 "选择/上传照片" 从媒体库选择。
• 点击 "添加外部链接" 输入图片 URL。
• 新添加的图片默认放入"未分组"。

2. 分组管理

• 在照片管理区域顶部输入名称，点击 "添加分组" 创建新分组。
• 拖拽图片：直接拖动图片到目标分组。
• 批量移动：勾选图片 → 点击"移动选中"按钮 → 在弹窗中选择目标分组 → 确认。
• 调整分组顺序：拖动分组标题左侧的 ≡ 图标。
• 所有操作需要点击 "保存更改" 才会生效。

3. 在页面显示

在任意页面或文章中使用短代码：

[photo_wall]

图片必须移动到一个已创建的分组后才会显示在前台；"未分组"是后台暂存区，不会公开显示。

同一页面可以放置多个 [photo_wall]，每个实例的分页和灯箱状态彼此独立。每个实例的顶部轮播也相互独立（共用同一组选图配置，各自独立播放）。

4. 顶部海报轮播

在后台 "照片墙" 菜单页面顶部，找到 "顶部海报轮播" 区块：

• 勾选 "启用轮播" 后，每个 [photo_wall] 顶部会显示自动轮播。
• 点击 "从媒体库添加" 选择本地图片，或 "添加外部链接" 输入图片 URL。
• 拖动图片左侧抓手可调整轮播顺序。
• 设置 "轮播间隔"（秒）与 "点击打开灯箱" 开关。
• 所有操作需点击 "保存更改" 生效。

轮播支持滑动过渡、悬停/聚焦暂停、触摸滑动切换、不同尺寸图片自动裁切铺满（object-fit: cover），并复用现有灯箱查看大图。

5. 前端功能

• 悬停图片会有轻微上浮效果。
• 点击图片进入全屏灯箱模式。
• 滚动到底部会自动加载更多（无限滚动）。
• 灯箱支持键盘导航（←→切换，Esc 关闭）、焦点循环和关闭后焦点恢复。

6. 设置选项

• 启用灯箱：可关闭内置灯箱（适用于主题已有灯箱的情况）。
• 下载按钮链接：配置外部网盘下载地址，前台显示下载入口。
• 顶部海报轮播：启用/禁用轮播、设置自动播放间隔、点击进灯箱。
• 自动删除无用媒体：开启后，从照片墙或顶部轮播移除媒体库图片时，若该图片已不被插件任何位置引用，将自动从媒体库永久删除，防止孤儿图片堆积。

📋 系统要求

• WordPress 6.0+
• PHP 7.4+

🔄 更新日志

2.3.0

• 新增：孤儿图片自动清理 —— 仅作用于真实图片附件，外链图片不涉及媒体库，完全跳过
• 新增：中英繁三语文案

2.2.0

• 修复：灯箱点击图片后始终打开第一张的问题（data-index 读写方式不一致导致索引丢失）
• 修复：卸载时未清理轮播相关 option，导致残留数据
• 修复：外链图片弹窗确认按钮文案显示为"添加到轮播"（i18n 重复键 add_to_wall 导致）
• 修复：分组拖拽提示文案错别字（"移动到通过分组"→"移动到其他分组"）
• 性能：i18n 翻译数组改为 static 缓存，避免每次调用重建
• 性能：照片数据 option 设为非自动加载，减少全站无关页面的数据库开销
• 重构：无限滚动加载复用共享数据层，消除重复分组排序逻辑
• 前端：灯箱新增触摸滑动切换支持（移动端）
• 前端：分组标题改为两侧渐变线装饰，更有质感
• 架构：分组数据读取去重，get_visible_items() 不再重复查询

2.1.0

- 新增顶部海报轮播功能（手动选图 + 自动轮播）
- 支持本地媒体库图片与外部链接图片
- 滑动过渡、悬停/聚焦暂停、触摸滑动切换
- 点击进入现有灯箱查看大图（可配置）
- 数据独立存储（独立 option），不影响原有照片墙结构与布局

2.0.3

• 前端优化：图片加载淡入动画，错落延迟效果，视觉更柔和
• 前端优化：分组标题重构，渐变色装饰线 + 加大分组间距，更有质感和呼吸感
• 修复：未保存提醒在页面初始加载时误触发的问题
• 改进：未保存提醒移至页面顶部醒目位置，使用自定义通知条样式
• 架构重构：主文件拆分为模块化结构（i18n / data / ajax / frontend），可维护性大幅提升
• 性能优化：后台缩略图由 PHP 端一次性预加载，消除 N+1 AJAX 请求

📜 许可证

GPL v2 or later