AXPhotoViewer 配置实战AXPagingConfig 翻页方向与照片间距完全指南【免费下载链接】AXPhotoViewerAn iOS/tvOS photo gallery viewer, useful for viewing a large (or small!) number of photos.项目地址: https://gitcode.com/gh_mirrors/ax/AXPhotoViewerAXPhotoViewer 是一款开源的 iOS/tvOS 照片浏览器Photo Gallery Viewer适合展示几十张甚至上千张图片并原生支持 GIF、手势缩放和上下文转场动画。而在它的全部配置项中AXPagingConfig 是最核心的“翻页配置类”它直接决定了照片浏览器的翻页方向水平左右滑动还是垂直上下滑动以及照片间距相邻两张照片之间的留白。这篇指南将带你从零掌握 AXPagingConfig 的每个参数、每种初始化方式并附上可直接套用的 Swift 代码示例。AXPagingConfig 是什么翻页配置的“总开关”AXPagingConfig 定义在 AXPagingConfig.swift 中是一个轻量级的模型类只负责把“翻页相关”的配置打包然后在初始化AXPhotosViewController时一次性传入。它总共暴露三个配置项配置项类型作用navigationOrientationUIPageViewController.NavigationOrientation翻页方向水平或垂直interPhotoSpacingCGFloat照片间距单位是 pt点loadingViewClassAXLoadingViewProtocol.Type自定义加载视图类可选其中前两项就是本篇文章的主角——翻页方向与照片间距。整个库的内部翻页器基于UIPageViewController实现源码中的初始化代码是这样的self.pageViewController UIPageViewController(transitionStyle: .scroll, navigationOrientation: self.pagingConfig.navigationOrientation, options: [.interPageSpacing: self.pagingConfig.interPhotoSpacing])也就是说你传给 AXPagingConfig 的值最终会原样映射到系统分页器的方向与页间距上理解这一点对后面排查问题非常有帮助。快速上手AXPagingConfig 默认配置与基本用法如果你不传任何配置AXPagingConfig 会使用一套开箱即用的默认值水平翻页方向.horizontal 20pt 照片间距默认间距常量DefaultHorizontalSpacing 20定义在源码文件顶部。最小可运行示例只需要三行let dataSource AXPhotosDataSource(photos: self.photos) let pagingConfig AXPagingConfig() let photosViewController AXPhotosViewController(dataSource: dataSource, pagingConfig: pagingConfig) self.present(photosViewController, animated: true)需要提醒的是navigationOrientation和interPhotoSpacing都是fileprivate(set)只读属性也就是说它们只能在初始化时确定之后无法通过属性赋值修改。想换方向或改间距就得重新构造一个 AXPagingConfig 再创建控制器。翻页方向navigationOrientation怎么设置翻页方向是用户体验的第一感受代码里只需要一个枚举值// 水平翻页左右滑动切换照片默认 let horizontalConfig AXPagingConfig(navigationOrientation: .horizontal) // 垂直翻页上下滑动切换照片类似 Instagram 信息流的上下浏览 let verticalConfig AXPagingConfig(navigationOrientation: .vertical)两种方向分别适合什么场景水平翻页最经典的照片浏览器交互左右滑动像翻相册绝大多数相册类 App 都采用这种模式。垂直翻页适合竖屏长内容浏览比如瀑布流、信息流式看图体验配合竖直方向的长图例如示例工程里的哈利法塔长图观感更佳。参考示例工程 TableViewController.swift 的写法配置好之后通过AXPhotosViewController(dataSource:pagingConfig:transitionInfo:)传入即可生效转场、缩放、手势下滑关闭等功能都会自动适配新的翻页方向。照片间距interPhotoSpacing怎么设置照片间距控制相邻两张图之间的留白宽度单位是 pt可以是 0 也可以是任意正数// 间距为 0照片之间无缝衔接类似连屏效果 let seamlessConfig AXPagingConfig(interPhotoSpacing: 0) // 间距为 30更宽松的留白视觉上更透气 let airyConfig AXPagingConfig(interPhotoSpacing: 30)这个间距值最终会传给UIPageViewController的.interPageSpacing选项所以它既会拉开相邻页面的视觉距离也会影响滑动切换时的“吸边”手感。一般建议在 1030pt 之间取值过大的间距会让快速连翻时略显松散。完整配置示例一次性设置方向、间距与加载视图AXPagingConfig 提供了一个全参数初始化方法以及四个便捷初始化方法覆盖了几乎所有组合场景// 完整配置垂直翻页 40pt 间距 自定义加载视图 let config AXPagingConfig(navigationOrientation: .vertical, interPhotoSpacing: 40, loadingViewClass: CustomLoadingView.self) let photosViewController AXPhotosViewController(dataSource: dataSource, pagingConfig: config, transitionInfo: transitionInfo)四个便捷初始化方法的“快捷语义”如下AXPagingConfig()水平 20pt 间距AXPagingConfig(navigationOrientation:)自定义方向 默认 20pt 间距AXPagingConfig(interPhotoSpacing:)默认水平方向 自定义间距AXPagingConfig(loadingViewClass:)水平 20pt 自定义加载视图其中loadingViewClass必须是一个 UIView 的子类并遵循AXLoadingViewProtocol协议否则会触发断言失败源码里做了assertionFailure校验。示例工程中的 CustomLoadingView.swift 就是一个现成的参考实现。实战经验与注意事项最后分享几个配置 AXPagingConfig 时容易踩的坑配置需在初始化时完成方向和间距都是只读属性控制器创建后无法热更新设计页面时需要提前定好方案。间距与方向要配套理解水平翻页时间距体现在左右两侧垂直翻页时体现在上下两侧库内部在计算可见页时会根据方向自动把间距换算进布局。预加载行为交给数据源翻页体验还受AXPhotosDataSource的prefetchBehavior影响如果照片很多建议配合.aggressive预加载模式让连翻更流畅。多平台一致可用AXPagingConfig 同时适用于 iOS 和 tvOSApple TV 上同样可以通过遥控器方向键切换照片。总结AXPagingConfig 虽然只有三个配置项却掌控着照片浏览器的骨架体验翻页方向决定用户怎么划照片间距决定观感舒不舒服。通过本文的指南你已经掌握了它的全部初始化方式与默认值规律可以按需组合出水平/垂直、紧凑/宽松的任意浏览方案。想让相册浏览更顺手从配置好 AXPagingConfig 开始吧。【免费下载链接】AXPhotoViewerAn iOS/tvOS photo gallery viewer, useful for viewing a large (or small!) number of photos.项目地址: https://gitcode.com/gh_mirrors/ax/AXPhotoViewer创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考