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.

Kind: static method of application

Typedef EditSettings

Example

Copy
let Color = require("scenegraph").Color;
let application = require("application");

let panelButton = document.querySelector("panel #myButton");

// When button is clicked, set selected item's fill to solid red
panelButton.addEventListener("click", (event) => {
  application.editDocument((selection) => {
    selection.items[0].fill = new Color("red");
  });
});
Copied to your clipboard
let Color = require("scenegraph").Color;
let application = require("application");

let panelButton = document.querySelector("panel #myButton");

// When button is clicked, set selected item's fill to solid red
panelButton.addEventListener("click", (event) => {
  application.editDocument((selection) => {
    selection.items[0].fill = new Color("red");
  });
});

Example

Copy
const { editDocument } = require("application");
const { Color, selection } = require("scenegraph");
var panel;

// Illustrates editing the selected document content in response to a "drop" event in the panel UI
function show(event) {
    if (!panel) {
        panel = document.createElement("div");

        // Specify plugin panel to have a draggable source div and a target div
        panel.innerHTML = `
            <div id="divDragSource" style="height: 50px; width: 50%; background-color: aqua" data-color="aqua" draggable=true>Drag Source</div>
            <div id="divDragTarget" style="height: 50px; width: 50%; background-color: black">Drag Target</div>`;

        // Upon starting drag, set custom data from drag source
        panel.querySelector("#divDragSource").addEventListener("dragstart", (event) => {
            event.dataTransfer.setData("text", event.target.getAttribute("data-color"));
        });

        // Upon dragging over target, change mouse cursor
        panel.querySelector("#divDragTarget").addEventListener("dragover", (event) => {
            event.preventDefault();
            event.dataTransfer.dropEffect = "link";
        });

        // Upon dropping onto target, get custom data from drag source
        panel.querySelector("#divDragTarget").addEventListener("drop", (event) => {
            event.preventDefault();
            let colorName = event.dataTransfer.getData("text");

            // Set the fill color of everything selected in the document
            editDocument(() => {
                selection.items.forEach(item => item.fill = new Color(colorName));
            });
        });

        event.node.appendChild(panel);
    }
}
Copied to your clipboard
const { editDocument } = require("application");
const { Color, selection } = require("scenegraph");
var panel;

// Illustrates editing the selected document content in response to a "drop" event in the panel UI
function show(event) {
    if (!panel) {
        panel = document.createElement("div");

        // Specify plugin panel to have a draggable source div and a target div
        panel.innerHTML = `
            <div id="divDragSource" style="height: 50px; width: 50%; background-color: aqua" data-color="aqua" draggable=true>Drag Source</div>
            <div id="divDragTarget" style="height: 50px; width: 50%; background-color: black">Drag Target</div>`;

        // Upon starting drag, set custom data from drag source
        panel.querySelector("#divDragSource").addEventListener("dragstart", (event) => {
            event.dataTransfer.setData("text", event.target.getAttribute("data-color"));
        });

        // Upon dragging over target, change mouse cursor
        panel.querySelector("#divDragTarget").addEventListener("dragover", (event) => {
            event.preventDefault();
            event.dataTransfer.dropEffect = "link";
        });

        // Upon dropping onto target, get custom data from drag source
        panel.querySelector("#divDragTarget").addEventListener("drop", (event) => {
            event.preventDefault();
            let colorName = event.dataTransfer.getData("text");

            // Set the fill color of everything selected in the document
            editDocument(() => {
                selection.items.forEach(item => item.fill = new Color(colorName));
            });
        });

        event.node.appendChild(panel);
    }
}

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

Typedef RenditionSettings

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

Typedef RenditionResult

Example

Copy
// Generate PNG rendition of the selected node
let application = require("application");
let fs = require("uxp").storage.localFileSystem;

let file = await fs.getFileForSaving();
let shape = selection.items[0];
let renditions = [
  {
    node: shape,
    outputFile: file,
    type: application.RenditionType.PNG,
    scale: 2,
  },
];
application.createRenditions(renditions).then(function (results) {
  // ...do something with outputFiles on disk...
});
Copied to your clipboard
// Generate PNG rendition of the selected node
let application = require("application");
let fs = require("uxp").storage.localFileSystem;

let file = await fs.getFileForSaving();
let shape = selection.items[0];
let renditions = [
  {
    node: shape,
    outputFile: file,
    type: application.RenditionType.PNG,
    scale: 2,
  },
];
application.createRenditions(renditions).then(function (results) {
  // ...do something with outputFiles on disk...
});

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

Example

Copy
const application = require("application");
const fs = require("uxp").storage.localFileSystem;

// Import all files in the plugin's temporary folder
application.editDocument({ editLabel: "Importing assets" }, async function () {
    let tempFolder = await fs.getTemporaryFolder();
    let entries = await tempFolder.getEntries();
    application.import(entries);
});

// Import one file selected by the user
application.editDocument({ editLabel: "Importing asset" }, async function () {
    let importTypes = ["ai", "bmp", "gif", "jpeg", "jpg", "json", "mp4", "png", "psd", "tif", "tiff", "txt"];
    let fileAsset = await fs.getFileForOpening({ types: importTypes });
    if (fileAsset) {
        application.import([fileAsset]);
    }
});
Copied to your clipboard
const application = require("application");
const fs = require("uxp").storage.localFileSystem;

// Import all files in the plugin's temporary folder
application.editDocument({ editLabel: "Importing assets" }, async function () {
    let tempFolder = await fs.getTemporaryFolder();
    let entries = await tempFolder.getEntries();
    application.import(entries);
});

// Import one file selected by the user
application.editDocument({ editLabel: "Importing asset" }, async function () {
    let importTypes = ["ai", "bmp", "gif", "jpeg", "jpg", "json", "mp4", "png", "psd", "tif", "tiff", "txt"];
    let fileAsset = await fs.getFileForOpening({ types: importTypes });
    if (fileAsset) {
        application.import([fileAsset]);
    }
});

version

▸ version: string

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

Kind: static property of application Read only: true

Example

Copy
console.log("Version:", application.version); // e.g. "13.0.21.3"
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

Copy
console.log("XD locale:", application.appLanguage); // e.g. "en"
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

Copy
console.log("OS locale:", application.systemLocale); // e.g. "en_US"
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

Example

Copy
let application = require("application");
let documentInfo = application.activeDocument;
console.log("Document title: " + documentInfo.name);
console.log("Document ID: " + documentInfo.guid);
Copied to your clipboard
let application = require("application");
let documentInfo = application.activeDocument;
console.log("Document title: " + documentInfo.name);
console.log("Document ID: " + documentInfo.guid);

Last updated 8/10/2021

Was this helpful?

Yes

No