Kingfisher 7.12.0

Kingfisher 7.12.0

×

测试已测试✓
语言语言 SwiftSwift
许可证 MIT
发布最后发布2024年6月
SPM支持 SPM✓

由Wei Wang维护。

Kingfisher 7.12.0

Kingfisher

Kingfisher 是一个强大的、纯 Swift 库，用于从网络下载和缓存图像。它为您提供了使用纯 Swift 方式在下一个应用程序中处理远程图像的机会。

特性

  • 异步图像下载和缓存。
  • 从基于 URLSession 的网络或本地提供的数据加载图像。
  • 提供有用的图像处理器和滤镜。
  • 多层混合缓存，包括内存和磁盘。
  • 细粒度控制缓存行为。可自定义过期日期和大小限制。
  • 可取消下载并自动重用先前下载的内容以提高性能。
  • 独立组件。根据需要独立使用下载器、缓存系统和图像处理器。
  • 预取图像并在缓存中显示它们以提升您的应用程序。
  • 为 UIImageView、NSImageView、NSButton、UIButton、NSTextAttachment、WKInterfaceImage、TVMonogramView 和 CPListItem 扩展，可以直接从 URL 设置图像。
  • 设置图像时内置过渡动画。
  • 加载图像时的自定义占位符和指示器。
  • 易于扩展图像处理和图像格式。
  • 支持低数据模式。
  • 支持 SwiftUI。

Kingfisher 入门教程

最简单的用法是用 UIImageView 扩展将图像设置到图像视图

import Kingfisher

let url = URL(string: "https://example.com/image.png")
imageView.kf.setImage(with: url)

Kingfisher 会从 url 下载图片，将其发送到内存缓存和磁盘缓存，并在 imageView 中显示。当你随后使用相同的 URL 设置时，图片将从缓存中检索并立即显示。

如果使用 SwiftUI，它同样有效。

var body: some View {
    KFImage(URL(string: "https://example.com/image.png")!)
}

更高级的示例

有了强大的选项，您可以以简单的方式使用 Kingfisher 完成繁重的任务。例如，下面的代码

  1. 下载高分辨率的图片。
  2. 将其下采样以与图像视图大小匹配。
  3. 使其具有给定半径的圆角。
  4. 在下载时显示系统指示器和占位符图片。
  5. 准备完毕后，它会以淡入效果动画化小缩略图。
  6. 将原始大图片也缓存在磁盘上以供以后使用，避免在详细视图中再次下载。
  7. 任务完成时打印控制台日志，无论是成功还是失败。
let url = URL(string: "https://example.com/high_resolution_image.png")
let processor = DownsamplingImageProcessor(size: imageView.bounds.size)
             |> RoundCornerImageProcessor(cornerRadius: 20)
imageView.kf.indicatorType = .activity
imageView.kf.setImage(
    with: url,
    placeholder: UIImage(named: "placeholderImage"),
    options: [
        .processor(processor),
        .scaleFactor(UIScreen.main.scale),
        .transition(.fade(1)),
        .cacheOriginalImage
    ])
{
    result in
    switch result {
    case .success(let value):
        print("Task done for: \(value.source.url?.absoluteString ?? "")")
    case .failure(let error):
        print("Job failed: \(error.localizedDescription)")
    }
}

这是我在日常工作中经常会遇到的情况。想想如果没有 Kingfisher，你需要写多少代码！

方法链式调用

如果你不喜欢 kf 扩展，你也可以更喜欢使用 KF 构建器和链式方法调用。下面的代码执行相同的操作

// Use `kf` extension
imageView.kf.setImage(
    with: url,
    placeholder: placeholderImage,
    options: [
        .processor(processor),
        .loadDiskFileSynchronously,
        .cacheOriginalImage,
        .transition(.fade(0.25)),
        .lowDataMode(.network(lowResolutionURL))
    ],
    progressBlock: { receivedSize, totalSize in
        // Progress updated
    },
    completionHandler: { result in
        // Done
    }
)

// Use `KF` builder
KF.url(url)
  .placeholder(placeholderImage)
  .setProcessor(processor)
  .loadDiskFileSynchronously()
  .cacheMemoryOnly()
  .fade(duration: 0.25)
  .lowDataModeSource(.network(lowResolutionURL))
  .onProgress { receivedSize, totalSize in  }
  .onSuccess { result in  }
  .onFailure { error in }
  .set(to: imageView)

而且更好的是，如果你后来想切换到 SwiftUI，只需将上面的 KF 改为 KFImage，你就完成了

struct ContentView: View {
    var body: some View {
        KFImage.url(url)
          .placeholder(placeholderImage)
          .setProcessor(processor)
          .loadDiskFileSynchronously()
          .cacheMemoryOnly()
          .fade(duration: 0.25)
          .lowDataModeSource(.network(lowResolutionURL))
          .onProgress { receivedSize, totalSize in  }
          .onSuccess { result in  }
          .onFailure { error in }
    }
}

了解更多

想通过更多示例来学习 Kingfisher 的使用，请查看精心准备的快捷指南 [Cheat Sheet](https://github.com/onevcat/Kingfisher/wiki/Cheat-Sheet)。在那里，我们总结了 Kingfisher 中的常见任务，您可以更好地了解此框架能做什么。同时也有一些性能提示，请务必查看。

需求

  • iOS 12.0+ / macOS 10.14+ / tvOS 12.0+ / watchOS 5.0+（如果您仅使用 UIKit/AppKit）
  • iOS 14.0+ / macOS 11.0+ / tvOS 14.0+ / watchOS 7.0+（如果您使用 SwiftUI）
  • Swift 5.0+

如果您需要从 iOS 10（UIKit/AppKit）或 iOS 13（SwiftUI）获取支持，请使用 Kingfisher 版本 6.x。但它在 Xcode 13.0 和 Xcode 13.1 上将不起作用 #1802。

如果您需要使用 Xcode 13.0 和 13.1 但无法升级到 v7，请使用 version6-xcode13 分支。但是，由于另一个 Xcode 13 bugs，您必须放弃对 iOS 10 的支持。

UIKit SwiftUI Xcode Kingfisher
iOS 10+ iOS 13+ 12 ~> 6.3.1
iOS 11+ iOS 13+ 13 version6-xcode13
iOS 12+ iOS 14+ 13 ~> 7.0

安装

有关安装的详细指南，请参阅 安装指南。

Swift 包管理器

  • 文件 > Swift 包 > 添加包依赖关系
  • 添加 https://github.com/onevcat/Kingfisher.git
  • 选择 "Next Major" 与 "7.0.0"

CocoaPods

source 'https://github.com/CocoaPods/Specs.git'
platform :ios, '12.0'
use_frameworks!

target 'MyApp' do
  pod 'Kingfisher', '~> 7.0'
end

Carthage

github "onevcat/Kingfisher" ~> 7.0

迁移

Kingfisher 7.0 迁移指南 - Kingfisher 7.x 与之前的版本不完全兼容。然而，更改应该是微不足道的或者根本不需要。当您准备在项目中升级 Kingfisher 时，请遵循迁移指南。

如果使用的是更早的版本，请参阅以下指南了解迁移步骤。

  • Kingfisher 6.0 迁移指南 - Kingfisher 6.x 与之前的版本不完全兼容。然而，迁移不太困难。根据您的用例，可能需要几分钟到几分钟来修改您现有的代码以适应新版本。当您准备在项目中升级 Kingfisher 时，请遵循迁移指南。
  • Kingfisher 5.0 迁移指南 - 如果您从 4.x 升级到 Kingfisher 5.x，请阅读此信息以获取更多信息。
  • Kingfisher 4.0 迁移 - Kingfisher 3.x 应该与 Kingfisher 4 源码兼容。进行重大更新的原因是我们需要显式指定 Xcode 的 Swift 版本。所有 Kingfisher 3 中的过时方法都已删除，请在迁移到 Kingfisher 4 时确保没有警告。在迁移过程中遇到任何问题时，请打开一个问题进行讨论。
  • Kingfisher 3.0 迁移指南 - 如果您是从较早版本升级到 Kingfisher 3.x，请阅读此信息以获取更多信息。

下一步

我们准备了一个wiki 页面。您可以在那里找到大量有用的信息。

  • 安装指南 - 遵循它将 Kingfisher 集成到您的项目中。
  • 速查表 - 对 Kingfisher 能做什么以及在您的项目中如何使用它感兴趣吗？查看此页面获取有用的代码片段。如果您已经熟悉 Kingfisher，您还可以学习一些新技巧，以改进您使用 Kingfisher 的方式！
  • API 参考 - 最后，请记住在需要更多详细文档时阅读完整的 API 参考。

其他

Kingfisher 的未来

我希望保持 Kingfisher 体积小巧。这个框架专注于提供下载和缓存图像的简单解决方案。这并不意味着框架不能得到改进。Kingfisher 远未完美，所以将进行必要的和有用的更新，使其变得更好。

开发和测试

欢迎任何贡献和拉取请求。然而，在您计划实现一些功能或尝试修复一个不确定的问题之前，建议首先发起一个讨论。如果您能够使所有测试都绿色的拉取请求将会非常感激：）

关于标志

金鱼鸟标志的设计灵感来源于七巧板，这是一款由七个平面形状组成的解谜游戏，源自中国。我认为它像一只金鱼鸟，而不是鸥，但有人坚称它是一只鸽子。我想给它取个名字。嗨，朋友们，你们有什么建议吗？

联系方式

在Twitter或新浪微博上关注和联系我。如果发现任何问题，请提交工单。欢迎提交拉取请求。

赞助商

开源项目离不开您的帮助。如果您觉得Kingfisher项目有用，请考虑通过成为赞助商的方式来支持本项目。您的用户图标或公司logo将出现在我的博客上，并附有链接到您的首页。

通过GitHub Sponsors成为赞助商。❤️

特别感谢

imgly

许可协议

Kingfisher遵循MIT许可协议。详细信息请参阅LICENSE。