kingfisher

Kingfisher é uma biblioteca poderosa, em Swift puro, para baixar e armazenar imagens da web. Ela oferece uma maneira totalmente em Swift de trabalhar com imagens remotas no seu próximo app. ## Recursos - Download e cache assíncronos de imagens. - Carregamento de imagens via rede baseada em URLSession ou dados locais fornecidos. - Processadores e filtros de imagem úteis já incluídos. - Cache híbrido em várias camadas, tanto em memória quanto em disco. - Controle refinado do comportamento do cache com data de expiração e limite de tamanho personalizáveis. - Verificação assíncrona opcional do cache no KingfisherManager para evitar bloquear a thread chamadora em checagens do cache em disco. - Download cancelável e reutilização automática de conteúdo baixado anteriormente para melhorar o desempenho. - Componentes independentes: use o downloader, o sistema de cache e os processadores de imagem separadamente conforme necessário. - Pré-carregamento de imagens e exibição a partir do cache para impulsionar seu app. - Extensões para UIImageView, NSImageView, NSButton, UIButton, NSTextAttachment, WKInterfaceImage, TVMonogramView e CPListItem para definir diretamente uma imagem a partir de uma URL. - Animação de transição integrada ao definir imagens. - Placeholder e indicador personalizáveis durante o carregamento de imagens. - Processamento de imagem e formato de imagem facilmente extensíveis. - Suporte a Modo de Baixo Consumo de Dados. - Suporte a SwiftUI. - Preparado para Swift 6 e Swift Concurrency (modo estrito). - Carregamento e cache para Live Photo. ## Kingfisher 101 O caso de uso mais simples é definir uma imagem em uma image view com a extensão UIImageView: ```swift import Kingfisher let url = URL(string: "https://example.com/image.png") imageView.kf.setImage(with: url) ``` O Kingfisher baixará a imagem da url, enviará para o cache em memória e para o cache em disco, e a exibirá na imageView. Quando você definir a mesma URL mais tarde, a imagem será recuperada do cache e mostrada imediatamente. Também funciona se você usar SwiftUI: ```swift var body: some View { KFImage(URL(string: "https://example.com/image.png")!) } ``` ## Um Exemplo Mais Avançado Com as opções poderosas, você pode realizar tarefas difíceis com o Kingfisher de maneira simples. Por exemplo, o código abaixo: 1. Baixa uma imagem em alta resolução. 2. Faz downsampling para corresponder ao tamanho da image view. 3. Aplica cantos arredondados com um raio fornecido. 4. Mostra um indicador do sistema e uma imagem placeholder durante o download. 5. Quando pronta, anima a pequena miniatura com um efeito de "fade in". 6. A imagem grande original também é armazenada em disco para uso posterior, evitando baixá-la novamente em uma tela de detalhes. 7. Um log no console é impresso quando a tarefa termina, seja com sucesso ou falha. ```swift 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)") } } ``` É uma situação comum que encontro no meu trabalho diário. Pense em quantas linhas você precisaria escrever sem o Kingfisher! ## Encadeamento de Métodos Se você não é fã da extensão kf, também pode preferir usar o builder KF e encadear as chamadas de métodos. O código abaixo faz a mesma coisa: ```swift // 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) ``` E melhor ainda, se depois você quiser mudar para SwiftUI, basta trocar o KF acima por KFImage, e pronto: ```swift 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 } } } ``` ## Requisitos ### Branch de desenvolvimento atual - iOS 15.0+ / macOS 12.0+ / tvOS 15.0+ / watchOS 9.0+ / visionOS 1.0+ - Compilador Xcode 26.0+ / Swift 6.2+ ### Kingfisher 8.0 - (UIKit/AppKit) iOS 13.0+ / macOS 10.15+ / tvOS 13.0+ / watchOS 6.0+ / visionOS 1.0+ - (SwiftUI) iOS 14.0+ / macOS 11.0+ / tvOS 14.0+ / watchOS 7.0+ / visionOS 1.0+ - Swift 5.9+ ### Kingfisher 7.0 - (UIKit/AppKit) iOS 12.0+ / macOS 10.14+ / tvOS 12.0+ / watchOS 5.0+ / visionOS 1.0+ - (SwiftUI) iOS 14.0+ / macOS 11.0+ / tvOS 14.0+ / watchOS 7.0+ / visionOS 1.0+ - Swift 5.0+ ## Instalação Consulte um dos tutoriais a seguir para instalar e usar o framework: - [Tutorial UIKit](https://swiftpackageindex.com/onevcat/kingfisher/master/tutorials/kingfisher/gettingstarteduikit) - [Tutorial SwiftUI](https://swiftpackageindex.com/onevcat/kingfisher/master/tutorials/kingfisher/gettingstartedswiftui) Alternativamente, você pode seguir um dos métodos abaixo. ### Swift Package Manager - File > Swift Packages > Add Package Dependency - Adicione `https://github.com/onevcat/Kingfisher.git` - Selecione "Up to Next Major" com "8.0.0" ### CocoaPods ```ruby source 'https://github.com/CocoaPods/Specs.git' platform :ios, '13.0' use_frameworks! target 'MyApp' do pod 'Kingfisher', '~> 8.0' end ``` ### Framework Pré-compilado 1. Abra a página de releases e baixe a versão mais recente do Kingfisher na seção de assets. 2. Arraste o `Kingfisher.xcframework` para o seu projeto e adicione-o ao target (geralmente o target do app). 3. Selecione seu target, na aba "General", encontre a seção "Frameworks, Libraries, and Embedded Content", defina `Embed Without Signing` para Kingfisher. ## Documentação Confira a documentação e os tutoriais: - [Página Inicial da Documentação](https://swiftpackageindex.com/onevcat/kingfisher/master/documentation/kingfisher) - [Primeiros Passos](https://swiftpackageindex.com/onevcat/kingfisher/master/documentation/kingfisher/gettingstarted) - [Tutorial UIKit](https://swiftpackageindex.com/onevcat/kingfisher/master/tutorials/kingfisher/gettingstarteduikit) - [Tutorial SwiftUI](https://swiftpackageindex.com/onevcat/kingfisher/master/tutorials/kingfisher/gettingstartedswiftui) - [Tarefas Comuns - Geral](https://swiftpackageindex.com/onevcat/kingfisher/master/documentation/kingfisher/commontasks) - [Tarefas Comuns - Cache](https://swiftpackageindex.com/onevcat/kingfisher/master/documentation/kingfisher/commontasks_cache) - [Tarefas Comuns - Downloader](https://swiftpackageindex.com/onevcat/kingfisher/master/documentation/kingfisher/commontasks_downloader) - [Tarefas Comuns - Processor](https://swiftpackageindex.com/onevcat/kingfisher/master/documentation/kingfisher/commontasks_processor) ### Migração - [Migração para Kingfisher 8.0](https://swiftpackageindex.com/onevcat/kingfisher/master/documentation/kingfisher/migration-to-8) - [Migração para Kingfisher 7.0](https://github.com/onevcat/Kingfisher/wiki/Kingfisher-7.0-Migration-Guide) Se você estiver usando uma versão ainda mais antiga, veja os guias abaixo para saber os passos de migração. ## Outros ### Futuro do Kingfisher Quero manter o Kingfisher leve. Este framework foca em fornecer uma solução simples para baixar e armazenar imagens. Isso não significa que o framework não possa ser melhorado. O Kingfisher está longe de ser perfeito, então atualizações necessárias e úteis serão feitas para torná-lo melhor. ### Desenvolvimento e Testes Qualquer contribuição e pull request são muito bem-vindos. No entanto, antes de planejar implementar alguns recursos ou tentar corrigir um problema incerto, é recomendável abrir uma discussão primeiro. Seria apreciado se seus pull requests pudessem compilar com todos os testes passando. :) ### Sobre o logo O logo do Kingfisher é inspirado no Tangram (七巧板), um quebra-cabeça de dissecação composto por sete formas planas da China. Acredito que ela seja um pássaro kingfisher em vez de um swift, mas alguém insiste que ela é um pombo. Acho que deveria dar um nome a ela. Ei, pessoal, vocês têm alguma sugestão? ### Contato Siga e entre em contato comigo no Twitter ou Sina Weibo. Se encontrar um problema, abra uma issue. Pull requests também são muito bem-vindos. ## Apoiadores e Patrocinadores Projetos open-source não vivem muito sem sua ajuda. Se você acha o Kingfisher útil, considere apoiar este projeto tornando-se um patrocinador. Seu ícone de usuário ou logo da empresa aparece no meu blog com um link para sua página inicial. Torne-se um patrocinador pelo GitHub Sponsors. :heart: Agradecimentos especiais a imgly e emergetools. ### Licença Kingfisher é distribuído sob a licença MIT. Veja LICENSE para detalhes.