Skip to content

Latest commit

 

History

History
146 lines (98 loc) · 5.45 KB

README.md

File metadata and controls

146 lines (98 loc) · 5.45 KB
Raw

SDWebImageLottiePlugin

CI Status Version License Platform Carthage compatible codecov

What's for

SDWebImageLottiePlugin is a plugin for SDWebImage framework, which provide the Lottie animation loading from JSON file.

You can find more resource about Lottie in their Official Site.

Requirements

  • iOS 11+
  • macOS 10.11+
  • tvOS 11+
  • Xcode 11+

Installation

Swift Package Manager

SDWebImageWebPCoder is available through Swift Package Manager.

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

CocoaPods

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

pod 'SDWebImageLottiePlugin', '~> 1.0'

Carthage (Deprecated)

SDWebImageLottiePlugin is available through Carthage.

github "SDWebImage/SDWebImageLottiePlugin", ~> 1.0

Note:

  1. Carthage macOS integration contains issue, because the module name is Lottie_macOS but not Lottie, wait the issue here been fixed 👀

Lottie 2 && Objective-C

Lottie 3.4 version's LottieConfiguration.shared.renderingEngine = .coreAnimation solve the huge performance regression in the issue here 🚀

So from SDWebImageLottiePlugin v1.0.0, we drop the Lottie 2 support, as well as the Objective-C support because Lottie 3 use pure Swift. And therefore, we drop the iOS 9-10 support because the upstream dependency need iOS 11+.

For user who still use Lottie 2 and Objective-C, please check the 0.x version updated to 0.3.0

Usage

Load Lottie from remote JSON

  • Swift
let animationView: Lottie.AnimationView
let lottieJSONURL: URL
animationView.sd_setImage(with: lottieJSONURL)

Note:

  • You can also load lottie json files on AnimatedControl, like switch button.
  • Lottie animation does not start automatically, you can use the completion block, or UITableView/UICollectionView's will display timing to play.
animationView.sd_setImage(with: lottieUrl, completed: { _,_,_,_ in
    self.animationView.play(fromProgress: 0, toProgress: 1, loopMode: .repeat(5)) { finished in
        // ...
    }
}
  • If your Lottie json files contains references to App bundle images, just set the imageProvider before the lottie animation start.
let bundle = Bundle(for: MyBundleClass.self)
animationView.imageProvider = BundleImageProvider(bundle: bundle, searchPath: nil)
animationView.sd_setImage(with: lottieUrl)

Advanced usage

This Lottie plugin use a wrapper class LottieImage because of SDWebImage's customization architecture design. Typically you should not care about this, however this can allows some advanced usage.

  • Swift
let animation = try? JSONDecoder().decode(Animation.self, from: data)
let animatedImage = LottieImage(animation: animation)
// Optional, custom image bundle
animatedImage.imageProvider = BundleImageProvider(bundle: bundle, searchPath: nil)
// Snapshot Lottie animation frame
let posterFrame = animatedImage.animatedImageFrame(at: 0)
let duration = animatedImage.animatedImageDuration(at: 0)

Note:

  • The snapshot is a bitmap version and used for special cases, like thumbnail poster. You'd better not play it on SDAnimatedImageView. Because Lottie is a vector animation and Lottie.AnimationView use Core Animation for rendering, which is faster.

Demo

If you have some issue about usage, SDWebImageLottiePlugin provide a demo for iOS && macOS platform. To run the demo, clone the repo and run the following command.

cd Example/
pod install
open SDWebImageLottiePlugin.xcworkspace

After the Xcode project was opened, click Run to build and run the demo.

Screenshot

  • iOS Demo

  • macOS Demo

The lottie json files are from lottie-web example

Author

DreamPiggy

License

SDWebImageLottiePlugin is available under the MIT license. See the LICENSE file for more info.