Open Design

Class LayerCollectionFacade

Indexable

[index: number]: LayerFacade

Iteration Accessors

length
get length(): number

Returns the number of layers explicitly included in the collection.

This count reflects the number of items returned by getLayers and the native iterator.

returns number

Layer Lookup Methods

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

Returns the first layer object from the collection (optionally down to a specific nesting level) matching the specified criteria.

Both layers explicitly included in the collection and layers nested within those layers are searched.

Note that the layer subtrees within the individual layers explicitly included in the collection are walked in document order, not level by level, which means that nested layers of a layer are searched before searching sibling layers of the layer.

Example:

Layer by name from any artboard

const layer = await collection.findLayer({ name: 'Share icon' })

Layer by function selector from any artboard

const shareIconLayer = await collection.findLayer((layer) => {
  return layer.name === 'Share icon'
})

Layer by name from a certain artboad subset

const layer = await collection.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 collection.findLayer(
  { name: 'Share icon' },
  { cancelToken: token }
)

Parameters:

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

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

options: default: {}

Options

Optionaldepth?: number

The maximum nesting level within the layers explictly included in the collection to search. By default, all levels are searched. 0 also means "no limit"; 1 means only the layers explicitly included in the collection should be searched.

returns null | LayerFacade

A matched layer object.

findLayers
findLayers(selector: DesignLayerSelector | (layer: LayerFacade) => boolean, options?: { depth?: number }): LayerCollectionFacade

Returns a collection of all layer objects from the collection (optionally down to a specific nesting level) matching the specified criteria.

Both layers explicitly included in the collection and layers nested within those layers are searched.

Note that the results from layer subtrees within the individual layers explicitly included in the collection are sorted in document order, not level by level, which means that nested layers of a layer are included before matching sibling layers of the layer.

Example:

Layers by name from all artboards

const layers = await collection.findLayers({ name: 'Share icon' })

Layers by function selector from all artboards

const shareIconLayers = await collection.findLayers((layer) => {
  return layer.name === 'Share icon'
})

Invisible layers from all a certain artboard subset

const layers = await collection.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 collection.findLayers(
  { type: 'shapeLayer' },
  { cancelToken: token }
)

Parameters:

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

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

options: default: {}

Options

Optionaldepth?: number

The maximum nesting level within the layers explictly included in the collection to search. By default, all levels are searched. 0 also means "no limit"; 1 means only the layers explicitly included in the collection should be searched.

A layer collection of matched layers.

getLayers
getLayers(): Array<LayerFacade>

Returns the collection layers as a native Array.

The layers explicitly included in the collection are iterated over, but layers nested in them are not.

returns Array<LayerFacade>

Asset Methods

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

Returns a list of bitmap assets used by the layers in the collection within the layer (optionally down to a specific nesting level).

Both layers explicitly included in the collection and layers nested within those layers are searched.

Example:

All bitmap assets from layers from any artboard

const bitmapAssetDescs = await collection.getBitmapAssets()

Bitmap assets excluding pre-renredered bitmaps from layers from any artboards

const bitmapAssetDescs = await collection.getBitmapAssets({
  includePrerendered: false,
})

Parameters:

options: default: {}

Options

Optionaldepth?: number

The maximum nesting level within the layer to search for bitmap asset usage. By default, all levels are searched. Specifying the depth of 0 leads to bitmap assets of layers nested in the explicitly included layers being omitted altogether.

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 Array<BitmapAssetDescriptor & { artboardLayerIds: Record<string, Array<string>> }>

A list of bitmap assets.

getFonts
getFonts(options?: { depth?: number }): Array<FontDescriptor & { artboardLayerIds: Record<string, Array<string>> }>

Returns a list of fonts used by the layers in the collection within the layer (optionally down to a specific nesting level).

Both layers explicitly included in the collection and layers nested within those layers are searched.

Example:

All fonts from layers from any artboard

const fontDescs = await design.getFonts()

Parameters:

options: default: {}

Options

Optionaldepth?: number

The maximum nesting level within the layer to search for font usage. By default, all levels are searched. Specifying the depth of 0 leads to bitmap assets of layers nested in the explicitly included layers being omitted altogether.

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

A list of bitmap assets.

Iteration Methods

[Symbol.iterator]
[Symbol.iterator](): Iterator<LayerFacade, any, undefined>

Returns an iterator which iterates over the collection layers.

The layers explicitly included in the collection are iterated over, but layers nested in them are not.

returns Iterator<LayerFacade, any, undefined>
filter
filter(filter: (layer: LayerFacade, index: number) => boolean): LayerCollectionFacade

Returns a new layer collection which only includes layers for which the filter returns true.

The layers explicitly included in the collection are iterated over, but layers nested in them are not.

Example:

const textLayers = collection.filter((layer) => {
  return layer.type === 'textLayer'
})

Parameters:

filter:

The filter to apply to the layers in the collection.

Parameters:

index: number
returns boolean

A filtered layer collection.

flatMap
flatMap<T>(mapper: (layer: LayerFacade, index: number, layers: Array<LayerFacade>) => Array<T>): Array<T>

Returns a native Array which returns mapper function results for all of the layers from the collection. The arrays produced by the mapper function are concatenated (flattened).

The layers explicitly included in the collection are iterated over, but layers nested in them are not.

Example:

const textValues = collection.flatMap((layer) => {
  const text = layer.getText()
  return text ? [ text.getTextContent() ] : []
})

Type parameters:

T

Parameters:

mapper:

The mapper function to apply to the layers in the collection.

Parameters:

index: number
layers: Array<LayerFacade>
returns Array<T>
returns Array<T>

An array of flattened mapper results.

forEach
forEach(fn: (layer: LayerFacade, index: number, layers: Array<LayerFacade>) => unknown): void

Iterates over the the layers in the collection and invokes the provided function with each one of them.

The layers explicitly included in the collection are iterated over, but layers nested in them are not.

Example:

collection.forEach((layer) => {
  console.log(layer.name)
})

Parameters:

fn:

The function to apply to the layers in the collection.

Parameters:

index: number
layers: Array<LayerFacade>
returns unknown
returns void
map
map<T>(mapper: (layer: LayerFacade, index: number, layers: Array<LayerFacade>) => T): Array<T>

Returns a native Array which returns mapper function results for each of the layers from the collection.

The layers explicitly included in the collection are iterated ovser, but layers nested in them are not.

Example:

const textValues = collection.map((layer) => {
  const text = layer.getText()
  return text ? text.getTextContent() : null
})

Type parameters:

T

Parameters:

mapper:

The mapper function to apply to the layers in the collection.

Parameters:

index: number
layers: Array<LayerFacade>
returns T
returns Array<T>

An array of mapper function results.

reduce
reduce<T>(reducer: (state: T, layer: LayerFacade, index: number) => T, initialValue: T): T

Returns a reduction of all layers from the collection.

The layers explicitly included in the collection are iterated over, but layers nested in them are not.

Example:

const textValues = collection.reduce((values, layer) => {
  const text = layer.getText()
  return text ? values.concat([ text.getTextContent() ]) : values
}, [])

Type parameters:

T

Parameters:

reducer:

The reducer function to apply to the layers in the collection.

Parameters:

state: T
index: number
returns T
initialValue: T

The value passed as the first argument to the reducer function applied to the first layer in the collection.

returns T

The reduction result.

Collection Manipulation Methods

concat

Returns a new layer collection which includes all layers explicitly included in the original collection and the provided collection.

Layers nested in the layers explicitly included in the collections are not explictly included in the new collection either.

Example:

Merge two collections

const textLayersFromA = await artboardA.findLayers({ type: 'textLayers' })
const textLayersFromB = await artboardB.findLayers({ type: 'textLayers' })
const textLayersFromAB = textLayersFromA.concat(textLayersFromB)

Append individual layers

const extraLayer = await artboard.getLayerById('<ID>')
const extendedCollection = collection.concat([ extraLayer ])

Parameters:

addedLayers: LayerCollectionFacade | Array<LayerFacade>

The layer collection to concatenate with the original collection. A native Array of layer objects can be provided instead of an actual collection object.

A merged layer collection.

flatten
flatten(options?: { depth?: number }): LayerCollectionFacade

Returns a new layer collection which includes all layers explicitly included in the original collection as well as layers nested within those layers (optionally down to a specific nesting level).

Example:

const groupLayers = await artboard.findLayers({ type: 'groupLayer' })

const groupLayersWithImmediateChildren = groupLayers.flatten({ depth: 1 })
const groupLayersWithAllChildren = groupLayers.flatten()

Parameters:

options: default: {}

Options

Optionaldepth?: number

The maximum nesting level within the layers explicitly included in the original collection to explicitly include in the new collection. 0 also means "no limit"; 1 means only the layers nested immediately in the collection layers should be included in the new colleciton.

A flattened layer collection.

Rendering Methods

renderToFile
renderToFile(filePath: string, options?: { bounds?: Bounds; cancelToken?: null | CancelToken; layerAttributes?: Record<string, LayerAttributesConfig>; scale?: number }): Promise<void>

Renders all layers in the collection as a single PNG image file.

In case of group layers, all visible nested layers are also included.

This can only be done for collections containing layers from a single artboards. When there are layers from multiple artboards, the operation is rejected.

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 combined layer area)

await collection.renderToFile(
  './rendered/collection.png'
)

With custom scale and crop and using the custom layer configuration

await collection.renderToFile(
  './rendered/collection.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 },
    layerAttributes: {
      '<LAYER1>': { blendingMode: 'SOFT_LIGHT', includeComponentBackground: true },
      '<LAYER2>': { opacity: 0.6 },
    }
  }
)

Parameters:

filePath: string

The target location of the produced PNG image file.

options: default: {}

Render options.

Optionalbounds?: Bounds

The area to include. This can be used to either crop or expand (add empty space to) the default layer area.

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.

OptionallayerAttributes?: Record<string, LayerAttributesConfig>

Layer-specific options to use for the rendering instead of the default values.

Optionalscale?: number

The scale (zoom) factor to use for rendering instead of the default 1x factor.

returns Promise<void>

A list of fonts.

SVG Export Methods

exportToSvgCode
exportToSvgCode(options?: { cancelToken?: null | CancelToken; layerAttributes?: Record<string, LayerOctopusAttributesConfig>; scale?: number }): Promise<string>

Return an SVG document string of all layers in the collection.

In case of group layers, all visible nested layers are also included.

This can only be done for collections containing layers from a single artboards. When there are layers from multiple artboards, the operation is rejected.

Uncached items (artboard content and bitmap assets of exported 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)

const svg = await collection.exportToSvgCode()

With a custom scale

const svg = await collection.exportToSvgCode({ scale: 2 })

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. the created image file is not deleted when cancelled during actual rendering). A cancellation token can be created via createCancelToken.

OptionallayerAttributes?: Record<string, LayerOctopusAttributesConfig>

Layer-specific options to use for instead of the default values.

Optionalscale?: number

The scale (zoom) factor to use for rendering instead of the default 1x factor.

returns Promise<string>

An SVG document string.

exportToSvgFile
exportToSvgFile(filePath: string, options?: { cancelToken?: null | CancelToken; layerAttributes?: Record<string, LayerOctopusAttributesConfig>; scale?: number }): Promise<void>

Export all layers in the collection as an SVG file.

In case of group layers, all visible nested layers are also included.

This can only be done for collections containing layers from a single artboards. When there are layers from multiple artboards, the operation is rejected.

Uncached items (artboard content and bitmap assets of exported 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)

const svg = await collection.exportToSvgFile('./collection.svg')

With a custom scale

const svg = await collection.exportToSvgFile('./collection.svg', { scale: 2 })

Parameters:

filePath: string

The target location of the produced SVG file.

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. the created image file is not deleted when cancelled during actual rendering). A cancellation token can be created via createCancelToken.

OptionallayerAttributes?: Record<string, LayerOctopusAttributesConfig>

Layer-specific options to use for instead of the default values.

Optionalscale?: number

The scale (zoom) factor to use for rendering instead of the default 1x factor.

returns Promise<void>