前端UI库/组件【免费下载链接】PhotoSwipeJavaScript image gallery for mobile and desktop, modular, framework independent项目地址https://gitcode.com/gh_mirrors/ph/PhotoSwipe点击查看免费下载PhotoSwipe当前仓库gh_mirrors/ph/PhotoSwipe是一款面向移动端与桌面的模块化、框架无关的 JavaScript 图片画廊库。本文基于仓库中的事件参考文档 docs/events.md系统讲解 PhotoSwipe 5 的整套事件体系包括初始化事件、开关过渡事件、关闭销毁事件、指针手势事件与幻灯片内容事件共五大类并深入结合 src/js/core/eventable.js、src/js/lightbox/lightbox.js、src/js/photoswipe.js 等核心源码说明每个事件在何时、由谁、以怎样的参数触发以及如何利用preventDefault()拦截默认行为。读完本文你将能在自己的图库集成中精准地在正确的时机挂载/卸载逻辑实现自定义 UI、自定义内容类型、加载状态提示、手势拦截等高级功能。事件模型基础绑定在 Lightbox 上自动转发到 PhotoSwipe 核心PhotoSwipe 的事件 API 遵循标准的发布/订阅模式核心方法在事件基类 src/js/core/eventable.js 的Eventable类中定义on(name, fn)注册事件监听器off(name, fn)移除监听器dispatch(name, details)触发事件返回事件对象内部使用addFilter / removeFilter / applyFilters与事件平行的过滤器机制见 docs/filters.md。文档开篇即给出了核心用法所有事件都可以直接绑定到 Lightbox 实例上当 PhotoSwipe 打开时它们会被自动映射到 PhotoSwipe 核心。const lightbox new PhotoSwipeLightbox({ // options... }); lightbox.init();这一自动映射的实现位于 src/js/lightbox/lightbox.jsLightbox 在创建出 PhotoSwipe 核心实例pswp后会把this._listeners中已注册的所有监听器逐一pswp.on(...)转发过去过滤器同理。因此你只需要关心 Lightbox 这一个对象无需关心实例何时创建。监听器的存储与事件对象Eventable内部用_listeners对象按事件名存储回调数组src/js/core/eventable.js。触发时dispatch会构造一个PhotoSwipeEvent事件对象src/js/core/eventable.js它包含三个关键能力event.type事件名称event.defaultPrevented布尔值表示是否已被preventDefault()拦截event.preventDefault()调用后置defaultPrevented true可拦截默认行为的事件会因此跳过 PhotoSwipe 的默认处理文档中凡标注 can be default prevented 的事件均可用。事件对象还会把dispatch时传入的详情对象如content、slide、width、isLazy等直接展开合并到自身所以回调里可以直接解构取值例如lightbox.on(contentInit, ({ content }) {...})。完整的事件名称与参数类型定义在 src/js/core/eventable.js 的PhotoSwipeEventsMap类型声明中TypeScript 与 JSDoc 用户可直接获得补全与类型检查支持。初始化事件理解 PhotoSwipe 的启动时间线文档给出的初始化事件示例完整如下读者可结合源码逐行理解每个事件的确切触发时机import PhotoSwipeLightbox from /photoswipe/photoswipe-lightbox.esm.js; const lightbox new PhotoSwipeLightbox({ gallery: #gallery--test-init-events, children: a, pswpModule: () import(/photoswipe/photoswipe.esm.js) }); lightbox.on(beforeOpen, () { console.log(beforeOpen); // photoswipe starts to open }); lightbox.on(firstUpdate, () { console.log(firstUpdate); // photoswipe keeps opening // you may modify initial index or basic DOM structure }); lightbox.on(initialLayout, () { console.log(initialLayout); // photoswipe measures size of various elements // if you need to read getBoundingClientRect of something - do it here }); lightbox.on(change, () { // triggers when slide is switched, and at initialization console.log(change); }); lightbox.on(afterInit, () { console.log(afterInit); // photoswipe fully initialized and opening transition is running (if available) }); lightbox.on(bindEvents, () { console.log(bindEvents); // photoswipe binds DOM events (such as pointer events, wheel, etc) }); lightbox.init();对照 src/js/photoswipe.js 的init()方法这组事件的真实触发顺序是beforeOpensrc/js/photoswipe.js紧接着遗留事件init之后触发。此时 PhotoSwipe 已标记为打开isOpen true随后会创建主 DOM 结构_createMainStructure()。适用于需要在打开前完成一次性准备的场景。firstUpdatesrc/js/photoswipe.js在currIndex/potentialIndex已从options.index初始化之后触发。文档明确提示这是修改初始索引或基础 DOM 结构的机会——例如根据路由参数、缩略图点击位置等动态修正起始页。注意在此之后 PhotoSwipe 会对索引做一次合法性修正NaN/越界时归零见 src/js/photoswipe.js所以在此事件中赋一个合法索引是安全的。initialLayoutsrc/js/photoswipe.js在updateSize()强制同步布局、拿到初始缩略图边界getThumbBounds()之后触发。此时各元素尺寸已经确定如果需要读取某个元素的getBoundingClientRect()应当在此事件中读取否则布局可能尚未完成。change在中间幻灯片内容setContent(...)完成后触发src/js/photoswipe.js。文档明确说明切页时会触发初始化时也会触发一次另外 src/js/main-scroll.js 在滚动切换目标后、src/js/photoswipe.js 在refreshSlideContent()后同样会派发change。afterInitsrc/js/photoswipe.js在opener.open()打开动画开始之后触发。此时 PhotoSwipe已经完全初始化且打开过渡动画如果可用正在运行。这是绝大多数业务逻辑如埋点、自定义计数器初始化的推荐挂载点。bindEventssrc/js/photoswipe.js在openingAnimationEnd回调里、PhotoSwipe 绑定window.resize/scroll监听之后触发。文档注释指出此时 PhotoSwipe 绑定 DOM 事件pointer 事件、滚轮事件等。如果你有需要与 PhotoSwipe 生命周期同步的全局监听如自定义键盘快捷键可在此事件中绑定。打开过程中的内部机制补充bindEvents被放在openingAnimationEnd之后并非偶然PhotoSwipe 打开时只会先为当前幻灯片设置内容itemHolders[1]相邻幻灯片的内容要等openingAnimationEnd后才填充见 src/js/photoswipe.js 中itemHolders[0]、itemHolders[2]的处理与appendHeavy()、contentLoader.updateLazy()的调用。这与文档中change切页时触发的描述相互印证——首屏之后每次滑动切换change都会再次触发。打开与关闭过渡事件无论是否禁用动画都会触发文档特别强调即便过渡动画被禁用如showHideAnimationType: none或动画时长被置零以下四个事件也依然会触发因此它们非常适合作为过渡开始/结束的可靠信号。import PhotoSwipeLightbox from /photoswipe/photoswipe-lightbox.esm.js; const lightbox new PhotoSwipeLightbox({ gallery: #gallery--test-opening-closing-events, children: a, pswpModule: () import(/photoswipe/photoswipe.esm.js) }); lightbox.on(openingAnimationStart, () { console.log(openingAnimationStart); }); lightbox.on(openingAnimationEnd, () { console.log(openingAnimationEnd); }); lightbox.on(closingAnimationStart, () { console.log(closingAnimationStart); }); lightbox.on(closingAnimationEnd, () { console.log(closingAnimationEnd); }); lightbox.init();源码佐证过渡编排集中在 src/js/opener.js 的Opener类中。openingAnimationStart/closingAnimationStart在_initiate()中派发src/js/opener.js同时会派发遗留事件initialZoomIn/initialZoomOut。此时过渡时长--pswp-transition-duration已被写入样式pswp--ui-visible类被切换。openingAnimationEnd/closingAnimationEnd在动画完成回调_onAnimationComplete()中派发src/js/opener.js同时派发遗留事件initialZoomInEnd/initialZoomOutEnd。若本次是关闭且动画完成紧接着会调用pswp.destroy()进入销毁流程见下文关闭事件。另外值得留意打开动画开始时 PhotoSwipe 会等待当前幻灯片占位图解码完成最长 250ms、最短 50mssrc/js/opener.js这保证了从缩略图缩放的过渡足够平滑。关闭事件在正确的时机卸载资源import PhotoSwipeLightbox from /photoswipe/photoswipe-lightbox.esm.js; const lightbox new PhotoSwipeLightbox({ gallery: #gallery--test-closing-events, children: a, pswpModule: () import(/photoswipe/photoswipe.esm.js) }); lightbox.on(close, () { // PhotoSwipe starts to close, unbind most events here console.log(close); }); lightbox.on(destroy, () { // PhotoSwipe is fully closed, destroy everything console.log(destroy); }); lightbox.init();close由pswp.close()触发src/js/photoswipe.js。此时 PhotoSwipe 将isDestroying true派发close后立即移除所有内部 DOM 事件this.events.removeAll()并开始关闭过渡。文档建议在这里解绑大部分事件。destroy在关闭过渡真正结束后closingAnimationEnd之后的pswp.destroy()触发src/js/photoswipe.js。此时 PhotoSwipe 清空监听器、移除根元素、销毁所有幻灯片与内容加载器。文档建议在这里销毁一切。若你在关闭动画期间pswp.close()未被调用就直接调用destroy()PhotoSwipe 会把showHideAnimationType置为none再走一次close()流程保证事件顺序依然正确src/js/photoswipe.js。在 Lightbox 层面destroy()后还会把window.pswp与this.pswp清理为undefinedsrc/js/lightbox/lightbox.js因此同一个 Lightbox 实例是可以被重复打开多次的——这正是事件监听器能自动映射、反复生效的前提。指针与手势事件拦截触摸与拖拽行为import PhotoSwipeLightbox from /photoswipe/photoswipe-lightbox.esm.js; const lightbox new PhotoSwipeLightbox({ gallery: #gallery--test-pointer-events, children: a, pswpModule: () import(/photoswipe/photoswipe.esm.js) }); lightbox.on(pointerDown, (e) { console.log(pointerDown, e.originalEvent); }); lightbox.on(pointerMove, (e) { console.log(pointerMove, e.originalEvent); }); lightbox.on(pointerUp, (e) { console.log(pointerUp, e.originalEvent); }); lightbox.on(pinchClose, (e) { // triggered when using pinch to close gesture // can be default prevented console.log(pinchClose, e.bgOpacity); }); lightbox.on(verticalDrag, (e) { // triggered when using vertical drag to close gesture // can be default prevented console.log(verticalDrag, e.panY); }); lightbox.init();这组事件的触发点在 src/js/gestures/gestures.js 的Gestures类中pointerDown/pointerMove/pointerUp分别在指针按下src/js/gestures/gestures.js、移动src/js/gestures/gestures.js、抬起src/js/gestures/gestures.js时派发事件参数为{ originalEvent }即浏览器原生 PointerEvent。三个事件均可通过preventDefault()拦截从而完全接管某类指针交互。注意pointerDown在opener.isOpen为 false即还在开关过渡中时会直接preventDefault()并返回此时不会派发事件。pinchClose由双指捏合关闭手势触发派发点位于 src/js/gestures/zoom-handler.js参数{ bgOpacity }表示随捏合进度变化的背景透明度。可被preventDefault()拦截拦截后背景透明度不会随捏合变化相当于禁用了捏合关闭。verticalDrag由垂直拖拽关闭手势触发派发点位于 src/js/gestures/drag-handler.js参数{ panY }为当前幻灯片垂直位移。可被preventDefault()拦截拦截后幻灯片不会产生带摩擦的垂直位移相当于禁用了下拉关闭。除上述文档收录的手势事件外PhotoSwipeEventsMap中还声明了未在文档中展开说明的imageClickAction、bgClickAction、tapAction、doubleTapAction点击/双击行为均可拦截以及keydown、wheel等事件可在 src/js/core/eventable.js 中查阅。幻灯片内容事件内容从创建到销毁的完整生命周期这是最庞大也最常用的一组事件覆盖了每一条幻灯片内容Content从诞生到销毁的全部阶段。文档示例import PhotoSwipeLightbox from /photoswipe/photoswipe-lightbox.esm.js; import PhotoSwipe from /photoswipe/photoswipe.esm.js; const lightbox new PhotoSwipeLightbox({ gallery: #gallery--test-content-events, children: a, pswpModule: PhotoSwipe }); lightbox.on(contentInit, ({ content }) { console.log(contentInit, content); }); lightbox.on(contentLoad, ({ content, isLazy }) { // content starts to load // can be default prevented // assign elements to content.element console.log(contentLoad, content, isLazy); }); lightbox.on(contentLoadImage, ({ content, isLazy }) { // similar to the previous one, but triggers only for image content // can be default prevented console.log(contentLoadImage, content, isLazy); }); lightbox.on(loadComplete, ({ content, slide }) { console.log(loadComplete, content); }); lightbox.on(contentResize, ({ content, width, height }) { // content will be resized // can be default prevented console.log(contentResize, content, width, height); }); lightbox.on(imageSizeChange, ({ content, width, height, slide }) { // content.element is image console.log(imageSizeChange, content, width, height, slide, slide.index); }); lightbox.on(contentLazyLoad, ({ content }) { // content start to lazy-load // can be default prevented console.log(contentLazyLoad, content); }); lightbox.on(contentAppend, ({ content }) { // content is added to dom // can be default prevented // content.slide.container.appendChild(content.element); console.log(contentAppend, content); }); lightbox.on(contentActivate, ({ content }) { // content becomes active (the current slide) // can be default prevented console.log(contentActivate, content); }); lightbox.on(contentDeactivate, ({ content }) { // content becomes inactive // can be default prevented console.log(contentDeactivate, content); }); lightbox.on(contentRemove, ({ content }) { // content is removed from DOM // can be default prevented console.log(contentRemove, content); }); lightbox.on(contentDestroy, ({ content }) { // content will be destroyed // can be default prevented console.log(contentDestroy, content); }); lightbox.init();文档说明这些事件的进阶用法示例请参阅 自定义内容。下面按内容对象在其实现类 src/js/slide/content.js 中的派发位置逐一说明触发时机与参数创建与加载阶段事件触发时机参数可否拦截contentInitContent构造时立即派发src/js/slide/content.js{ content }否contentLazyLoad内容开始懒加载前lazyLoad()src/js/slide/content.js{ content }是contentLoad内容开始加载前load()src/js/slide/content.js{ content, isLazy }是contentLoadImage仅图片内容、开始加载图片前loadImage()src/js/slide/content.js{ content, isLazy }是loadComplete加载成功onLoaded()src/js/slide/content.js或失败onError()src/js/slide/content.js时失败时isError: true{ content, slide, isError? }否理解这几个事件的关键在于 PhotoSwipe 的两阶段加载模型懒加载阶段Lightbox 打开前就可能发生lazyLoadData()/lazyLoadSlide()见 src/js/slide/loader.js会先依据视口与初始缩放级别估算图片显示尺寸然后调用content.lazyLoad()→ 派发contentLazyLoad→load(true)→ 派发contentLoadisLazy: true→ 若是图片再派发contentLoadImage。正式显示阶段幻灯片被激活后setDisplayedSize()首次获得显示尺寸时会触发loadImage(false)src/js/slide/content.js此时再派发一次contentLoad/contentLoadImageisLazy: false。contentLoad的一个典型用法是文档注释中提到的为自定义内容类型手动把元素赋给content.element配合content.type与content.data.html详见 docs/custom-content.md。尺寸与状态阶段事件触发时机参数可否拦截contentResize内容即将应用新显示尺寸前setDisplayedSize()src/js/slide/content.js{ content, width, height }是imageSizeChange图片内容尺寸更新后src/js/slide/content.js{ content, width, height, slide }否contentAppend内容被加入 DOM 前append()src/js/slide/content.js{ content }是contentActivate内容成为当前活动幻灯片前activate()src/js/slide/content.js{ content }是contentDeactivate内容变为非活动时deactivate()src/js/slide/content.js{ content }是contentRemove内容从 DOM 移除前remove()src/js/slide/content.js{ content }是contentDestroy内容销毁前destroy()src/js/slide/content.js{ content }是实践要点contentResize拦截后PhotoSwipe 不会把新的宽高写入内容元素src/js/slide/content.js适合自定义尺寸管理contentAppend拦截后你需要自行把content.element挂到content.slide.container上文档注释中直接给出了content.slide.container.appendChild(content.element)的替代写法contentActivate内部在非 Safari 且图片解码中的情况下会强制提前挂载图片src/js/slide/content.js拦截该事件会影响此行为使用时需谨慎contentDeactivate同时负责把holderElement的aria-hidden置为truesrc/js/slide/content.js拦截后需自行处理无障碍属性。图片解码优化contentAppend之后PhotoSwipe 会利用HTMLImageElement.decode()对非活动幻灯片以及 Safari 下的所有幻灯片做解码优化解码完成后再调用appendImage()真正挂载图片src/js/slide/content.js并在其中派发未收录在文档中的contentAppendImage事件src/js/slide/content.js。这保证了图片在完整加载前即可部分渲染提升翻页流畅度。事件触发时序总览综合上述源码分析一个完整的 PhotoSwipe 会话打开 → 浏览 → 关闭的核心事件时间线如下lightbox.init() └─ 点击缩略图 → loadAndOpen() → 加载 pswpModule PhotoSwipe.init() ├─ beforeOpen 打开流程开始创建 DOM 结构 ├─ firstUpdate 可修改初始索引 ├─ initialLayout 尺寸已就绪可读 getBoundingClientRect ├─ change 初始化时首次触发之后每次切页都会触发 ├─ contentInit → contentLazyLoad → contentLoad → contentLoadImage → loadComplete ├─ openingAnimationStart ├─ openingAnimationEnd → bindEvents相邻幻灯片内容填充、挂载 resize/scroll ├─ contentAppend / contentActivate / imageSizeChange / contentResize浏览期间反复触发 ├─ ... ├─ close 关闭流程开始解绑大部分事件 ├─ closingAnimationStart ├─ closingAnimationEnd └─ destroy 彻底销毁实战建议与常见场景初始索引修正在firstUpdate中根据业务条件改写pswp.currIndex比在构造后修改更可靠源码在 src/js/photoswipe.js 中先赋值后派发事件。自定义加载状态提示监听contentLoad开始加载与loadComplete结束注意isError参数区分成败在content.element或 UI 上切换加载指示器。拦截手势关闭在pinchClose/verticalDrag中调用e.preventDefault()即可禁用捏合/下拉关闭需要同时保留手势动画则只读取bgOpacity/panY做自定义处理。自定义内容类型在contentLoad中为content.type非image的内容创建并赋值content.element完整范式见 docs/custom-content.md。埋点与统计打开埋点放afterInit切页埋点放change结合slide.index或pswp.currIndex关闭埋点放close销毁清理放destroy。绑定 vs 卸载对称性bindEvents打开后绑定全局监听与close解绑是天然的对称配对close中务必解绑你在bindEvents中挂到window上的监听器。最后提醒以上代码示例中的/photoswipe/photoswipe-lightbox.esm.js与/photoswipe/photoswipe.esm.js是官方文档站的资源路径在本仓库中构建产物位于 demo-docs-website/static/photoswipe/含 ESM 与 UMD 格式生产项目中也可通过 npm 安装后按需引入Lightbox 与核心模块分离核心通过pswpModule动态加载以减小首屏体积。若需在源码层面进一步深入事件派发细节可重点阅读 src/js/core/eventable.js、src/js/photoswipe.js、src/js/opener.js、src/js/gestures/gestures.js 与 src/js/slide/content.js。赞分享前端UI库/组件【免费下载链接】PhotoSwipeJavaScript image gallery for mobile and desktop, modular, framework independent项目地址https://gitcode.com/gh_mirrors/ph/PhotoSwipe点击查看免费下载相关推荐mojs动画事件系统从触发到完成的全生命周期mojs动画事件系统从触发到完成的全生命周期 动画交互是现代Web应用提升用户体验的核心手段但要实现流畅自然的动画效果离不开对事件生命周期的精准控制。mo前端Resumable.js事件系统完全指南从文件添加到上传完成的完整生命周期Resumable.js事件系统完全指南从文件添加到上传完成的完整生命周期 Resumable.js是一个强大的JavaScript库专门用于实现可恢复的大前端Uppy插件生命周期终极指南从初始化到销毁的完整过程Uppy插件生命周期终极指南从初始化到销毁的完整过程 Uppy作为一款功能强大的开源文件上传器其插件系统是实现灵活扩展的核心。本文将深入解析Uppy插件从初前端UI组件后端上一篇Mastra工作流重试指南3步配好重试策略5条调优清单下一篇PCSX2模拟器力反馈(FFB)支持的技术演进与优化创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考