虚构

目录

• 描述
• 使用方法
  • 基础
  • 高级
  • 配置
  • 图像获取器
• 安装

描述

如今，在应用程序中使用远程图像几乎是必需的。这个过程应该简单、直接且无烦恼，而使用Imaginary就实现了这一点。这个库提供了一个窄而灵活的公共API和一系列内置的特别功能

• 异步图像下载
• 基于Cache的内存和磁盘缓存
• 图像解压缩
• 默认过渡动画
• 可以预处理和修改原始图像
• 适用于任何视图，包括ImageView、Button等
• 支持iOS、tvOS、macOS

使用方法

在最常见的情况下，您希望将远程图片从 URL 设置到 ImageView。 Imaginary 执行下载和缓存图像的重任。缓存通过 2 个缓存层（内存和磁盘）进行，以实现快速检索。它还为您管理有效期。好消息是，您可以自定义大多数这些功能。

基本

使用 URL 设置图像

只需传递 URL 进行获取。

let imageUrl = URL(string: "https://avatars2.githubusercontent.com/u/1340892?v=3&s=200")
imageView.setImage(url: imageUrl)

使用占位符

占位符是可选的。但是在图片正在获取的过程中，如果用户能看到一些内容，他们会感到更愉悦。

let placeholder = UIImage(named: "PlaceholderImage")
let imageUrl = URL(string: "https://avatars2.githubusercontent.com/u/1340892?v=3&s=200")

imageView.setImage(url: imageUrl, placeholder: placeholder)

在图像获取时使用回调

如果您想获取更多有关获取结果的信息，可以将闭包作为 completion 传递。

imageView.setImage(url: imageUrl) { result in
  switch result {
  case .value(let image):
    print(image)
  case .error(let error):
    print(error)
  }
}

result 是一个枚举 Result，让您知道操作是否成功或失败。可能出现的错误是 ImaginaryError。

高级

传递选项

在获取图片时，您还可以传递Option，这允许对获取过程进行精确控制。Option默认不使用预处理器，并为ImageView提供一个显示器。

let option = Option()
imageView.setImage(url: imageUrl, option: option)

预处理

图片是在后台进行获取、解压缩和预处理的。如果想要修改，只需实现自己的ImageProcessor并在Option中指定它。预处理是在将图片设置为视图之前在后台完成的。

public protocol ImageProcessor {
  func process(image: Image) -> Image
}

这是在设置图片之前应用色调颜色的方法。

let option = Option(imagePreprocessor: TintImageProcessor(tintColor: .orange))
imageView.setImage(url: imageUrl, option: option)

Imaginary提供以下内置预处理器

• TintImageProcessor：使用颜色混合效果应用色调颜色
• ResizeImageProcessor：调整大小
• RoundImageProcessor：制作圆角

显示

Imaginary支持任何View，可以是UIImageView、UIButton、MKAnnotationView、UINavigationBar等。如您所见，获取方法相同，区别在于图片的显示方式。为了避免代码重复，Imaginary利用Swift协议来允许完全自定义。

您可以通过遵守ImageDisplayer来创建自己的displayer，并在Option中指定它

public protocol ImageDisplayer {
  func display(placeholder: Image, onto view: View)
  func display(image: Image, onto view: View)
}

这是为UIButton设置图片的方法

let option = Option(imageDisplayer: ButtonDisplayer())
button.setImage(url: imageUrl, option: option)

let option = Option(imageDisplayer: ImageDisplayer(animationOption: .transitionCurlUp))
imageView.setImage(url: imageUrl, option: option)

以下是内置的显示器。您需要为您的视图提供正确的显示器

• ImageDisplayer：在UI|NSImageView上显示。这是默认的，带有交叉溶解动画。
• ButtonDisplayer：使用setImage(_ image: UIImage?, for state: UIControlState)在UI|NSButton上显示
• ButtonBackgroundDisplayer：使用setBackgroundImage(_ image: UIImage?, for state: UIControlState)在UI|NSButton上显示

下载

Imaginary在后面使用了ImageFetcher，它包含下载器和存储。您可以指定自己的ImageDownloader与一个modifyRequest闭包，在那里您可以更改请求体或添加更多HTTP头信息。

var option = Option()
option.downloaderMaker = {
  return ImageDownloader(modifyRequest: { 
    var request = $0
    request.addValue("Bearer 123", forHTTPHeaderField: "Authorization")
    return request 
  })
}

imageView.setImage(imageUrl, option: option)

缓存

存储默认为Configuration.storage，但你也可以使用自己的Storage，这允许你根据特定功能分组保存的图片。如果你想强制下载并忽略存储？那么只需返回nil。有关如何配置storage，请参阅存储

var option = Option()
option.storageMaker = {
  return Configuration.imageStorage
}

配置

您可以通过Configuration自定义Imaginary的总体体验。

• trackBytesDownloaded：追踪下载特定图片使用的字节数
• trackError：追踪在获取图片时是否发生了错误。
• imageStorage：所有获取操作所使用的存储。

ImageFetcher

Imaginary在内部使用ImageFetcher。但你也可以将其作为一个独立的组件使用。

ImageDownloader

其主要任务是下载图片并执行各种检查。

let downloader = ImageDownloader()
downloader.download(url: imageUrl) { result in
  // handle result
}

ImageFetcher

它知道如何获取和缓存图片。它会首先检查内存和磁盘缓存看看是否有图片。如果没有，则会执行网络下载。你可以选择通过将存储设置为零nil来忽略缓存。

let fetcher = ImageFetcher(downloader: ImageDownloader(), storage: myStorage()
fetcher.fetch(url: imageUrl) { result in
  // handle result
}

MultipleImageFetcher

有时提前下载图片以提高用户体验是有意义的。我们为您提供了 MultipleImageFetcher

let multipleFetcher = MultipleImageFetcher(fetcherMaker: {
  return ImageFetcher()
})

multipleFetcher.fetch(urls: imageUrls, each: { result in
  // handle when each image is fetched
}, completion: {
  // handle when all images are fetched
})

这对于新的 UICollectionView 的预取模式非常理想

安装

Imaginary 可以通过 CocoaPods 获得。要安装，只需在您的 Podfile 中添加以下行

pod 'Imaginary'

Imaginary 也可以通过 Carthage 获得。要在 Cartfile 中安装，只需写入

github "hyperoslo/Imaginary"

Imaginary 也可以手动安装。只需下载并将 Sources 文件夹拖放到您的项目中。

作者

Hyper Interaktiv AS, [email protected]

许可

Imaginary 在 MIT 许可证下提供。有关更多信息，请参阅 LICENSE 文件。