深挖 Galeria iOS 实现：ImageViewer.swift 与 DynamicTransition 如何打造 1:1 原生体验

深挖 Galeria iOS 实现ImageViewer.swift 与 DynamicTransition 如何打造 1:1 原生体验【免费下载链接】galeriaThe React (Native) Image Viewer. 项目地址: https://gitcode.com/gh_mirrors/ga/galeriaGaleria是一款 React Native 图片查看器Image Viewer组件库它让你在缩略图上轻点一下照片就能飞到全屏查看——而这套丝滑体验在 iOS 上并不是靠 JavaScript 模拟的而是由ImageViewer.swift和DynamicTransition两大原生 Swift 库联手完成。本文将带你以新手视角拆解这套 1:1 原生体验背后的实现原理。为什么 iOS 端手感像原生 App先看一个核心结论Galeria 的 iOS 端几乎没有 JS 参与的动画。JS 层只负责声明有哪些图片、主题是什么真正的过渡动画、缩放、拖拽全部交给原生 Swift 执行。整体架构可以分成三层层角色关键文件TS 声明层桥接 Props 与事件GaleriaView.ios.tsx原生桥接层Expo Module挂载手势与视图GaleriaModule.swift、GaleriaView.swift原生体验层查看器 过渡动画ios/ImageViewer.swift/、ios/Transition/DynamicTransition/TS 侧通过 Expo 的requireNativeView拿到原生视图把urls、theme、onIndexChange等属性透传下去——你可以从 GaleriaView.ios.tsx 看到完整声明。所有魔法都发生在下面两层。第一层ImageViewer.swift——全屏查看器的地基ImageViewer.swift是一个通用的 UIKit 图片查看器库它为普通的UIImageView提供了一个点我就全屏的能力。1. 一张扩展 API 点石成金核心入口是 UIImageView_Extensions.swift 中的setupImageViewer系列方法childImage.setupImageViewer(urls: urlObjects, initialIndex: initialIndex, options: options)一行调用UIImageView就自动获得点击放大、多图画廊、下拉关闭。内部原理是在图片上挂了一个私有手势识别器TapWithDataRecognizer见 UIImageView_Extensions.swift把数据源、加载器、选项全部藏在手势里。2. 占位视图 快照无缝衔接的秘诀用户点下缩略图的瞬间showImageViewer会发生一件很巧妙的事先创建一个透明的占位根视图Placeholder覆盖全屏把真正的ImageViewerRootView查看器本体通过导航栈推上去过渡期间用源图片的快照填充画面避免闪白。查看器本体由 ImageViewerRootView.swift 搭建用UIPageViewController实现左右滑动切换多图、顶部悬浮UINavigationBar显示关闭按钮、双击放大、捏合缩放。3. 图片加载与数据源数据源SimpleImageDatasource.swift 统一管理 URL / 本地UIImage加载器ImageLoader.swift 优先使用SDWebImage如项目中已引入否则回退到URLSession自带下载。这保证了远程图片和本地图片都开箱即用也支持先显示小尺寸缩略图、放大后加载高清图。第二层DynamicTransition——共享元素过渡引擎如果说 ImageViewer.swift 提供了房间那 DynamicTransition 就是让照片飞进房间的传送带。它解决了一个经典难题如何让缩略图生长成全屏图而不是生硬地淡入1. NavigationView没有控制器的导航栈NavigationView.swift 用纯 UIView 模拟了一套 push/pop 导航栈。Galeria 把查看器挂到 Window 上见 UIImageView_Extensions.swift 的pushView(viewerView, animated: true)完全不经过UINavigationController因此过渡过程不受系统默认动画束缚可以逐帧自定义。2. MatchTransition共享元素的核心MatchTransition.swift 是整篇文章最值得看的文件它做了几件关键的事双向匹配通过MatchTransitionDelegate协议分别向背景页和前景页询问你的匹配视图是谁。Galeria 在 GaleriaView.swift 中实现了这个协议——它遍历视图树找到那个UIImageView还会自动继承父容器的圆角所以缩略图是圆角的放大后也自然带圆角帧计算calculateTargetFramesMatchTransition.swift算出缩略图位置与全屏位置的精确矩形再用 scale/center 偏移驱动动画滚动同步过渡期间监听源视图所在UIScrollView的偏移量列表滚动时图片会实时追着你的手指动画结束后自动清理监听。3. 动画驱动Motion 让过渡可中断过渡动画不是UIView.animate一发了事。DynamicTransition 内嵌了一个 Motion 动画库其 AnimationDriver.swift 基于CADisplayLink逐帧驱动并适配 120Hz 高刷屏弹簧/衰减函数SpringFunction.swift 与 DecayFunction.swift 提供物理感可打断交互TransitionPropertyAnimator支持手指接管动画——下拉关闭时松手图片会根据当前速度惯性飞出或弹回见 MatchTransition.swift 中基于 velocity 的shouldDismiss判断触感反馈手势开始时触发UIImpactFeedbackGenerator这正是原生 App 的哒一声。4. 模糊遮罩与阴影过渡时背景会淡入一层模糊BlurOverlayView.swift前景图带阴影容器ShadowContainerView.swift。Galeria 提供了hideBlurOverlay属性一键关闭模糊——这些开关一路从 TS 层GaleriaView.ios.tsx透传到 ImageViewerRootView.swift。串起来看一次点击的完整旅程 把两层拼起来你在 App 里点一下缩略图实际发生的是TS 层Galeria urls{...}的 Props 经 GaleriaModule.swift 写入原生GaleriaView注册GaleriaView.swift 将每个缩略图按组 ID 下标登记进注册表多图画廊关闭时能精确落回原图点击TapWithDataRecognizer触发创建占位视图并pushView全屏查看器过渡MatchTransition计算两个匹配视图的矩形Motion 驱动逐帧插值图片从缩略图位置生长到全屏背景模糊渐入使用中左右滑动切图触发onIndexChange回传 JS键盘状态被自动收起与恢复GaleriaView.swift关闭下拉或点击空白处popView走反向动画图片带着惯性飞回缩略图原位。整个过程 JS 只在第 5 步收到一次回调其余 100% 原生执行——这就是1:1 原生体验的来源。给开发者的三个实用提示 环境要求iOS 16.4且必须启用 New ArchitectureFabric即 React Native 0.79 或 Expo SDK 54BYOICBring Your Own Image ComponentGaleria 不关心你用什么图片组件——react-native、expo-image、solito甚至 Web 的img /都可以包在Galeria.Image里因为 iOS 层只认最终的UIImageView想动手研究建议按 GaleriaView.swift → UIImageView_Extensions.swift → MatchTransition.swift 的顺序阅读从桥接一路追到动画核心约半小时就能吃透整条链路。总结Galeria 的 iOS 实现是一次教科书级的原生库组合ImageViewer.swift提供了全屏查看器骨架DynamicTransition提供了共享元素过渡与可中断动画而 Expo Module 桥接层把两者优雅地缝进了 React 组件树。对新手而言这套源码也是学习共享元素过渡Shared Element Transition在 iOS 上如何落地的绝佳范本。【免费下载链接】galeriaThe React (Native) Image Viewer. 项目地址: https://gitcode.com/gh_mirrors/ga/galeria创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考