Project Icon

SDWebImageSwiftUI

基于SDWebImage的SwiftUI图像加载框架 支持异步缓存与动画

SDWebImageSwiftUI是基于SDWebImage的SwiftUI图像加载框架。该框架提供异步图像加载、内存/磁盘缓存和动画图像播放功能。它包含WebImage和AnimatedImage等符合SwiftUI设计的API,支持占位图、加载选项、进度指示和过渡动画。SDWebImageSwiftUI针对SwiftUI进行了优化,适用于iOS 14+、macOS 11+等平台,为SwiftUI应用提供完整的图像处理方案。

SDWebImageSwiftUI

CI Status Version License Platform Carthage compatible SwiftPM compatible codecov

If you support iOS 15+/macOS 12+ only and don't care about animated image format, try SwiftUI's AsyncImage

What's for

SDWebImageSwiftUI is a SwiftUI image loading framework, which based on SDWebImage.

It brings all your favorite features from SDWebImage, like async image loading, memory/disk caching, animated image playback and performances.

The framework provide the different View structs, which API match the SwiftUI framework guideline. If you're familiar with Image, you'll find it easy to use WebImage and AnimatedImage.

Apple VisionOS

From v3.0.0, SDWebImageSwiftUI can be compiled for visionOS platform. However, due to the lacking package manager support (need tools update), we don't support CocoaPods/SPM yet.

You can only use the Xcode's built-in package manager dependency to build on visionOS.

To run the visionOS example, you need to clone and add both SDWebImage and SDWebImageSwiftUI, open the SDWebImageSwiftUI.xcworkspace and drag those folders to become local package dependency, see: Editing a package dependency as a local package

If you really want to build framework instead of using Xcode's package dependency, following the manual steps below:

  1. Clone SDWebImage, open SDWebImage.xcodeproj and build SDWebImage target for visionOS platform (Change MACH_O_TYPE to static library if you need)
  2. Clone SDWebImageSwiftUI, create directory at Carthage/Build/visionOS and copy SDWebImage.framework into it
  3. Open SDWebImageSwiftUI.xcodeproj and build SDWebImageSwiftUI visionOS target

Features

Since SDWebImageSwiftUI is built on top of SDWebImage, it provide both the out-of-box features as well as advanced powerful features you may want in real world Apps. Check our Wiki when you need:

  • Animated Image full-stack solution, with balance of CPU && RAM
  • Progressive image loading, with animation support
  • Reusable download, never request single URL twice
  • URL Request / Response Modifier, provide custom HTTP Header
  • Image Transformer, apply corner radius or CIFilter
  • Multiple caches system, query from different source
  • Multiple loaders system, load from different resource

You can also get all benefits from the existing community around with SDWebImage. You can have massive image format support (GIF/APNG/WebP/HEIF/AVIF/SVG/PDF) via Coder Plugins, PhotoKit support via SDWebImagePhotosPlugin, Firebase integration via FirebaseUI, etc.

Besides all these features, we do optimization for SwiftUI, like Binding, View Modifier, using the same design pattern to become a good SwiftUI citizen.

Version

This framework is under heavily development, it's recommended to use the latest release as much as possible (including SDWebImage dependency).

This framework follows Semantic Versioning. Each source-break API changes will bump to a major version.

Changelog

This project use keep a changelog format to record the changes. Check the CHANGELOG.md about the changes between versions. The changes will also be updated in Release page.

Contribution

All issue reports, feature requests, contributions, and GitHub stars are welcomed. Hope for active feedback and promotion if you find this framework useful.

Requirements

  • Xcode 14+
  • iOS 14+
  • macOS 11+
  • tvOS 14+
  • watchOS 7+
  • visionOS 1+

for SwiftUI 1.0 (iOS 13)

iOS 14(macOS 11) introduce the SwiftUI 2.0, which keep the most API compatible, but changes many internal behaviors, which breaks the SDWebImageSwiftUI's function.

From v3.0.0, SDWebImageSwiftUI drop iOS 13 support. To use on iOS 13, checkout the latest v2.x version (or using 2.x branch) instead.

for future transition

Since SDWebImage 6.0 will introduce mixed Swift/Objc codebase, this repo will migrate into SDWebImage Core Repo.

But don't worry, we will use the automatic cross module overlay, whic means, you can use:

import SwiftUI
import SDWebImage

to works like:

import SwiftUI
import SDWebImage
import SDWebImageSwiftUI // <-- Automatic infer this

You will automatically link the SDWebImageSwiftUI, and this library's naming will still be preserved in SPM target. So the transition is smooth for most of you, I don't want to bump another major version. The 3.x is the final version for SDWebImageSwiftUI dedicated repo

Note: For super advanced user, if you using some custom Swift toolchain, be sure to pass -Xfrontend -enable-cross-import-overlays

Installation

Swift Package Manager

SDWebImageSwiftUI is available through Swift Package Manager.

  • For App integration

For App integration, you should using Xcode 12 or higher, to add this package to your App target. To do this, check Adding Package Dependencies to Your App about the step by step tutorial using Xcode.

  • For downstream framework

For downstream framework author, you should create a Package.swift file into your git repo, then add the following line to mark your framework dependent our SDWebImageSwiftUI.

let package = Package(
    dependencies: [
        .package(url: "https://github.com/SDWebImage/SDWebImageSwiftUI.git", from: "3.0.0")
    ],
)

CocoaPods

SDWebImageSwiftUI is available through CocoaPods. To install it, simply add the following line to your Podfile:

pod 'SDWebImageSwiftUI'

Carthage

SDWebImageSwiftUI is available through Carthage.

github "SDWebImage/SDWebImageSwiftUI"

Usage

Using WebImage to load network image

  • Supports placeholder and detail options control for image loading as SDWebImage
  • Supports progressive image loading (like baseline)
  • Supports success/failure/progress changes event for custom handling
  • Supports indicator with activity/progress indicator and customization
  • Supports built-in animation and transition, powered by SwiftUI
  • Supports animated image as well!
var body: some View {
    WebImage(url: URL(string: "https://nokiatech.github.io/heif/content/images/ski_jump_1440x960.heic")) { image in
        image.resizable() // Control layout like SwiftUI.AsyncImage, you must use this modifier or the view will use the image bitmap size
    } placeholder: {
            Rectangle().foregroundColor(.gray)
    }
    // Supports options and context, like `.delayPlaceholder` to show placeholder only when error
    .onSuccess { image, data, cacheType in
        // Success
        // Note: Data exist only when queried from disk cache or network. Use `.queryMemoryData` if you really need data
    }
    .indicator(.activity) // Activity Indicator
    .transition(.fade(duration: 0.5)) // Fade Transition with duration
    .scaledToFit()
    .frame(width: 300, height: 300, alignment: .center)
}

Note: This WebImage using Image for internal implementation, which is the best compatible for SwiftUI layout and animation system. But unlike SwiftUI's Image which does not support animated image or vector image, WebImage supports animated image as well (by defaults from v2.0.0).

However, The WebImage animation provide simple common use case, so it's still recommend to use AnimatedImage for advanced controls like progressive animation rendering, or vector image rendering.

@State var isAnimating: Bool = true
var body: some View {
    WebImage(url: URL(string: "https://raw.githubusercontent.com/liyong03/YLGIFImage/master/YLGIFImageDemo/YLGIFImageDemo/joy.gif"), isAnimating: $isAnimating)) // Animation Control, supports dynamic changes
    // The initial value of binding should be true
    .customLoopCount(1) // Custom loop count
    .playbackRate(2.0) // Playback speed rate
    .playbackMode(.bounce) // Playback normally to the end, then reversely back to the start
    // `WebImage` supports advanced control just like `AnimatedImage`, but without the progressive animation support
}

Note: For indicator, you can custom your own as well. For example, iOS 14/watchOS 7 introduce the new ProgressView, which can be easily used via:

WebImage(url: url)
.indicator(.activity)

or you can just write like:

WebImage(url: url)
.indicator {
    Indicator { _, _ in
        ProgressView()
    }
}

Using AnimatedImage to play animation

  • Supports network image as well as local data and bundle image
  • Supports animated image format as well as vector image format
  • Supports animated progressive image loading (like web browser)
  • Supports animation control using the SwiftUI Binding
  • Supports indicator and transition, powered by SDWebImage and Core Animation
  • Supports advanced control like loop count, playback rate, buffer size, runloop mode, etc
  • Supports coordinate with native UIKit/AppKit view
var body: some View {
    Group {
        AnimatedImage(url: URL(string: "https://raw.githubusercontent.com/liyong03/YLGIFImage/master/YLGIFImageDemo/YLGIFImageDemo/joy.gif"), placeholderImage: .init(systemName: "photo")) // Placeholder Image
        // Supports options and context, like `.progressiveLoad` for progressive animation loading
        .onFailure { error in
            // Error
        }
        .resizable() // Resizable like SwiftUI.Image, you must use this modifier or the view will use the image bitmap size
        .indicator(.activity) // Activity Indicator
        .transition(.fade) // Fade Transition
        .scaledToFit() // Attention to call it on AnimatedImage, but not `some View` after View Modifier (Swift Protocol Extension method is static dispatched)
        
        // Supports SwiftUI ViewBuilder placeholder as well
        AnimatedImage(url: url) {
            Circle().foregroundColor(.gray)
        }
        
        // Data
        AnimatedImage(data: try! Data(contentsOf: URL(fileURLWithPath: "/tmp/foo.webp")))
        .customLoopCount(1) // Custom loop count
        .playbackRate(2.0) // Playback speed rate
        
        // Bundle (not Asset Catalog)
        AnimatedImage(name: "animation1.gif", isAnimating: $isAnimating) // Animation control binding
        .maxBufferSize(.max)
        .onViewUpdate { view, context in // Advanced native view coordinate
            // AppKit tooltip for mouse hover
            view.toolTip = "Mouseover Tip"
            // UIKit advanced content mode
            view.contentMode = .topLeft
            // Coordinator, used for Cocoa Binding or Delegate method
            let coordinator = context.coordinator
        }
    }
}

Note: AnimatedImage supports both image url or image data for animated image format. Which use the SDWebImage's Animated ImageView for internal implementation. Pay attention that since this base on UIKit/AppKit representable, some advanced SwiftUI layout and animation system may not work as expected. You may need UIKit/AppKit and Core Animation to modify the native view.

Note: AnimatedImage some methods like .transition, .indicator and .aspectRatio have the same naming as SwiftUI.View protocol methods. But the args receive the different type. This is because AnimatedImage supports to be used with UIKit/AppKit component and animation. If you find ambiguity, use full type declaration instead of the dot expression syntax.

Note: some of methods on AnimatedImage will return some View, a new Modified Content. You'll lose the type related modifier method. For this case, you can either reorder the method call, or use native view (actually SDAnimatedImageView) in .onViewUpdate, use UIKIt/AppKit API for rescue.


// Using UIKit components
var body: some View {
    AnimatedImage(name: "animation2.gif") 
    .indicator(SDWebImageProgressIndicator.default) // UIKit indicator component
    .transition(SDWebImageTransition.flipFromLeft) // UIKit animation transition
}

// Using SwiftUI components
var body: some View {
    AnimatedImage(name: "animation2.gif")
    .indicator(Indicator.progress) // SwiftUI indicator component
    .transition(AnyTransition.flipFromLeft) // SwiftUI animation transition
}

Which View to choose

Why we have two different View types here, is because of current SwiftUI limit. But we're aimed to provide best solution for all use cases.

If you don't need animated image, prefer to use WebImage firstly. Which behaves the seamless as built-in SwiftUI View. If SwiftUI works, it works. If SwiftUI doesn't work, it either :)

If you need simple animated image, use WebImage. Which provide the basic animated image support. But it does not support progressive animation rendering, nor vector image, if you don't care about this.

If you need powerful animated image, AnimatedImage is the one to choose. Remember it supports static image as well, you don't need to check the format, just use as it. Also, some powerful feature like UIKit/AppKit tint color, vector image, symbol image configuration, tvOS layered image, only available in AnimatedImage but not currently in SwfitUI.

But, because AnimatedImage use UIViewRepresentable and driven by UIKit, currently there may be some small incompatible issues between UIKit and SwiftUI layout and animation system, or bugs related to SwiftUI itself. We try our best to match SwiftUI behavior, and provide the same API as WebImage, which make it easy to switch between these two types if needed.

Use ImageManager for your own View type

The ImageManager is a class which conforms to Combine's ObservableObject protocol. Which is the core fetching data source of WebImage we provided.

For advanced use case, like loading image into the complicated View graph which you don't want to use WebImage. You can directly bind your own View type with the Manager.

It looks familiar like SDWebImageManager, but it's built for SwiftUI world, which provide the Source of Truth for loading images. You'd better use SwiftUI's @ObservedObject to bind each single manager instance for your View instance, which automatically update your View's body when image status changed.

struct MyView : View {
    @ObservedObject var imageManager = ImageManager()
    var body: some View {
        // Your custom complicated view graph
        Group {
            if imageManager.image != nil {
                Image(uiImage: imageManager.image!)
            } else {
                Rectangle().fill(Color.gray)
            }
        }
        // Trigger image loading when appear
        .onAppear { self.imageManager.load(url: url) }
        // Cancel image loading when disappear
        .onDisappear { self.imageManager.cancel() }
    }
}

Customization and configuration setup

This framework is based on SDWebImage, which supports advanced customization and configuration to meet different users' demand.

You can register multiple coder plugins for external image format. You can register multiple caches (different paths and config), multiple loaders (URLSession and Photos URLs). You can control the cache expiration date, size, download priority, etc. All in our wiki.

The best place to put these setup code

项目侧边栏1项目侧边栏2
推荐项目
Project Cover

豆包MarsCode

豆包 MarsCode 是一款革命性的编程助手,通过AI技术提供代码补全、单测生成、代码解释和智能问答等功能,支持100+编程语言,与主流编辑器无缝集成,显著提升开发效率和代码质量。

Project Cover

问小白

问小白是一个基于 DeepSeek R1 模型的智能对话平台,专为用户提供高效、贴心的对话体验。实时在线,支持深度思考和联网搜索。免费不限次数,帮用户写作、创作、分析和规划,各种任务随时完成!

Project Cover

白日梦AI

白日梦AI提供专注于AI视频生成的多样化功能,包括文生视频、动态画面和形象生成等,帮助用户快速上手,创造专业级内容。

Project Cover

有言AI

有言平台提供一站式AIGC视频创作解决方案,通过智能技术简化视频制作流程。无论是企业宣传还是个人分享,有言都能帮助用户快速、轻松地制作出专业级别的视频内容。

Project Cover

讯飞绘镜

讯飞绘镜是一个支持从创意到完整视频创作的智能平台,用户可以快速生成视频素材并创作独特的音乐视频和故事。平台提供多样化的主题和精选作品,帮助用户探索创意灵感。

Project Cover

讯飞文书

讯飞文书依托讯飞星火大模型,为文书写作者提供从素材筹备到稿件撰写及审稿的全程支持。通过录音智记和以稿写稿等功能,满足事务性工作的高频需求,帮助撰稿人节省精力,提高效率,优化工作与生活。

Project Cover

阿里绘蛙

绘蛙是阿里巴巴集团推出的革命性AI电商营销平台。利用尖端人工智能技术,为商家提供一键生成商品图和营销文案的服务,显著提升内容创作效率和营销效果。适用于淘宝、天猫等电商平台,让商品第一时间被种草。

Project Cover

Trae

Trae是一种自适应的集成开发环境(IDE),通过自动化和多元协作改变开发流程。利用Trae,团队能够更快速、精确地编写和部署代码,从而提高编程效率和项目交付速度。Trae具备上下文感知和代码自动完成功能,是提升开发效率的理想工具。

Project Cover

AIWritePaper论文写作

AIWritePaper论文写作是一站式AI论文写作辅助工具,简化了选题、文献检索至论文撰写的整个过程。通过简单设定,平台可快速生成高质量论文大纲和全文,配合图表、参考文献等一应俱全,同时提供开题报告和答辩PPT等增值服务,保障数据安全,有效提升写作效率和论文质量。

投诉举报邮箱: service@vectorlightyear.com
@2024 懂AI·鲁ICP备2024100362号-6·鲁公网安备37021002001498号