瀑布流画廊插件

项目概述

瀑布流画廊插件是一个专为Typecho博客系统开发的图片展示增强插件，采用现代化的瀑布流布局技术，为博客提供美观、高效的图片展示解决方案。插件支持图片懒加载、响应式布局、图片预览等丰富功能。

核心特性

布局功能

• 瀑布流布局：自动计算最优图片排列
• 响应式设计：适配各种屏幕尺寸
• 图片懒加载：提升页面加载性能
• 无限滚动：支持大量图片的流畅浏览

交互功能

• 图片预览：点击图片查看大图
• 缩放功能：支持图片缩放操作
• 幻灯片模式：全屏幻灯片浏览
• 键盘导航：支持键盘快捷键操作

性能优化

• 图片压缩：自动压缩和优化图片
• CDN支持：支持CDN加速加载
• 缓存机制：智能缓存提升性能
• 预加载：关键图片预加载

技术实现

前端架构

// 瀑布流核心类
class WaterfallGallery {
    constructor(container, options) {
        this.container = container;
        this.options = Object.assign({}, this.defaultOptions, options);
        this.init();
    }
    
    init() {
        this.setupContainer();
        this.bindEvents();
        this.loadImages();
    }
    
    // 计算瀑布流布局
    calculateLayout(images) {
        const containerWidth = this.container.offsetWidth;
        const columnCount = Math.floor(containerWidth / this.options.minColumnWidth);
        const columns = new Array(columnCount).fill(0);
        
        return images.map(img => {
            const shortestColumn = columns.indexOf(Math.min(...columns));
            const x = shortestColumn * this.options.minColumnWidth;
            const y = columns[shortestColumn];
            
            columns[shortestColumn] += img.height + this.options.gap;
            
            return { ...img, x, y };
        });
    }
}

后端PHP实现

<?php
/**
 * 瀑布流画廊插件主类
 */
class WaterfallGallery_Plugin implements Typecho_Plugin_Interface
{
    /**
     * 插件激活
     */
    public static function activate()
    {
        // 注册管理页面
        Helper::addPanel(1, 'WaterfallGallery/manage.php', '瀑布流画廊', '瀑布流画廊管理', 'administrator');
        
        // 注册钩子
        Typecho_Plugin::factory('Widget_Archive')->header = array('WaterfallGallery_Plugin', 'header');
        Typecho_Plugin::factory('Widget_Archive')->footer = array('WaterfallGallery_Plugin', 'footer');
    }
    
    /**
     * 获取图片数据
     */
    public static function getImages($limit = 20, $offset = 0)
    {
        $db = Typecho_Db::get();
        $select = $db->select()
            ->from('table.contents')
            ->where('type = ?', 'attachment')
            ->where('status = ?', 'publish')
            ->order('created', Typecho_Db::SORT_DESC)
            ->limit($limit)
            ->offset($offset);
            
        return $db->fetchAll($select);
    }
}

安装配置

1. 环境要求

• Typecho 1.2.0+
• PHP 7.0+
• 支持JavaScript的现代浏览器
• 图片处理扩展（GD或ImageMagick）

2. 安装步骤

# 下载插件
git clone https://github.com/ongwu/typecho-waterfall-gallery.git

# 复制到插件目录
cp -r typecho-waterfall-gallery /path/to/typecho/usr/plugins/WaterfallGallery

# 设置权限
chmod -R 755 /path/to/typecho/usr/plugins/WaterfallGallery

3. 配置选项

// 插件配置
return array(
    'enableLazyLoad' => true,        // 启用懒加载
    'minColumnWidth' => 300,         // 最小列宽
    'gap' => 10,                     // 图片间距
    'enablePreview' => true,         // 启用预览功能
    'enableZoom' => true,            // 启用缩放功能
    'maxImageWidth' => 800,          // 最大图片宽度
    'quality' => 85,                 // 图片质量
    'enableCDN' => false,            // 启用CDN
    'cdnUrl' => ''                   // CDN地址
);

使用指南

1. 基本使用

<!-- 在模板中添加画廊容器 -->
<div id="waterfall-gallery" class="waterfall-container">
    <!-- 图片将通过JavaScript动态加载 -->
</div>

<!-- 初始化瀑布流画廊 -->
<script>
const gallery = new WaterfallGallery('#waterfall-gallery', {
    minColumnWidth: 300,
    gap: 10,
    enableLazyLoad: true
});
</script>

2. 自定义样式

/* 瀑布流容器样式 */
.waterfall-container {
    position: relative;
    width: 100%;
    min-height: 500px;
}

/* 图片项样式 */
.waterfall-item {
    position: absolute;
    transition: all 0.3s ease;
    cursor: pointer;
    border-radius: 8px;
    overflow: hidden;
    box-shadow: 0 2px 8px rgba(0,0,0,0.1);
}

.waterfall-item:hover {
    transform: translateY(-2px);
    box-shadow: 0 4px 16px rgba(0,0,0,0.2);
}

/* 图片样式 */
.waterfall-item img {
    width: 100%;
    height: auto;
    display: block;
}

3. 高级配置

// 高级配置示例
const gallery = new WaterfallGallery('#waterfall-gallery', {
    // 布局配置
    minColumnWidth: 300,
    gap: 15,
    
    // 懒加载配置
    enableLazyLoad: true,
    lazyLoadThreshold: 100,
    
    // 预览配置
    enablePreview: true,
    previewMode: 'modal', // modal, lightbox, inline
    
    // 性能配置
    enablePreload: true,
    preloadCount: 5,
    
    // 事件回调
    onImageLoad: function(img) {
        console.log('图片加载完成:', img.src);
    },
    
    onImageClick: function(img, index) {
        console.log('点击图片:', index);
    }
});

功能详解

1. 懒加载实现

// 懒加载实现
class LazyLoader {
    constructor(container, threshold = 100) {
        this.container = container;
        this.threshold = threshold;
        this.observer = new IntersectionObserver(this.handleIntersection.bind(this), {
            rootMargin: `${threshold}px`
        });
    }
    
    observe(element) {
        this.observer.observe(element);
    }
    
    handleIntersection(entries) {
        entries.forEach(entry => {
            if (entry.isIntersecting) {
                this.loadImage(entry.target);
                this.observer.unobserve(entry.target);
            }
        });
    }
    
    loadImage(imgElement) {
        const src = imgElement.dataset.src;
        if (src) {
            imgElement.src = src;
            imgElement.classList.add('loaded');
        }
    }
}

2. 图片预览功能

// 图片预览实现
class ImagePreview {
    constructor(gallery) {
        this.gallery = gallery;
        this.currentIndex = 0;
        this.images = [];
        this.createPreviewModal();
    }
    
    createPreviewModal() {
        this.modal = document.createElement('div');
        this.modal.className = 'image-preview-modal';
        this.modal.innerHTML = `
            <div class="preview-overlay"></div>
            <div class="preview-container">
                <img class="preview-image" src="" alt="">
                <button class="preview-close">&times;</button>
                <button class="preview-prev">&lt;</button>
                <button class="preview-next">&gt;</button>
            </div>
        `;
        document.body.appendChild(this.modal);
        this.bindEvents();
    }
    
    show(index) {
        this.currentIndex = index;
        this.updateImage();
        this.modal.classList.add('active');
        document.body.style.overflow = 'hidden';
    }
    
    hide() {
        this.modal.classList.remove('active');
        document.body.style.overflow = '';
    }
}

3. 响应式处理

// 响应式处理
class ResponsiveHandler {
    constructor(gallery) {
        this.gallery = gallery;
        this.breakpoints = {
            mobile: 768,
            tablet: 1024,
            desktop: 1200
        };
        this.currentBreakpoint = this.getCurrentBreakpoint();
        this.bindResize();
    }
    
    getCurrentBreakpoint() {
        const width = window.innerWidth;
        if (width < this.breakpoints.mobile) return 'mobile';
        if (width < this.breakpoints.tablet) return 'tablet';
        if (width < this.breakpoints.desktop) return 'desktop';
        return 'large';
    }
    
    handleResize() {
        const newBreakpoint = this.getCurrentBreakpoint();
        if (newBreakpoint !== this.currentBreakpoint) {
            this.currentBreakpoint = newBreakpoint;
            this.gallery.refresh();
        }
    }
}

性能优化

1. 图片优化

// 图片优化处理
class ImageOptimizer
{
    public static function optimizeImage($imagePath, $maxWidth = 800, $quality = 85)
    {
        $info = getimagesize($imagePath);
        $width = $info[0];
        $height = $info[1];
        
        if ($width > $maxWidth) {
            $newHeight = ($maxWidth * $height) / $width;
            return self::resizeImage($imagePath, $maxWidth, $newHeight, $quality);
        }
        
        return $imagePath;
    }
    
    private static function resizeImage($imagePath, $newWidth, $newHeight, $quality)
    {
        $image = imagecreatefromjpeg($imagePath);
        $resized = imagecreatetruecolor($newWidth, $newHeight);
        
        imagecopyresampled($resized, $image, 0, 0, 0, 0, $newWidth, $newHeight, imagesx($image), imagesy($image));
        
        $outputPath = str_replace('.jpg', '_optimized.jpg', $imagePath);
        imagejpeg($resized, $outputPath, $quality);
        
        imagedestroy($image);
        imagedestroy($resized);
        
        return $outputPath;
    }
}

2. 缓存机制

// 缓存管理
class WaterfallCache
{
    public static function getCachedImages($page = 1, $limit = 20)
    {
        $cacheKey = "waterfall_images_{$page}_{$limit}";
        $cache = Typecho_Cache::getInstance();
        
        $cached = $cache->get($cacheKey);
        if ($cached !== false) {
            return $cached;
        }
        
        $images = WaterfallGallery_Plugin::getImages($limit, ($page - 1) * $limit);
        $cache->set($cacheKey, $images, 3600); // 缓存1小时
        
        return $images;
    }
}

浏览器兼容性

浏览器	版本支持	特性支持
Chrome	60+	完全支持
Firefox	55+	完全支持
Safari	12+	完全支持
Edge	79+	完全支持
IE	11+	基础支持

更新日志

v1.1.0 (2025-01-13)

• 新增图片预览功能
• 优化懒加载性能
• 改进响应式布局
• 增强错误处理

v1.0.0 (2024-12-01)

• 初始版本发布
• 基础瀑布流布局
• 图片懒加载支持
• 响应式设计

许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。

---

瀑布流画廊插件让图片展示更美观、更高效！