Document
Represents a single Photoshop document that is currently open You can access instances of documents using one of these methods:
Copied to your clipboard1// The currently active document from the Photoshop object2const currentDocument = app.activeDocument34// Choose one of the open documents from the Photoshop object5const secondDocument = app.documents[1]67// You can also create an instance of a document via a UXP File entry8let 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 clipboard1let entry = await require('uxp').storage.localFileSystem.getFileForSaving("target.psd");2document.saveAs.psd(entry);34// Save as a Copy (High JPG quality)5document.saveAs.jpg(entryJpg, { quality: 12 }, true);67// Save a PSB, with some options:8document.saveAs.psb(entryPsb, { embedColorProfile: true });9
Type declaration#
Name | Type |
---|---|
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#
Name | Type | Access | Description |
---|---|---|---|
activeChannels | Channel[] | Read-write | Currently active channels of the document |
activeHistoryBrushSource | HistoryState | Read-write | The history state that history brush tool will use as its source |
activeHistoryState | HistoryState | Read-write | Currently active history state of the document |
activeLayers | Layers | Read-only | The selected layers in the document |
artboards | Layers | Read-only | The artboards in the document |
backgroundLayer | Layer | Read-only | Background layer, if it exists |
bitsPerChannel | BitsPerChannelType | Read-write | The bits per color channel. |
channels | Channels | Read-only | All channels in the document. |
cloudDocument | boolean | Read-only | This document is in the Adobe Creative Cloud. |
cloudWorkAreaDirectory | string | Read-only | Local directory for this cloud document. |
colorProfileName | string | Read-write | Name of the color profile. Valid only when colorProfileType is `CUSTOM` or `WORKING`, returns "None" otherwise |
colorProfileType | ColorProfileType | Read-write | Whether the document uses the working color profile, a custom profile, or no profile. |
compositeChannels | Channel[] | Read-only | Composite channels in the document. |
guides | Guides | Read-only | - |
height | number | Read-only | Document's height in pixels |
histogram | number[] | Read-only | A 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}` |
historyStates | HistoryStates | Read-only | History states of the document |
id | number | Read-only | The 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 |
layers | Layers | Read-only | All the layers in the document at the top level |
mode | DocumentMode | Read-only | The color profile. To change it, please use Document.changeMode |
name | string | Read-only | The name of the document |
path | string | Read-only | Full file system path to this document, or the identifier if it is a cloud document |
pathItems | PathItems | Read-only | The collection of paths in this document, currently shown in the Paths panel. Added in 23.3 |
pixelAspectRatio | number | Read-write | The (custom) pixel aspect ratio to use |
quickMaskMode | boolean | Read-write | The state of Quick Mask mode. If true, the app is in Quick Mask mode. |
resolution | number | Read-only | Document's resolution (in pixels per inch) |
saved | boolean | Read-only | True if the document has been saved since the last change. |
title | string | Read-only | Document title |
typename | string | Read-only | The class name of the referenced Document object |
width | number | Read-only | Document's width in pixels |
Methods#
changeMode#
async : Promise<void>
Changes the color profile of the document
Parameters#
Name | Type |
---|---|
mode | ChangeMode |
options? | BitmapConversionOptions | IndexedConversionOptions |
close#
async : Promise<void>
Closes the document, showing a prompt to save unsaved changes if specified
Parameters#
Name | Type |
---|---|
saveDialogOptions | SaveOptions |
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#
Name | Type |
---|---|
destinationProfile | string |
intent | Intent |
blackPointCompensation? | boolean |
dither? | boolean |
createLayer#
async : Promise<Layer>
Create a layer. See @CreateOptions
Copied to your clipboard1const myEmptyLayer = await doc.createLayer()2const myLayer = await doc.createLayer({ name: "myLayer", opacity: 80, mode: "colorDodge" })
Parameters#
Name | Type |
---|---|
options? | LayerCreateOptions |
createLayerGroup#
async : Promise<Layer>
Create a layer group. See GroupLayerCreateOptions
Copied to your clipboard1const 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#
Name | Type |
---|---|
options? | GroupLayerCreateOptions |
crop#
async : Promise<void>
Crops the document to given bounds
Parameters#
Name | Type | Default value |
---|---|---|
bounds | Bounds | - |
angle | number | 0 |
width | number | 0 |
height | number | 0 |
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#
Name | Type |
---|---|
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 clipboard1// duplicate some layers2const layerCopies = await document.duplicateLayers([layer1, layer3])3layerCopies.forEach((layer) => { layer.blendMode = 'multiply' })4// ...to another document5const finalDoc = await photoshop.open('~/path/to/collated/image.psd')6await document.duplicateLayers([logo1, textLayer1], finalDoc)7await finalDoc.close(SaveOptions.SAVECHANGES)
Parameters#
Name | Type | Description |
---|---|---|
layers | Layer[] | |
targetDocument? | Document | if 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 clipboard1const layers = doc.layers2const group = await doc.groupLayers([layers[1], layers[2], layers[4]])
Parameters#
Name | Type |
---|---|
layers | Layer[] |
linkLayers#
Layer[]
Links layers together if possible, and returns a list of linked layers.
Parameters#
Name | Type | Description |
---|---|---|
layers | Layer[] | 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#
Name | Type |
---|---|
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 clipboard1// grow the canvas by 400px2let width = await document.width3let height = await document.height4await document.resizeCanvas(width + 400, height + 400)
Parameters#
Name | Type | Description |
---|---|---|
width | number | Numeric value of new width in pixels |
height | number | Numeric value of new height in pixels |
anchor? | AnchorPosition | Anchor 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 clipboardawait document.resizeImage(800, 600)
Parameters#
Name | Type | Description |
---|---|---|
width? | number | Numeric value of new width in pixels |
height? | number | Numeric value of new height in pixels |
resolution? | number | Image resolution in pixels per inch (ppi) |
resampleMethod? | ResampleMethod | Method used during image interpolation. |
amount? | number | Numeric 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#
Name | Type |
---|---|
angles | number |
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 clipboard1// To save a document in the current location2document.save()34// Shows the save dialog5unsavedDocument.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 clipboard1 require("photoshop").app.activeDocument.suspendHistory(async (context) => {2 // context.document is the `app.activeDocument`3 context.document.activeLayers[0].name = "Changed name";4 });
Parameters#
Name | Type |
---|---|
callback | (e : SuspendHistoryContext) => void |
historyStateName | string |
trap#
async : Promise<void>
Applies trapping to a CMYK document.
Valid only when Document.mode is Constants.DocumentMode.CMYK
Parameters#
Name | Type |
---|---|
width | number |
trim#
async : Promise<void>
Trims the transparent area around the image on the specified sides of the canvas base on trimType
Parameters#
Name | Type | Default value |
---|---|---|
trimType | TrimType | - |
top | boolean | true |
left | boolean | true |
bottom | boolean | true |
right | boolean | true |