🍕功能说明：图片浏览器

Function description: picture preview

你可以点击本页面中的随机示例图片来进行体验。

一、功能介绍：

图片浏览器功能写在templets\default\js\media-preview.js 中，提供了高质量的图片预览、缩放、拖拽等功能，具有良好的移动端支持和用户体验。主要功能如下：

1.1 图片预览自动获取页面中所有位于.image-carousel（轮播图）和.Content-Type（文章内容）内的图片，并组合在一起形成一个图片列表，点击页面中的图片打开图片预览模态框，浏览器由三部分组成：顶部的标题栏，中间的图片浏览区域和底部的缩略图滑条；；

1.2 平滑切换和关闭鼠标或者触摸左右滑动可以切换图片，左右方向键也可以切换图片，切换图片时顶部的标题和底部缩略图会同步切换状态；空白区域单击，或者按esc，或者拖住图片向下滑动可以关闭图片浏览器，页面会定位到图片所在的位置；

1.3 图片缩放和平移：支持鼠标滚轮或双指捏合缩放图片、双击放大/恢复图片、放大的图片可以鼠标拖拽或触摸平移；

1.4 缩略图导航：底部显示缩略图，支持点击导航；

1.5 精美动效设计：添加了大量的平滑过渡、弹性动画、惯性动画效果，比如下滑关闭模态框时，图片会逐渐缩、，背景透明度逐渐降低、并且由模糊逐渐清晰。松开图片后，原网页图片位置显示一个回弹动画，模拟图片回到原位置的效果；而在放大后的图片上拖拽平移时，添加了适当的惯性动画，使得操作体验更丝滑流畅。

二、功能特色：

图片浏览器最大的特色同时耗费我心血最多的部分，就是最终的呈现效果和动态设计上。具体来说：

2.1 切换图片时，缩略图会由 1:1 丝滑过渡为原始图片比例，稍稍放大并排斥周围的图片；
2.2 图片很多超出屏幕时，当前浏览的图片缩略图将始终定位在视口中央位置；
2.3 退出图片浏览器时，网页将始终定位在当前浏览的图片所在位置，并播放一个包含缩放、模糊、位移的动画，以模拟回到页面中的动态效果；
2.4 放大后的图片上拖拽平移时，添加了适当的惯性动画，使得操作体验更丝滑流畅。
2.5 鼠标滚轮的缩放轴心会融合视口中央位置和缩放比例，并结合鼠标当前位置综合计算，简单来说，图片较小时偏向向视口为中心缩放，图片较大时偏向鼠标为中心缩放；

为了达到这些效果，期间产生了各种各样有意思的问题，甚至有些问题无法解决，采用了其他比较讨巧的方式来处理。

三、使用方法：

3.1 基本步骤：

- 添加脚本：将脚本添加到html页面中：
<script src="/templets/default/js/media-preview.js"></script>

- 配置变量：在media-preview.js文件的顶部，有以下可以配置的变量，根据需要自行调整，其中需要根据项目进行的必要调整为CSS_PATH（CSS文件路径）、 IMAGE_SELECTORS（配置需要自动组合的图片区域也就是图片所在的父级div的class名称、及标题来源的标签，图片浏览器会根据这里的顺序进行组合）：

(function() {
    // 配置常量
    const CONFIG = {
        CSS_PATH: '/templets/default/style/image-preview.css', // CSS文件路径
        ZOOM: { // 缩放相关配置
            MIN: 0.8, // 最小缩放比例
            MAX: 5,   // 最大缩放比例
            STEP: 0.1 // 滚轮缩放步长
        },
        ANIMATION: { // 动画相关配置
            DURATION: 300, // 动画持续时间 (ms)
            TIMING: 'ease'   // 动画时间函数
        },
        DRAG: { // 拖拽相关配置
            THRESHOLD: 5,       // 判定为拖拽的最小移动像素
            CLOSE_THRESHOLD: 150, // 向下拖拽关闭模态框的最小距离 (px)
            HORIZONTAL_SWIPE_THRESHOLD: 100 // 水平拖动切换图片的最小距离 (px)
        },
        INERTIA: { // 惯性滚动配置
            DAMPING: 0.92,     // 阻尼系数 (越小越快停止)
            MIN_VELOCITY: 0.1 // 停止惯性动画的最小速度阈值
        },
        THUMBNAILS: { // 缩略图相关配置
            MARGIN: 50 // 每个幻灯片（Slide）右侧的间距 (px)
        },
        PINCH: { // 双指缩放相关配置
            MIN_CHANGE: 0.005,         // 判定为有效缩放变化的最小比例差
            MIN_POSITION_CHANGE: 0.5 // 判定为有效位置变化的最小像素差
        },
        IMAGE_SELECTORS: [ // 图片选择器及对应的描述属性
            { selector: '.image-carousel img', captionAttr: 'alt' }, // 选择器及其描述来源属性，按先后顺序组合
            { selector: '.Content-Type img', captionAttr: 'title' }
        ],
        ASPECT_RATIO_PRESETS: { // 缩略图宽高比预设
            portrait: '1/1',   // 竖向图片的预设比例
            landscape: '4/3'   // 横向图片的预设比例
        },
        DRAG_EFFECTS: { // 垂直拖拽关闭效果
            SCALE_MIN: 0.5,             // 向下拖动时的最小缩放比例
            SCALE_DISTANCE_FACTOR: 1000, // 计算缩放比例的距离除数 (越大变化越慢)
            OPACITY_MIN: 0.3,           // 向下拖动时背景最小透明度
            OPACITY_DISTANCE_FACTOR: 300, // 计算透明度的距离除数 (越大变化越慢)
            BLUR_MAX: 20,               // 向下拖动时背景最大模糊值 (px)
            BLUR_DISTANCE_FACTOR: 300,  // 计算模糊效果的距离除数 (越大变化越慢)
            BACKGROUND_RGB: '51, 51, 51', // 模态框背景RGB颜色
            BACKDROP_BLUR_BASE: 20      // 模态框背景基础模糊值 (px)
        }
    };

3.2 HTML结构要求：

为确保预览功能正常工作，请确保您的图片元素：
- 符合配置中定义的选择器
- 具有相应的描述属性（如`alt`或`title`）
- 确保图片有正确的`src`属性指向有效的图片资源

示例：

<!-- 轮播图示例 -->
<div class="image-carousel">
    <img src="image1.jpg" alt="图片1描述" />
    <img src="image2.jpg" alt="图片2描述" />
</div>

<!-- 内容区域图片示例 -->
<div class="Content-Type">
    <img src="image3.jpg" title="图片3描述" />
</div>

3.3 自动初始化

脚本会在页面加载时自动初始化，并在图片异步加载完成时更新UI，无需额外的JavaScript调用。图片预览功能将自动应用于符合选择器的所有图片。组件会自动加载配置中的样式文件。

3.4 其他特性

- 模块划分：代码按以下模块划分：

  1. 配置管理 (`CONFIG`)
  2. 状态管理 (`createStore`, `store`)
  3. DOM元素缓存 (`DOM`)
  4. 工具函数 (`Utils`)
  5. UI构建 (`UIBuilder`)
  6. 核心功能 (`ImagePreview`)
  7. 功能处理模块 (`DragHandler`, `ZoomHandler`, `InertiaHandler`, `DoubleClickZoomHandler`等)

- 状态管理：使用状态管理器统一管理状态，避免全局变量
- 功能内聚：每个模块应职责单一，内聚性高，只处理特定功能