commands

You can make structural changes to the scenegraph, and perform other complex operations, by programmatically invoking the same commands as XD users have access to in the UI. Because structural changes have many nuanced rules and behaviors in XD, these calls function more like automating the UI than like low-level APIs.

For example, these methods do not take arguments. Instead, set the selection to the objects you want the command to target, then invoke the command. Commands may also change the selection when run - for example, group() selects the newly created Group node.

Example

let commands = require("commands");
selection.items = [shape1, shape2, maskShape];
commands.createMaskGroup();
console.log(selection.items); // [Group]
Copied to your clipboard
1let commands = require("commands");
2selection.items = [shape1, shape2, maskShape];
3commands.createMaskGroup();
4console.log(selection.items); // [Group]

group()

▸ group()

Wraps the selected objects in a Group, leaving the Group selected afterward. Equivalent to Object > Group in the UI.

Kind: static method of commands

Example

let shape1 = new Rectangle();
// ...configure Rectangle size & appearance...
let label = new Text();
// ...configure Text content & appearance...

// Add both nodes to the current edit context first
selection.insertionParent.addChild(shape1);
selection.insertionParent.addChild(label);

// Select both shapes, then run the group() command
selection.items = [shape1, label];
commands.group();
let group = selection.items[0]; // the new Group node is what's selected afterward
Copied to your clipboard
1let shape1 = new Rectangle();
2// ...configure Rectangle size & appearance...
3let label = new Text();
4// ...configure Text content & appearance...
5
6// Add both nodes to the current edit context first
7selection.insertionParent.addChild(shape1);
8selection.insertionParent.addChild(label);
9
10// Select both shapes, then run the group() command
11selection.items = [shape1, label];
12commands.group();
13let group = selection.items[0]; // the new Group node is what's selected afterward

ungroup()

▸ ungroup()

Ungroups any of the selected objects that are ungroupable containers (Group, SymbolInstance, RepeatGrid, etc.). Equivalent to Object > Ungroup.

Kind: static method of commands

createMaskGroup()

▸ createMaskGroup()

Creates a masked Group from the selected objects, using the object that is highest in the z order as the mask shape. The mask shape must be a leaf node or BooleanGroup. Equivalent to Object > Mask With Shape.

Kind: static method of commands

Example

let shape1 = new Rectangle(),
  shape2 = new Ellipse();
// ...configure shapes' size & appearance...
let maskShape = new Ellipse();
// ...configure mask shape's size...

// Create a Masked Group: add all nodes to the current edit context, select them, then run the createMaskGroup() command
selection.insertionParent.addChild(shape1);
selection.insertionParent.addChild(shape2);
selection.insertionParent.addChild(maskShape); // added last: topmost in z order
selection.items = [shape1, shape2, maskShape]; // order of selection array does not matter
commands.createMaskGroup();
let maskedGroup = selection.items[0];
Copied to your clipboard
1let shape1 = new Rectangle(),
2  shape2 = new Ellipse();
3// ...configure shapes' size & appearance...
4let maskShape = new Ellipse();
5// ...configure mask shape's size...
6
7// Create a Masked Group: add all nodes to the current edit context, select them, then run the createMaskGroup() command
8selection.insertionParent.addChild(shape1);
9selection.insertionParent.addChild(shape2);
10selection.insertionParent.addChild(maskShape); // added last: topmost in z order
11selection.items = [shape1, shape2, maskShape]; // order of selection array does not matter
12commands.createMaskGroup();
13let maskedGroup = selection.items[0];

convertToPath()

▸ convertToPath()

Converts each selected object to a Path with the exact same visual appearance. Only applies to leaf nodes and Boolean Groups. Equivalent to Object > Path > Convert to Path.

Kind: static method of commands

outlineStroke()

▸ outlineStroke()

Since: XD 42

Converts each selected object's stroke to a Path with the exact same visual appearance. Only applies to leaf nodes, Groups and Boolean Groups. Equivalent to Object > Path > Outline Stroke.

Example

const commands = require("commands");

// Newly created shape nodes.
let shape1 = ...,
    shape2 = ...;

// Select both shapes, then run the Outline Stroke command.
selection.items = [shape1, shape2];
commands.outlineStroke();
console.log(selection.items);  // [shape1, outline1, shape2, outline2]
Copied to your clipboard
1const commands = require("commands");
2
3// Newly created shape nodes.
4let shape1 = ...,
5    shape2 = ...;
6
7// Select both shapes, then run the Outline Stroke command.
8selection.items = [shape1, shape2];
9commands.outlineStroke();
10console.log(selection.items);  // [shape1, outline1, shape2, outline2]

Kind: static method of commands

duplicate()

▸ duplicate()

Duplicates all selected objects, leaving the duplicates selected afterward.

If the objects are artboards, the duplicates are positioned to not overlap any more artboards, and are placed at the top of the artboard z order.
If normal objects, each duplicate is in the exact same position as the original, and just above it in the z order (duplicates of a multiple selection will not be contiguous in the z order if the originals were not).

Interactions triggered from the selected objects are only duplicated if the user is currently in the Prototype workspace. Equivalent to Edit > Duplicate.

Kind: static method of commands

bringToFront()

▸ bringToFront()

Brings selected objects to the front of the z order. Equivalent to Object > Arrange > Bring to Front.

Kind: static method of commands

bringForward()

▸ bringForward()

Brings each selected object one step closer to the front of the z order. Equivalent to Object > Arrange > Bring Forward.

Kind: static method of commands

sendToBack()

▸ sendToBack()

Sends selected objects to the back of the z order. Equivalent to Object > Arrange > Send to Back.

Kind: static method of commands

sendBackward()

▸ sendBackward()

Sends each selected object one step closer to the back of the z order. Equivalent to Object > Arrange > Send Backward.

Kind: static method of commands

alignLeft()

▸ alignLeft()

Aligns all selected objects flush left. Equivalent to Object > Align > Left.

Kind: static method of commands

alignRight()

▸ alignRight()

Aligns all selected objects flush right. Equivalent to Object > Align > Right.

Kind: static method of commands

alignHorizontalCenter()

▸ alignHorizontalCenter()

Aligns all selected objects along their horizontal centerlines. Equivalent to Object > Align > Center (Horizontally).

Kind: static method of commands

alignTop()

▸ alignTop()

Aligns all selected objects flush top. Equivalent to Object > Align > Top.

Kind: static method of commands

alignBottom()

▸ alignBottom()

Aligns all selected objects flush bottom. Equivalent to Object > Align > Bottom.

Kind: static method of commands

alignVerticalCenter()

▸ alignVerticalCenter()

Aligns all selected objects along their vertical centerlines. Equivalent to Object > Align > Center (Vertically).

Kind: static method of commands

distributeHorizontal()

▸ distributeHorizontal()

Distributes all selected objects evenly along the X axis. Equivalent to Object > Distribute > Horizontally.

Kind: static method of commands

distributeVertical()

▸ distributeVertical()

Distributes all selected objects evenly along the Y axis. Equivalent to Object > Distribute > Vertically.

Kind: static method of commands

alignToPixelGrid()

▸ alignToPixelGrid()

Shifts all selected objects and their content so they align crisply with the pixel grid. Equivalent to Object > Align to Pixel Grid.

Kind: static method of commands

makeBackground()

▸ makeBackground()

Makes a stack background. Equivalent to Object > Make Background, which is available when selecting a single SceneNode that simultaneously meets the following conditions:

is a stack cell
is a valid background candidate
belongs to a Stack that has no background
the Stack contains at least two stack cells

For the example below, see layout for examples of creating Stack without background.

Example

const stack = ...;
// suppose this node is a Stack containing at least two stack cells
if (stack.layout.type === scenegraph.SceneNode.LAYOUT_STACK && stack.contentChildren.length > 1) {
    // assume the first stack cell is a valid background candidate
    const futureBackground = stack.contentChildren.at(0);

   // suppose the Stack has no background
   if (!stack.layout.padding.background) {
        console.log(stack.layout.padding.background); // prints `null`
        selection.items = [futureBackground];
        commands.makeBackground();
        console.log(stack.layout.padding.background.name); // prints the name of the "featureBackground" node
    }
}
Copied to your clipboard
1const stack = ...;
2// suppose this node is a Stack containing at least two stack cells
3if (stack.layout.type === scenegraph.SceneNode.LAYOUT_STACK && stack.contentChildren.length > 1) {
4    // assume the first stack cell is a valid background candidate
5    const futureBackground = stack.contentChildren.at(0);
6
7   // suppose the Stack has no background
8   if (!stack.layout.padding.background) {
9        console.log(stack.layout.padding.background); // prints `null`
10        selection.items = [futureBackground];
11        commands.makeBackground();
12        console.log(stack.layout.padding.background.name); // prints the name of the "featureBackground" node
13    }
14}

Kind: static method of commands

replaceBackground()

▸ replaceBackground()

Replaces a stack background. Equivalent to Object > Replace Background, which is available when selecting a single SceneNode that simultaneously meets the following conditions:

is a stack cell
is a valid background candidate
belongs to a Stack that has a background, which is different from the selected stack cell
the Stack contains at least two stack cells

For the example below, see layout for examples of creating Stack without background.

Example

const stack = ...;
// suppose this node is a Stack containing at least two stack cells
if (stack.layout.type === scenegraph.SceneNode.LAYOUT_STACK && stack.contentChildren.length > 1) {
    // assume the first stack cell is a valid background candidate
    const futureBackground = stack.contentChildren.at(0);

    // suppose the Stack contains a background, which is different from the selected one
    if (stack.layout.padding.background && featureBackground.guid !== stack.layout.padding.background.guid) {
        console.log(stack.layout.padding.background.name); // prints the name of the actual background node
        selection.items = [futureBackground];
        commands.replaceBackground();
        console.log(stack.layout.padding.background.name); // prints the name of the "featureBackground" node
    }
}
Copied to your clipboard
1const stack = ...;
2// suppose this node is a Stack containing at least two stack cells
3if (stack.layout.type === scenegraph.SceneNode.LAYOUT_STACK && stack.contentChildren.length > 1) {
4    // assume the first stack cell is a valid background candidate
5    const futureBackground = stack.contentChildren.at(0);
6
7    // suppose the Stack contains a background, which is different from the selected one
8    if (stack.layout.padding.background && featureBackground.guid !== stack.layout.padding.background.guid) {
9        console.log(stack.layout.padding.background.name); // prints the name of the actual background node
10        selection.items = [futureBackground];
11        commands.replaceBackground();
12        console.log(stack.layout.padding.background.name); // prints the name of the "featureBackground" node
13    }
14}

Kind: static method of commands

reset3DTransforms()

▸ reset3DTransforms()

Since: XD 47

Resets the 3D properties (X rotation, Y rotation, Z position) of selected objects (but not their content) to 0. Equivalent to Object > Transform > Reset 3D Transforms.

Kind: static method of commands

Color

Ellipse