1404 lines
50 KiB
Markdown
1404 lines
50 KiB
Markdown
---
|
||
name: photopea-embedded-editor
|
||
description: Embed Photopea in web apps using photopea.js. Covers embedding, file I/O, scripting, exporting, layers, text, filters, and the full Photoshop-compatible API.
|
||
risk: safe
|
||
source: community
|
||
source_repo: yikuansun/PhotopeaAPI
|
||
source_type: community
|
||
license: MIT
|
||
license_source: "https://github.com/yikuansun/PhotopeaAPI/blob/master/LICENSE"
|
||
date_added: 2026-05-20
|
||
---
|
||
|
||
# Photopea Embedded Editor Skill
|
||
## Using photopea.js (yikuansun/PhotopeaAPI) in Websites & Apps
|
||
|
||
---
|
||
|
||
## When to Use This Skill
|
||
|
||
Use this skill for **every task** that involves:
|
||
- Embedding Photopea as an image editor inside a webpage or web app
|
||
- Controlling an embedded Photopea instance from your JavaScript code
|
||
- Automating image editing workflows from a host page (open files, run scripts, export results)
|
||
- Building an image editing feature into your product using Photopea as the engine
|
||
- Writing scripts to manipulate documents, layers, text, selections, filters, colors, and paths
|
||
|
||
**Do NOT** use raw `postMessage` wiring — always use `photopea.js` as the wrapper.
|
||
|
||
---
|
||
|
||
## Library: photopea.js
|
||
|
||
`photopea.js` is a Promises-based JavaScript wrapper around the Photopea Live Messaging API.
|
||
Repository: https://github.com/yikuansun/PhotopeaAPI
|
||
npm package: https://www.npmjs.com/package/photopea
|
||
|
||
### Installation
|
||
|
||
**CDN (no build step)**
|
||
```html
|
||
<script src="https://cdn.jsdelivr.net/npm/photopea@1.1.1/dist/photopea.min.js"></script>
|
||
```
|
||
|
||
**Self-hosted**
|
||
```html
|
||
<script src="./photopea.min.js"></script>
|
||
```
|
||
|
||
**npm (Webpack / Vite / Rollup)**
|
||
```bash
|
||
npm install photopea
|
||
```
|
||
```js
|
||
import Photopea from "photopea";
|
||
```
|
||
|
||
---
|
||
|
||
## Core API: The `Photopea` Class
|
||
|
||
| Method | Description |
|
||
|--------|-------------|
|
||
| `Photopea.createEmbed(container)` | Creates + injects the iframe, resolves when ready |
|
||
| `new Photopea(window.parent)` | Plugin mode: wrap the parent window |
|
||
| `pea.runScript(script)` | Run JS string inside Photopea; returns output array |
|
||
| `pea.loadAsset(arrayBuffer)` | Load binary file (image, font, brush, etc.) |
|
||
| `pea.openFromURL(url, asSmart)` | Open remote URL as new doc or smart object layer |
|
||
| `pea.exportImage(type)` | Export current doc; returns `Blob` (`"png"` or `"jpg"`) |
|
||
|
||
All methods return Promises — always `await` or `.then()`.
|
||
|
||
---
|
||
|
||
## Step 1 — Embed
|
||
|
||
The container `<div>` **must** have a fixed width and height before calling `createEmbed`.
|
||
|
||
```html
|
||
<div id="editor" style="width:1000px; height:650px;"></div>
|
||
<script src="https://cdn.jsdelivr.net/npm/photopea@1.1.1/dist/photopea.min.js"></script>
|
||
<script>
|
||
Photopea.createEmbed(document.getElementById("editor")).then(async (pea) => {
|
||
// pea is ready
|
||
});
|
||
</script>
|
||
```
|
||
|
||
**React:**
|
||
```jsx
|
||
import { useEffect, useRef } from "react";
|
||
import Photopea from "photopea";
|
||
|
||
export default function Editor() {
|
||
const containerRef = useRef(null);
|
||
const peaRef = useRef(null);
|
||
|
||
useEffect(() => {
|
||
if (!containerRef.current || peaRef.current) return;
|
||
Photopea.createEmbed(containerRef.current).then((pea) => {
|
||
peaRef.current = pea;
|
||
});
|
||
}, []);
|
||
|
||
return <div ref={containerRef} style={{ width: "100%", height: "650px" }} />;
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## Step 2 — Opening Files
|
||
|
||
```js
|
||
// Remote URL → new document
|
||
await pea.openFromURL("https://example.com/design.psd", false);
|
||
|
||
// Remote URL → smart object layer inside current document
|
||
await pea.openFromURL("https://example.com/overlay.png", true);
|
||
|
||
// Local file (user input → ArrayBuffer → loadAsset)
|
||
document.getElementById("fileInput").addEventListener("change", async (e) => {
|
||
const buf = await e.target.files[0].arrayBuffer();
|
||
await pea.loadAsset(buf);
|
||
});
|
||
|
||
// Base64 data URI via runScript
|
||
await pea.runScript(`app.open("data:image/png;base64,iVBORw0...");`);
|
||
```
|
||
|
||
---
|
||
|
||
## Step 3 — Running Scripts
|
||
|
||
`runScript` sends a JS string, returns an array of `app.echoToOE(...)` values + `"done"` last.
|
||
|
||
```js
|
||
const result = await pea.runScript(`app.echoToOE("hello");`);
|
||
// result → ["hello", "done"]
|
||
|
||
// Return structured data
|
||
const out = await pea.runScript(`
|
||
app.echoToOE(JSON.stringify({
|
||
width: app.activeDocument.width,
|
||
height: app.activeDocument.height,
|
||
layers: app.activeDocument.layers.length
|
||
}));
|
||
`);
|
||
const info = JSON.parse(out[0]);
|
||
```
|
||
|
||
---
|
||
|
||
## Step 4 — Exporting
|
||
|
||
```js
|
||
// PNG Blob (via exportImage)
|
||
const blob = await pea.exportImage("png");
|
||
document.getElementById("preview").src = URL.createObjectURL(blob);
|
||
|
||
// JPEG Blob
|
||
const blob = await pea.exportImage("jpg");
|
||
|
||
// WebP / PSD / quality-controlled JPEG via saveToOE
|
||
const result = await pea.runScript(`app.activeDocument.saveToOE("webp:0.85");`);
|
||
const webpBlob = new Blob([result[0]], { type: "image/webp" });
|
||
|
||
const result = await pea.runScript(`app.activeDocument.saveToOE("psd:true");`);
|
||
const psdBlob = new Blob([result[0]], { type: "application/octet-stream" });
|
||
|
||
// Trigger download
|
||
async function download(pea, filename = "export.png") {
|
||
const blob = await pea.exportImage("png");
|
||
const a = Object.assign(document.createElement("a"), {
|
||
href: URL.createObjectURL(blob),
|
||
download: filename
|
||
});
|
||
a.click();
|
||
}
|
||
```
|
||
|
||
**Export format strings for `saveToOE`:**
|
||
|
||
| String | Format |
|
||
|--------|--------|
|
||
| `"png"` | PNG lossless |
|
||
| `"jpg"` | JPEG default |
|
||
| `"jpg:0.8"` | JPEG quality 0.0–1.0 |
|
||
| `"webp:0.7"` | WebP quality 0.0–1.0 |
|
||
| `"psd"` | Full PSD |
|
||
| `"psd:true"` | Minified PSD |
|
||
| `"svg:true"` | SVG |
|
||
|
||
---
|
||
|
||
## Step 5 — Loading Assets
|
||
|
||
```js
|
||
// Font
|
||
const buf = await (await fetch("https://example.com/MyFont.otf")).arrayBuffer();
|
||
await pea.loadAsset(buf);
|
||
// Now usable in textItem.font
|
||
|
||
// Brush
|
||
await pea.loadAsset(await (await fetch("Nature.ABR")).arrayBuffer());
|
||
|
||
// Gradient
|
||
await pea.loadAsset(await (await fetch("Gradients.GRD")).arrayBuffer());
|
||
```
|
||
|
||
---
|
||
|
||
## Step 6 — Plugin Mode
|
||
|
||
```js
|
||
// Your page is inside Photopea's sidebar iframe
|
||
const pea = new Photopea(window.parent);
|
||
|
||
const out = await pea.runScript(`app.echoToOE(app.activeDocument.width);`);
|
||
console.log("Width:", out[0]);
|
||
|
||
// Load an asset from your plugin
|
||
const buf = await (await fetch("https://my-assets.com/sticker.png")).arrayBuffer();
|
||
await pea.loadAsset(buf);
|
||
```
|
||
|
||
Plugin config:
|
||
```json
|
||
{
|
||
"environment": {
|
||
"plugins": [{
|
||
"name": "My Plugin",
|
||
"url": "https://my-plugin.example.com",
|
||
"icon": "===https://my-plugin.example.com/icon.png"
|
||
}]
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## Utility Patterns
|
||
|
||
### addImageAndWait — robust async layer insertion
|
||
```js
|
||
async function addImageAndWait(pea, imgURI) {
|
||
let count = "done";
|
||
while (count === "done")
|
||
count = (await pea.runScript(`app.echoToOE(app.activeDocument.layers.length)`))[0];
|
||
count = parseInt(count);
|
||
|
||
const imageUrlLiteral = JSON.stringify(imgURI);
|
||
await pea.runScript(`app.open(${imageUrlLiteral}, null, true);`);
|
||
|
||
return new Promise((resolve) => {
|
||
const check = async () => {
|
||
const n = parseInt((await pea.runScript(
|
||
`app.echoToOE(app.activeDocument.layers.length)`
|
||
))[0]);
|
||
n === count + 1 ? resolve() : setTimeout(check, 50);
|
||
};
|
||
check();
|
||
});
|
||
}
|
||
```
|
||
|
||
### getDocumentAsImage — returns `<img>` element
|
||
```js
|
||
async function getDocumentAsImage(pea) {
|
||
const result = await pea.runScript(`app.activeDocument.saveToOE('png')`);
|
||
return new Promise((resolve) => {
|
||
const fr = new FileReader();
|
||
fr.addEventListener("load", (e) => {
|
||
const img = new Image(); img.src = e.target.result; resolve(img);
|
||
});
|
||
fr.readAsDataURL(new Blob([result[0]], { type: "image/png" }));
|
||
});
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## Real-World Patterns
|
||
|
||
### Pattern A — Open + Export UI
|
||
```html
|
||
<input type="file" id="fileInput" accept="image/*,.psd">
|
||
<button id="exportBtn">Export PNG</button>
|
||
<div id="editor" style="width:100%;height:600px;"></div>
|
||
<script src="https://cdn.jsdelivr.net/npm/photopea@1.1.1/dist/photopea.min.js"></script>
|
||
<script>
|
||
let pea;
|
||
Photopea.createEmbed(document.getElementById("editor")).then(p => pea = p);
|
||
|
||
document.getElementById("fileInput").addEventListener("change", async e => {
|
||
await pea.loadAsset(await e.target.files[0].arrayBuffer());
|
||
});
|
||
document.getElementById("exportBtn").addEventListener("click", async () => {
|
||
const blob = await pea.exportImage("png");
|
||
const a = Object.assign(document.createElement("a"), {
|
||
href: URL.createObjectURL(blob), download: "export.png"
|
||
});
|
||
a.click();
|
||
});
|
||
</script>
|
||
```
|
||
|
||
### Pattern B — Template + Text Edit + Export
|
||
```js
|
||
async function generateCard(pea, name, tagline) {
|
||
await pea.openFromURL("https://example.com/card.psd", false);
|
||
const nameLiteral = JSON.stringify(name);
|
||
const taglineLiteral = JSON.stringify(tagline);
|
||
await pea.runScript(`
|
||
app.activeDocument.layers.getByName("Name").textItem.contents = ${nameLiteral};
|
||
app.activeDocument.layers.getByName("Tagline").textItem.contents = ${taglineLiteral};
|
||
`);
|
||
return await pea.exportImage("png");
|
||
}
|
||
```
|
||
|
||
### Pattern C — Batch Watermark
|
||
```js
|
||
async function batchWatermark(pea, imageURLs, watermarkURL) {
|
||
const results = [];
|
||
for (const url of imageURLs) {
|
||
await pea.openFromURL(url, false);
|
||
await pea.openFromURL(watermarkURL, true);
|
||
await pea.runScript(`
|
||
var doc = app.activeDocument, wm = doc.activeLayer;
|
||
wm.translate(doc.width - wm.bounds[2] - 20, doc.height - wm.bounds[3] - 20);
|
||
wm.opacity = 70;
|
||
`);
|
||
results.push(await pea.exportImage("png"));
|
||
await pea.runScript(`app.activeDocument.close(SaveOptions.DONOTSAVECHANGES);`);
|
||
}
|
||
return results;
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
# FULL SCRIPTING API REFERENCE
|
||
|
||
> All code in this section runs **inside `pea.runScript("...")`** strings.
|
||
> Photopea implements the Adobe Photoshop CC 2015 JavaScript scripting interface.
|
||
> Any Photoshop script targeting that version should work in Photopea.
|
||
|
||
---
|
||
|
||
## `app` — Application Object
|
||
|
||
### Properties
|
||
|
||
| Property | Type | R/W | Description |
|
||
|----------|------|-----|-------------|
|
||
| `app.activeDocument` | Document | R/W | The currently active document |
|
||
| `app.documents` | Documents | R | Collection of all open documents |
|
||
| `app.documents.length` | number | R | Count of open documents |
|
||
| `app.documents[i]` | Document | R | Access by zero-based index |
|
||
| `app.foregroundColor` | SolidColor | R/W | Current foreground color |
|
||
| `app.backgroundColor` | SolidColor | R/W | Current background color |
|
||
| `app.preferences.rulerUnits` | Units | R/W | `Units.PIXELS`, `Units.CM`, `Units.INCHES`, `Units.MM`, `Units.PICAS`, `Units.POINTS`, `Units.PERCENT` |
|
||
| `app.preferences.typeUnits` | TypeUnits | R/W | `TypeUnits.PIXELS`, `TypeUnits.MM`, `TypeUnits.POINTS` |
|
||
| `app.displayDialogs` | DialogModes | R/W | `DialogModes.NO`, `DialogModes.ALL`, `DialogModes.ERROR` |
|
||
|
||
### Methods
|
||
|
||
| Method | Description |
|
||
|--------|-------------|
|
||
| `app.open(url)` | Open URL as new document |
|
||
| `app.open(url, null, true)` | Open URL as smart object layer in active document |
|
||
| `app.echoToOE(string)` | **Photopea extension** — send string to host page (captured by `runScript`) |
|
||
| `app.showWindow("magiccut")` | **Photopea extension** — open Magic Cut panel |
|
||
| `app.showWindow("vbitmap")` | **Photopea extension** — open Vectorize Bitmap panel |
|
||
| `app.UI.zoomIn()` | Zoom in |
|
||
| `app.UI.zoomOut()` | Zoom out |
|
||
| `app.UI.fitTheArea()` | Fit canvas to viewport |
|
||
| `app.UI.pixelToPixel()` | 100% zoom |
|
||
| `app.UI.switchFullscreen()` | Toggle fullscreen |
|
||
| `app.UI.scroll(dx, dy)` | Scroll by delta |
|
||
| `app.UI.scrollTo(x, y)` | Scroll to absolute position |
|
||
|
||
**Important:** Always set ruler units to pixels at the start of any script that uses pixel measurements:
|
||
```js
|
||
var savedUnits = app.preferences.rulerUnits;
|
||
app.preferences.rulerUnits = Units.PIXELS;
|
||
// ... your code ...
|
||
app.preferences.rulerUnits = savedUnits;
|
||
```
|
||
|
||
---
|
||
|
||
## `Document` — Document Object
|
||
|
||
Access via `app.activeDocument` or `app.documents[i]`.
|
||
|
||
### Properties
|
||
|
||
| Property | Type | R/W | Description |
|
||
|----------|------|-----|-------------|
|
||
| `width` | number | R | Document width in current ruler units |
|
||
| `height` | number | R | Document height in current ruler units |
|
||
| `resolution` | number | R | DPI (pixels per inch) |
|
||
| `name` | string | **R/W** | **Photopea extension** — display label (no history step) |
|
||
| `source` | string | **R/W** | **Photopea extension** — file origin URL or `"local,X,NAME"` |
|
||
| `mode` | DocumentMode | R | `DocumentMode.RGB`, `GRAYSCALE`, `CMYK`, `LAB`, `BITMAP`, `INDEXEDCOLOR`, `MULTICHANNEL` |
|
||
| `bitsPerChannel` | BitsPerChannelType | R | `BitsPerChannelType.EIGHT`, `SIXTEEN`, `THIRTYTWO` |
|
||
| `colorProfileName` | string | R | Name of embedded color profile |
|
||
| `activeLayer` | Layer/ArtLayer/LayerSet | R/W | Set to activate a layer |
|
||
| `currentLayer` | ArtLayer | R/W | Alias for `activeLayer` |
|
||
| `layers` | Layers | R | All top-level layers (both art + group) |
|
||
| `artLayers` | ArtLayers | R | All top-level art layers only |
|
||
| `layerSets` | LayerSets | R | All top-level group layers only |
|
||
| `selection` | Selection | R | The current selection |
|
||
| `channels` | Channels | R | All channels |
|
||
| `historyStates` | HistoryStates | R | Undo history |
|
||
| `activeHistoryState` | HistoryState | R/W | Current history position |
|
||
| `layerComps` | LayerComps | R | Layer comps collection |
|
||
| `guides` | Guides | R | Guides collection |
|
||
| `pathItems` | PathItems | R | Vector paths |
|
||
| `id` | number | R | Unique document ID |
|
||
| `saved` | boolean | R | Whether document has unsaved changes |
|
||
| `quickMaskMode` | boolean | R | Whether in Quick Mask mode |
|
||
| `backgroundLayer` | ArtLayer | R | The background layer |
|
||
| `pixelAspectRatio` | number | R | Custom pixel aspect ratio (0.1–10.0) |
|
||
| `histogram` | array | R | 256-element histogram array |
|
||
|
||
### Methods
|
||
|
||
| Method | Signature | Description |
|
||
|--------|-----------|-------------|
|
||
| `resizeImage` | `(w, h, res, resampleMethod)` | Resize image pixels. ResampleMethod: `BICUBIC`, `BILINEAR`, `NEARESTNEIGHBOR`, `NONE`, `BICUBICSHARPER`, `BICUBICSMOOTHER` |
|
||
| `resizeCanvas` | `(w, h, anchor)` | Resize canvas without scaling. AnchorPosition: `TOPLEFT`, `TOPCENTER`, `TOPRIGHT`, `MIDDLELEFT`, `MIDDLECENTER`, `MIDDLERIGHT`, `BOTTOMLEFT`, `BOTTOMCENTER`, `BOTTOMRIGHT` |
|
||
| `rotateCanvas` | `(degrees)` | Rotate entire canvas. Positive = clockwise |
|
||
| `flipCanvas` | `(direction)` | `Direction.HORIZONTAL` or `Direction.VERTICAL` |
|
||
| `crop` | `([x1,y1,x2,y2], angle, w, h)` | Crop canvas. Angle and dimensions are optional |
|
||
| `trim` | `(trimType, top, left, bottom, right)` | Trim transparent/background-color borders. TrimType: `TRANSPARENT`, `TOPLEFT`, `BOTTOMRIGHT` |
|
||
| `revealAll` | `()` | Expand canvas to show clipped content |
|
||
| `flatten` | `()` | Merge all layers into one |
|
||
| `mergeVisibleLayers` | `()` | Merge all visible layers |
|
||
| `rasterizeAllLayers` | `()` | Rasterize all vector/text layers |
|
||
| `changeMode` | `(mode, options)` | Convert color mode (e.g., `ChangeMode.GRAYSCALE`) |
|
||
| `convertProfile` | `(profileName, renderingIntent, blackPointCompensation, dither)` | Convert color profile |
|
||
| `duplicate` | `(name, mergedLayers)` | Duplicate the document |
|
||
| `close` | `(saveOptions)` | Close document. SaveOptions: `DONOTSAVECHANGES`, `SAVECHANGES`, `PROMPTTOSAVECHANGES` |
|
||
| `save` | `()` | Save (requires server config in embed) |
|
||
| `saveToOE` | `(format)` | **Photopea extension** — send binary to host. Formats: `"png"`, `"jpg:0.8"`, `"webp:0.7"`, `"psd:true"`, `"svg:true"` |
|
||
| `clearHistory` | `()` | **Photopea extension** — clear undo history to free RAM |
|
||
| `exportDocument` | `(file, exportType, options)` | Export to filesystem (triggers ZIP). ExportType: `SAVEFORWEB` |
|
||
| `paste` | `(intoSelection)` | Paste clipboard into document |
|
||
| `suspendHistory` | `(historyName, callback)` | Wrap multiple ops in one history state |
|
||
|
||
**Practical examples:**
|
||
```js
|
||
var doc = app.activeDocument;
|
||
|
||
// Resize image to 1920×1080 at 72dpi bicubic
|
||
doc.resizeImage(1920, 1080, 72, ResampleMethod.BICUBIC);
|
||
|
||
// Expand canvas to 2000px wide, keeping content centered
|
||
doc.resizeCanvas(2000, doc.height, AnchorPosition.MIDDLECENTER);
|
||
|
||
// Crop to a region
|
||
doc.crop([100, 100, 900, 600]);
|
||
|
||
// Trim transparent edges
|
||
doc.trim(TrimType.TRANSPARENT, true, true, true, true);
|
||
|
||
// Flip horizontal
|
||
doc.flipCanvas(Direction.HORIZONTAL);
|
||
|
||
// Change to grayscale
|
||
doc.changeMode(ChangeMode.GRAYSCALE);
|
||
|
||
// One undo step for many operations
|
||
doc.suspendHistory("Batch Edit", "action");
|
||
// (Inside Photopea, all ops become one history state)
|
||
|
||
// Export PNG to filesystem (triggers ZIP download)
|
||
var opts = new ExportOptionsSaveForWeb();
|
||
opts.format = SaveDocumentType.PNG;
|
||
opts.PNG8 = false;
|
||
opts.quality = 100;
|
||
doc.exportDocument(new File("/output.png"), ExportType.SAVEFORWEB, opts);
|
||
|
||
// Close without saving
|
||
doc.close(SaveOptions.DONOTSAVECHANGES);
|
||
```
|
||
|
||
---
|
||
|
||
## `Layers` / `ArtLayers` / `LayerSets` Collections
|
||
|
||
These collections exist on `Document`, `LayerSet` (groups within groups), and can be iterated.
|
||
|
||
```js
|
||
var doc = app.activeDocument;
|
||
|
||
// Access
|
||
doc.layers // all top-level (art + groups)
|
||
doc.artLayers // top-level art layers only
|
||
doc.layerSets // top-level group layers only
|
||
|
||
// By index (0 = topmost)
|
||
doc.layers[0]
|
||
doc.layers[doc.layers.length - 1] // bottommost
|
||
|
||
// By name (throws if not found)
|
||
doc.layers.getByName("Background")
|
||
doc.artLayers.getByName("Logo")
|
||
doc.layerSets.getByName("Header Group")
|
||
|
||
// Add
|
||
var newLayer = doc.artLayers.add(); // new blank art layer
|
||
var newGroup = doc.layerSets.add(); // new group
|
||
var innerLayer = newGroup.artLayers.add(); // layer inside a group
|
||
|
||
// Remove
|
||
doc.artLayers.getByName("Temp").remove();
|
||
|
||
// Iterate all layers recursively
|
||
function walkLayers(parent) {
|
||
for (var i = 0; i < parent.layers.length; i++) {
|
||
var l = parent.layers[i];
|
||
if (l.typename === "LayerSet") walkLayers(l);
|
||
else /* ArtLayer */ processLayer(l);
|
||
}
|
||
}
|
||
walkLayers(doc);
|
||
```
|
||
|
||
---
|
||
|
||
## `ArtLayer` — Individual Layer
|
||
|
||
### Properties
|
||
|
||
| Property | Type | R/W | Description |
|
||
|----------|------|-----|-------------|
|
||
| `name` | string | R/W | Layer name |
|
||
| `visible` | boolean | R/W | Layer visibility |
|
||
| `opacity` | number | R/W | Layer opacity 0–100 |
|
||
| `fillOpacity` | number | R | Fill opacity 0–100 |
|
||
| `blendMode` | BlendMode | R/W | Blend mode (see enum below) |
|
||
| `kind` | LayerKind | R/W | Layer type (can set to `LayerKind.TEXT` on empty layer) |
|
||
| `textItem` | TextItem | R | Text object (only when `kind === LayerKind.TEXT`) |
|
||
| `bounds` | array | R | `[left, top, right, bottom]` in current ruler units |
|
||
| `parent` | Document/LayerSet | R | Containing object |
|
||
| `typename` | string | R | Always `"ArtLayer"` |
|
||
| `selected` | boolean | R | **Photopea extension** — is layer highlighted in panel |
|
||
| `isBackgroundLayer` | boolean | R | Is this the locked background layer |
|
||
| `grouped` | boolean | R | Is clipping mask applied |
|
||
| `pixelsLocked` | boolean | R | Pixels locked |
|
||
| `positionLocked` | boolean | R | Position locked |
|
||
| `transparentPixelsLocked` | boolean | R | Transparent pixels locked |
|
||
| `layerMaskDensity` | number | R | Layer mask density 0–100 |
|
||
| `layerMaskFeather` | number | R | Layer mask feather 0–250 |
|
||
| `vectorMaskDensity` | number | R | Vector mask density 0–100 |
|
||
| `vectorMaskFeather` | number | R | Vector mask feather 0–250 |
|
||
|
||
### Transform Methods
|
||
|
||
| Method | Signature | Description |
|
||
|--------|-----------|-------------|
|
||
| `translate` | `(deltaX, deltaY)` | Move layer by offset |
|
||
| `rotate` | `(angle, anchor)` | Rotate by degrees. AnchorPosition optional (default center) |
|
||
| `resize` | `(widthPct, heightPct, anchor)` | Scale as percentage of current size |
|
||
| `rasterize` | `(target)` | Rasterize. RasterizeType: `ENTIRE`, `FILLCONTENT`, `LAYERCLIPPINGMASK`, `LINKEDLAYERS`, `SHAPE`, `TEXTCONTENTS`, `VECTORMASK` |
|
||
|
||
### Layer Management Methods
|
||
|
||
| Method | Signature | Description |
|
||
|--------|-----------|-------------|
|
||
| `duplicate` | `()` | Duplicate to same document, returns new layer |
|
||
| `duplicate` | `(doc, placement)` | Duplicate to another document |
|
||
| `remove` | `()` | Delete the layer |
|
||
| `merge` | `()` | Merge down; returns the merged ArtLayer |
|
||
| `move` | `(relativeLayer, placement)` | Reorder. ElementPlacement: `PLACEBEFORE`, `PLACEAFTER`, `PLACEATBEGINNING`, `PLACEATEND`, `INSIDE` |
|
||
| `copy` | `(merged)` | Copy to clipboard |
|
||
| `cut` | `()` | Cut to clipboard |
|
||
| `clear` | `()` | Cut without clipboard |
|
||
|
||
### Adjustment Methods on ArtLayer
|
||
|
||
| Method | Signature | Description |
|
||
|--------|-----------|-------------|
|
||
| `adjustBrightnessContrast` | `(brightness, contrast)` | Brightness -100–100, Contrast -100–100 |
|
||
| `adjustColorBalance` | `(shadows, midtones, highlights, preserveLuminosity)` | Each is `[cyan-red, magenta-green, yellow-blue]` array |
|
||
| `adjustCurves` | `(curveShape)` | Array of `[input,output]` pairs per channel |
|
||
| `adjustLevels` | `(inputRangeStart, inputRangeEnd, gamma, outputRangeStart, outputRangeEnd)` | Levels adjustment |
|
||
| `autoLevels` | `()` | Auto levels |
|
||
| `autoContrast` | `()` | Auto contrast |
|
||
| `desaturate` | `()` | Convert to grayscale values in current mode |
|
||
| `equalize` | `()` | Equalize brightness distribution |
|
||
| `invert` | `()` | Invert pixel colors |
|
||
| `posterize` | `(levels)` | Posterize (2–255 levels) |
|
||
| `threshold` | `(level)` | B&W threshold (1–255) |
|
||
| `shadowHighlight` | `(shadowAmount, shadowWidth, shadowRadius, highlightAmount, highlightWidth, highlightRadius, colorCorrection, midtoneContrast, blackClip, whiteClip)` | Shadows/Highlights |
|
||
| `photoFilter` | `(fillColor, density, luminosity)` | Photo filter |
|
||
| `mixChannels` | `(outputChannels, monochrome)` | Channel mixer |
|
||
| `selectiveColor` | `(colors, cyan, magenta, yellow, black, method)` | Selective color |
|
||
|
||
### Filter Methods on ArtLayer
|
||
|
||
| Method | Signature | Description |
|
||
|--------|-----------|-------------|
|
||
| `applyGaussianBlur` | `(radius)` | Gaussian blur (0.1–250 px radius) |
|
||
| `applyMotionBlur` | `(angle, distance)` | Motion blur |
|
||
| `applyRadialBlur` | `(amount, blurMethod, blurQuality)` | Radial blur |
|
||
| `applySmartBlur` | `(radius, threshold, blurQuality, blurMode)` | Smart blur |
|
||
| `applyBlur` | `()` | Simple blur |
|
||
| `applyBlurMore` | `()` | Blur more |
|
||
| `applyUnSharpMask` | `(amount, radius, threshold)` | Unsharp mask |
|
||
| `applySharpen` | `()` | Sharpen |
|
||
| `applySharpenEdges` | `()` | Sharpen edges |
|
||
| `applySharpenMore` | `()` | Sharpen more |
|
||
| `applyAddNoise` | `(amount, distribution, monochromatic)` | Add noise. NoiseDistribution: `GAUSSIAN`, `UNIFORM` |
|
||
| `applyDespeckle` | `()` | Despeckle |
|
||
| `applyDustAndScratches` | `(radius, threshold)` | Dust and scratches |
|
||
| `applyMedianNoise` | `(radius)` | Median noise reduction |
|
||
| `applyMaximum` | `(radius)` | Maximum filter (dilate) |
|
||
| `applyMinimum` | `(radius)` | Minimum filter (erode) |
|
||
| `applyHighPass` | `(radius)` | High pass |
|
||
| `applyOffset` | `(horizontal, vertical, undefinedAreas)` | Offset. UndefinedAreas: `SETTOBACKGROUND`, `WRAPAROUND`, `REPEATEDGEPIXELS` |
|
||
| `applyRipple` | `(amount, size)` | Ripple. RippleSize: `SMALL`, `MEDIUM`, `LARGE` |
|
||
| `applyWave` | `(generators, minWavelength, maxWavelength, minAmplitude, maxAmplitude, horizScale, vertScale, waveType, undefinedAreas, randomSeed)` | Wave filter |
|
||
| `applyZigZag` | `(amount, ridges, style)` | Zig-Zag |
|
||
| `applyTwirl` | `(angle)` | Twirl |
|
||
| `applyPolarCoordinates` | `(conversion)` | Polar coordinates |
|
||
| `applySpherize` | `(amount, mode)` | Spherize |
|
||
| `applyPinch` | `(amount)` | Pinch (-100–100) |
|
||
| `applyShear` | `(curve, undefinedAreas)` | Shear |
|
||
| `applyDisplace` | `(horizontalScale, verticalScale, displacementType, undefinedAreas, displacementMapFile)` | Displace |
|
||
| `applyClouds` | `()` | Render Clouds |
|
||
| `applyDifferenceClouds` | `()` | Difference Clouds |
|
||
| `applyLensFlare` | `(brightness, flareCenter, lensType)` | Lens Flare. LensType: `ZOOMWIDE, ZOOMNORMAL, MOVIE` |
|
||
| `applyDiffuseGlow` | `(graininess, glowAmount, clearAmount)` | Diffuse Glow |
|
||
| `applyGlassEffect` | `(distortion, smoothness, scaling, invert, texture, textureFile)` | Glass |
|
||
| `applyOceanRipple` | `(size, magnitude)` | Ocean Ripple |
|
||
| `applyLensBlur` | `(source, focalDistance, invertDepthMap, shape, radius, bladeCurvature, rotation, brightness, threshold, amount, distribution, monochromatic)` | Lens Blur |
|
||
| `applyAverage` | `()` | Average blur |
|
||
| `applyDeInterlace` | `(eliminateFields, createFields)` | De-interlace |
|
||
| `applyNTSC` | `()` | NTSC colors |
|
||
| `applyCustomFilter` | `(characteristics, scale, offset)` | Custom filter (5×5 matrix) |
|
||
| `applyTextureFill` | `(textureFile)` | Texture fill |
|
||
| `applyStyle` | `(styleName)` | Apply a layer style preset by name |
|
||
| `photoFilter` | `(fillColor, density, luminosity)` | Photo Filter |
|
||
|
||
**Practical examples:**
|
||
```js
|
||
var layer = app.activeDocument.activeLayer;
|
||
|
||
// Move to absolute position (layer.bounds[0] = current left edge)
|
||
layer.translate(200 - layer.bounds[0], 100 - layer.bounds[1]);
|
||
|
||
// Rotate 45° around center
|
||
layer.rotate(45);
|
||
|
||
// Scale to 50% keeping center
|
||
layer.resize(50, 50, AnchorPosition.MIDDLECENTER);
|
||
|
||
// Gaussian blur radius 10
|
||
layer.applyGaussianBlur(10);
|
||
|
||
// Unsharp mask
|
||
layer.applyUnSharpMask(50, 2, 0);
|
||
|
||
// Levels: input 0–200, gamma 1.2, output 0–255
|
||
layer.adjustLevels(0, 200, 1.2, 0, 255);
|
||
|
||
// Brightness +20, Contrast +10
|
||
layer.adjustBrightnessContrast(20, 10);
|
||
|
||
// Invert
|
||
layer.invert();
|
||
|
||
// Rasterize text
|
||
layer.rasterize(RasterizeType.TEXTCONTENTS);
|
||
|
||
// Duplicate layer
|
||
var copy = layer.duplicate();
|
||
copy.name = "Layer Copy";
|
||
|
||
// Move layer below another
|
||
var target = doc.layers.getByName("Background");
|
||
layer.move(target, ElementPlacement.PLACEAFTER);
|
||
```
|
||
|
||
---
|
||
|
||
## `LayerSet` — Group Layer
|
||
|
||
A LayerSet is a folder/group in the Layers panel. It has the same layer management methods as `Document`.
|
||
|
||
### Properties
|
||
|
||
| Property | Type | R/W | Description |
|
||
|----------|------|-----|-------------|
|
||
| `name` | string | R/W | Group name |
|
||
| `visible` | boolean | R/W | Group visibility |
|
||
| `opacity` | number | R/W | Group opacity 0–100 |
|
||
| `blendMode` | BlendMode | R/W | Group blend mode |
|
||
| `bounds` | array | R | Bounding box `[left,top,right,bottom]` |
|
||
| `layers` | Layers | R | All layers inside this group |
|
||
| `artLayers` | ArtLayers | R | Art layers inside this group |
|
||
| `layerSets` | LayerSets | R | Sub-groups inside this group |
|
||
| `parent` | Document/LayerSet | R | Parent container |
|
||
| `typename` | string | R | Always `"LayerSet"` |
|
||
|
||
### Methods
|
||
Same as Document for layer management: `layers.add()`, `artLayers.add()`, `layerSets.add()`, `.getByName()`, plus `duplicate()`, `remove()`, `move()`.
|
||
|
||
```js
|
||
// Create group with layers inside
|
||
var group = doc.layerSets.add();
|
||
group.name = "Product Card";
|
||
|
||
var bgLayer = group.artLayers.add(); bgLayer.name = "Background";
|
||
var textLayer = group.artLayers.add(); textLayer.kind = LayerKind.TEXT;
|
||
textLayer.textItem.contents = "Buy Now";
|
||
textLayer.textItem.size = 36;
|
||
|
||
// Collapse/expand group (Photopea specific, not in standard DOM)
|
||
// Use visibility as workaround
|
||
|
||
// Get specific layer inside a group
|
||
var innerLayer = doc.layerSets.getByName("Header Group").artLayers.getByName("Title");
|
||
```
|
||
|
||
---
|
||
|
||
## `TextItem` — Text Layer Content
|
||
|
||
Access via `layer.textItem` on any layer with `layer.kind === LayerKind.TEXT`.
|
||
|
||
### Core Properties (most commonly used)
|
||
|
||
| Property | Type | R/W | Description |
|
||
|----------|------|-----|-------------|
|
||
| `contents` | string | R/W | The actual text content |
|
||
| `font` | string | R/W | Font PostScript name (e.g. `"ArialMT"`, `"Verdana-Bold"`) |
|
||
| `size` | number | R/W | Font size in points |
|
||
| `color` | SolidColor | R/W | Text color |
|
||
| `position` | array | R/W | `[x, y]` origin of text (point text) or bounding box top-left |
|
||
| `justification` | Justification | R/W | `Justification.LEFT`, `CENTER`, `RIGHT`, `FULLJUSTIFY` |
|
||
| `kind` | TextType | R/W | `TextType.POINTTEXT` or `TextType.PARAGRAPHTEXT` |
|
||
| `width` | number | R/W | Width of bounding box (paragraph text only) |
|
||
| `height` | number | R/W | Height of bounding box (paragraph text only) |
|
||
| `direction` | Direction | R/W | `Direction.HORIZONTAL` or `Direction.VERTICAL` |
|
||
|
||
### Typography Properties
|
||
|
||
| Property | Type | R/W | Description |
|
||
|----------|------|-----|-------------|
|
||
| `leading` | number | R/W | Line spacing in points |
|
||
| `tracking` | number | R/W | Letter spacing -1000–10000 (1000 = 1 em) |
|
||
| `horizontalScale` | number | R/W | Horizontal scaling 0–1000% |
|
||
| `verticalScale` | number | R/W | Vertical scaling 0–1000% |
|
||
| `baselineShift` | number | R/W | Baseline offset in points |
|
||
| `capitalization` | Case | R/W | `Case.NORMAL`, `ALLCAPS`, `SMALLCAPS` |
|
||
| `fauxBold` | boolean | R/W | Simulated bold |
|
||
| `fauxItalic` | boolean | R/W | Simulated italic |
|
||
| `underline` | UnderlineType | R/W | `UnderlineType.NONE`, `UNDERLINELEFT`, `UNDERLINERIGHT` |
|
||
| `strikeThru` | StrikeThruType | R/W | `StrikeThruType.NONE`, `STRIKEBOX`, `STRIKEHEIGHT` |
|
||
| `antiAliasMethod` | AntiAlias | R/W | `AntiAlias.NONE`, `SHARP`, `CRISP`, `STRONG`, `SMOOTH` |
|
||
| `autoKerning` | AutoKernType | R/W | `AutoKernType.MANUAL`, `METRICS`, `OPTICAL` |
|
||
| `language` | Language | R/W | `Language.ENGLISH`, etc. |
|
||
| `ligatures` | boolean | R/W | Enable ligatures |
|
||
| `alternateLigatures` | boolean | R/W | Enable alternate ligatures |
|
||
| `oldStyle` | boolean | R/W | Old-style numerals |
|
||
| `noBreak` | boolean | R/W | Prevent line breaks in this text |
|
||
| `useAutoLeading` | boolean | R/W | Use font's built-in leading |
|
||
| `autoLeadingAmount` | number | R/W | Auto leading percentage 0.01–5000 |
|
||
| `hyphenation` | boolean | R/W | Enable hyphenation |
|
||
|
||
### Paragraph Properties
|
||
|
||
| Property | Type | R/W | Description |
|
||
|----------|------|-----|-------------|
|
||
| `leftIndent` | number | R/W | Left indent -1296–1296 |
|
||
| `rightIndent` | number | R/W | Right indent -1296–1296 |
|
||
| `firstLineIndent` | number | R/W | First line indent -1296–1296 |
|
||
| `spaceBefore` | number | R/W | Space before paragraph -1296–1296 |
|
||
| `spaceAfter` | number | R/W | Space after paragraph -1296–1296 |
|
||
| `hangingPuntuation` | boolean | R/W | Roman hanging punctuation |
|
||
| `textComposer` | TextComposer | R/W | `TextComposer.ADOBEEVERYLINE`, `ADOBESINGLELINE` |
|
||
|
||
### Warp Properties
|
||
|
||
| Property | Type | R/W | Description |
|
||
|----------|------|-----|-------------|
|
||
| `warpStyle` | WarpStyle | R/W | `WarpStyle.NONE`, `ARC`, `ARCH`, `BULGE`, `SHELLLOWER`, `SHELLUPPER`, `FLAG`, `WAVE`, `FISH`, `RISE`, `FISHEYE`, `INFLATE`, `SQUEEZE`, `TWIST` |
|
||
| `warpDirection` | Direction | R/W | `Direction.HORIZONTAL` or `Direction.VERTICAL` |
|
||
| `warpBend` | number | R/W | Warp bend -100–100 |
|
||
| `warpHorizontalDistortion` | number | R/W | Horizontal distortion -100–100 |
|
||
| `warpVerticalDistortion` | number | R/W | Vertical distortion -100–100 |
|
||
|
||
### Photopea Extensions
|
||
|
||
| Property | Type | Description |
|
||
|----------|------|-------------|
|
||
| `totalTextStyle` | string | JSON string with ALL style parameters of the text |
|
||
| `transform` | string | JSON array — the affine transform matrix of the text |
|
||
|
||
### Methods
|
||
|
||
| Method | Description |
|
||
|--------|-------------|
|
||
| `convertToShape()` | Convert text to a filled shape layer with text as clipping path |
|
||
| `createPath()` | Create work path from text outlines |
|
||
|
||
**Practical examples:**
|
||
```js
|
||
var layer = doc.layers.getByName("Headline");
|
||
var text = layer.textItem;
|
||
|
||
// Set content
|
||
text.contents = "Hello World";
|
||
|
||
// Style
|
||
text.font = "Verdana-Bold";
|
||
text.size = 72;
|
||
text.color.rgb.hexValue = "FF0000"; // red
|
||
|
||
// Position point text at (50, 100)
|
||
text.position = [50, 100];
|
||
|
||
// Center align
|
||
text.justification = Justification.CENTER;
|
||
|
||
// Paragraph text with bounding box
|
||
text.kind = TextType.PARAGRAPHTEXT;
|
||
text.width = new UnitValue("400 pixels");
|
||
text.height = new UnitValue("200 pixels");
|
||
|
||
// Letter spacing
|
||
text.tracking = 100; // 10% spacing
|
||
|
||
// Scale text horizontally to 80%
|
||
text.horizontalScale = 80;
|
||
|
||
// Warp arc
|
||
text.warpStyle = WarpStyle.ARC;
|
||
text.warpBend = 30;
|
||
|
||
// Read all text styles as JSON (Photopea extension)
|
||
var styles = JSON.parse(text.totalTextStyle);
|
||
app.echoToOE(JSON.stringify(styles));
|
||
```
|
||
|
||
---
|
||
|
||
## Creating a Text Layer from Scratch
|
||
|
||
```js
|
||
app.preferences.rulerUnits = Units.PIXELS;
|
||
|
||
var layer = doc.artLayers.add();
|
||
layer.kind = LayerKind.TEXT; // Convert blank layer to text
|
||
layer.name = "My Title";
|
||
|
||
var text = layer.textItem;
|
||
text.contents = "Welcome";
|
||
text.font = "ArialMT";
|
||
text.size = 48;
|
||
text.justification = Justification.CENTER;
|
||
text.position = [doc.width / 2, 100];
|
||
|
||
var color = new SolidColor();
|
||
color.rgb.red = 255;
|
||
color.rgb.green = 255;
|
||
color.rgb.blue = 255;
|
||
text.color = color;
|
||
```
|
||
|
||
---
|
||
|
||
## `SolidColor` — Color Object
|
||
|
||
```js
|
||
// RGB (most common in Photopea)
|
||
var c = new SolidColor();
|
||
c.rgb.red = 255; // 0–255
|
||
c.rgb.green = 128;
|
||
c.rgb.blue = 0;
|
||
c.rgb.hexValue = "FF8000"; // Set via hex string (no #)
|
||
|
||
// CMYK
|
||
var c2 = new SolidColor();
|
||
c2.cmyk.cyan = 0; // 0–100
|
||
c2.cmyk.magenta = 50;
|
||
c2.cmyk.yellow = 100;
|
||
c2.cmyk.black = 0;
|
||
|
||
// Grayscale
|
||
var c3 = new SolidColor();
|
||
c3.gray.gray = 50; // 0–100
|
||
|
||
// HSB
|
||
var c4 = new SolidColor();
|
||
c4.hsb.hue = 30; // 0–360
|
||
c4.hsb.saturation = 100; // 0–100
|
||
c4.hsb.brightness = 100; // 0–100
|
||
|
||
// Lab
|
||
var c5 = new SolidColor();
|
||
c5.lab.l = 50; // 0–100
|
||
c5.lab.a = 20; // -128–127
|
||
c5.lab.b = 40; // -128–127
|
||
|
||
// Set as foreground color
|
||
app.foregroundColor = c;
|
||
|
||
// Use with selection fill
|
||
doc.selection.selectAll();
|
||
doc.selection.fill(c);
|
||
doc.selection.deselect();
|
||
```
|
||
|
||
---
|
||
|
||
## `Selection` — Selection Object
|
||
|
||
Access via `doc.selection`.
|
||
|
||
### Properties
|
||
|
||
| Property | Type | Description |
|
||
|----------|------|-------------|
|
||
| `bounds` | array | `[left, top, right, bottom]` bounding rectangle |
|
||
| `solid` | boolean | Whether selection is a solid rectangle |
|
||
|
||
### Methods
|
||
|
||
| Method | Signature | Description |
|
||
|--------|-----------|-------------|
|
||
| `selectAll` | `()` | Select entire document |
|
||
| `deselect` | `()` | Remove selection |
|
||
| `invert` | `()` | Invert the selection |
|
||
| `select` | `(region, type, feather, antiAlias)` | Select polygon region. Region is array of `[x,y]` points. SelectionType: `REPLACE`, `ADD`, `SUBTRACT`, `INTERSECT` |
|
||
| `feather` | `(radius)` | Feather the selection edges |
|
||
| `contract` | `(radius)` | Contract (shrink) selection |
|
||
| `expand` | `(radius)` | Expand selection |
|
||
| `grow` | `(tolerance, antiAlias)` | Grow selection to similar adjacent pixels |
|
||
| `similar` | `(tolerance, antiAlias)` | Select similar pixels throughout document |
|
||
| `smooth` | `(radius)` | Smooth selection edges |
|
||
| `selectBorder` | `(width)` | Select only the border of the current selection |
|
||
| `resize` | `(widthPct, heightPct, anchor)` | Resize selection boundary |
|
||
| `rotate` | `(angle, anchor)` | Rotate selection boundary |
|
||
| `translate` | `(deltaX, deltaY)` | Move selection boundary |
|
||
| `fill` | `(fillWith, mode, opacity, preserveTransparency)` | Fill selection with color or content. fillWith is SolidColor or string |
|
||
| `stroke` | `(strokeColor, width, location, mode, opacity, preserveTransparency)` | Stroke selection border. StrokeLocation: `INSIDE`, `OUTSIDE`, `CENTER` |
|
||
| `copy` | `(merged)` | Copy selection to clipboard |
|
||
| `cut` | `()` | Cut selection to clipboard |
|
||
| `clear` | `()` | Delete selection content |
|
||
| `load` | `(from, type, invert)` | Load selection from channel |
|
||
| `store` | `(into, type)` | Save selection as channel |
|
||
| `makeWorkPath` | `(tolerance)` | Convert to work path |
|
||
|
||
**Practical examples:**
|
||
```js
|
||
var sel = doc.selection;
|
||
|
||
// Rectangle select (top-left to bottom-right)
|
||
sel.select([[0,0],[500,0],[500,300],[0,300]]);
|
||
|
||
// Select all
|
||
sel.selectAll();
|
||
|
||
// Add to existing selection
|
||
sel.select([[600,0],[900,0],[900,300],[600,300]], SelectionType.ADD);
|
||
|
||
// Feather 10px
|
||
sel.feather(10);
|
||
|
||
// Contract by 5px
|
||
sel.contract(5);
|
||
|
||
// Fill with red
|
||
var red = new SolidColor();
|
||
red.rgb.red = 255; red.rgb.green = 0; red.rgb.blue = 0;
|
||
sel.fill(red);
|
||
|
||
// Stroke selection with black, 3px, inside
|
||
var black = new SolidColor();
|
||
black.rgb.hexValue = "000000";
|
||
sel.stroke(black, 3, StrokeLocation.INSIDE);
|
||
|
||
// Copy, paste as new layer
|
||
sel.copy();
|
||
doc.paste();
|
||
|
||
// Invert and delete (remove background)
|
||
sel.invert();
|
||
sel.clear();
|
||
sel.deselect();
|
||
```
|
||
|
||
---
|
||
|
||
## `BlendMode` Enum — All Values
|
||
|
||
Used in `layer.blendMode` (string form in Photopea) and `BlendMode` constant (standard):
|
||
|
||
| `BlendMode` Constant | Photopea String | Name |
|
||
|----------------------|-----------------|------|
|
||
| `BlendMode.NORMAL` | `"norm"` | Normal |
|
||
| `BlendMode.DISSOLVE` | `"diss"` | Dissolve |
|
||
| `BlendMode.DARKEN` | `"dark"` | Darken |
|
||
| `BlendMode.MULTIPLY` | `"mul "` | Multiply |
|
||
| `BlendMode.COLORBURN` | `"idiv"` | Color Burn |
|
||
| `BlendMode.LINEARBURN` | `"lbrn"` | Linear Burn |
|
||
| `BlendMode.DARKERCOLOR` | `"dkCl"` | Darker Color |
|
||
| `BlendMode.LIGHTEN` | `"lite"` | Lighten |
|
||
| `BlendMode.SCREEN` | `"scrn"` | Screen |
|
||
| `BlendMode.COLORDODGE` | `"div "` | Color Dodge |
|
||
| `BlendMode.LINEARDODGE` | `"lddg"` | Linear Dodge (Add) |
|
||
| `BlendMode.LIGHTERCOLOR` | `"lgCl"` | Lighter Color |
|
||
| `BlendMode.OVERLAY` | `"over"` | Overlay |
|
||
| `BlendMode.SOFTLIGHT` | `"sLit"` | Soft Light |
|
||
| `BlendMode.HARDLIGHT` | `"hLit"` | Hard Light |
|
||
| `BlendMode.VIVIDLIGHT` | `"vLit"` | Vivid Light |
|
||
| `BlendMode.LINEARLIGHT` | `"lLit"` | Linear Light |
|
||
| `BlendMode.PINLIGHT` | `"pLit"` | Pin Light |
|
||
| `BlendMode.HARDMIX` | `"hMix"` | Hard Mix |
|
||
| `BlendMode.DIFFERENCE` | `"diff"` | Difference |
|
||
| `BlendMode.EXCLUSION` | `"smud"` | Exclusion |
|
||
| `BlendMode.SUBTRACT` | `"fsub"` | Subtract |
|
||
| `BlendMode.DIVIDE` | `"fdiv"` | Divide |
|
||
| `BlendMode.HUE` | `"hue "` | Hue |
|
||
| `BlendMode.SATURATION` | `"sat "` | Saturation |
|
||
| `BlendMode.COLOR` | `"colr"` | Color |
|
||
| `BlendMode.LUMINOSITY` | `"lum "` | Luminosity |
|
||
| `BlendMode.PASSTHROUGH` | `"pass"` | Pass Through (groups only) |
|
||
|
||
```js
|
||
// Use either form:
|
||
layer.blendMode = BlendMode.SCREEN; // constant
|
||
layer.blendMode = "scrn"; // string (Photopea internal form)
|
||
```
|
||
|
||
---
|
||
|
||
## `LayerKind` Enum
|
||
|
||
| Constant | Description |
|
||
|----------|-------------|
|
||
| `LayerKind.NORMAL` | Regular pixel layer |
|
||
| `LayerKind.TEXT` | Text layer |
|
||
| `LayerKind.SMARTOBJECT` | Smart Object / linked layer |
|
||
| `LayerKind.SOLIDFILL` | Solid color fill layer |
|
||
| `LayerKind.GRADIENTFILL` | Gradient fill layer |
|
||
| `LayerKind.PATTERNFILL` | Pattern fill layer |
|
||
| `LayerKind.BRIGHTNESSCONTRAST` | Brightness/Contrast adjustment layer |
|
||
| `LayerKind.CURVES` | Curves adjustment layer |
|
||
| `LayerKind.LEVELS` | Levels adjustment layer |
|
||
| `LayerKind.HUESATURATION` | Hue/Saturation adjustment layer |
|
||
| `LayerKind.COLORBALANCE` | Color Balance adjustment layer |
|
||
| `LayerKind.CHANNELMIXER` | Channel Mixer adjustment layer |
|
||
| `LayerKind.GRADIENTMAP` | Gradient Map adjustment layer |
|
||
| `LayerKind.INVERSION` | Invert adjustment layer |
|
||
| `LayerKind.POSTERIZE` | Posterize adjustment layer |
|
||
| `LayerKind.THRESHOLD` | Threshold adjustment layer |
|
||
| `LayerKind.SELECTIVECOLOR` | Selective Color adjustment layer |
|
||
| `LayerKind.PHOTOFILTER` | Photo Filter adjustment layer |
|
||
| `LayerKind.EXPOSURE` | Exposure adjustment layer |
|
||
| `LayerKind.VIBRANCE` | Vibrance adjustment layer |
|
||
| `LayerKind.COLORLOOKUP` | Color Lookup adjustment layer |
|
||
| `LayerKind.LAYER3D` | 3D layer (not generally useful in Photopea) |
|
||
| `LayerKind.VIDEO` | Video layer |
|
||
|
||
```js
|
||
// Identify layer type
|
||
var layer = doc.activeLayer;
|
||
if (layer.kind === LayerKind.TEXT) /* text layer */;
|
||
if (layer.kind === LayerKind.SMARTOBJECT) /* smart object */;
|
||
if (layer.typename === "LayerSet") /* group */;
|
||
|
||
// Filter: collect all text layers recursively
|
||
var textLayers = [];
|
||
function collectText(parent) {
|
||
for (var i = 0; i < parent.layers.length; i++) {
|
||
var l = parent.layers[i];
|
||
if (l.typename === "LayerSet") collectText(l);
|
||
else if (l.kind === LayerKind.TEXT) textLayers.push(l);
|
||
}
|
||
}
|
||
collectText(doc);
|
||
```
|
||
|
||
---
|
||
|
||
## `AnchorPosition` Enum
|
||
|
||
| Constant | Position |
|
||
|----------|----------|
|
||
| `AnchorPosition.TOPLEFT` | Top left |
|
||
| `AnchorPosition.TOPCENTER` | Top center |
|
||
| `AnchorPosition.TOPRIGHT` | Top right |
|
||
| `AnchorPosition.MIDDLELEFT` | Middle left |
|
||
| `AnchorPosition.MIDDLECENTER` | Center |
|
||
| `AnchorPosition.MIDDLERIGHT` | Middle right |
|
||
| `AnchorPosition.BOTTOMLEFT` | Bottom left |
|
||
| `AnchorPosition.BOTTOMCENTER` | Bottom center |
|
||
| `AnchorPosition.BOTTOMRIGHT` | Bottom right |
|
||
|
||
---
|
||
|
||
## `ElementPlacement` Enum
|
||
|
||
Used with `layer.move(relativeObject, placement)`:
|
||
|
||
| Constant | Effect |
|
||
|----------|--------|
|
||
| `ElementPlacement.PLACEBEFORE` | Above the target layer in the panel |
|
||
| `ElementPlacement.PLACEAFTER` | Below the target layer in the panel |
|
||
| `ElementPlacement.PLACEATBEGINNING` | Top of the layer stack |
|
||
| `ElementPlacement.PLACEATEND` | Bottom of the layer stack |
|
||
| `ElementPlacement.INSIDE` | Into a LayerSet (makes layer a child) |
|
||
|
||
---
|
||
|
||
## `ResampleMethod` Enum
|
||
|
||
Used with `doc.resizeImage()`:
|
||
|
||
| Constant | Description |
|
||
|----------|-------------|
|
||
| `ResampleMethod.BICUBIC` | High quality, good for smooth gradients |
|
||
| `ResampleMethod.BICUBICSHARPER` | Best for reduction |
|
||
| `ResampleMethod.BICUBICSMOOTHER` | Best for enlargement |
|
||
| `ResampleMethod.BILINEAR` | Medium quality |
|
||
| `ResampleMethod.NEARESTNEIGHBOR` | No anti-aliasing, fastest |
|
||
| `ResampleMethod.NONE` | No resampling (change resolution only) |
|
||
|
||
---
|
||
|
||
## `SaveOptions` Enum
|
||
|
||
Used with `doc.close(saveOption)`:
|
||
|
||
| Constant | Meaning |
|
||
|----------|---------|
|
||
| `SaveOptions.DONOTSAVECHANGES` | Discard all changes and close |
|
||
| `SaveOptions.SAVECHANGES` | Save then close |
|
||
| `SaveOptions.PROMPTTOSAVECHANGES` | Show dialog (may block in headless) |
|
||
|
||
---
|
||
|
||
## `ExportOptionsSaveForWeb` — Export to Filesystem
|
||
|
||
Used with `doc.exportDocument()` to write files that Photopea packages into a ZIP.
|
||
|
||
```js
|
||
// Export PNG
|
||
var pngOpts = new ExportOptionsSaveForWeb();
|
||
pngOpts.format = SaveDocumentType.PNG;
|
||
pngOpts.PNG8 = false; // PNG-24
|
||
pngOpts.quality = 100;
|
||
pngOpts.transparency = true;
|
||
doc.exportDocument(new File("/export.png"), ExportType.SAVEFORWEB, pngOpts);
|
||
|
||
// Export JPEG
|
||
var jpgOpts = new ExportOptionsSaveForWeb();
|
||
jpgOpts.format = SaveDocumentType.JPEG;
|
||
jpgOpts.quality = 80; // 0–100
|
||
doc.exportDocument(new File("/export.jpg"), ExportType.SAVEFORWEB, jpgOpts);
|
||
|
||
// Export GIF
|
||
var gifOpts = new ExportOptionsSaveForWeb();
|
||
gifOpts.format = SaveDocumentType.GIF;
|
||
gifOpts.colors = 256;
|
||
gifOpts.dither = 100;
|
||
gifOpts.transparency = true;
|
||
doc.exportDocument(new File("/export.gif"), ExportType.SAVEFORWEB, gifOpts);
|
||
```
|
||
|
||
---
|
||
|
||
## `executeAction` — Advanced Operations
|
||
|
||
Used for operations not exposed in the standard DOM (adjustments applied as adjustment layers,
|
||
Smart Object editing, etc.). Takes the Photoshop Action Manager approach.
|
||
|
||
```js
|
||
// Open Smart Object for editing
|
||
var l = doc.layers.getByName("SmartObj");
|
||
doc.activeLayer = l;
|
||
executeAction(stringIDToTypeID("placedLayerEditContents"));
|
||
// Smart Object is now the active document
|
||
doc.activeLayer.rotate(90);
|
||
doc.save();
|
||
doc.close();
|
||
|
||
// Apply Hue/Saturation as destructive adjustment
|
||
var desc = new ActionDescriptor();
|
||
var list = new ActionList();
|
||
var channel = new ActionDescriptor();
|
||
channel.putEnumerated(stringIDToTypeID("presetKind"), stringIDToTypeID("presetKindType"), stringIDToTypeID("presetKindDefault"));
|
||
channel.putInteger(stringIDToTypeID("hue"), 20); // hue shift
|
||
channel.putInteger(stringIDToTypeID("saturation"), 30); // saturation
|
||
channel.putInteger(stringIDToTypeID("lightness"), 0);
|
||
list.putObject(stringIDToTypeID("hueSaturationAdjustmentV2Layer"), channel);
|
||
desc.putList(stringIDToTypeID("adjustment"), list);
|
||
executeAction(stringIDToTypeID("hueSaturation"), desc, DialogModes.NO);
|
||
|
||
// Select a layer by name using AM
|
||
function selectLayerByName(name) {
|
||
var desc = new ActionDescriptor();
|
||
var ref = new ActionReference();
|
||
ref.putName(charIDToTypeID("Lyr "), name);
|
||
desc.putReference(charIDToTypeID("null"), ref);
|
||
desc.putBoolean(charIDToTypeID("MkVs"), false);
|
||
executeAction(charIDToTypeID("slct"), desc, DialogModes.NO);
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## Complete Practical Script Examples
|
||
|
||
### 1. Rename all text layers based on their contents
|
||
```js
|
||
app.preferences.rulerUnits = Units.PIXELS;
|
||
var doc = app.activeDocument;
|
||
|
||
function processLayers(parent) {
|
||
for (var i = 0; i < parent.layers.length; i++) {
|
||
var l = parent.layers[i];
|
||
if (l.typename === "LayerSet") processLayers(l);
|
||
else if (l.kind === LayerKind.TEXT) {
|
||
l.name = l.textItem.contents.substring(0, 30);
|
||
}
|
||
}
|
||
}
|
||
processLayers(doc);
|
||
app.echoToOE("done");
|
||
```
|
||
|
||
### 2. Export each layer as a separate PNG
|
||
```js
|
||
app.preferences.rulerUnits = Units.PIXELS;
|
||
var doc = app.activeDocument;
|
||
|
||
for (var i = 0; i < doc.layers.length; i++) {
|
||
// Hide all layers
|
||
for (var j = 0; j < doc.layers.length; j++) doc.layers[j].visible = false;
|
||
// Show only this layer
|
||
doc.layers[i].visible = true;
|
||
// Export
|
||
var opts = new ExportOptionsSaveForWeb();
|
||
opts.format = SaveDocumentType.PNG;
|
||
opts.PNG8 = false;
|
||
opts.quality = 100;
|
||
doc.exportDocument(
|
||
new File("/" + doc.layers[i].name + ".png"),
|
||
ExportType.SAVEFORWEB, opts
|
||
);
|
||
}
|
||
|
||
// Restore visibility
|
||
for (var i = 0; i < doc.layers.length; i++) doc.layers[i].visible = true;
|
||
```
|
||
|
||
### 3. Find and replace text across all text layers
|
||
```js
|
||
var searchText = "2024";
|
||
var replaceText = "2025";
|
||
|
||
function findReplaceText(parent) {
|
||
for (var i = 0; i < parent.layers.length; i++) {
|
||
var l = parent.layers[i];
|
||
if (l.typename === "LayerSet") findReplaceText(l);
|
||
else if (l.kind === LayerKind.TEXT) {
|
||
var t = l.textItem;
|
||
if (t.contents.indexOf(searchText) !== -1) {
|
||
t.contents = t.contents.split(searchText).join(replaceText);
|
||
}
|
||
}
|
||
}
|
||
}
|
||
findReplaceText(app.activeDocument);
|
||
app.echoToOE("Find & Replace complete");
|
||
```
|
||
|
||
### 4. Grid of duplicate layers
|
||
```js
|
||
app.preferences.rulerUnits = Units.PIXELS;
|
||
var doc = app.activeDocument;
|
||
var layer = doc.activeLayer;
|
||
var cols = 4, rows = 3;
|
||
var padX = 20, padY = 20;
|
||
var w = layer.bounds[2] - layer.bounds[0];
|
||
var h = layer.bounds[3] - layer.bounds[1];
|
||
|
||
for (var r = 0; r < rows; r++) {
|
||
for (var c = 0; c < cols; c++) {
|
||
if (r === 0 && c === 0) continue; // skip original
|
||
var copy = layer.duplicate();
|
||
var targetX = layer.bounds[0] + c * (w + padX);
|
||
var targetY = layer.bounds[1] + r * (h + padY);
|
||
copy.translate(targetX - copy.bounds[0], targetY - copy.bounds[1]);
|
||
copy.opacity = 100 - (r * cols + c) * 5;
|
||
}
|
||
}
|
||
```
|
||
|
||
### 5. Apply watermark from URL
|
||
```js
|
||
app.preferences.rulerUnits = Units.PIXELS;
|
||
var doc = app.activeDocument;
|
||
|
||
// Open watermark as smart object layer
|
||
app.open("https://example.com/watermark.png", null, true);
|
||
var wm = doc.activeLayer;
|
||
|
||
// Resize to 20% of document width
|
||
var wmW = wm.bounds[2] - wm.bounds[0];
|
||
var targetW = doc.width * 0.2;
|
||
var scalePct = (targetW / wmW) * 100;
|
||
wm.resize(scalePct, scalePct, AnchorPosition.TOPLEFT);
|
||
|
||
// Move to bottom-right with 20px margin
|
||
var wmNewW = wm.bounds[2] - wm.bounds[0];
|
||
var wmNewH = wm.bounds[3] - wm.bounds[1];
|
||
wm.translate(
|
||
doc.width - wmNewW - 20 - wm.bounds[0],
|
||
doc.height - wmNewH - 20 - wm.bounds[1]
|
||
);
|
||
wm.opacity = 60;
|
||
app.echoToOE("watermark applied");
|
||
```
|
||
|
||
### 6. Get all layer info as JSON
|
||
```js
|
||
function getLayerInfo(parent, depth) {
|
||
depth = depth || 0;
|
||
var result = [];
|
||
for (var i = 0; i < parent.layers.length; i++) {
|
||
var l = parent.layers[i];
|
||
var info = {
|
||
name: l.name,
|
||
type: l.typename,
|
||
visible: l.visible,
|
||
opacity: l.opacity,
|
||
depth: depth
|
||
};
|
||
if (l.typename === "ArtLayer") {
|
||
info.kind = l.kind.toString();
|
||
info.bounds = [l.bounds[0], l.bounds[1], l.bounds[2], l.bounds[3]];
|
||
if (l.kind === LayerKind.TEXT) {
|
||
info.text = l.textItem.contents;
|
||
info.font = l.textItem.font;
|
||
info.size = l.textItem.size;
|
||
}
|
||
} else if (l.typename === "LayerSet") {
|
||
info.children = getLayerInfo(l, depth + 1);
|
||
}
|
||
result.push(info);
|
||
}
|
||
return result;
|
||
}
|
||
app.echoToOE(JSON.stringify(getLayerInfo(app.activeDocument)));
|
||
```
|
||
|
||
---
|
||
|
||
## Common Mistakes & Gotchas
|
||
|
||
| Problem | Cause | Fix |
|
||
|---------|-------|-----|
|
||
| `createEmbed` never resolves | Container has no size | Add `width` + `height` CSS to the container `<div>` |
|
||
| `runScript` returns `["done"]` with no data | No `echoToOE` in script | Add `app.echoToOE(value)` for anything you want back |
|
||
| `result[0]` is `"done"`, not the expected value | `echoToOE` not reached | Check script logic for early exit or errors |
|
||
| Images won't load (network error) | CORS | Server must respond with `Access-Control-Allow-Origin: *` |
|
||
| `openFromURL(url, true)` layer not ready | Async loading lag | Use `addImageAndWait` utility |
|
||
| `exportImage` only PNG/JPG | `exportImage` limitation | Use `runScript("saveToOE('webp:0.85')")` for other formats |
|
||
| Pixel coordinates behave unexpectedly | Wrong ruler units | Always set `app.preferences.rulerUnits = Units.PIXELS` first |
|
||
| Text `size` set but looks different | Wrong type units | Set `app.preferences.typeUnits = TypeUnits.PIXELS` |
|
||
| Layer not found by name | Wrong layer level | Layers are scoped; use recursive search for nested layers |
|
||
| `layer.bounds[0]` returns a UnitValue, not number | Ruler units issue | Force `Units.PIXELS` before reading bounds |
|
||
| Smart Object edit hangs | Missing `doc.save(); doc.close()` | Always save + close when done editing SO |
|
||
| React double-mount in dev | Strict Mode | Use `if (peaRef.current) return` guard in `useEffect` |
|
||
|
||
---
|
||
|
||
## Limitations
|
||
|
||
- This skill covers host-page integration patterns; it does not replace Photopea's own terms, API documentation, or licensing guidance.
|
||
- Remote URL loading depends on browser CORS behavior, network availability, and the user's Photopea account/session state.
|
||
- `runScript` executes scripts inside the embedded Photopea document context. Only run scripts you understand and only with user-approved files.
|
||
- Serialize dynamic values with `JSON.stringify` before embedding them in a `runScript` string. Never concatenate user-provided URLs, layer names, or text directly into Photopea script source.
|
||
- Export behavior can vary by document size, browser memory limits, and the formats supported by the active Photopea runtime.
|
||
|
||
---
|
||
|
||
## Sources
|
||
|
||
- photopea.js: https://github.com/yikuansun/PhotopeaAPI
|
||
- npm: https://www.npmjs.com/package/photopea
|
||
- Photopea Live Messaging API: https://www.photopea.com/api/live
|
||
- Photopea Script reference: https://www.photopea.com/learn/scripts
|
||
- Photoshop JS Scripting reference (compatible): https://theiviaxx.github.io/photoshop-docs/Photoshop/index.html
|
||
- Plugin dev gists (addImageAndWait, getDocumentAsImage): https://gist.github.com/yikuansun/c0f1a602b4e9d4e344a41c4f49ded3bf
|