Welcome to the AsyncDisplayKit beta! Documentation — including this README — will be fleshed out for the initial public release. Until then, please direct questions and feedback to the Paper Engineering Community group.
AsyncDisplayKit is a library for smooth asynchronous user interfaces on iOS.
UIKit traditionally only runs on the main thread. This includes expensive tasks like text sizing and rendering, as well as image decoding.
AsyncDisplayKit can handle all of the expensive parts asynchronously on a background thread, caching the values before actual views are created, and finally laying out views or layers efficiently on the main thread.
AsyncDisplayKit uses display nodes to represent views and layers. The node API is designed to be as similar as possible to UIKit's.
AsyncDisplayKit is available on CocoaPods. You can manually include it in your project's Podfile:
pod 'AsyncDisplayKit', :git => 'git@github.com:facebook/AsyncDisplayKit.git'
and run
pod install
Start by importing the header:
#import <AsyncDisplayKit/AsyncDisplayKit.h>
An ASDisplayNode is an abstraction over UIView and CALayer that allows you to perform all standard view- and layer-related tasks (layout, sizing calculations, view hierarchy management), moving expensive work off the main thread and with additional optimisations. More specifically, with node-based hierarchy, you can:
- offload more-complex layout code to the background
- enable layer-backing (on nodes that don't require touch handling)
- enable subtree precompositing
- create entire view hierarchies over multiple runloops
and do all of this in advance and in the background, so complex content is ready to go by the time the user scrolls to it.
The node API is designed to be as similar as possible to UIView.
ASDisplayNode can be allocated, initialized and its properties can be set all on a background thread.
dispatch_async(background_queue, ^{
n = [[ASDisplayNode alloc] init];
n.frame = CGRectMake(0, 40, 100, 100);
n.backgroundColor = [UIColor greenColor];
});
Hierarchies can be created in a similar way as UIKit:
dispatch_async(background_queue, ^{
s = [[ASDisplayNode alloc] init];
[n addSubnode:s];
});
A node may be backed by a view or layer, which must take place on the main thread. At this point, views may read their cached calculatedSize when performing layout.
dispatch_async(dispatch_get_main_queue(), ^{
UIView *v = [node view];
// You can now add it to the view hierarchy
[someView addSubview:v];
// The properties you set earlier will be preserved
// v.frame is {0, 40, 100, 100}
// v.backgroundColor is green
});
Besides ASDisplayNode, AsyncDisplayKit has UIKit equivalent classes:
- ASControlNode: a UIButton equivalent
- ASTextNode: a UITextView equivalent, with features like tap highlights, custom truncation strings, gradients, shadows, and tappable links.
- ASImageNode: a UIImageView equivalent
Node-aware UITableView and UICollectionView implementations are currently planned, but not yet implemented.
To make your own nodes, start with the subclasses header
#import <AsyncDisplayKit/ASDisplayNode+Subclasses.h>
The header contains possible and recommanded methods to override.
See the wiki for more details on use cases, performance, subclassing, bridged properties, sizing and layout, and UIKit divergence.
AsyncDisplayKit has extensive unit test coverage. You'll need to run pod install in the root AsyncDisplayKit directory to set up OCMock.
See the CONTRIBUTING file for how to help out.
AsyncDisplayKit is BSD-licensed. We also provide an additional patent grant.