Class PageFacade
Identification Accessors
The key which can be used to name files in the file system. It SHOULD be unique within a design.
IDs can include characters invalid for use in file names (such as :).
Example:
// Safe:
page.renderToFile(`./pages/${page.fileKey}.png`)
// Unsafe:
page.renderToFile(`./pages/${page.id}.png`)The ID of the page.
Beware that this value may not be safely usable for naming files in the file system and the fileKey value should be instead.
The name of the artboard.
Reference Methods
Returns the design object associated with the page object.
Example:
const design = page.getDesign()Layer Lookup Methods
Returns the first layer object from any artboard within the page (optionally down to a specific nesting level) matching the specified criteria.
This method internally triggers loading of all the artboards. Uncached items are downloaded when the API is configured (and cached when the local cache is configured).
Example:
Layer by name from any artboard on the page
const layer = await page.findLayer({ name: 'Share icon' })Layer by function selector from any artboard on the page
const shareIconLayer = await page.findLayer((layer) => {
return layer.name === 'Share icon'
})Layer by name from a certain artboad subset within the page
const layer = await page.findLayer({
name: 'Share icon',
artboardId: [ '<ID1>', '<ID2>' ],
})With timeout
const { cancel, token } = createCancelToken()
setTimeout(cancel, 5000) // Throw an OperationCancelled error in 5 seconds.
const layer = await page.findLayer(
{ name: 'Share icon' },
{ cancelToken: token }
)Parameters:
A design-wide layer selector. All specified fields must be matched by the result.
Options
A cancellation token which aborts the asynchronous operation. When the token is cancelled, the promise is rejected and side effects are not reverted (e.g. newly cached artboards are not uncached). A cancellation token can be created via createCancelToken.
The maximum nesting level within the artboard layers to search. By default, all levels are searched. 0 also means "no limit"; 1 means only root layers in artboards should be searched.
A matched layer object.
Returns the first layer object which has the specified ID within the artboards on the page.
Layer IDs are unique within individual artboards but different artboards can potentially have layer ID clashes. This is the reason the method is not prefixed with "get".
This method internally triggers loading of all the artboards. Uncached items are downloaded when the API is configured (and cached when the local cache is configured).
Example:
const layer = await page.findLayerById('<ID>')With timeout
const { cancel, token } = createCancelToken()
setTimeout(cancel, 5000) // Throw an OperationCancelled error in 5 seconds.
const layer = await page.findLayerById('<ID>', { cancelToken: token })Parameters:
A layer ID.
Options
A cancellation token which aborts the asynchronous operation. When the token is cancelled, the promise is rejected and side effects are not reverted (e.g. newly cached artboards are not uncached). A cancellation token can be created via createCancelToken.
The maximum nesting level within artboard layers to search. By default, all levels are searched. 0 also means "no limit"; 1 means only root layers in artboards should be searched.
A matched layer object.
Returns a collection of all layer objects from all artboards within the page (optionally down to a specific nesting level) matching the specified criteria.
This method internally triggers loading of all the artboards. Uncached items are downloaded when the API is configured (and cached when the local cache is configured).
Example:
Layers by name from all artboards on the page
const layers = await page.findLayers({ name: 'Share icon' })Layers by function selector from all artboards on the page
const shareIconLayers = await page.findLayers((layer) => {
return layer.name === 'Share icon'
})Invisible layers from all a certain artboard subset within the page
const layers = await page.findLayers({
visible: false,
artboardId: [ '<ID1>', '<ID2>' ],
})With timeout
const { cancel, token } = createCancelToken()
setTimeout(cancel, 5000) // Throw an OperationCancelled error in 5 seconds.
const layer = await page.findLayers(
{ type: 'shapeLayer' },
{ cancelToken: token }
)Parameters:
A design-wide layer selector. All specified fields must be matched by the result.
Options
A cancellation token which aborts the asynchronous operation. When the token is cancelled, the promise is rejected and side effects are not reverted (e.g. newly cached artboards are not uncached). A cancellation token can be created via createCancelToken.
The maximum nesting level within the artboard layers to search. By default, all levels are searched. 0 also means "no limit"; 1 means only root layers in artboards should be searched.
A collection of matched layer.
Returns a collection of all layer objects which have the specified ID within the artboards on the page.
Layer IDs are unique within individual artboards but different artboards can potentially have layer ID clashes.
This method internally triggers loading of all the artboards. Uncached items are downloaded when the API is configured (and cached when the local cache is configured).
Example:
const layers = await page.findLayersById('<ID>')With timeout
const { cancel, token } = createCancelToken()
setTimeout(cancel, 5000) // Throw an OperationCancelled error in 5 seconds.
const layers = await page.findLayersById('<ID>', { cancelToken: token })Parameters:
A layer ID.
Options
A cancellation token which aborts the asynchronous operation. When the token is cancelled, the promise is rejected and side effects are not reverted (e.g. newly cached artboards are not uncached). A cancellation token can be created via createCancelToken.
The maximum nesting level within artboard layers to search. By default, all levels are searched. 0 also means "no limit"; 1 means only root layers in artboards should be searched.
A collection of matched layer.
Returns a collection of all layers from all artboards within the page (optionally down to a specific nesting level).
The produced collection can be queried further for narrowing down the search.
This method internally triggers loading of all artboards within the page. Uncached items are downloaded when the API is configured (and cached when the local cache is configured).
Example:
All layers from all artboards on the page
const layers = await page.getFlattenedLayers()Root layers from all artboards on the page
const rootLayers = await page.getFlattenedLayers({ depth: 1 })With timeout
const { cancel, token } = createCancelToken()
setTimeout(cancel, 5000) // Throw an OperationCancelled error in 5 seconds.
const layers = await page.getFlattenedLayers({ cancelToken: token })Parameters:
Options
A cancellation token which aborts the asynchronous operation. When the token is cancelled, the promise is rejected and side effects are not reverted (e.g. newly cached artboards are not uncached). A cancellation token can be created via createCancelToken.
The maximum nesting level of layers within the artboards to include in the collection. By default, all levels are included. 0 also means "no limit"; 1 means only root layers in the artboard should be included.
A collection of flattened layers.
Asset Methods
Returns a list of bitmap assets used by layers in all artboards the page contains (optionally down to a specific nesting level).
This method internally triggers loading of all artboards the page contains. Uncached items are downloaded when the API is configured (and cached when the local cache is configured).
Example:
All bitmap assets from all artboards on the page
const bitmapAssetDescs = await page.getBitmapAssets()Bitmap assets excluding pre-rendered bitmaps from all artboards on the page
const bitmapAssetDescs = await page.getBitmapAssets({
includePrerendered: false,
})Parameters:
Options
A cancellation token which aborts the asynchronous operation. When the token is cancelled, the promise is rejected and side effects are not reverted (e.g. newly cached artboards are not uncached). A cancellation token can be created via createCancelToken.
The maximum nesting level within page and artboard layers to search for bitmap asset usage. By default, all levels are searched. 0 also means "no limit"; 1 means only root layers in artboards should be searched.
Whether to also include "pre-rendered" bitmap assets. These assets can be produced by the rendering engine (if configured; future functionality) but are available as assets for either performance reasons or due to the some required data (such as font files) potentially not being available. By default, pre-rendered assets are included.
A list of bitmap assets.
Returns a list of fonts used by layers in all artboards the page contains (optionally down to a specific nesting level).
This method internally triggers loading of all artboards the page contains. Uncached items are downloaded when the API is configured (and cached when the local cache is configured).
Example:
All fonts from all artboards on the page
const fontDescs = await page.getFonts()Parameters:
Options
A cancellation token which aborts the asynchronous operation. When the token is cancelled, the promise is rejected and side effects are not reverted (e.g. newly cached artboards are not uncached). A cancellation token can be created via createCancelToken.
The maximum nesting level within page and artboard layers to search for font usage. By default, all levels are searched. 0 also means "no limit"; 1 means only root layers in artboards should be searched.
A list of fonts.
Rendering Methods
Renders all artboards from the page as a single PNG image file.
All visible layers from the artboards are included.
Uncached items (artboard content and bitmap assets of rendered layers) are downloaded and cached.
The rendering engine and the local cache have to be configured when using this method.
Example:
With default options (1x, whole page area)
await page.renderPageToFile('./rendered/page.png')With custom scale and crop
await page.renderPageToFile('./rendered/page.png', {
scale: 2,
// The result is going to have the dimensions of 400x200 due to the 2x scale.
bounds: { left: 100, top: 0, width: 100, height: 50 },
})Parameters:
The target location of the produced PNG image file.
Render options
A cancellation token which aborts the asynchronous operation. When the token is cancelled, the promise is rejected and side effects are not reverted (e.g. the created image file is not deleted when cancelled during actual rendering). A cancellation token can be created via createCancelToken.
Artboard Lookup Methods
Looks up the first artboard object the page contains matching the provided criteria.
Example:
const productArtboard = page.findArtboard({ name: /Product/i })
const productArtboard = page.findArtboard((artboard) => /Product/i.test(artboard.name))
const oneOfArtboards123 = page.findArtboard({ id: ['<ID1>', '<ID2>', '<ID3>'] })Parameters:
An artboard selector. All specified fields must be matched by the result.
A matched artboard object.
Looks up all artboard objects the page contains matching the provided criteria.
Example:
const productArtboards = page.findArtboards({ name: /Product/i })
const productArtboards = page.findArtboards((artboard) => /Product/i.test(artboard.name))
const artboards123 = page.findArtboards({ id: ['<ID1>', '<ID2>', '<ID3>'] })Parameters:
An artboard selector. All specified fields must be matched by the results.
A list of matched artboard objects.
Returns an artboard object of a specific (main/master) component. These can be used to work with the artboard contents. Component artboards from other pages are not returned.
Example:
const artboard = page.getArtboardByComponentId('<COMPONENT_ID>')Returns a single artboard object. This can be used to work with the artboard contents. Artboards from other pages are not returned.
Example:
const artboard = page.getArtboardById('<ARTBOARD_ID>')Returns a list of artboard object the page contains. These can be used to work with artboard contents.
Example:
const artboards = page.getArtboards()Returns (main/master) component artboard objects the page contains. These can be used to work with artboard contents.
Example:
const componentArtboards = page.getComponentArtboards()Page Lookup Methods
Returns whether the page matches the provided selector.
Example:
console.log(page.name) // A
page.matches({ name: 'A' }) // trueParameters:
The selector against which to test the page.
Whether the page matches.
Status Methods
Returns whether the page content and the content of all artboards the page contains are loaded in memory from the API, a local .octopus file or a local cache.
Example:
const loaded = page.isLoaded()Was this article helpful?