Edit in GitHubLog an issue

Photoshop API Changelog

Photoshop Beta (24.2 February 2023)

Imaging API Beta

We are excited to provide an entirely new capability with the Imaging API. Anyone that has been eagerly awaiting the ability to directly get and set pixels in a document should head to the dedicated page. Note: we are serious about the Beta label. While this is exciting new territory, keep in mind that the API is in an early form. We want your feedback to help guide it toward maturity.

Text support

The UXP DOM features a variety of new text-related APIs, that provide a more robust and consistent experience for developers. Instead of aiming for ExtendScript parity, the UXP DOM has been designed to provide a more modern and intuitive API surface. While still providing the old functionality, it's been extended to cover many features that weren't previously available.

  • A Document.createTextLayer method was added, which allows developers to create a new text layer in a document. It accepts a TextLayerCreateOptions object, which can be used to set the initial text content, style, and other properties.
  • The textItem property of a Text Layer is the entrypoint for everything text-related. It provides direct access to a few properties and methods:
    • contents
    • isParagraphText
    • isPointText
    • orientation
    • textClickPoint
    • convertToParagraphText()
    • convertToPointText()
    • convertToShape()
    • createWorkPath()
  • Properties and methods related to features made available by Photoshop in the Character palette are now grouped in the textItem.characterStyle object:
    • alternateLigatures
    • antiAliasMethod
    • autoKerning
    • baseline
    • baselineShift
    • capitalization
    • characterAlignment
    • color
    • fauxBold
    • fauxItalic
    • font
    • fractionalWidths
    • fractions
    • horizontalScale
    • kashidas
    • horizontalDiacriticPosition
    • verticalDiacriticPosition
    • language
    • leading
    • ligatures
    • middleEasternDigitsType
    • middleEasternTextDirection
    • noBreak
    • ordinals
    • size
    • strikeThrough
    • stylisticAlternates
    • swash
    • titlingAlternates
    • tracking
    • useAutoLeading
    • verticalScale
    • reset()
  • Properties and methods related to features made available by Photoshop in the Paragraph palette are now grouped in the textItem.paragraphStyle object:
    • firstLineIndent
    • hyphenation
    • hyphenationFeatures
    • justification
    • justificationFeatures
    • layoutMode
    • kashidaWidth
    • kinsoku
    • mojikumi
    • leftIndent
    • rightIndent
    • spaceAfter
    • spaceBefore
    • reset()
  • Properties and methods related to features made available by Photoshop in the Warp text dialog are now grouped in the textItem.warpStyle object:
    • style
    • direction
    • bend
    • horizontalDistortion
    • verticalDistortion
    • reset()

UXP

From the UXP team we have integrated the following update.

v6.5 Integration

New
  • Allow unrestricted relative paths in require from scripts
  • getEntryWithUrl in LocalFileProvider

Photoshop 24.1 (December 2022)

app.getColorProfiles

Color profiles are needed for the Imaging API, so a new method on the app is introduced to return profile names. At this time, only profiles for RGB and Gray are available.

CountItems support

The CountItems DOM API is now available in Photoshop.

  • The CountItems collection behaves like other collections at the Document level in the API. CountItems further support the following properties and methods:
    • typename, length, parent.
    • add(), removeAll(), getAll(), createGroup(), renameActiveGroup(), removeGroupByIndex(), toggleActiveGroupVisibility(), activateGroupByIndex(), setActiveMarkerSize(), setActiveLabelSize(), setActiveColor().

Other fixes

We now throw errors in more situations with layer blend modes

  • Passing a value that is not in [[Constants.blendMode]].

  • Passing a blend mode that is not compatible with the document's color mode or bit depth. Previously, this call would fail silently.

  • Attempting to set the blend mode on the Background layer. Previously, doing so would convert Background to a regular layer and generate a new layer ID. Automatic Background promotion is undesirable as a side effect in this case. This action is not available via the UI.

  • The CountItem class implements the following properties and methods:

    • typename, parent, itemIndex, groupIndex, position
    • move(), remove()

UXP

From the UXP team we have integrated the following update.

v6.4 Integration

New
  • Webviews for Panels
  • Support Path Module APIs
  • Script can run fsapi with full access in localFileSystem
Bugs Fixes
  • PluginManifest parsing / Load Plugin errors not logged in UDT
  • Error shown in UDT APP logs on Plugin UnLoad
  • UXP script : file session tokens are not getting created
  • Error message and stack are empty in case of reject("error string") executed in script
  • [Win only]-Volume is being muted automatically for 3rd video in the tutorial while opening the video in Theatre mode
  • After closing the theatre mode, video's are Overlapping while scrolling up and down in DP
  • Provide an API to programmatically close dialog in pop-out/theatre mode.
  • Plugin Data folder shouldn't be created for scripts
  • Crash on exit
  • script.setResult("kSuccess") not working
  • Resource Leaks in Window Dialog on UWP
  • Privilege plugin fail to add in XD in certain cases
  • Fixed mouse/keyboard events within Webview in XD v55 and Win 10.

Photoshop 24.0 (October 2022)

Preferences

Adds API to change some of the Photoshop preferences. Only first set of 38 preferences was added. More will follow.

ColorSamplers support

The ColorSampler DOM API is now available in Photoshop.

  • The ColorSamplers collection behaves like other collections at the Document level in the API. ColorSamplers further supports the following methods:
    • colorSamplers.add()
    • colorSamplers.removeAll()
  • The ColorSamplers class implements the following properties and methods:
    • typename: String
    • parent: Document
    • position: {x: number, y: number}
    • color: SolidColor
    • move({x: number, y: number})
    • remove()
  • The Document class implements a new sampleColor() method that samples an {x, y} position on the fly, returning a SolidColor object without the need to create a ColorSampler object.

Layer Comps support

  • Document.layerComps property is now added, giving access to similar APIs from ExtendScript to work with layer comps.
  • LayerComps collection
    • Adds the following Layer Comp methods: add(), removeAll(), getByName()
    • Create new layer comps in the document using LayerComps.add() method. Constructors for them can be found in app object.
  • LayerComp class
    • Adds the following Layer Comp properties: name, comment, selected, appearance, position, visibility, childComp.
    • Adds the following Layer Comp methods: apply(), recapture(), remove(), resetLayerComp(), duplicate()

Guide fixes

  • Guide.coordinate Fixes coordinate getter when document resolution is not 72 PPI
  • Guide.coordinate Fixes coordinate setter when document resolution is not 72 PPI
  • Guides.add Fixes coordinate when creating a new guide if document resolution is not 72 PPI
  • Guides.add Creating a new guide had returned an invalid, nonexistent instance. It now points to an existing guide.

Known Issues and Workarounds

  • A new page of Known Issues and Workarounds was introduced, and aims to outline some common issues encountered by our developer community. New entries will be summarized in this changelog.
  • A note about increased error throws from batchPlay, specifically with the move command, was added.

Layer Filter Methods

Other

  • Color mode validation for all filters
  • Fixed Lens Flare coordinates
  • Fixed file arguments for filters

Photoshop 23.5 (August 2022)

UXP Scripting

Script files with extension .psjs are executed using UXP.

Layer Filter methods

Photoshop 23.4 (July 2022)

convertUnits method on the Photoshop Application object

  • Application.convertUnits is a method for converting the pixel values found in the UXP API to other units. For example, use this routine for converting a document's width from pixels to inches.

Photoshop 23.3 (April 2022)

Paths support

  • Document.pathItems property is now added, giving access to same APIs from ExtendScript to work with paths.
  • Document.pathItems provides the collection class PathItems, which is a collection of PathItem objects.
  • PathItem.subPathItems provides the collection class SubPathItems, which is a collection of SubPathItem objects.
  • SubPathItem.pathPoints provides the collection class PathPoints, which is a collection of PathPoint objects.
  • Create new paths in the document using PathItems.add method by providing PathPointInfo and SubPathInfo objects. Constructors for them can be found in app object.

Load on Launch support

You can now set your plugin manifest to load your plugin on app launch. See Photoshop Manifest for details.

batchPlay development helper: Copy as Javascript

It is now possible to use the Photoshop Actions panel to help build your plugin. Record valid actions, and let Photoshop generate readable and valid batchPlay to use in your UXP plugin. See the batchPlay documentation under "Accepted action descriptors".

Core event: "userIdle"

This event is generated when Photoshop detects that a user becomes idle, while Photoshop is the foreground application. A plugin must specify a number of idle seconds, and then may choose to batch process-intensive tasks. See photoshopCore.

Interactive Mode for executeAsModal

As an alterative to a UI-blocking progress bar when a plugin is within a Modal Execution scope, interactiveMode can be requested to allow for user interaction in specific circumstances. See Interactive Mode.

Photoshop 23.2 (February 2022)

  • Core Module: setExecutionMode()
  • Core Module: getPluginInfo()

Photoshop 23.1 (December 2022)

  • Core Module: batchPlaySync()
  • Core Module: validateReference()
  • Core Module: isModal()
  • Core Module: getCPUInfo()
  • Core Module: getGPUInfo()

Photoshop 23.0 (October 2021)

Channel support

  • Channels collections behave like other collections in the API. Channels further supports channels.add() and channels.removeAll().
  • Channel class
    • Supports four types of channels, as listed in Constants.ChannelType: COMPONENT, MASKEDAREA, SELECTEDAREA, SPOTCOLOR.
    • Adds the following Channel properties: name, type, visible, histogram, color, opacity.
    • Adds the following Channel methods: remove(), merge() (for ChannelType.SPOTCOLOR).
    • Adds to the Document class: get compositeChannels, get activeChannels, set activeChannels.

Document Transformations

  • Document.crop(bounds: Bounds, angle, width, height): Crops the document. The bounds paramter is an array of four coordinates for the region remaining after cropping, [left, top, right, bottom].
  • Document.resizeCanvas(width, height, Constants.AnchorPosition): Changes the size of the canvas to display more or less of the image but does not change the image size. See resizeImage
  • Document.resizeImage(width, heigh, resolution, Constants.ResampleMethod, amount): Changes the size of the image. The amount of noise value when using preserve details (Range: 0 1 100).
  • Document.rotateCanvas(angle): Rotates the image and resizes the canvas to fit the resized image.
  • Document.trim(Constants.TrimType, top, left, bottom, right): If TrimType.TRANSPARENT, trims the transparent area around the image on the specified sides of the canvas. Trims surround areas that color match the top left corner or bottom right corner pixel if TrimType.TOPLEFT or TrimType.BOTTOMRIGHT is specified, respectively.

Layer cut and copy

  • layer.cut(): Cut the pixels out of the layer.
  • layer.copy(merge: boolean): Copy the layer or if a selection is present the merge option will copy from multiple layers..

Layer Methods

  • layer.duplicate(relativeObject?: Document | Layer, insertionLocation?: Constants.ElementPlacement, name?: string): Duplicates the layer, creating a copy above it in layer stack and returns the newly created layer.
  • layer.delete(): Deletes this layer from the document.
  • layer.link(): Creates a link between this layer and the target layer if not already linked and returns a list of layers linked to this layer.
  • layer.unlink(): Unlinks the layer from any existing links.

Document paste

  • document.paste(intoSelection: boolean): 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.

Document Methods

  • Document.flatten(): Merges all visible layers in the document into a single layer.
  • Document.mergeVisibleLayers(): Flattens all visible layers in the document
  • Document.revealAll(): Expands the document to show clipped sections.
  • Document.rasterizeAllLayers(): Rasterizes all layers.
  • Document.splitChannels(): Splits the document channels into separate, single-channel documents.
  • Document.duplicate(): Creates a copy of the document, switching to the copy.

SolidColor API

  • Add require('photoshop').app.SolidColor constructor, which allows for creation of SolidColor objects.
  • APIs that accept colors now also accept SolidColor objects.
    • app.foregroundColor and app.backgroundColor.
    • app.documents.add fillColor property.
    • Document.saveAs methods that use colors.
  • require('photoshop').core.convertColor low level API added, used internally by SolidColor. It uses app color settings to convert between color spaces.

Adobe Photoshop Beta Build 65: Sep 3, 2021 (23.0)

Layer Transformations

  • layer.rotate(angle: number, anchor?: Constants.AnchorPosition): Rotate by angle about anchor.
  • layer.scale(width: number, height: number, anchor?: Constants.AnchorPosition): Scale layer by width percent and height percent of the image, relative to anchor.
  • layer.translate(horizontal: number, vertical: number): Translate layer by horizontal and vertical offset (by pixel or percent).

app.fonts and TextFont classes

  • app.fonts getter: Returns all installed fonts
  • TextFont class and TextFonts collection class

Document Properties

  • Document.bitsPerChannel (read-write): The bits per color channel (type Constants.BitsPerChannelType)
  • Document.cloudDocument (read only): This document is in the Adobe Creative Cloud (type boolean)
  • Document.cloudWorkAreaDirectory (read only): Local directory for this cloud document (type string)
  • Document.histogram (read only): A histogram containing the number of pixels at each color intensity level for the composite channel. The array contains 256 members.
  • Document.name (read only): The name of the document (type string)
  • Document.path (read only): Full file system path to this document, or the identifier if it is a cloud document (type string)
  • Document.quickMaskMode (read-write): The state of Quick Mask mode. If true, the app is in Quick Mask mode (type boolean)
  • Document.saved (read only): True if the document has been saved since the last change (type boolean)

Document Color Profile APIs

  • Document.mode property (read only)
  • Document.colorProfileType and Document.colorProfileName properties (read-write)
  • Document.changeMode(), Document.convertProfile(), and Document.trap() methods

Adobe Photoshop Beta Build 64: Aug 6, 2021 (23.0)

Document.suspendHistory

This API wraps around core.executeAsModal within a single document to make it easier for you to run your code under a single history state. Unlike it's ExtendScript predecessor, this method takes a Javascript function, rather than a script string.

Layer Move APIs

  • Arrange layers with layer.move(targetLayer, Constants.ElementPlacement). Added Constants.ElementPlacement for moving layers: "placeAfter" (place below a layer, below group if group layer), "placeBefore" (place above a layer, above group if group layer), and "placeInside" (inside group layers only).
  • Send a layer to the back or bring a layer to the front with layer.sendToBack() and layer.bringToFront(). If layer is within a group, the commands will operate within that group.

Adobe Photoshop Prerelease Build 61: Jun 24, 2021 (22.5)

Updated DOM API

  • New Layers collection, the old layerTree object is now called layers but as a collection using the JavaScript Proxy object. See below for introduction of collections. The old layers behavior is no longer part of the DOM. Most scripts can be updated to replace layerTree with layers. A document and a layer, if the layer kind is group, will have a valid layers collection. A pixel layer will have null for the layers property. A collection has the same semantics as an Array. The additional ExtendScript routines of add and getByName are also available. Use LayerKind.GROUP on a layer to see if any layers are available.
  • GroupLayer has been removed. Use activeLayer.kind === LayerKind.GROUP instead.
  • Constants.LayerKind, similar to ExtendScript version, but with "group" layer addition.
  • Layer APIs
    • new locked, read-only way to tell if any of the properties are locked
    • allLocked, pixelsLocked, positionLocked, transparentPixelsLocked properties
    • Some existing properties exposed in documentation

Adobe Photoshop Prerelease Build 60: Jun 10, 2021 (22.5)

This update contains changes that were made since the MAX 2020 (Adobe Photoshop 22.0) release.

Breaking changes

To use the new set of APIs, your project's manifest.json must be updated to include the following under the host object:

Copied to your clipboard
1    "data" : {
2        "apiVersion": 2
3    }

Further, your manifest.json must use version 4:

Copied to your clipboard
  "manifestVersion": 4

To roll back to the MAX 2020 version of the Photoshop DOM API, set the apiVersion to 1.

Updated DOM API

  • Collections
    • We're introducing collection classes built using Proxies, to make it easier to interact with the DOM.
    • Try iterating through all the documents as such: app.documents.forEach(h => console.log(h.title));
  • HistoryStates collections and HistoryState API
    • We've built HistoryStates to mirror ExtendScript functionality. length, parent, and getByName(name) are provided. You can also use indices as such: activeDocument.historyStates[2].
    • HistoryState provides name, parent, snapshot.
  • Documents collections
    • Documents also follows ExtendScript functionality. length, add, getByName(name), parent are provided.
  • Constants module, collecting all enumerations and constants used in DOM API. Accessible via require("photoshop").constants.
  • Updated app.createDocument / app.add
    • Create a document with no params for a default document, with a predefined preset, or by providing a host of DocumentCreateOptions).
  • Updated document.save and document.saveAs
    • save no longer infers the file type from the requested file name. Instead, it invokes a save dialog for unsaved files, and performs a save operation for saved, modified files.
    • saveAs is provided for bmp, gif, jpg, png, psb, psd formats. Use SaveOptions objects to request specific saves (e.g. PhotoshopSaveOptions).
  • layer.id getter
  • Updated document.createLayer and document.createLayerGroup

Photoshop Core updates

  • Execute as Modal allows you to create plugins that can be guaranteed exclusive control over Photoshop during execution. It further allows for clear user feedback when this is occuring, and allows plugins to suspendHistory and resumeHistory.
Was this helpful?

Community

Support

Adobe Developer

  • Privacy
  • Terms of Use
  • Do not sell or share my personal information
  • AdChoices
Copyright © 2023 Adobe. All rights reserved.