Skip to content

Commit 6117165

Browse files
committed
Update the readme with the information matches the v1.0.0 release. Previous 0.x related behavior are removed
1 parent b32d3ca commit 6117165

File tree

1 file changed

+47
-33
lines changed

1 file changed

+47
-33
lines changed

README.md

Lines changed: 47 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,8 @@ SDWebImageSwiftUI is a SwiftUI image loading framework, which based on [SDWebIma
1414

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

17+
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`.
18+
1719
## Features
1820

1921
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](https://github.com/SDWebImage/SDWebImage/wiki/Advanced-Usage) when you need:
@@ -34,9 +36,9 @@ Besides all these features, we do optimization for SwiftUI, like Binding, View M
3436

3537
This framework is under heavily development, it's recommended to use [the latest release](https://github.com/SDWebImage/SDWebImageSwiftUI/releases) as much as possible (including SDWebImage dependency).
3638

37-
The v1.0.0 version is now **on beta**, all the previous users are recommended to use, test and report issues. We need you feedback to drive the future development. The official version may released in February.
39+
The v1.0.0 version is now **released**, which provide all the function above, with the stable API, fully documentation and unit test.
3840

39-
The v1.0.0 version provide all the function above, with the stable API, fully documentation and unit test. This framework follows [Semantic Versioning](https://semver.org/).
41+
This framework follows [Semantic Versioning](https://semver.org/). Each source-break API changes will bump to a major version.
4042

4143
## Contribution
4244

@@ -78,10 +80,6 @@ SDWebImageSwiftUI is available through [Swift Package Manager](https://swift.org
7880

7981
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](https://developer.apple.com/documentation/xcode/adding_package_dependencies_to_your_app?language=objc) about the step by step tutorial using Xcode.
8082

81-
Note for any pre-release version like 1.0.0 beta, you should use the `Exact` dependency, or the `Range` dependency. Using `Up to next Major` does not resolve the pre-release version.
82-
83-
![](https://user-images.githubusercontent.com/6919743/73805686-5451c180-4802-11ea-9b72-d082ad315bfc.png)
84-
8583
+ For downstream framework
8684

8785
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.
@@ -94,16 +92,6 @@ let package = Package(
9492
)
9593
```
9694

97-
Note for any pre-release version like 1.0.0 beta, you should use the SwiftPM [prereleaseIdentifiers](https://developer.apple.com/documentation/swift_packages/version/2878264-prereleaseidentifiers) API to specify it. The default `from:` does not resolve the pre-release version.
98-
99-
```swift
100-
let package = Package(
101-
dependencies: [
102-
.package(url: "https://github.com/SDWebImage/SDWebImageSwiftUI.git", from: Version(1, 0, 0, prereleaseIdentifiers: ["-beta"])))
103-
],
104-
)
105-
```
106-
10795
## Usage
10896

10997
### Using `WebImage` to load network image
@@ -113,7 +101,7 @@ let package = Package(
113101
- [x] Supports success/failure/progress changes event for custom handling
114102
- [x] Supports indicator with activity/progress indicator and customization
115103
- [x] Supports built-in animation and transition, powered by SwiftUI
116-
- [x] Supports animated image as well! (from v0.9.0)
104+
- [x] Supports animated image as well!
117105

118106
```swift
119107
var body: some View {
@@ -135,17 +123,17 @@ var body: some View {
135123
}
136124
```
137125

138-
Note: This `WebImage` using `Image` for internal implementation, which is the best compatible for SwiftUI layout and animation system. In previous version, `WebImage` supports static image format only, because unlike `UIImageView` in UIKit, SwiftUI's `Image` does not support animated image or vector image.
126+
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.
139127

140-
Note: From v0.9.0, `WebImage` supports animated image as well! You can use `.animated()` to start animation. This is done by using the native SwiftUI rendering system and SDWebImage's powerful [Animated Player](https://github.com/SDWebImage/SDWebImage/wiki/Advanced-Usage#animated-player-530). The `WebImage` animated image provide common use case, so it's still recommend to use `AnimatedImage` for advanced controls like progressive animation rendering.
128+
Note: The `WebImage` animation provide common use case, so it's still recommend to use `AnimatedImage` for advanced controls like progressive animation rendering.
141129

142130
```swift
143131
var body: some View {
144-
WebImage(url: URL(string: "https://raw.githubusercontent.com/liyong03/YLGIFImage/master/YLGIFImageDemo/YLGIFImageDemo/joy.gif"), isAnimating: $isAnimating)) // Animation Control in 1.0.0, supports dynamic changes
132+
WebImage(url: URL(string: "https://raw.githubusercontent.com/liyong03/YLGIFImage/master/YLGIFImageDemo/YLGIFImageDemo/joy.gif"), isAnimating: $isAnimating)) // Animation Control, supports dynamic changes
145133
// The initial value of binding should be true (or you can use `.animatedImageClass` context option and pass `SDAnimatedImage`)
146134
.customLoopCount(1) // Custom loop count
147135
.playbackRate(2.0) // Playback speed rate
148-
// In 1.0.0, `WebImage` supports advanced control just like `AnimatedImage`, but without the progressive animation support
136+
// `WebImage` supports advanced control just like `AnimatedImage`, but without the progressive animation support
149137
}
150138
```
151139

@@ -190,17 +178,13 @@ var body: some View {
190178

191179
Note: `AnimatedImage` supports both image url or image data for animated image format. Which use the SDWebImage's [Animated ImageView](https://github.com/SDWebImage/SDWebImage/wiki/Advanced-Usage#animated-image-50) 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.
192180

193-
Note: From v0.9.0, `AnimatedImage` on watchOS drop the supports on watchOS, because of using hacks and private APIs. For watchOS user, choose `WebImage` instead.
194-
195-
Note: From v0.8.0, `AnimatedImage` on watchOS support all features the same as iOS/tvOS/macOS, including Animated WebP rendering, runloop mode, pausable, purgeable, playback rate, etc. It use the SDWebImage's [Animated Player](https://github.com/SDWebImage/SDWebImage/wiki/Advanced-Usage#animated-player-530), which is the same backend engine for iOS/tvOS/macOS's Animated ImageView.
196-
197181
### Which View to choose
198182

199183
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.
200184

201185
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.
202186

203-
If you need simple animated image, use v0.9.0 above with `WebImage`. Which provide the basic animated image support. But it does not support progressive animation rendering, playback rate, etc.
187+
If you need simple animated image, use `WebImage`. Which provide the basic animated image support. But it does not support progressive animation rendering, playback rate, etc.
204188

205189
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.
206190

@@ -289,25 +273,55 @@ NavigationView {
289273

290274
#### Using for backward deployment and weak linking SwiftUI
291275

292-
SDWebImageSwiftUI from v0.10.0, 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.
276+
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.
293277

294278
To use backward deployment, you have to do the follow things:
295279

296-
+ Add `-weak_framework SwiftUI -weak_framework Combine` in your App Target's `Other Linker Flags` build setting
280+
##### Add weak linking framework
297281

298-
You should notice that all the third party SwiftUI frameworks should have this build setting as well, not only just SDWebImageSwiftUI (we already added in v0.10.0). Or when running on iOS 12 device, it will trigger the runtime dyld error on startup.
282+
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.
299283

300-
+ Use CocoaPods or Carthage (SwiftPM does not support weak linking nor backward deployment currently)
284+
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.
301285

302-
For Carthage user, the built binary framework will use [Library Evolution](https://swift.org/blog/abi-stability-and-more/) to support for backward deployment.
286+
##### Backward deployment on iOS 12.1-
303287

304-
For CocoaPods user, you can skip the platform version validation in Podfile with:
288+
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.
289+
290+
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.
291+
292+
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`).
293+
294+
+ For CocoaPods user, you can change the min deployment target version in the Podfile via post installer:
295+
296+
```ruby
297+
post_install do |installer|
298+
installer.pods_project.targets.each do |target|
299+
target.build_configurations.each do |config|
300+
config.build_settings['IPHONEOS_DEPLOYMENT_TARGET'] = '11.0' # version you need
301+
end
302+
end
303+
end
304+
```
305+
306+
+ 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.
307+
308+
+ For SwiftPM user, you have to use the local dependency (with the Git submodule) to change the deployment target version.
309+
310+
##### Backward deployment on iOS 12.2+
311+
312+
+ For Carthage user, the built binary framework will use [Library Evolution](https://swift.org/blog/abi-stability-and-more/) to support for backward deployment.
313+
314+
+ For CocoaPods user, you can skip the platform version validation in Podfile with:
305315

306316
```ruby
307317
platform :ios, '13.0' # This does not effect your App Target's deployment target version, just a hint for CocoaPods
308318
```
319+
320+
+ For SwiftPM user, SwiftPM does not support weak linking nor Library Evolution, so it can not deployment to iOS 12+ user without changing the min deployment target.
309321

310-
+ Add **all the SwiftUI code** with the available annotation and runtime check, like this:
322+
##### Add available annotation
323+
324+
Add **all the SwiftUI code** with the available annotation and runtime check, like this:
311325

312326
```swift
313327
// AppDelegate.swift

0 commit comments

Comments
 (0)