xd-scenegraph-helper

xd-scenegraph-helper.

xd-scenegraph-helper is a set of lightweight helper functions with no external dependencies that let's you easily traverse the scenegraph of a XD document. While traversing, these functions will always respect the order of XD document flow. XD's default flow is: Nodes are included in back-to-front order

Before Installation.

Make sure you have scenengraph correctly exposed to your plugin's code as a dependency. If you're using webpack you can do it by adding this to webpack.config.js:

externals: {
scenegraph:  "scenegraph",
},

Installation.

You can install this package via npm.

npm i xd-scenegraph-helper
// or
yarn add xd-scenegraph-helper

Usage

You can use it in your plugin setup like so:

const {findAll, findOne, findChildren, findChild} = require("xd-scenegraph-helper");

API

findAll

Searches this entire subtree (this node's children, its children's children, etc). Returns all nodes for which callback returns true.

Signature

findAll (targetNode: SceneNode.isContainer ,callback?: (node: SceneNode) => boolean): ReadonlyArray<[SceneNode]>

Parameters

callback

A function that evaluates whether to return the provided node. If this argument is omitted, findAll returns all nodes in the subtree.

Remarks

Nodes are included in back-to-front order. Parents always appear before their children, and children appear in same relative order before their children, and children appear in same relative order as in the children array.

This traversal method is known as "pre-order traversal". Example: find all Rectangle nodes and all nodes across the tree.

const  scenegraph  =  require("scenegraph");
//selected node is an Artboard here.
const  selectedNode =  scenegraph.selection.items[0];
const {findAll} = require("xd-scenegraph-helper");
//for getting all nodes across the tree.
const allNodesInTree = findAll(selectedNode);
//for getting specific nodes across the tree.
const rectangles = findAll(selectedNode, (node)=> node instanceof scenegraph.Rectangle)

findOne

Searches this entire subtree (this node's children, its children's children, etc). Returns the first node for which callback returns true.

Signature

findOne (targetNode: SceneNode.isContainer ,callback?: (node: SceneNode) => boolean): Scenenode | null

Parameters

callback

A function that evaluates whether to return the provided node.

Remarks

This function returns null if no matching node is found. The traversal order is the same as in findAll. Example:

const  scenegraph  =  require("scenegraph");
//selected node is an Artboard here.
const  selectedNode =  scenegraph.selection.items[0];
const {findOne} = require("xd-scenegraph-helper");
//for getting specific a node across the tree.
const rectangle = findOne(selectedNode, (node)=> node instanceof scenegraph.Rectangle)

findChild

Searches the immediate children of this node (i.e. not including the children's children). Returns the first node for which callback returns true.

Signature

findChild (targetNode: SceneNode.isContainer, callback?: (node: SceneNode) => boolean): Scenenode | null

Parameters

callback

A function that evaluates whether to return the provided node.

Remarks

This function returns null if no matching node is found. Example: find Group node whose is a immediate child of the targetNode.

const  scenegraph  =  require("scenegraph");
//selected node is an Artboard here.
const  selectedNode =  scenegraph.selection.items[0];
const {findChild} = require("xd-scenegraph-helper");
//for getting specific immediate child.
const rectangle = findChild(selectedNode,(node)=> node instanceof scenegraph.Group)

findChildren

Searches the immediate children of this node (i.e. not including the children's children). Returns all nodes for which callback returns true.

Signature

findChildren (targetNode: SceneNode.isContainer, callback?: (node: SceneNode) => boolean): ReadonlyArray<[SceneNode]>

Parameters

callback

A function that evaluates whether to return the provided node. If this argument is omitted, findChildren returns node.children.

Remarks

Example: find all Group nodes who are immediate child of the targetNode.

const  scenegraph  =  require("scenegraph");
//selected node is an Artboard here.
const  selectedNode =  scenegraph.selection.items[0];
const {findChildren} = require("xd-scenegraph-helper");
//for getting specific immediate children.
const groups = findChild(selectedNode,(node)=> node instanceof scenegraph.Group)

Authors

• Saud Tauqeer [e-mail]

License

MIT

Acknowledgments

xd-scenegraph-herlper is heavily inspired by figma's API implementation.

Issues

Feel free to open an issue or submit a PR (please include isolated reproducible code) and i'll take a look at it as soon as humanly possible.