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

Properties#

saveAs#

saveAs: object

Save the document to a desired file type.

For operations that require a UXP File token, use the UXP storage APIs to generate one. See https://www.adobe.com/go/ps-api-uxp-filesystemprovider.

Copied to your clipboard
1let entry = await require('uxp').storage.localFileSystem.getFileForSaving("target.psd");
2document.saveAs.psd(entry);
3
4// Save as a Copy (High JPG quality)
5document.saveAs.jpg(entryJpg, { quality: 12 }, true);
6
7// Save a PSB, with some options:
8document.saveAs.psb(entryPsb, { embedColorProfile: true });
9

Type declaration#

NameType
bmp(entry: File, saveOptions?: BMPSaveOptions, asCopy: boolean) => Promise<void>
gif(entry: File, saveOptions?: GIFSaveOptions, asCopy: boolean) => Promise<void>
jpg(entry: File, saveOptions?: JPEGSaveOptions, asCopy: boolean) => Promise<void>
png(entry: File, saveOptions?: PNGSaveOptions, asCopy: boolean) => Promise<void>
psb(entry: File, saveOptions?: PhotoshopSaveOptions, asCopy: boolean) => Promise<void>
psd(entry: File, saveOptions?: PhotoshopSaveOptions, asCopy: boolean) => Promise<void>

Properties#

NameTypeAccessDescription
activeChannelsChannel[]Read-writeCurrently active channels of the document
activeHistoryBrushSourceHistoryStateRead-writeThe history state that history brush tool will use as its source
activeHistoryStateHistoryStateRead-writeCurrently active history state of the document
activeLayersLayersRead-onlyThe selected layers in the document
artboardsLayersRead-onlyThe artboards in the document
backgroundLayerLayerRead-onlyBackground layer, if it exists
bitsPerChannelBitsPerChannelTypeRead-writeThe bits per color channel.
channelsChannelsRead-onlyAll channels in the document.
cloudDocumentbooleanRead-onlyThis document is in the Adobe Creative Cloud.
cloudWorkAreaDirectorystringRead-onlyLocal directory for this cloud document.
colorProfileNamestringRead-writeName of the color profile. Valid only when colorProfileType is `CUSTOM` or `WORKING`, returns "None" otherwise
colorProfileTypeColorProfileTypeRead-writeWhether the document uses the working color profile, a custom profile, or no profile.
compositeChannelsChannel[]Read-onlyComposite channels in the document.
guidesGuidesRead-only-
heightnumberRead-onlyDocument's height in pixels
histogramnumber[]Read-onlyA histogram containing the number of pixels at each color intensity level for the composite channel. The array contains 256 members. Valid only when mode = `DocumentMode.{RGB,CMYK,INDEXEDCOLOR}`
historyStatesHistoryStatesRead-onlyHistory states of the document
idnumberRead-onlyThe internal ID of this document, valid as long as this document is open Can be used for batchPlay calls to refer to this document, used internally
layersLayersRead-onlyAll the layers in the document at the top level
modeDocumentModeRead-onlyThe color profile. To change it, please use Document.changeMode
namestringRead-onlyThe name of the document
pathstringRead-onlyFull file system path to this document, or the identifier if it is a cloud document
pathItemsPathItemsRead-onlyThe collection of paths in this document, currently shown in the Paths panel. Added in 23.3
pixelAspectRationumberRead-writeThe (custom) pixel aspect ratio to use
quickMaskModebooleanRead-writeThe state of Quick Mask mode. If true, the app is in Quick Mask mode.
resolutionnumberRead-onlyDocument's resolution (in pixels per inch)
savedbooleanRead-onlyTrue if the document has been saved since the last change.
titlestringRead-onlyDocument title
typenamestringRead-onlyThe class name of the referenced Document object
widthnumberRead-onlyDocument's width in pixels

Methods#

changeMode#

async : Promise<void>

Changes the color profile of the document

Parameters#

NameType
modeChangeMode
options?BitmapConversionOptions | IndexedConversionOptions

close#

async : Promise<void>

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

Parameters#

NameType
saveDialogOptionsSaveOptions

closeWithoutSaving#

void

Close the document, reverting all unsaved changes.


convertProfile#

async : Promise<void>

Changes the color profile.

destinationProfile must be either a string that names the color mode, or one of these below, meaning of the working color spaces or Lab color.

"Working RGB", "Working CMYK", "Working Gray", "Lab Color"

Parameters#

NameType
destinationProfilestring
intentIntent
blackPointCompensation?boolean
dither?boolean

createLayer#

async : Promise<Layer>

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" })

Parameters#

NameType
options?LayerCreateOptions

createLayerGroup#

async : Promise<Layer>

Create a layer group. See GroupLayerCreateOptions

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] })

Parameters#

NameType
options?GroupLayerCreateOptions

crop#

async : Promise<void>

Crops the document to given bounds

Parameters#

NameTypeDefault value
boundsBounds-
anglenumber0
widthnumber0
heightnumber0

duplicate#

Promise<Document>

Creates a duplicate of the document, making the duplicate active.

The optional parameter name provides the name for the duplicated document.

The optional parameter mergeLayersOnly indicates whether to only duplicate merged layers.

Parameters#

NameType
name?string
mergeLayersOnly?boolean

duplicateLayers#

async : 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(SaveOptions.SAVECHANGES)

Parameters#

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

flatten#

async : Promise<void>

Flatten all layers in the document


groupLayers#

async : Promise<Layer>

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

Parameters#

NameType
layersLayer[]

linkLayers#

Layer[]

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

Parameters#

NameTypeDescription
layersLayer[]array of layers to link together

mergeVisibleLayers#

async : Promise<void>

Merges all visible layers in the document into a single layer.


paste#

async : Promise<Layer>

Pastes the contents of the clipboard into the document. If the optional argument is set to true and a selection is active, the contents are pasted into the selection.

Parameters#

NameType
intoSelection?boolean

rasterizeAllLayers#

async : Promise<void>

Rasterizes all layers.


resizeCanvas#

async : 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)

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.

resizeImage#

async : Promise<void>

Changes the size of the image

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

Parameters#

NameTypeDescription
width?numberNumeric value of new width in pixels
height?numberNumeric value of new height in pixels
resolution?numberImage resolution in pixels per inch (ppi)
resampleMethod?ResampleMethodMethod used during image interpolation.
amount?numberNumeric value that controls the amount of noise value when using preserve details 0..100

revealAll#

async : Promise<void>

Expands the document to show clipped sections.


rotate#

async : Promise<void>

Rotates the image clockwise in given angle, expanding canvas if necessary. (Previously rotateCanvas)

Parameters#

NameType
anglesnumber

save#

async : Promise<void>

Performs a save of the document. The user will be presented with a Save dialog if the file has yet to be saved on disk.

Copied to your clipboard
1// To save a document in the current location
2document.save()
3
4// Shows the save dialog
5unsavedDocument.save()

splitChannels#

async : Promise<Document[]>

Splits the document channels into separate, single-channel documents.


suspendHistory#

Promise<void>

Creates a single history state encapsulating everything that is done in the callback, only for this document. All changes to the document should be done in this callback.

Note: If you make changes to any other document, those changes will not be suspended in the same history state.

The callback is passed in a SuspendHistoryContext object, which contains the current document in a variable document.

For more info and advanced context, see core.executeAsModal API, for which this API is a simple wrapper for.

Copied to your clipboard
1 require("photoshop").app.activeDocument.suspendHistory(async (context) => {
2 // context.document is the `app.activeDocument`
3 context.document.activeLayers[0].name = "Changed name";
4 });

Parameters#

NameType
callback(e: SuspendHistoryContext) => void
historyStateNamestring

trap#

async : Promise<void>

Applies trapping to a CMYK document.

Valid only when Document.mode is Constants.DocumentMode.CMYK

Parameters#

NameType
widthnumber

trim#

async : Promise<void>

Trims the transparent area around the image on the specified sides of the canvas base on trimType

Parameters#

NameTypeDefault value
trimTypeTrimType-
topbooleantrue
leftbooleantrue
bottombooleantrue
rightbooleantrue
  • Privacy
  • Terms of Use
  • Do not sell my personal information
  • AdChoices
Copyright © 2022 Adobe. All rights reserved.