Agrume

Swift 编写的 iOS 图片查看器，支持多张图片。

需求

Swift 5.0
iOS 9.0+
Xcode 10.2+

安装

或者 CocoaPods。将依赖项添加到您的 Podfile，然后运行 pod install

pod "Agrume"

或者 Carthage。将依赖项添加到您的 Cartfile，然后运行 carthage update

github "JanGorman/Agrume"

使用方法

您可以使用多种方式使用图片查看器（提供的示例项目显示了所有方法）。

对于一张图片来说，这样操作就足够简单：

基本

import Agrume

private lazy var agrume = Agrume(image: UIImage(named: "…")!)

@IBAction func openImage(_ sender: Any) {
  agrume.show(from: self)
}

您还可以传递一个 URL ，Agrume 会为您处理下载。

SwiftUI

当前 SwiftUI 实现没有公开配置，因此只能用作单张图片的基本查看器 - 欢迎提交 PR 来扩展其功能。

import Agrume

struct ExampleView: View {
    
  let images: [UIImage]

  @State var showAgrume = false

  var body: some View {
    VStack {
      // Hide the presenting button (or other view) whenever Agrume is shown
      if !showAgrume {
        Button("Launch Agrume from SwiftUI") {
          withAnimation {
            showAgrume = true
          }
        }
      }

      if showAgrume {
        // You can pass a single or multiple images
        AgrumeView(images: images, isPresenting: $showAgrume)
      }
    }
  }
}

背景配置

Agrume 有不同的背景配置。您可以使其模糊覆盖的视图或提供背景颜色

let agrume = Agrume(image: UIImage(named: "…")!, background: .blurred(.regular))
// or
let agrume = Agrume(image: UIImage(named: "…")!, background: .colored(.green))

多张图片

如果您正在显示 UICollectionView 并希望支持缩放，您也可以使用包含图像或 URL 数组的 Agrume。

// In case of an array of [UIImage]:
let agrume = Agrume(images: images, startIndex: indexPath.item, background: .blurred(.light))
// Or an array of [URL]:
// let agrume = Agrume(urls: urls, startIndex: indexPath.item, background: .blurred(.light))

agrume.didScroll = { [unowned self] index in
  self.collectionView.scrollToItem(at: IndexPath(item: index, section: 0), at: [], animated: false)
}
agrume.show(from: self)

这显示了保持已缩放库与背景中的库同步的方法。

动画 GIF

Agrume 内置了 SwiftyGif 以显示动画 GIF。您使用 SwiftyGif 的自定义 UIImage 初始化器

let image = UIImage(gifName: "animated.gif")
let agrume = Agrume(image: image)
agrume.display(from: self)

// Or gif using data:

let image = UIImage(gifData: data)
let agrume = Agrume(image: image)

// Or multiple images:

let images = [UIImage(gifName: "animated.gif"), UIImage(named: "foo.png")] // You can pass both animated and regular images at the same time
let agrume = Agrume(images: images)

支持远程动画 GIF（即使用 url 或 urls 初始化器）。Agrume 执行图像类型检测并正确显示它们。如果从自定义的 UIImageView 使用 Agrume，您可能需要使用原始数据重建 UIImage 以保留动画，而不是使用从图像视图获取的 UIImage 实例。

关闭按钮

默认情况下，您可以通过将图像拖离屏幕或快速滑动手势来关闭缩放视图。您可以选择退出此行为，并显示一个关闭按钮。为了使界面与您的应用程序相匹配，您可以传递一个自定义的 UIBarButtonItem

// Default button that displays NSLocalizedString("Close", …)
let agrume = Agrume(image: UIImage(named: "…")!, .dismissal: .withButton(nil))
// Customise the button any way you like. For example display a system "x" button
let button = UIBarButtonItem(barButtonSystemItem: .stop, target: nil, action: nil)
button.tintColor = .red
let agrume = Agrume(image: UIImage(named: "…")!, .dismissal: .withButton(button))

所提供的示例应用程序显示了这两种情况以供参考。

自定义下载处理

如果您想要控制图像的下载（例如，为了缓存），您也可以设置一个回调到 Agrume 以设置图像的下载闭包。例如，让我们使用 MapleBacon。

import Agrume
import MapleBacon

private lazy var agrume = Agrume(url: URL(string: "https://dl.dropboxusercontent.com/u/512759/MapleBacon.png")!)

@IBAction func openURL(_ sender: Any) {
  agrume.download = { url, completion in
    Downloader.default.download(url) { image in
      completion(image)
    }
  }
  agrume.show(from: self)
}

全局自定义下载处理

您不需要在每个实例上定义处理程序，而是可以在 AgrumeServiceLocator 上设置处理程序。Agrume 将使用此处理程序进行所有下载，除非如上所述在实例中覆盖

import Agrume

AgrumeServiceLocator.shared.setDownloadHandler { url, completion in
  // Download data, cache it and call the completion with the resulting UIImage
}

// Some other place
agrume.show(from: self)

自定义数据源

对于更动态的库需求，您可以实现 AgrumeDataSource 协议，为 Agrume 提供图像。Agrume 将查询数据源以获取图像数量，如果该数量发生变化，它将重新加载其滚动图像视图。

import Agrume

let dataSource: AgrumeDataSource = MyDataSourceImplementation()
let agrume = Agrume(dataSource: dataSource)

agrume.show(from: self)

状态栏外观

您可以在显示缩放视图时自定义状态栏的外观。Agrume 有一个 statusBarStyle 属性

let agrume = Agrume(image: image)
agrume.statusBarStyle = .lightContent
agrume.show(from: self)

长按手势和图片下载

如果您想处理图像上的长按手势，存在一个可选的 onLongPress 闭包。这将传递一个可选的 UIImage 和 Agrume UIViewController 的引用作为参数。项目中包括一个辅助类 AgrumePhotoLibraryHelper，可以轻松地选择将图像下载到用户的相册。首先创建辅助类的实例

private func makeHelper() -> AgrumePhotoLibraryHelper {
  let saveButtonTitle = NSLocalizedString("Save Photo", comment: "Save Photo")
  let cancelButtonTitle = NSLocalizedString("Cancel", comment: "Cancel")
  let helper = AgrumePhotoLibraryHelper(saveButtonTitle: saveButtonTitle, cancelButtonTitle: cancelButtonTitle) { error in
    guard error == nil else {
      print("Could not save your photo")
      return
    }
    print("Photo has been saved to your library")
  }
  return helper
}

然后将此辅助类的长按处理程序传递给 Agrume，如下所示

let helper = makeHelper()
agrume.onLongPress = helper.makeSaveToLibraryLongPressGesture

自定义覆盖视图

您可以自定义图像视图的外观和功能。为此，您需要创建一个继承自 AgrumeOverlayView: UIView 的类。作为这是一个普通的 UIView，您可以对其进行任何操作，如添加自定义工具栏或按钮。示例应用展示了如何实现的详细示例。

实时文本支持

Agrume 支持 iOS 16 及更高版本中引入的实时文本。这使得用户可以在图像中与文本和二维码进行交互。这适用于 iOS 16 或更高版本，设备需要配备 A12 仿生芯片（iPhone XS）或更高版本。

let agrume = Agrume(image: UIImage(named: "…")!, enableLiveText: true)

生命周期

Agrume 提供以下生命周期闭包，您可以选择设置

willDismiss
didDismiss
didScroll

运行示例代码

本项目附带一个示例应用程序，展示了上述文档中记录的不同功能。由于依赖SwiftyGif库，因此您还需要获取该库才能运行项目。SwiftyGif作为git子模块包含在内。在获取仓库后，从项目的根目录运行：

git submodule update --init

许可证

Agrume使用MIT许可证发布。详情请见LICENSE文件

Agrume 5.8.10

Agrume 5.8.10

Agrume 5.8.10

Agrume

需求

安装

使用方法

基本

SwiftUI

背景配置

多张图片

动画 GIF

关闭按钮

自定义下载处理

全局自定义下载处理

自定义数据源

状态栏外观

长按手势和图片下载

自定义覆盖视图

实时文本支持

生命周期

运行示例代码

许可证