Kingfisher Swift: методы, примеры, установка

Введение в Kingfisher: что это и зачем нужно

Kingfisher — это мощная и популярная библиотека для Swift, предназначенная для загрузки и кэширования изображений из сети. Она предоставляет разработчикам простой, но гибкий API для работы с изображениями в iOS, macOS, tvOS и watchOS приложениях. Библиотека написана на чистом Swift и активно поддерживается сообществом.

Зачем нужен Kingfisher? В современных мобильных приложениях работа с изображениями — одна из ключевых задач. Пользователи ожидают быстрой загрузки контента, плавного скроллинга и минимального потребления трафика. Kingfisher решает эти проблемы, автоматически управляя загрузкой, кэшированием (в памяти и на диске) и отображением изображений. Вместо того чтобы писать сложный код для управления сетевыми запросами, обработки ошибок и кэширования, вы можете просто вызвать один метод setImage(with:).

Ключевые возможности:

Асинхронная загрузка: изображения загружаются в фоновом потоке, не блокируя UI.
Многоуровневое кэширование: сначала проверяется кэш в памяти (быстрый доступ), затем дисковый кэш (персистентное хранение).
Обработка ошибок: встроенные механизмы для обработки сетевых ошибок, неверных URL и поврежденных данных.
Поддержка GIF и SVG: возможность отображения анимированных изображений и векторной графики.
Трансформации изображений: встроенные методы для изменения размера, обрезки, наложения фильтров и округления углов.
Интеграция с UIKit и AppKit: расширения для UIImageView, NSImageView, UIButton и других элементов.
Отмена загрузки: автоматическая отмена запросов при переиспользовании ячеек в UITableView/UICollectionView.

Kingfisher — это не просто загрузчик изображений, это полноценный фреймворк для управления медиа-контентом, который экономит часы разработки и повышает производительность приложения.

Установка Kingfisher

Kingfisher можно установить несколькими способами. Рекомендуемый метод — через Swift Package Manager (SPM), так как это нативный инструмент для управления зависимостями в Swift.

1. Swift Package Manager (SPM) — Рекомендуемый способ

Откройте ваш проект в Xcode, перейдите в File → Add Packages... и вставьте URL репозитория:

https://github.com/onevcat/Kingfisher.git

Выберите версию (рекомендуется "Up to Next Major Version" с последней стабильной версией) и добавьте пакет в ваш таргет.

2. CocoaPods

Добавьте в ваш Podfile:

pod 'Kingfisher', '~> 7.0'

Затем выполните в терминале:

pod install

3. Carthage

Добавьте в ваш Cartfile:

github "onevcat/Kingfisher" ~> 7.0

Затем выполните:

carthage update

4. Ручная установка

Скачайте последний релиз с GitHub и добавьте файлы из папки Sources/Kingfisher в ваш проект.

После установки не забудьте импортировать библиотеку в файлах, где вы планируете её использовать:

import Kingfisher

Быстрый старт: первый пример

Давайте начнем с самого простого примера — загрузка изображения по URL и отображение его в UIImageView. Это базовая операция, с которой начинается работа с Kingfisher.

import UIKit
import Kingfisher

class ViewController: UIViewController {
    @IBOutlet weak var imageView: UIImageView!
    
    override func viewDidLoad() {
        super.viewDidLoad()
        
        let url = URL(string: "https://example.com/image.jpg")!
        imageView.kf.setImage(with: url)
    }
}

В этом примере мы вызываем метод setImage(with:) на экземпляре UIImageView. Kingfisher автоматически:

Проверяет, есть ли изображение в кэше (сначала в памяти, потом на диске).
Если изображение найдено в кэше — мгновенно отображает его.
Если изображения нет в кэше — загружает его асинхронно по URL.
После загрузки сохраняет изображение в кэш и отображает его.
Если загрузка не удалась — показывает placeholder (если он был задан) или ничего не показывает.

Этот простой пример демонстрирует основную философию Kingfisher: минимум кода для максимум функциональности.

Основные методы и функции Kingfisher

Ниже представлены ключевые методы библиотеки с подробным описанием, параметрами и примерами кода.

1. `setImage(with:placeholder:options:completionHandler:)`

Что делает: Основной метод для загрузки и отображения изображения. Он доступен как расширение для UIImageView, NSImageView, UIButton и других элементов. Это самый часто используемый метод в Kingfisher.

Параметры:

with (URL?) — URL изображения для загрузки.
placeholder (Placeholder?) — изображение, которое отображается во время загрузки. Может быть UIImage, GIF или nil.
options (KingfisherOptionsInfo?) — словарь опций для настройки загрузки (таймаут, кэширование, трансформации и т.д.).
completionHandler ((Result<RetrieveImageResult, KingfisherError>) -> Void)? — замыкание, вызываемое после завершения загрузки (успех или ошибка).

Пример кода:

let url = URL(string: "https://example.com/photo.png")!
let placeholder = UIImage(named: "placeholder")

imageView.kf.setImage(
    with: url,
    placeholder: placeholder,
    options: [
        .transition(.fade(0.3)), // плавное появление
        .cacheMemoryOnly         // кэшировать только в памяти
    ],
    completionHandler: { result in
        switch result {
        case .success(let value):
            print("Изображение загружено: \(value.source.url?.absoluteString ?? "")")
        case .failure(let error):
            print("Ошибка загрузки: \(error.localizedDescription)")
        }
    }
)

2. `setImage(with:placeholder:options:progressBlock:completionHandler:)`

Что делает: Расширенная версия метода setImage с возможностью отслеживания прогресса загрузки. Полезно для отображения индикатора загрузки.

Параметры: Те же, что и в предыдущем методе, плюс:

progressBlock ((Int64, Int64) -> Void)? — замыкание, которое вызывается во время загрузки. Первый параметр — количество загруженных байт, второй — общий размер.

Пример кода:

imageView.kf.setImage(
    with: url,
    placeholder: placeholder,
    progressBlock: { receivedSize, totalSize in
        let progress = Float(receivedSize) / Float(totalSize)
        print("Прогресс: \(progress * 100)%")
    },
    completionHandler: { result in
        // обработка результата
    }
)

3. `cancelDownloadTask()`

Что делает: Отменяет текущую задачу загрузки изображения для данного элемента (UIImageView, UIButton и т.д.). Очень полезно при переиспользовании ячеек в таблицах и коллекциях, чтобы избежать загрузки старых изображений.

Параметры: Нет.

Пример кода:

// В методе prepareForReuse ячейки UITableView
override func prepareForReuse() {
    super.prepareForReuse()
    imageView.kf.cancelDownloadTask()
    imageView.image = nil // сброс изображения
}

4. `downloadTask(with:options:completionHandler:)`

Что делает: Загружает изображение по URL без привязки к конкретному UI-элементу. Возвращает объект DownloadTask, который можно использовать для отмены загрузки или отслеживания прогресса. Полезно для предзагрузки изображений или работы с ними в фоновом режиме.

Параметры:

with (URL) — URL изображения.
options (KingfisherOptionsInfo?) — опции загрузки.
completionHandler ((Result<RetrieveImageResult, KingfisherError>) -> Void)? — замыкание с результатом.

Пример кода:

let task = KingfisherManager.shared.downloadTask(
    with: url,
    options: [.cacheMemoryOnly]
) { result in
    switch result {
    case .success(let value):
        let image = value.image
        // Используем изображение
    case .failure(let error):
        print("Ошибка: \(error)")
    }
}

// При необходимости можно отменить
task?.cancel()

5. `cache(_:forKey:toDisk:serializer:)`

Что делает: Сохраняет изображение в кэш Kingfisher вручную. Это может быть полезно, если вы загрузили изображение другим способом (например, через URLSession) и хотите добавить его в кэш Kingfisher для последующего использования.

Параметры:

_ (Image) — изображение для кэширования.
forKey (String) — ключ, по которому изображение будет сохранено в кэше. Обычно это URL строкой.
toDisk (Bool) — сохранять ли на диск (true) или только в память (false).
serializer (CacheSerializer?) — сериализатор для преобразования изображения в данные.

Пример кода:

let image = UIImage(named: "localImage")!
let cache = KingfisherManager.shared.cache

// Сохраняем в кэш с ключом "my_custom_key"
cache.store(image, forKey: "my_custom_key", toDisk: true)

// Позже можно загрузить из кэша
cache.retrieveImage(forKey: "my_custom_key") { result in
    switch result {
    case .success(let value):
        if let cachedImage = value.image {
            // Используем изображение
        }
    case .failure(let error):
        print("Ошибка получения из кэша: \(error)")
    }
}

6. `retrieveImage(forKey:options:callbackQueue:completionHandler:)`

Что делает: Извлекает изображение из кэша по ключу. Сначала проверяется кэш в памяти, затем на диске. Если изображение не найдено, возвращается ошибка.

Параметры:

forKey (String) — ключ для поиска.
options (KingfisherOptionsInfo?) — опции для извлечения.
callbackQueue (CallbackQueue?) — очередь, в которой будет вызван completionHandler.
completionHandler ((Result<ImageCacheResult, KingfisherError>) -> Void) — замыкание с результатом.

Пример кода:

KingfisherManager.shared.cache.retrieveImage(
    forKey: "https://example.com/image.jpg",
    options: nil
) { result in
    switch result {
    case .success(let cacheResult):
        if let image = cacheResult.image {
            print("Изображение найдено в кэше: \(cacheResult.cacheType)")
        } else {
            print("Изображение не найдено")
        }
    case .failure(let error


                
    
  Также в библиотеке
  
                
                  
                 Логирование для PHP: лучшие решения и библиотеки
      
                
                  
                 Mongoose Paginate для JavaScript (Node.js): полное руководство с примерами
      
                
                  
                 Авторизация и аутентификация в Rust: библиотеки и инструменты
      
                
                  
                 Awaitility для Java: полное руководство с примерами
      
                
                  
                 Работа с Apache Kafka в Swift (iOS/macOS): библиотеки и примеры