- macOS 10.14+
- Xcode 10.2+
Action Extensions can let users access features of your app directly from macOS. For example, if your app contains the functionality to perform image processing, an Action Extension could allow users to process their images directly from Finder. This sample code project creates three Action Extensions, two for processing images and one for processing text. One extension also presents a user interface and all three are available from both the Touch Bar and Finder Preview pane.
The project consists of four targets:
A macOS app target that has no functionality, but would normally contain your main application.
Thumbnail, an Action Extension target that takes images of any type as inputs and outputs thumbnail versions of them. This extension preserves the original input files and creates thumbnails as new files.
Remove, an Action Extension target that takes PNG images as inputs and replaces them with opaque versions of the same images. During processing, this extension prompts the user for a color to draw as the background behind the transparent image.
Uppercase, an Action Extension target that takes text as input and converts it to be uppercase.
The extensions in this sample all accept file data from Finder, process it, and output the data back to Finder.
By default, new Action Extensions are not enabled in macOS. After running this sample code project, enable the extensions by selecting the “Create Thumbnail”, “Make PNG Opaque”, and “Convert Text to Upper Case” checkboxes in the Actions, Finder, and Touch Bar categories of the Extensions System Preferences.
Accept File Data
The system makes Action Extensions available depending on the type of data that the user has selected in Finder. For example, if the user selects a
PNG file, Action Extensions that support images are shown. Each of the extensions in this sample operate on different kinds of input content:
Thumbnailoperates on any kind of image.
Removeoperates specifically on PNG images.
Uppercaseoperates on text.
NSExtension key in the
Info of the associated target determines the conditions under which extensions are available. The value for this key can either be a dictionary, or a string.
Uppercase are both configured with dictionary values.
Thumbnail specifies that it accepts image data with the
NSExtension key and
Uppercase specifies that it accepts text data with the
For more information on valid dictionary keys for
NSExtension, see the App Extension Keys reference.
Remove uses a
NSPredicate query as a string value for the
NSExtension. The query in this sample project filters images to only be valid if they are in PNG format.
For more information on defining extension activation rules, see the App Extension Programming Guide.
Process Input Attachments
When a user invokes an Action Extension, the system instantiates the
NSExtensionPrincipalClass specified in the
Info and asks it to handle the request through the
Once processing completes, pass output files back to the system by creating new
NSItem objects and registering them with
To obtain the correct directory path for writing output files, use
url(for:, passing the
Finally, signal that the action is complete by calling
Process Text Data
Uppercase extension accepts any text, either supplied as attachments in the same way as
Remove, or from other sources such as a standard
NSText control. Check the
attributed property for input from text fields.
Present a User Interface
If the action requires user interaction then the extension may present a user interface. Set the
NSExtensionPointIdentifier key in the
com and ensure that the principal class is a subclass of
NSView. If the extension does not require user interaction, specify
com and have the principal class conform to
Extensions that present a user interface show their view controller’s view immediately after the extension calls
begin and should input files with the
extension property of
Once the extension’s user interface has completed any required user interaction for the task, process the files in the normal way by calling
Support the Touch Bar and Finder Preview Pane
Users may also access Action Extensions from the Touch Bar and from the Quick Actions menu in Finder’s Preview pane. Set both
YES in the
Info to support the Touch Bar and Preview Pane.
Each extension must also have a template icon for use in the Quick Actions menu and the Finder Preview pane. Specify the icon with the
NSExtension key of the
Info for each target. For more information, see the Human Interface Guidelines. The color of the Touch Bar button can also be customized using the
NSExtension key. By default, this is a
Touch color but can be any color in the asset catalog for the target.
For information on how to add Quick Actions to the Touch Bar see the Automator User Guide.