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
.
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:
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.
This framework is under heavily development, it's recommended to use the latest release as much as possible (including SDWebImage dependency).
The v1.0.0 version is now released, which provide all the function above, with the stable API, fully documentation and unit test.
This framework follows Semantic Versioning. Each source-break API changes will bump to a major version.
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.
All issue reports, feature requests, contributions, and GitHub stars are welcomed. Hope for active feedback and promotion if you find this framework useful.
SDWebImageSwiftUI is available through Swift Package Manager.
For App integration, you should using Xcode 11 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 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: "1.0")
],
)
SDWebImageSwiftUI is available through CocoaPods. To install it, simply add the following line to your Podfile:
pod 'SDWebImageSwiftUI'
SDWebImageSwiftUI is available through Carthage.
github "SDWebImage/SDWebImageSwiftUI"
WebImage
to load network imagevar body: some View {
WebImage(url: URL(string: "https://nokiatech.github.io/heif/content/images/ski_jump_1440x960.heic"))
// 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
}
.resizable() // Resizable like SwiftUI.Image, you must use this modifier or the view will use the image bitmap size
.placeholder(Image(systemName: "photo")) // Placeholder Image
// Supports ViewBuilder as well
.placeholder {
Rectangle().foregroundColor(.gray)
}
.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.
Note: The WebImage
animation provide common use case, so it's still recommend to use AnimatedImage
for advanced controls like progressive animation 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
// `WebImage` supports advanced control just like `AnimatedImage`, but without the progressive animation support
}
AnimatedImage
to play animationvar body: some View {
Group {
AnimatedImage(url: URL(string: "https://raw.githubusercontent.com/liyong03/YLGIFImage/master/YLGIFImageDemo/YLGIFImageDemo/joy.gif"))
// 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
.placeholder(UIImage(systemName: "photo")) // Placeholder Image
// Supports ViewBuilder as well
.placeholder {
Circle().foregroundColor(.gray)
}
.indicator(SDWebImageActivityIndicator.medium) // 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)
// 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", 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 in .onViewUpdate
for rescue.
var body: some View {
AnimatedImage(name: "animation2") // Just for showcase, don't mix them at the same time
.indicator(SDWebImageProgressIndicator.default) // UIKit indicator component
.indicator(Indicator.progress) // SwiftUI indicator component
.transition(SDWebImageTransition.flipFromLeft) // UIKit animation transition
.transition(AnyTransition.flipFromLeft) // SwiftUI animation transition
}
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.
ImageManager
for your own View typeThe 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() }
// Cancel image loading when disappear
.onDisappear { self.imageManager.cancel() }
}
}
struct MyView_Previews: PreviewProvider {
static var previews: some View {
MyView(imageManager: ImageManager(url: URL(string: "https://via.placeholder.com/200x200.jpg"))
}
}
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 for SwiftUI App, it's the AppDelegate.swift
:
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
// Add WebP/SVG/PDF support
SDImageCodersManager.shared.addCoder(SDImageWebPCoder.shared)
SDImageCodersManager.shared.addCoder(SDImageSVGCoder.shared)
SDImageCodersManager.shared.addCoder(SDImagePDFCoder.shared)
// Add default HTTP header
SDWebImageDownloader.shared.setValue("image/webp,image/apng,image/*,*/*;q=0.8", forHTTPHeaderField: "Accept")
// Add multiple caches
let cache = SDImageCache(namespace: "tiny")
cache.config.maxMemoryCost = 100 * 1024 * 1024 // 100MB memory
cache.config.maxDiskSize = 50 * 1024 * 1024 // 50MB disk
SDImageCachesManager.shared.addCache(cache)
SDWebImageManager.defaultImageCache = SDImageCachesManager.shared
// Add multiple loaders with Photos Asset support
SDImageLoadersManager.shared.addLoader(SDImagePhotosLoader.shared)
SDWebImageManager.defaultImageLoader = SDImageLoadersManager.shared
return true
}
For more information, it's really recommended to check our demo, to learn detailed API usage. You can also have a check at the latest API documentation, for advanced usage.
SwiftUI's Button
apply overlay to its content (except Text
) by default, this is common mistake to write code like this, which cause strange behavior:
// Wrong
Button(action: {
// Clicked
}) {
WebImage(url: url)
}
// NavigationLink create Button implicitly
NavigationView {
NavigationLink(destination: Text("Detail view here")) {
WebImage(url: url)
}
}
Instead, you must override the .buttonStyle
to use the plain style, or the .renderingMode
to use original mode. You can also use the .onTapGesture
modifier for touch handling. See How to disable the overlay color for images inside Button and NavigationLink
// Correct
Button(action: {
// Clicked
}) {
WebImage(url: url)
}
.buttonStyle(PlainButtonStyle())
// Or
NavigationView {
NavigationLink(destination: Text("Detail view here")) {
WebImage(url: url)
.renderingMode(.original)
}
}
SDWebImageSwiftUI supports to use when your App Target has a deployment target version less than iOS 13/macOS 10.15/tvOS 13/watchOS 6. Which will weak linking of SwiftUI(Combine) to allows writing code with available check at runtime.
To use backward deployment, you have to do the follow things:
Add -weak_framework SwiftUI -weak_framework Combine
in your App Target's Other Linker Flags
build setting. You can also do this using Xcode's Optional Framework
checkbox, there have the same effect.
You should notice that all the third party SwiftUI frameworks should have this build setting as well, not only just SDWebImageSwiftUI. Or when running on iOS 12 device, it will trigger the runtime dyld error on startup.
For deployment target version below iOS 12.2 (The first version which Swift 5 Runtime bundled in iOS system), you have to change the min deployment target version of SDWebImageSwiftUI. This may take some side effect on compiler's optimization and trigger massive warnings for some frameworks.
However, for iOS 12.2+, you can still keep the min deployment target version to iOS 13, no extra warnings or performance slow down for iOS 13 client.
Because Swift use the min deployment target version to detect whether to link the App bundled Swift runtime, or the System built-in one (/usr/lib/swift/libswiftCore.dylib
).
post_install do |installer|
installer.pods_project.targets.each do |target|
target.build_configurations.each do |config|
config.build_settings['IPHONEOS_DEPLOYMENT_TARGET'] = '11.0' # version you need
end
end
end
For Carthage user, you can use carthage update --no-build
to download the dependency, then change the Xcode Project's deployment target version and build the binary framework.
For SwiftPM user, you have to use the local dependency (with the Git submodule) to change the deployment target version.
For Carthage user, the built binary framework will use Library Evolution to support for backward deployment.
For CocoaPods user, you can skip the platform version validation in Podfile with:
platform :ios, '13.0' # This does not effect your App Target's deployment target version, just a hint for CocoaPods
Add all the SwiftUI code with the available annotation and runtime check, like this:
// AppDelegate.swift
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
// ...
if #available(iOS 13, *) {
window.rootViewController = UIHostingController(rootView: ContentView())
} else {
window.rootViewController = ViewController()
}
// ...
}
// ViewController.swift
class ViewController: UIViewController {
var label: UILabel = UILabel()
override func viewDidLoad() {
super.viewDidLoad()
view.backgroundColor = .white
view.addSubview(label)
label.text = "Hello World iOS 12!"
label.sizeToFit()
label.center = view.center
}
}
// ContentView.swift
@available(iOS 13.0, OSX 10.15, tvOS 13.0, watchOS 6.0, *)
struct ContentView : View {
var body: some View {
Group {
Text("Hello World iOS 13!")
WebImage(url: URL(string: "https://i.loli.net/2019/09/24/rX2RkVWeGKIuJvc.jpg"))
}
}
}
To run the example using SwiftUI, following the steps:
cd Example
pod install
Then open the Xcode Workspace to run the demo application.
Since SwiftUI is aimed to support all Apple platforms, our demo does this as well, one codebase including:
Demo Tips:
Switch
(right-click on macOS/force press on watchOS) to switch between WebImage
and AnimatedImage
.Reload
(right-click on macOS/force press on watchOS) to clear cache.Swipe Left
(menu button on tvOS) to delete one image url from list.SDWebImageSwiftUI has Unit Test to increase code quality. For SwiftUI, there are no official Unit Test solution provided by Apple.
However, since SwiftUI is State-Based and Attributed-Implemented layout system, there are open source projects who provide the solution:
.frame
modifier, .image
value). We use this to test AnimatedImage
and WebImage
. It also allows the inspect to native UIView/NSView, which we use to test ActivityIndicator
and ProgressIndicator
.To run the test:
carthage build
on root directory to install the dependency.SDWebImageSwiftUI.xcodeproj
, wait for SwiftPM finishing downloading the test dependency.SDWebImageSwiftUITests
scheme and start testing.We've already setup the CI pipeline, each PR will run the test case and upload the test report to codecov.
Besides all above things, this project can also ensure the following function available on Swift platform for SDWebImage itself.
Which means, this project is one core use case and downstream dependency, which driven SDWebImage itself future development.
SDWebImageSwiftUI is available under the MIT license. See the LICENSE file for more info.
此处可能存在不合适展示的内容,页面不予展示。您可通过相关编辑功能自查并修改。
如您确认内容无涉及 不当用语 / 纯广告导流 / 暴力 / 低俗色情 / 侵权 / 盗版 / 虚假 / 无价值内容或违法国家有关法律法规的内容,可点击提交进行申诉,我们将尽快为您处理。
1. 开源生态
2. 协作、人、软件
3. 评估模型