Open Design

Class PageFacade

Identification Accessors

fileKey
get fileKey(): string

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`)
returns string
id
get id(): string

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.

returns string
name
get name(): null | string

The name of the artboard.

returns null | string

Reference Methods

getDesign
getDesign(): DesignFacade

Returns the design object associated with the page object.

Example:

const design = page.getDesign()
returns DesignFacade

Layer Lookup Methods

findLayer
findLayer(selector: DesignLayerSelector | (layer: LayerFacade) => boolean, options?: { cancelToken?: null | CancelToken; depth?: number }): Promise<null | LayerFacade>

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:

selector: DesignLayerSelector | (layer: LayerFacade) => boolean

A design-wide layer selector. All specified fields must be matched by the result.

options: default: {}

Options

OptionalcancelToken?: null | CancelToken

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.

Optionaldepth?: number

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.

returns Promise<null | LayerFacade>

A matched layer object.

findLayerById
findLayerById(layerId: string, options?: { cancelToken?: null | CancelToken; depth?: number }): Promise<null | LayerFacade>

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:

layerId: string

A layer ID.

options: default: {}

Options

OptionalcancelToken?: null | CancelToken

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.

Optionaldepth?: number

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.

returns Promise<null | LayerFacade>

A matched layer object.

findLayers
findLayers(selector: DesignLayerSelector | (layer: LayerFacade) => boolean, options?: { cancelToken?: null | CancelToken; depth?: number }): Promise<LayerCollectionFacade>

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:

selector: DesignLayerSelector | (layer: LayerFacade) => boolean

A design-wide layer selector. All specified fields must be matched by the result.

options: default: {}

Options

OptionalcancelToken?: null | CancelToken

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.

Optionaldepth?: number

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.

returns Promise<LayerCollectionFacade>

A collection of matched layer.

findLayersById
findLayersById(layerId: string, options?: { cancelToken?: null | CancelToken; depth?: number }): Promise<LayerCollectionFacade>

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:

layerId: string

A layer ID.

options: default: {}

Options

OptionalcancelToken?: null | CancelToken

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.

Optionaldepth?: number

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.

returns Promise<LayerCollectionFacade>

A collection of matched layer.

getFlattenedLayers
getFlattenedLayers(options?: { cancelToken?: null | CancelToken; depth?: number }): Promise<LayerCollectionFacade>

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: default: {}

Options

OptionalcancelToken?: null | CancelToken

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.

Optionaldepth?: number

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.

returns Promise<LayerCollectionFacade>

A collection of flattened layers.

Asset Methods

getBitmapAssets
getBitmapAssets(options?: { cancelToken?: null | CancelToken; depth?: number; includePrerendered?: boolean }): Promise<Array<BitmapAssetDescriptor & { artboardLayerIds: Record<string, Array<string>> }>>

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: default: {}

Options

OptionalcancelToken?: null | CancelToken

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.

Optionaldepth?: number

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.

OptionalincludePrerendered?: boolean

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.

returns Promise<Array<BitmapAssetDescriptor & { artboardLayerIds: Record<string, Array<string>> }>>

A list of bitmap assets.

getFonts
getFonts(options?: { cancelToken?: null | CancelToken; depth?: number }): Promise<Array<FontDescriptor & { artboardLayerIds: Record<string, Array<string>> }>>

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: default: {}

Options

OptionalcancelToken?: null | CancelToken

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.

Optionaldepth?: number

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.

returns Promise<Array<FontDescriptor & { artboardLayerIds: Record<string, Array<string>> }>>

A list of fonts.

Rendering Methods

renderToFile
renderToFile(filePath: string, options?: { cancelToken?: null | CancelToken }): Promise<void>

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:

filePath: string

The target location of the produced PNG image file.

options: default: {}

Render options

OptionalcancelToken?: null | CancelToken

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.

returns Promise<void>

Artboard Lookup Methods

findArtboard
findArtboard(selector: ArtboardSelector | (artboard: ArtboardFacade) => boolean): null | ArtboardFacade

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:

selector: ArtboardSelector | (artboard: ArtboardFacade) => boolean

An artboard selector. All specified fields must be matched by the result.

returns null | ArtboardFacade

A matched artboard object.

findArtboards
findArtboards(selector: ArtboardSelector | (artboard: ArtboardFacade) => boolean): Array<ArtboardFacade>

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:

selector: ArtboardSelector | (artboard: ArtboardFacade) => boolean

An artboard selector. All specified fields must be matched by the results.

returns Array<ArtboardFacade>

A list of matched artboard objects.

getArtboardByComponentId
getArtboardByComponentId(componentId: string): null | ArtboardFacade

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>')

Parameters:

componentId: string

A component ID.

returns null | ArtboardFacade

An artboard object.

getArtboardById
getArtboardById(artboardId: string): null | ArtboardFacade

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>')

Parameters:

artboardId: string

An artboard ID.

returns null | ArtboardFacade

An artboard object.

getArtboards
getArtboards(): Array<ArtboardFacade>

Returns a list of artboard object the page contains. These can be used to work with artboard contents.

Example:

const artboards = page.getArtboards()
returns Array<ArtboardFacade>
getComponentArtboards
getComponentArtboards(): Array<ArtboardFacade>

Returns (main/master) component artboard objects the page contains. These can be used to work with artboard contents.

Example:

const componentArtboards = page.getComponentArtboards()
returns Array<ArtboardFacade>

Page Lookup Methods

matches
matches(selector: PageSelector): boolean

Returns whether the page matches the provided selector.

Example:

console.log(page.name) // A
page.matches({ name: 'A' }) // true

Parameters:

selector: PageSelector

The selector against which to test the page.

returns boolean

Whether the page matches.

Status Methods

isLoaded
isLoaded(): boolean

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()
returns boolean