Action
An Action extension helps users view or transform content originating in a host app. For example, an Action extension might help users edit an image in a document that they’re viewing in a text editor. Another type of Action extension might let users view a selected item in a different way, such as viewing an image in a different format or reading text in a different language.
The system offers an Action extension to users only when the extension declares it can work with the type of content a user is currently using. For example, if an Action extension declares it works only with text, it isn’t made available when a user is viewing images.
To learn how to declare the types of content an Action extension can work with, read Declaring Supported Data Types for a Share or Action Extension).
Understand Action Extensions
Action extensions behave differently depending on the platform. In OS X, an Action extension:
Can be an editor, in which users can make changes to selected content, or a viewer, in which users can view selected content in a new way
Can transmit to the host app the content changes that users make within the app extension
Can appear in a modal view that emerges from the host app’s window or in a custom view that surrounds the user’s selected items
Automatically receives the user’s selected content as part of the extension context
In iOS, an Action extension:
Helps users view the current document in a different way
Always appears in an action sheet or full-screen modal view
Receives selected content only if explicitly provided by the host app
On both platforms, users get access to Action extensions in the system-provided UI. In iOS, an Action extension is listed in the action area of the activity view controller that appears when users tap the Share button. In OS X, there are a few ways in which users can reveal a list of Action extensions. For example, users can:
Move the pointer over some selected content and click the button that appears
Click the Share toolbar button
Click the Action extension’s custom toolbar button
Use the Xcode Action Extension Template
The Xcode Action extension template provides default source files for the principal view controller class (called ActionViewController
), an Info.plist
file, and an interface file (that is, a storyboard or xib file).
By default, the Action template supplies the following Info.plist
keys and values, shown here for an OS X target:
<key>NSExtension</key>
<dict>
<key>NSExtensionAttributes</key>
<dict>
<key>NSExtensionServiceRoleType</key>
<string>NSExtensionServiceRoleTypeEditor</string>
</dict>
<key>NSExtensionPointIdentifier</key>
<string>com.apple.ui-services</string>
<key>NSExtensionPrincipalClass</key>
<string>ActionViewController</string>
</dict>
To specify the task your OS X Action extension enables, use one of the following values for the required NSExtensionServiceRoleType
key:
NSExtensionServiceRoleTypeEditor
—The extension enables editing or other content transformation and returns the user’s edits to the host appNSExtensionServiceRoleTypeViewer
—The extension lets users view the selected content in a different way, such as in a different format
An Action extension uses the view controller’s extensionContext
property to get an NSExtensionContext
object. In OS X, the extension context contains the user’s selected content as well as the size and position of that content.
In iOS, an extension context has content specified explicitly by the host app; this can, at the discretion of the host, include user selected content.
To learn more about the extension context, see Respond to the Host App’s Request.
Design the UI
iOS. If you want to present your iOS Action extension full screen, add the following key-value pair to the extension’s NSExtension
dictionary:
<key>NSExtensionActionWantsFullScreenPresentation</key>
<true/>
OS X. Consider the size and position of the selected content in the host app when specifying the size and position of the Action extension’s view.
Use the preferredContentSize
property of the NSViewController
class to specify the extension view’s preferred size, based on the size of the selected content. (You can also specify minimum and maximum sizes for the extension’s view, to ensure that a host app doesn’t make unreasonable adjustments to your view.) To specify a preferred position for the extension view, set the preferredScreenOrigin
property to the lower-left corner of the extension’s view.
Returning Edited Content to the Host
On both platforms, an Action extension uses an NSExtensionContext
method to send the user’s edits to the host app. Listing 5-1 shows code that returns edited text to the host app when the user chooses a Done button.
- (IBAction)done:(id)sender {
NSExtensionItem *outputItem = [[NSExtensionItem alloc] init];
outputItem.attributedContentText = self.myTextView.attributedString;
NSArray *outputItems = @[outputItem];
[self.extensionContext completeRequestReturningItems:outputItems];
}
Copyright © 2018 Apple Inc. All rights reserved. Terms of Use | Privacy Policy | Updated: 2017-10-19