Edit in GitHubLog an issue

application

The application module exposes APIs for exporting content, initiating edits from panel UI, and getting version / locale info.

editDocument()

editDocument(options, editFunction) | (editFunction)

Call editDocument() from a plugin panel UI event listener to initiate an edit operation batch in order to modify the XD document. This API is irrelevant for plugin menu item commands, which are wrapped in an edit batch automatically.

XD calls the editFunction() synchronously (before editDocument() returns). This function is treated the same as a menu command handler:

  • It is passed two arguments, the selection and the root node of the scenegraph
  • It can return a Promise to extend the duration of the edit asynchronously

You can only call editDocument() in response to a user action, such as a button "click" event or a text input's "input" event. This generally means you must call it while a UI event handler is on the call stack. For a plugin's panel, these UI events can trigger a call to editDocument():

  • blur
  • change
  • click
  • drop (since XD 47)
  • input
  • keydown
  • keypress
  • keyup
  • mousedown
  • mouseup

For UI events that often occur in rapid-fire clusters, such as dragging a slider or pressing keys in a text field, XD tries to smartly merge consecutive edits into a single atomic Undo step. See the mergeId option below to customize this behavior.

ParamTypeDescription
options
EditSettings
Optional settings object (see below). This argument can be omitted.
editFunction
function(Selection, RootNode):?Promise
Function which will perform your plugin's edits to the scenegraph.

Kind: static method of application

Typedef EditSettings

PropertyTypeDescription
editLabel
?string
Used as the Undo label in the Edit menu. If unspecified, XD uses the uxp-edit-label attribute on the DOM node which the user interacted with, and if that does not exist then the plugin's name will be used.
mergeId
?string
If two consecutive edits to the same selection have the same mergeId, they are flattened together into one Undo step. If unspecified, for "high frequency" UI events (see above), XD treats the originating DOM node as a unique identifier for merging; for other UI events, merging is disabled.

Example

Copied to your clipboard
1let Color = require("scenegraph").Color;
2let application = require("application");
3
4let panelButton = document.querySelector("panel #myButton");
5
6// When button is clicked, set selected item's fill to solid red
7panelButton.addEventListener("click", (event) => {
8 application.editDocument((selection) => {
9 selection.items[0].fill = new Color("red");
10 });
11});

Example

Copied to your clipboard
1const { editDocument } = require("application");
2const { Color, selection } = require("scenegraph");
3var panel;
4
5// Illustrates editing the selected document content in response to a "drop" event in the panel UI
6function show(event) {
7 if (!panel) {
8 panel = document.createElement("div");
9
10 // Specify plugin panel to have a draggable source div and a target div
11 panel.innerHTML = `
12 <div id="divDragSource" style="height: 50px; width: 50%; background-color: aqua" data-color="aqua" draggable=true>Drag Source</div>
13 <div id="divDragTarget" style="height: 50px; width: 50%; background-color: black">Drag Target</div>`;
14
15 // Upon starting drag, set custom data from drag source
16 panel.querySelector("#divDragSource").addEventListener("dragstart", (event) => {
17 event.dataTransfer.setData("text", event.target.getAttribute("data-color"));
18 });
19
20 // Upon dragging over target, change mouse cursor
21 panel.querySelector("#divDragTarget").addEventListener("dragover", (event) => {
22 event.preventDefault();
23 event.dataTransfer.dropEffect = "link";
24 });
25
26 // Upon dropping onto target, get custom data from drag source
27 panel.querySelector("#divDragTarget").addEventListener("drop", (event) => {
28 event.preventDefault();
29 let colorName = event.dataTransfer.getData("text");
30
31 // Set the fill color of everything selected in the document
32 editDocument(() => {
33 selection.items.forEach(item => item.fill = new Color(colorName));
34 });
35 });
36
37 event.node.appendChild(panel);
38 }
39}

Info For comparison, plugin menu command handlers are effectively run as if they were passed to editDocument() with editLabel set to the menu item's label and mergeId set to null.

createRenditions()

createRenditions(renditions)

Generate renditions of nodes in the document in a batch. Overwrites any existing files without warning.

A single createRenditions() call can generate any number of renditions, including multiple renditions of the same node (with different output settings) or renditions of multiple different nodes. Only one createRenditions() call can be executing at any given time, so wait for the Promise it returns before calling it again.

Returns: Promise<Array<RenditionResult>, string> - Promise which is fulfilled with an array of RenditionResults (pointing to the same outputFiles that were originally passed in, or rejected with an error string if one or more renditions failed for any reason.

Kind: static method of application

ParamTypeDescription
renditions
Array<RenditionSettings>
List of renditions to generate

Typedef RenditionSettings

All rendition settings fields are required (for a given rendition type) unless otherwise specified.

PropertyTypeDescription
node
SceneNode
Root of scenegraph subtree to render. This may be any node in the scenegraph, regardless of the current edit context.
outputFile
uxp.storage.File
File to save the rendition to (overwritten without warning if it already exists)
type
string
File type: RenditionType.PNG, JPG, PDF, or SVG
scale
number
(PNG & JPG renditions) DPI multipler in the range [0.1, 100], e.g. 2.0 for @2x DPI.
quality
number
(JPG renditions) Compression quality in the range [1, 100].
background
?Color
(PNG & JPEG renditions) Alpha component ignored for JPG. Optional: defaults to transparent for PNG, solid white for JPG.
minify
boolean
(SVG renditions) If true, SVG code is minified.
embedImages
boolean
(SVG renditions) If true, bitmap images are stored as base64 data inside the SVG file. If false, bitmap images are saved as separate files linked from the SVG code.

Typedef RenditionResult

PropertyTypeDescription
outputFile
uxp.storage.File
File the rendition was written to (equal to outputFile in RenditionSettings)

Example

Copied to your clipboard
1// Generate PNG rendition of the selected node
2let application = require("application");
3let fs = require("uxp").storage.localFileSystem;
4
5let file = await fs.getFileForSaving();
6let shape = selection.items[0];
7let renditions = [
8 {
9 node: shape,
10 outputFile: file,
11 type: application.RenditionType.PNG,
12 scale: 2,
13 },
14];
15application.createRenditions(renditions).then(function (results) {
16 // ...do something with outputFiles on disk...
17});

import()

import(entries)

Since: XD 45

Equivalent to File > Import. Brings assets into the XD document, including images, videos, and Adobe Photoshop or Adobe Illustrator files. Assets will be added as a child of the artboard that is the parent of the current selection (or to the document root if nothing is selected).

Supported import file extensions: AI (Illustrator), BMP, GIF, JPG, JPEG, JSON (Lottie), MP4 (Video), PNG, PSD (Photoshop), TIF, TIFF, TXT

An error will be thrown if a passed file does not exist or has an unsupported file extension. Parsing errors or other import problems that are specific to formats supported by XD are displayed to the user in the same way the File > Import action informs users.

Kind: static method of application

ParamTypeDescription
entries
List of files to be imported

Example

Copied to your clipboard
1const application = require("application");
2const fs = require("uxp").storage.localFileSystem;
3
4// Import all files in the plugin's temporary folder
5application.editDocument({ editLabel: "Importing assets" }, async function () {
6 let tempFolder = await fs.getTemporaryFolder();
7 let entries = await tempFolder.getEntries();
8 application.import(entries);
9});
10
11// Import one file selected by the user
12application.editDocument({ editLabel: "Importing asset" }, async function () {
13 let importTypes = ["ai", "bmp", "gif", "jpeg", "jpg", "json", "mp4", "png", "psd", "tif", "tiff", "txt"];
14 let fileAsset = await fs.getFileForOpening({ types: importTypes });
15 if (fileAsset) {
16 application.import([fileAsset]);
17 }
18});

version

version: string

Adobe XD version number in the form "major.minor.patch.build"

Kind: static property of application Read only: true

Example

Copied to your clipboard
console.log("Version:", application.version); // e.g. "13.0.21.3"

appLanguage

appLanguage: string

Current language the application UI is using. This may not equal the user's OS locale setting: it is the closest locale supported by XD - use this when you want your plugin's UI to be consistent with XD's UI. Specifies language only, with no region info (e.g. "fr", not "fr_FR").

Kind: static property of application Read only: true

Example

Copied to your clipboard
console.log("XD locale:", application.appLanguage); // e.g. "en"

systemLocale

systemLocale: string

User's OS-wide locale setting. May not match the XD UI, since XD does not support all world languages. Includes both language and region (e.g. "fr_CA" or "en_US").

Kind: static property of application Read only: true

Example

Copied to your clipboard
console.log("OS locale:", application.systemLocale); // e.g. "en_US"

activeDocument

activeDocument: DocumentInfo

Information about the document which this instance of the plugin is attached to.

Tip > This does not indicate the frontmost "active" document window in the XD application. In XD, each document window loads a separate copy of your plugin. When a given instance of your plugin calls this API, you will always receive information about the document that this instance of the plugin is attached to, even if it's not the active window.

Kind: static property of application Read only: true

Typedef DocumentInfo

PropertyTypeDescription
name
string
Document name as displayed in the titlebar. For untitled documents, this will be a localized string such as "Untitled-1."
guid
string
Semi-unique document identifier. Duplicating an .xd file on disk will result in two files with the same GUID. Duplicating a document via "Save As" will change its GUID; thus two cloud documents will never have the same GUID. The GUID of an Untitled document doesn't change when it is saved for the first time.

This returns the same value as scenegraph.root.guid.

Example

Copied to your clipboard
1let application = require("application");
2let documentInfo = application.activeDocument;
3console.log("Document title: " + documentInfo.name);
4console.log("Document ID: " + documentInfo.guid);
  • Privacy
  • Terms of Use
  • Do not sell or share my personal information
  • AdChoices
Copyright © 2023 Adobe. All rights reserved.