Edit in GitHubLog an issue

Document

Represents a single Photoshop document that is currently open You can access instances of documents using one of these methods:

Copied to your clipboard
1// The currently active document from the Photoshop object
2const currentDocument = app.activeDocument
3
4// Choose one of the open documents from the Photoshop object
5const secondDocument = app.documents[1]
6
7// You can also create an instance of a document via a UXP File entry
8let fileEntry = require('uxp').storage.localFileSystem.getFileForOpening()
9const newDocument = await app.open('/project.psd')

Accessors#

activeLayers#

get activeLayers(): Layer[]

The selected layers in the document

Copied to your clipboard
1const layers = doc.activeLayers;
2const topLayer = layers[0]

backgroundLayer#

get backgroundLayer(): Layer | null

Background layer, if it exists

Copied to your clipboard
const bgLayer = currentDocument.backgroundLayer

height#

get height(): number

Document's height in pixels


layerTree#

get layerTree(): LayerTypes[]

Top level layers in the document


layers#

get layers(): LayerTypes[]

All the layers in the document, in a flat list

Copied to your clipboard
1const layers = currentDocument.layers
2const topLayer = layers[0]

path#

get path(): string

Path to this document, or it's identifier if a cloud document


resolution#

get resolution(): number

Document's resolution (in pixels per inch)

For example, in the default PS document (7 in wide by 5 in tall at 300 ppi)

Copied to your clipboard
1const resolution = doc.resolution // 300
2const width = doc.width // 2100
3const height = doc.height // 1500

title#

get title(): string

Document title

Copied to your clipboard
const currentTitle = doc.title

readonly


width#

get width(): number

Document's width in pixels

Methods#

close#

close(saveDialogOptions?: SaveDialogOptions): Promise‹void›

Closes the document, showing a prompt to save unsaved changes if specified

async

Parameters:

NameType
saveDialogOptions?SaveDialogOptions

closeWithoutSaving#

closeWithoutSaving(): void


createLayer#

createLayer(options?: LayerCreateOptions): Promise‹Layer | null›

Create a layer. See @CreateOptions

Copied to your clipboard
1const myEmptyLayer = await doc.createLayer()
2const myLayer = await doc.createLayer({ name: "myLayer", opacity: 80, mode: "colorDodge" })

async

Parameters:

NameType
options?LayerCreateOptions

createLayerGroup#

createLayerGroup(options?: GroupLayerCreateOptions): Promise‹GroupLayer | null›

Create a layer group. See @CreateOptions

Copied to your clipboard
1const myEmptyGroup = await doc.createLayerGroup()
2const myGroup = await doc.createLayerGroup({ name: "myLayer", opacity: 80, mode: "colorDodge" })
3const nonEmptyGroup = await doc.createLayerGroup({ name: "group", fromLayers: [layer1, layer2] })

async

Parameters:

NameType
options?GroupLayerCreateOptions

crop#

crop(bounds: PsCommon.Bounds, angle: number): Promise‹void›

Crops the document to given bounds

async

Parameters:

NameTypeDefaultDescription
boundsPsCommon.Bounds--
anglenumber0

duplicateLayers#

duplicateLayers(layers: Layer[], targetDocument?: Document): Promise‹Layer[]›

Duplicates given layer(s), creating all copies above the top most one in layer stack, and returns the newly created layers.

Copied to your clipboard
1// duplicate some layers
2const layerCopies = await document.duplicateLayers([layer1, layer3])
3layerCopies.forEach((layer) => { layer.blendMode = 'multiply' })
4// ...to another document
5const finalDoc = await photoshop.open('~/path/to/collated/image.psd')
6await document.duplicateLayers([logo1, textLayer1], finalDoc)
7await finalDoc.close(SaveDialogOptions.SAVE_CHANGES)

async

Parameters:

NameTypeDescription
layersLayer[]-
targetDocument?Documentif specified, duplicate to a different document target.

flatten#

flatten(): Promise‹void›

Flatten all layers in the document

async


groupLayers#

groupLayers(layers: Layer[]): Promise‹GroupLayer | null›

Create a layer group from existing layers.

Copied to your clipboard
1const layers = doc.layers
2const group = await doc.groupLayers([layers[1], layers[2], layers[4]])

async

Parameters:

NameType
layersLayer[]

linkLayers#

linkLayers(layers: Layer[]): Layer[]

Links layers together if possible, and returns a list of linked layers.

Parameters:

NameTypeDescription
layersLayer[]array of layers to link together

array of successfully linked layers


mergeVisibleLayers#

mergeVisibleLayers(): Promise‹void›

Flattens all visible layers in the document

async


resizeCanvas#

resizeCanvas(width: number, height: number, anchor?: AnchorPosition): Promise‹void›

Changes the size of the canvas, but does not change image size To change the image size, see resizeImage

Copied to your clipboard
1// grow the canvas by 400px
2let width = await document.width
3let height = await document.height
4await document.resizeCanvas(width + 400, height + 400)

async

Parameters:

NameTypeDescription
widthnumberNumeric value of new width in pixels
heightnumberNumeric value of new height in pixels
anchor?AnchorPositionAnchor point for resizing, by default will resize an equal amount on all sides.
Of format:
[top/middle/bottom]-[left/center/right]

resizeImage#

resizeImage(width: number, height: number, resolution?: number, resampleMethod?: ResampleMethod): Promise‹void›

Changes the size of the image

Copied to your clipboard
await document.resizeImage(800, 600)

async

Parameters:

NameTypeDescription
widthnumberNumeric value of new width in pixels
heightnumberNumeric value of new height in pixels
resolution?numberImage resolution in pixels per inch (ppi)
resampleMethod?ResampleMethodMethod used during image interpolation.
Possible values are:
  • nearestNeighbor
  • bilinear
  • bicubic
  • bicubicSmoother
  • bicubicSharper
  • bicubicAutomatic
  • preserveDetailsUpscale
  • deepUpscale

rotate#

rotate(angles: number): Promise‹void›

Rotates the image clockwise in given angle, expanding canvas if necessary

async

Parameters:

NameType
anglesnumber

save#

save(entry?: File, saveOptions?: SaveOptions): Promise‹void›

Saves the document or a copy, the format is deduced by the extension

Copied to your clipboard
1// To save a document in the same location
2document.save()
3
4// Shows the save dialog
5unsavedDocument.save()
6
7// To save to a path, use UXP storage APIs to get a file for saving
8let entry = await require('uxp').storage.localFileSystem.getFileForSaving("target.psd")
9document.save(entry)
10
11// To save to a path, but with some options:
12document.save(entry, { embedColorProfile: true })

async

Parameters:

NameType
entry?File
saveOptions?SaveOptions
Copyright © 2021 Adobe. All rights reserved.