Class

NSItemProvider

An item provider for conveying data or a file between processes during drag and drop or copy/paste activities, or from a host app to an app extension.

Overview

Starting in iOS 11, item providers play a central role in drag and drop, and in copy/paste. They continue to play their role with app extensions.

All completion blocks used in the NSItemProvider class are called by the system on an internal queue. When using an item provider with drag and drop, ensure that user-interface updates take place on the main queue as follows:

DispatchQueue.main.async {
    // work that impacts the user interface
}

App Extension Support

An app extension typically encounters item providers when examining the attachments property of an NSExtensionItem object. During that examination, the extension can use the hasItemConformingToTypeIdentifier(_:) method to look for data that it recognizes. Item providers use Uniform Type Identifier (UTI) values to identify the data they contain. After finding a type of data that your extension can use, it calls the loadItem(forTypeIdentifier:options:completionHandler:) method to load the actual data, which is delivered to the provided completion handler.

You can create item providers to vend data to another process. An extension that modifies an original data item can create a new NSItemProvider object to send back to the host app. When creating data items, you specify your data object and the type of that object. You can optionally use the previewImageHandler property to generate a preview image for your data.

A single item provider may use custom blocks to provide its data in many different formats. When configuring an item provider, use the registerItem(forTypeIdentifier:loadHandler:) method to register your blocks and the formats each one supports. When a client requests data in a particular format, the item provider executes the corresponding block, which is then responsible for coercing the data to the appropriate type and returning it to the client.

Topics

Initializing an Item Provider

init?(contentsOf: URL!)

Provides data backed by the contents of an existing file. The system uses the URL’s filename extension to select an appropriate UTI.

init(item: NSSecureCoding?, typeIdentifier: String?)

Initializes an item provider with an object, according to the NSItemProvider type coercion policy.

init()

Instantiates an empty item provider to which you can later register a data or file representation.

Beta
init(object: NSItemProviderWriting)

Initializes a new item provider, employing a specified object’s type identifiers to specify the data representations eligible to be loaded by the provider.

Beta

Getting the Item’s Data

func canLoadObject(ofClass: NSItemProviderReading.Type)

Returns a Boolean value indicating whether an item provider can load objects of a given class.

Beta
func hasItemConformingToTypeIdentifier(String)

A convenience method equivalent to the hasRepresentationConforming(toTypeIdentifier:fileOptions:) method, but with the fileOptions parameter set to a value of 0.

func loadDataRepresentation(forTypeIdentifier: String, completionHandler: (Data?, Error?) -> Void)

Asynchronously copies the provided, typed data into a Data object, returning a Progress object.

Beta
func loadFileRepresentation(forTypeIdentifier: String, completionHandler: (URL?, Error?) -> Void)

Asynchronously writes a copy of the provided, typed data to a temporary file, returning a Progress object.

Beta
func loadInPlaceFileRepresentation(forTypeIdentifier: String, completionHandler: (URL?, Bool, Error?) -> Void)

Asynchronously opens a file in place, if doing so is possible, returning a Progress object.

Beta
func loadObject(ofClass: NSItemProviderReading.Type, completionHandler: (NSItemProviderReading?, Error?) -> Void)

Asynchronously loads an object of a specified class to an item provider, returning a Progress object.

Beta
func hasRepresentationConforming(toTypeIdentifier: String, fileOptions: NSItemProviderFileOptions = [])

Returns a Boolean value indicating whether an item provider contains a data representation conforming to a specified uniform type identifier (UTI) and to specified open-in-place behavior.

Beta
func registeredTypeIdentifiers(fileOptions: NSItemProviderFileOptions = [])

Returns an array with a subset of type identifiers for the item provider, according to the specified file options, listed in the same order in which they were registered.

Beta

Providing the Item’s Data

func registerObject(NSItemProviderWriting, visibility: NSItemProviderRepresentationVisibility)

Adds representations of a specified object to an item provider, based on the object’s implementation of the NSItemProviderWriting protocol and adhering to a visibility specification.

Beta
func registerObject(ofClass: NSItemProviderWriting.Type, visibility: NSItemProviderRepresentationVisibility, loadHandler: ((NSItemProviderWriting?, Error?) -> Void) -> Progress?)

Lazily adds representations of a specified object to an item provider, based on the object’s implementation of the NSItemProviderWriting protocol and adhering to a visibility specification.

Beta

Registering Custom Coercion Handlers

func registerItem(forTypeIdentifier: String, loadHandler: NSItemProvider.LoadHandler)

Lazily registers an item, according to the NSItemProvider type coercion policy.

var registeredTypeIdentifiers: [String]

Returns the array of type identifiers for the item provider, listed in the same order in which they were registered.

Generating a Preview Image

func loadPreviewImage(options: [AnyHashable : Any]! = [:], completionHandler: NSItemProvider.CompletionHandler!)

Loads the preview image for the item that is represented by the item provider.

var previewImageHandler: NSItemProvider.LoadHandler?

The custom preview image handler block for the item provider.

Getting the Visual Attributes

var sourceFrame: NSRect

The rectangle (in screen coordinates) occupied by the item in the host app’s source window.

var containerFrame: NSRect

The rectangle (in screen coordinates) of the item’s visible content.

var preferredPresentationSize: CGSize

The ideal presentation size of the item.

Constants

typealias NSItemProvider.CompletionHandler

A block that receives the item provider’s data.

typealias NSItemProvider.LoadHandler

A block that loads the item provider’s data and coerces it to the specified type.

Options Dictionary Key

Keys indicating options to use when generating the item provider’s data.

Keys for Items Accessed in JavaScript Code

Keys used in property list items received from or sent to JavaScript code.

class let errorDomain: String

The error domain associated with the NSItemProvider class.

struct NSItemProviderFileOptions

Data-access specifications that declare how items should be handled.

Beta
protocol NSItemProviderReading

The interface for supporting instantiation of objects using data loaded by an item provider, used by a destination app when consuming pasted or dropped items.

Beta
protocol NSItemProviderWriting

The interface for supporting initialization of an item provider based on an object, used by a source app when providing copied or dragged items.

Beta
enum NSItemProviderRepresentationVisibility

Specifications that control which categories of processes can see an item.

Beta
enum NSItemProvider.ErrorCode

The error codes that describe problems with consuming data from an item provider.

Relationships

Inherits From

See Also

Attachments

class NSExtensionItem

An immutable collection of values representing different aspects of an item for an extension to act upon.

Beta Software

This documentation contains preliminary information about an API or technology in development. This information is subject to change, and software implemented according to this documentation should be tested with final operating system software.

Learn more about using Apple's beta software