Document

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

Copy
const {app, constants} = require('photoshop');

// The currently active document from the Photoshop object
const currentDocument = app.activeDocument;

// Choose one of the open documents from the Photoshop object
const secondDocument = app.documents[1];

// You can also create an instance of a document via a UXP File entry
let fileEntry = require('uxp').storage.localFileSystem.getFileForOpening();
const newDocument = await app.open('/project.psd');
Copied to your clipboard
const {app, constants} = require('photoshop');

// The currently active document from the Photoshop object
const currentDocument = app.activeDocument;

// Choose one of the open documents from the Photoshop object
const secondDocument = app.documents[1];

// You can also create an instance of a document via a UXP File entry
let fileEntry = require('uxp').storage.localFileSystem.getFileForOpening();
const 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.

Copy
let entry = await require('uxp').storage.localFileSystem.getFileForSaving("target.psd");
document.saveAs.psd(entry);

// Save as a Copy (High JPG quality)
document.saveAs.jpg(entryJpg, { quality: 12 }, true);

// Save a PSB, with some options:
document.saveAs.psb(entryPsb, { embedColorProfile: true });
Copied to your clipboard
let entry = await require('uxp').storage.localFileSystem.getFileForSaving("target.psd");
document.saveAs.psd(entry);

// Save as a Copy (High JPG quality)
document.saveAs.jpg(entryJpg, { quality: 12 }, true);

// Save a PSB, with some options:
document.saveAs.psb(entryPsb, { embedColorProfile: true });

Type declaration

selection

• Readonly selection: Selection

The object containing the document's currently active selection

Properties

Methods

calculations

async : Promise<void | Channel | Document>

The Calculations command lets you blend two individual channels from one or more source images. You can then apply the results to a new image or to a new channel or selection in the active image.

Performs Image > Calculations on the document. See the CalculationsOptions object for more info and examples.

Copy
const doc = app.activeDocument;
const options = {
    source1: {
        document: doc,
        layer: doc.layers[0],
        channel: constants.CalculationsChannel.GRAY
        invert: true
    },
    source2: {
        document: doc,
        layer: constants.CalculationsLayer.MERGED,
        channel: doc.channels[2]
    },
    blending: constants.CalculationsBlendMode.DARKEN,
    opacity: 50,
    result: constants.CalculationsResult.NEWCHANNEL
};
doc.calculations(options);

Copied to your clipboard
const doc = app.activeDocument;
const options = {
    source1: {
        document: doc,
        layer: doc.layers[0],
        channel: constants.CalculationsChannel.GRAY
        invert: true
    },
    source2: {
        document: doc,
        layer: constants.CalculationsLayer.MERGED,
        channel: doc.channels[2]
    },
    blending: constants.CalculationsBlendMode.DARKEN,
    opacity: 50,
    result: constants.CalculationsResult.NEWCHANNEL
};
doc.calculations(options);

Known issue: currently calculations requires having exactly one unlocked pixel layer being selected otherwise it won't work. In future there should not be any layer requirements since this cannot output into layer.

Parameters

changeMode

async : Promise<void>

Changes the color mode of the document.

Parameters

close

async : Promise<void>

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

Parameters

closeWithoutSaving

void

Close the document, discarding 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

createLayer

async : Promise<Layer>

General form of the kind-specific methods below. See those methods for more information.

Create a new layer of the given kind. With no arguments, a pixel layer will be created. The options object will have properties specific to the kind, though all layers share a basic set of properties common to all. The override signatures below are provided as type guardrails to help ensure the options provided match the layer kind.

Copy
await doc.createLayer(); // defaults to pixel layer

await doc.createLayer(
  constants.LayerKind.NORMAL, // pixel layer
  { name: "myLayer",
    opacity: 80,
    blendMode: constants.BlendMode.COLORDODGE }
);
Copied to your clipboard
await doc.createLayer(); // defaults to pixel layer

await doc.createLayer(
  constants.LayerKind.NORMAL, // pixel layer
  { name: "myLayer",
    opacity: 80,
    blendMode: constants.BlendMode.COLORDODGE }
);

Promise<Layer>

Parameters

async : Promise<Layer>

Create a new layer group.

Copy
await doc.createLayer(
  constants.LayerKind.GROUP,
  { name: "myLayer", opacity: 80 }
);
Copied to your clipboard
await doc.createLayer(
  constants.LayerKind.GROUP,
  { name: "myLayer", opacity: 80 }
);

Parameters

async : Promise<Layer>

Create a new text layer.

Copy
await doc.createLayer( 
  Constants.LayerKind.TEXT,
  { name: "message", contents: "Hello World" }
);
Copied to your clipboard
await doc.createLayer( 
  Constants.LayerKind.TEXT,
  { name: "message", contents: "Hello World" }
);

Parameters

createLayerGroup

async : Promise<Layer>

Create a layer group using options described by GroupLayerCreateOptions.

Copy
const myEmptyGroup = await doc.createLayerGroup()
const myGroup = await doc.createLayerGroup({
  name: "myLayer",
  opacity: 80,
  blendMode: "colorDodge"
});
const nonEmptyGroup = await doc.createLayerGroup({
  name: "group",
  fromLayers: [layer1, layer2]
});
const selectedGroup = await doc.createLayerGroup({
  name: "group",
  fromLayers: doc.activeLayers
});
Copied to your clipboard
const myEmptyGroup = await doc.createLayerGroup()
const myGroup = await doc.createLayerGroup({
  name: "myLayer",
  opacity: 80,
  blendMode: "colorDodge"
});
const nonEmptyGroup = await doc.createLayerGroup({
  name: "group",
  fromLayers: [layer1, layer2]
});
const selectedGroup = await doc.createLayerGroup({
  name: "group",
  fromLayers: doc.activeLayers
});

Parameters

createPixelLayer

async : Promise<Layer>

Create a pixel layer using options described by PixelLayerCreateOptions.

Copy
await doc.createPixelLayer({
  name: "myLayer",
  opacity: 80,
  fillNeutral: true
});
Copied to your clipboard
await doc.createPixelLayer({
  name: "myLayer",
  opacity: 80,
  fillNeutral: true
});

Parameters

createTextLayer

async : Promise<Layer>

Create a text layer using options described by TextLayerCreateOptions.

Copy
await doc.createTextLayer()
await doc.createTextLayer({
  name: "myTextLayer",
  contents: "Hello, World!",
  fontSize: 32
});
Copied to your clipboard
await doc.createTextLayer()
await doc.createTextLayer({
  name: "myTextLayer",
  contents: "Hello, World!",
  fontSize: 32
});

Parameters

crop

async : Promise<void>

Crops the document to the given bounds.

Parameters

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

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.

Copy
// duplicate some layers
const layerCopies = await document.duplicateLayers([layer1, layer3])
layerCopies.forEach((layer) => { layer.blendMode = 'multiply' })
// ...to another document
const finalDoc = await photoshop.open('~/path/to/collated/image.psd')
await document.duplicateLayers([logo1, textLayer1], finalDoc)
await finalDoc.close(SaveOptions.SAVECHANGES)
Copied to your clipboard
// duplicate some layers
const layerCopies = await document.duplicateLayers([layer1, layer3])
layerCopies.forEach((layer) => { layer.blendMode = 'multiply' })
// ...to another document
const finalDoc = await photoshop.open('~/path/to/collated/image.psd')
await document.duplicateLayers([logo1, textLayer1], finalDoc)
await finalDoc.close(SaveOptions.SAVECHANGES)

Parameters

flatten

async : Promise<void>

Flatten all layers in the document. The remaining layer will become Background.

groupLayers

async : Promise<Layer>

Create a layer group from existing layers.

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

Parameters

linkLayers

Layer[]

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

Parameters

mergeVisibleLayers

async : Promise<void>

Merges all visible layers in the document into a single layer. In constrast to flatten, mergeVisibleLayers will not convert the remaining layer to Background if no Background already exists. If not Background, then the name of the merged layer will be either that of the top of the selected layers or the top 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

rasterizeAllLayers

async : Promise<void>

Converts all layers to pixel layers.

resizeCanvas

async : Promise<void>

Changes the size of the document, but does not scale the image. To scale the image size, see resizeImage.

Copy
// grow the canvas by 400px
const {width, height} = await app.activeDocument;
await document.resizeCanvas(width + 400, height + 400);
Copied to your clipboard
// grow the canvas by 400px
const {width, height} = await app.activeDocument;
await document.resizeCanvas(width + 400, height + 400);

Parameters

resizeImage

async : Promise<void>

Changes the size of the image by scaling the dimensions to meet the targeted number of pixels.

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

Parameters

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

sampleColor

async : Promise<SolidColor | NoColor>

Returns a SolidColor object sampled from the document at the given position.

Copy
let col = await app.activeDocument.sampleColor({x: 100, y: 100});
console.log(col.rgb);
// {
//    red: 233,
//    green: 179,
//    blue: 135,
//    hexValue: "E9B387"
// }
Copied to your clipboard
let col = await app.activeDocument.sampleColor({x: 100, y: 100});
console.log(col.rgb);
// {
//    red: 233,
//    green: 179,
//    blue: 135,
//    hexValue: "E9B387"
// }

Parameters

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.

Copy
// To save a document in the current location
document.save()

// Shows the save dialog
unsavedDocument.save()
Copied to your clipboard
// To save a document in the current location
document.save()

// Shows the save dialog
unsavedDocument.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 suspendHistory is a simple wrapper.

Copy
   app.activeDocument.suspendHistory(async (context) => {
       // context.document below is, in this case, `app.activeDocument`
       context.document.activeLayers[0].name = "Changed name";
   });
Copied to your clipboard
   app.activeDocument.suspendHistory(async (context) => {
       // context.document below is, in this case, `app.activeDocument`
       context.document.activeLayers[0].name = "Changed name";
   });

Parameters

trap

async : Promise<void>

Applies trapping to a CMYK document.

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

Parameters

trim

async : Promise<void>

Trims the area around the image according to the type of pixels given. All sides of the image are targeted by default. Optionally, the sides may be individually specified for exclusion.

Copy
//  trim transparent pixels from only the bottom of the image
app.activeDocument.trim(constants.TrimType.TRANSPARENT, false, false, true, false);
Copied to your clipboard
//  trim transparent pixels from only the bottom of the image
app.activeDocument.trim(constants.TrimType.TRANSPARENT, false, false, true, false);

Parameters

Last updated 9/27/2022

Was this helpful?

Yes

No