Photopea Embedded Editor Fähigkeit
Verwendung von photopea.js (yikuansun/PhotopeaAPI) in Websites und Apps
Wann diese Fähigkeit verwenden
Verwenden Sie diese Fähigkeit für jede Aufgabe, die Folgendes umfasst:
- Einbetten von Photopea als Bildeditor innerhalb einer Webseite oder Web-App
- Steuern einer eingebetteten Photopea-Instanz aus Ihrem JavaScript-Code
- Automatisieren von Bildbearbeitungs-Workflows von einer Host-Seite aus (Dateien öffnen, Skripte ausführen, Ergebnisse exportieren)
- Entwickeln einer Bildbearbeitungsfunktion in Ihr Produkt mit Photopea als Engine
- Schreiben von Skripten zur Manipulation von Dokumenten, Ebenen, Text, Auswahlen, Filtern, Farben und Pfaden
Nicht rohe postMessage-Verkabelung verwenden – immer photopea.js als Wrapper verwenden.
Bibliothek: photopea.js
photopea.js ist ein Promise-basierter JavaScript-Wrapper um die Photopea Live-Messaging-API.
Repository: https://github.com/yikuansun/PhotopeaAPI
npm-Paket: https://www.npmjs.com/package/photopea
Installation
CDN (ohne Build-Schritt)
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/photopea.min.js"></script>
Selbst gehostet
<script src="./photopea.min.js"></script>
npm (Webpack / Vite / Rollup)
npm install photopea
import Photopea from "photopea";
Kern-API: Die Photopea-Klasse
| Methode | Beschreibung |
|---|---|
Photopea.createEmbed(container) | Erstellt + injiziert den Iframe, wird aufgelöst, wenn bereit |
new Photopea(window.parent) | Plugin-Modus: umschließt das übergeordnete Fenster |
pea.runScript(script) | Führt einen JS-String innerhalb von Photopea aus; gibt ein Ausgabearray zurück |
pea.loadAsset(arrayBuffer) | Lädt eine Binärdatei (Bild, Schriftart, Pinsel usw.) |
pea.openFromURL(url, asSmart) | Öffnet eine entfernte URL als neues Dokument oder als Smart-Objekt-Ebene |
pea.exportImage(type) | Exportiert das aktuelle Dokument; gibt Blob zurück ("png" oder "jpg") |
Alle Methoden geben Promises zurück – immer await oder .then() verwenden.
Schritt 1 — Einbetten
Das Container-<div> muss vor dem Aufruf von createEmbed eine feste Breite und Höhe haben.
<div id="editor" style="width:1000px; height:650px;"></div>
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/photopea.min.js"></script>
<script>
Photopea.createEmbed(document.getElementById("editor")).then(async (pea) => {
// pea ist bereit
});
</script>
React:
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" }} />;
}
Schritt 2 — Dateien öffnen
// Entfernte URL → neues Dokument
await pea.openFromURL("https://example.com/design.psd", false);
// Entfernte URL → Smart-Objekt-Ebene im aktuellen Dokument
await pea.openFromURL("https://example.com/overlay.png", true);
// Lokale Datei (Benutzereingabe → ArrayBuffer → loadAsset)
document.getElementById("fileInput").addEventListener("change", async (e) => {
const buf = await e.target.files[0].arrayBuffer();
await pea.loadAsset(buf);
});
// Base64-Daten-URI über runScript
await pea.runScript(`app.open("data:image/png;base64,iVBORw0...");`);
Schritt 3 — Skripte ausführen
runScript sendet einen JS-String, gibt ein Array von app.echoToOE(...)-Werten + "done" als letztes zurück.
const result = await pea.runScript(`app.echoToOE("hello");`);
// result → ["hello", "done"]
// Strukturierte Daten zurückgeben
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]);
Schritt 4 — Exportieren
// PNG-Blob (über exportImage)
const blob = await pea.exportImage("png");
document.getElementById("preview").src = URL.createObjectURL(blob);
// JPEG-Blob
const blob = await pea.exportImage("jpg");
// WebP / PSD / qualitätsgesteuertes JPEG über 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" });
// Download auslösen
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 für saveToOE:
| String | Format |
|---|---|
"png" | PNG verlustfrei |
"jpg" | JPEG Standard |
"jpg:0.8" | JPEG-Qualität 0.0–1.0 |
"webp:0.7" | WebP-Qualität 0.0–1.0 |
"psd" | Volles PSD |
"psd:true" | Minifiziertes PSD |
"svg:true" | SVG |
Schritt 5 — Assets laden
// Schriftart
const buf = await (await fetch("https://example.com/MyFont.otf")).arrayBuffer();
await pea.loadAsset(buf);
// Jetzt in textItem.font verwendbar
// Pinsel
await pea.loadAsset(await (await fetch("Nature.ABR")).arrayBuffer());
// Verlauf
await pea.loadAsset(await (await fetch("Gradients.GRD")).arrayBuffer());
Schritt 6 — Plugin-Modus
// Ihre Seite befindet sich im Seiten-Iframe von Photopea
const pea = new Photopea(window.parent);
const out = await pea.runScript(`app.echoToOE(app.activeDocument.width);`);
console.log("Breite:", out[0]);
// Ein Asset von Ihrem Plugin laden
const buf = await (await fetch("https://my-assets.com/sticker.png")).arrayBuffer();
await pea.loadAsset(buf);
Plugin-Konfiguration:
{
"environment": {
"plugins": [{
"name": "Mein Plugin",
"url": "https://my-plugin.example.com",
"icon": "===https://my-plugin.example.com/icon.png"
}]
}
}
Hilfsmuster
addImageAndWait — robuste asynchrone Ebeneneinfügung
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 — gibt ein <img>-Element zurück
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" }));
});
}
Praxis-Muster
Muster A — Öffnen + Export-UI
<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/[email protected]/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>
Muster B — Vorlage + Text bearbeiten + Export
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");
}
Muster C — Batch-Wasserzeichen
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;
}
VOLLSTÄNDIGE SCRIPTING-API-REFERENZ
Der gesamte Code in diesem Abschnitt wird innerhalb von
pea.runScript("...")-Strings ausgeführt. Photopea implementiert die Adobe Photoshop CC 2015 JavaScript-Scripting-Schnittstelle. Jedes Photoshop-Skript, das auf diese Version abzielt, sollte in Photopea funktionieren.
app — Anwendungsobjekt
Eigenschaften
| Eigenschaft | Typ | L/S | Beschreibung |
|---|---|---|---|
app.activeDocument | Document | L/S | Das aktuell aktive Dokument |
app.documents | Documents | L | Sammlung aller offenen Dokumente |
app.documents.length | number | L | Anzahl der offenen Dokumente |
app.documents[i] | Document | L | Zugriff über nullbasierten Index |
app.foregroundColor | SolidColor | L/S | Aktuelle Vordergrundfarbe |
app.backgroundColor | SolidColor | L/S | Aktuelle Hintergrundfarbe |
app.preferences.rulerUnits | Units | L/S | Units.PIXELS, Units.CM, Units.INCHES, Units.MM, Units.PICAS, Units.POINTS, Units.PERCENT |
app.preferences.typeUnits | TypeUnits | L/S | TypeUnits.PIXELS, TypeUnits.MM, TypeUnits.POINTS |
app.displayDialogs | DialogModes | L/S | DialogModes.NO, DialogModes.ALL, DialogModes.ERROR |
Methoden
| Methode | Beschreibung |
|---|---|
app.open(url) | URL als neues Dokument öffnen |
app.open(url, null, true) | URL als Smart-Objekt-Ebene im aktiven Dokument öffnen |
app.echoToOE(string) | Photopea-Erweiterung — Sendet einen String an die Host-Seite (von runScript erfasst) |
app.showWindow("magiccut") | Photopea-Erweiterung — Magic Cut-Bedienfeld öffnen |
app.showWindow("vbitmap") | Photopea-Erweiterung — Bitmap vektorisieren-Bedienfeld öffnen |
app.UI.zoomIn() | Vergrößern |
app.UI.zoomOut() | Verkleinern |
app.UI.fitTheArea() | Leinwand an Ansichtsfenster anpassen |
app.UI.pixelToPixel() | 100% Zoom |
app.UI.switchFullscreen() | Vollbild umschalten |
app.UI.scroll(dx, dy) | Um Delta scrollen |
app.UI.scrollTo(x, y) | Zu absoluter Position scrollen |
Wichtig: Setzen Sie die Linealeinheiten immer zu Beginn eines Skripts, das Pixelmaße verwendet, auf Pixel:
var savedUnits = app.preferences.rulerUnits;
app.preferences.rulerUnits = Units.PIXELS;
// ... Ihr Code ...
app.preferences.rulerUnits = savedUnits;
Document — Dokumentobjekt
Zugriff über app.activeDocument oder app.documents[i].
Eigenschaften
| Eigenschaft | Typ | L/S | Beschreibung |
|---|---|---|---|
width | number | L | Dokumentbreite in aktuellen Linealeinheiten |
height | number | L | Dokumenthöhe in aktuellen Linealeinheiten |
resolution | number | L | DPI (Pixel pro Zoll) |
name | string | L/S | Photopea-Erweiterung — Anzeigelabel (kein Historienschritt) |
source | string | L/S | Photopea-Erweiterung — Datei-Ursprungs-URL oder "local,X,NAME" |
mode | DocumentMode | L | DocumentMode.RGB, GRAYSCALE, CMYK, LAB, BITMAP, INDEXEDCOLOR, MULTICHANNEL |
bitsPerChannel | BitsPerChannelType | L | BitsPerChannelType.EIGHT, SIXTEEN, THIRTYTWO |
colorProfileName | string | L | Name des eingebetteten Farbprofils |
activeLayer | Layer/ArtLayer/LayerSet | L/S | Setzen, um eine Ebene zu aktivieren |
currentLayer | ArtLayer | L/S | Alias für activeLayer |
layers | Layers | L | Alle obersten Ebenen (sowohl Art als auch Gruppe) |
artLayers | ArtLayers | L | Nur alle obersten Art-Ebenen |
layerSets | LayerSets | L | Nur alle obersten Gruppenebenen |
selection | Selection | L | Die aktuelle Auswahl |
channels | Channels | L | Alle Kanäle |
historyStates | HistoryStates | L | Rückgängig-Verlauf |
activeHistoryState | HistoryState | L/S | Aktuelle Verlaufsposition |
layerComps | LayerComps | L | Ebenenkompositionen-Sammlung |
guides | Guides | L | Hilfslinien-Sammlung |
pathItems | PathItems | L | Vektorpfade |
id | number | L | Eindeutige Dokument-ID |
saved | boolean | L | Ob das Dokument ungespeicherte Änderungen hat |
quickMaskMode | boolean | L | Ob im Schnellmasken-Modus |
backgroundLayer | ArtLayer | L | Die Hintergrundebene |
pixelAspectRatio | number | L | Benutzerdefiniertes Pixel-Seitenverhältnis (0.1–10.0) |
histogram | array | L | 256-Element-Histogramm-Array |
Methoden
| Methode | Signatur | Beschreibung |
|---|---|---|
resizeImage | (w, h, res, resampleMethod) | Bildpixel in der Größe ändern. ResampleMethod: BICUBIC, BILINEAR, NEARESTNEIGHBOR, NONE, BICUBICSHARPER, BICUBICSMOOTHER |
resizeCanvas | (w, h, anchor) | Leinwand ohne Skalierung in der Größe ändern. AnchorPosition: TOPLEFT, TOPCENTER, TOPRIGHT, MIDDLELEFT, MIDDLECENTER, MIDDLERIGHT, BOTTOMLEFT, BOTTOMCENTER, BOTTOMRIGHT |
rotateCanvas | (degrees) | Gesamte Leinwand drehen. Positiv = im Uhrzeigersinn |
flipCanvas | (direction) | Direction.HORIZONTAL oder Direction.VERTICAL |
crop | ([x1,y1,x2,y2], angle, w, h) | Leinwand zuschneiden. Winkel und Abmessungen sind optional |
trim | (trimType, top, left, bottom, right) | Beschneiden auf Basis von Pixeln. Alle Parameter optional |
flatten | () | Ebenen reduzieren |
mergeVisibleLayers | () | Sichtbare Ebenen zusammenführen |
close | (SaveOptions) | Dokument schließen (SaveOptions.DONOTSAVECHANGES, SAVECHANGES, PROMPTTOSAVECHANGES) |
saveAs | (url) | Als PSD speichern. Dateipfad-URL erforderlich |
saveToOE | (formatStr) | Photopea-Erweiterung — Dokument als Byte-Stream für OE-Export speichern (zurück in Host-Seiten-JS) |
duplicate | (name, mergeLayersOnly) | Dokument duplizieren |
link | (url) | Place Smart-Objekt verknüpft (ersetzt die eingebettete Datei) |
revert | () | Rückgängig machen zuletzt gespeicherter Version |
paste | (pasteIntoSelection) | Zwischenablage einfügen |
autoContrast | () | Automatischen Kontrast anwenden |
autoColor | () | Automatische Farbe anwenden |
autoTone | () | Automatischen Tonwert anwenden |
applyImage | (sourceDoc, sourceChannel, blendMode, opacity) | Bild anwenden |
calculations | (...) | Berechnungen (wie Photoshop) |
selectAll | () | Alle auswählen |
selectSimilar | () | Ähnliches auswählen (alpha-ähnlich) |
expandSelection | (by) | Auswahl erweitern (in Pixeln) |
contractSelection | (by) | Auswahl verkleinern (in Pixeln) |
featherSelection | (by) | Auswahl weichzeichnen (in Pixeln) |
smoothSelection | (by) | Auswahl glätten (in Pixeln) |
invertSelection | () | Auswahl umkehren |
loadSelection | (channelName) | Kanal-CSD laden (muss in app.channels existieren) |
intersectSelection | (channelName) | Auswahl mit Kanal schneiden |
growSelection | (by) | Auswahl vergrößern (in Pixeln) |
colorRange | (color, fuzziness) | color = RGB-Objekt, fuzziness = 0–255 |
rasterizeAll | () | Alle Ebenen rasterisieren |
mergeVisibleLayers | () | Sichtbare Ebenen zusammenführen |
mergeVisibleLayersAndGroups | () | Sichtbare Ebenen und Gruppen zusammenführen |
desaturate | () | Entsättigen (luminosity every px) |
invert | () | Invertieren |
posterize | (levels) | 2–255 Stufen |
threshold | (level) | 0–255 Schwellenwert |
splitChannels | () | Kanäle aufteilen |
mergeChannels | (mode) | Kanäle mit angegebenem Modus zusammenführen |
revealAll | () | Außerhalb-Leinwand-Inhalt anzeigen (Bild in Leinwand einpassen) |
trap | (width) | Überfüllung, wenn CMYK |
deletePsdComments | () | Alle PSD-Kommentare (Anmerkungen) löschen |
set | (prop, value) | Photoshop-spezifische Anwendungseigenschaften festlegen |
Layer — Ebenen-API
Alle Ebenen (ArtLayer + LayerSet) erben von Layer. Zugriff über doc.layers[i], getByName("Name") usw.
Gemeinsame Eigenschaften
| Eigenschaft | Typ | L/S | Beschreibung |
|---|---|---|---|
name | string | L/S | Ebenenname |
visible | boolean | L/S | Sichtbarkeit |
opacity | number | L/S | 0–100 |
fillOpacity | number | L/S | 0–100 (Fülldeckkraft) |
blendMode | BlendMode | L/S | BlendMode.NORMAL, MULTIPLY, SCREEN, OVERLAY, DIFFERENCE usw. |
locked | boolean | L/S | Vollständig gesperrt |
allLocked | boolean | L/S | Alle Sperr-Optionen |
transparencyLocked | boolean | L/S | Transparenz gesperrt |
compositeLocked | boolean | L/S | Bildpixel gesperrt |
positionLocked | boolean | L/S | Position gesperrt |
pxLocked | boolean | L/S | Pixel gesperrt (Alias für compositeLocked) |
bounds | array | L | [x1,y1,x2,y2] in Pixelkoordinaten relativ zur Leinwand |
boundsNoEffects | array | L | Gleiche wie bounds, ohne Ebeneneffekte |
kind | LayerKind | L | LayerKind.NORMAL, TEXT, SMARTOBJECT, ADJUSTMENT, SHAPE, VIDEO, CLIPGROUP |
isBackgroundLayer | boolean | L | |
isTextLayer | boolean | L | |
groupID | number | L/S | Photopea-Erweiterung — Gruppenebenen-ID (0 = keine Gruppe) |
id | number | L | Eindeutige Ebenen-ID |
Methoden
| Methode | Signatur | Beschreibung |
|---|---|---|
duplicate | (relativeObject, insertionLocation) | Ebene duplizieren. InsertionLocation: ElementPlacement.INSIDE, INSIDEEND, PLACEBEFORE, PLACEAFTER, PLACEATBEGINNING, PLACEATEND |
remove | () | Ebene löschen |
move | (relativeObject, insertionLocation) | Ebene in der Ebenenreihenfolge verschieben |
resize | (horiz, vert, anchor) | Prozentskala (z. B. 200 = verdoppeln). Optional anchor |
scale | (horiz, vert, anchor) | Alias für resize |
rotate | (degrees, anchor) | Relative Rotation um Mittelpunkt (an der Stelle) |
translate | (deltaX, deltaY) | Um dx, dy Pixel relativ verschieben |
translateAbsolute | (x, y) | An Position (in Pixelkoordinaten) verschieben |
flip | (direction) | Direction.HORIZONTAL oder Direction.VERTICAL |
adjustBrightnessContrast | (brightness, contrast) | Helligkeit/Kontrast anpassen |
adjustLevels | (inputRange, inputRangeGamma, outputRange, ...) | Tonwertkorrektur über Arrays |
adjustCurves | (channel, curve) | curve = Array von Kontrollpunkten [{x,y},...] |
adjustColorBalance | (shadows, midtones, highlights) | Alle drei sind [cy,mg,yel]-Arrays |
adjustHueSaturation | (hue, saturation, lightness) | Alle 0–180, 0–100, -100–100 |
adjustPhotoFilter | (color, density) | color = SolidColor, density = 0–100 |
adjustExposure | (exposure, offset, gamma) | Alle drei Zahlen |
adjustInvert | () | Invertieren |
adjustPosterize | (levels) | 2–255 Stufen |
adjustThreshold | (level) | 0–255 Schwellenwert |
adjustSelectiveColor | (method, colors) | method = "relative" oder "absolute", colors = Objekt von Farbkomponenten |
adjustGradientMap | (gradient) | Gradient-Objekt |
applyFilter | (filterName, settings) | Filter anwenden (siehe Filter-Abschnitt unten) |
set | (prop, value) | Photoshop-spezifische Ebeneneigenschaft (z. B. layer.set("layerId", 5)) |
get | (prop) | Photoshop-spezifische Ebeneneigenschaft abrufen |
ArtLayer — Pixel-/Inhaltsebene
Erbt alle Layer-Eigenschaften + Methoden. Zusätzlich:
| Eigenschaft | Beschreibung |
|---|---|
textItem | TextItem-Objekt (siehe unten), wenn kind === LayerKind.TEXT, sonst null |
smartObject | SmartObject (siehe unten), wenn kind === LayerKind.SMARTOBJECT, sonst null |
adjustment | Einstellungstyp (String), wenn kind === LayerKind.ADJUSTMENT |
pxData | Photopea-Erweiterung — Zugriff auf die Pixel (Array/ByteArray) für diese Ebene |
LayerSet — Gruppenebene
Erbt alle Layer-Eigenschaften + Methoden. Zusätzlich:
| Eigenschaft | Beschreibung |
|---|---|
layers | Layers |
artLayers | ArtLayers |
layerSets | LayerSets |
background | Background |
opacity | number |
TextItem — Textebene
Zugriff: layer.textItem (wenn layer.kind === LayerKind.TEXT)
Eigenschaften
| Eigenschaft | Typ | L/S | Beschreibung |
|---|---|---|---|
contents | string | L/S | Textinhalt |
font | string | L/S | Schriftfamilienname |
size | number | L/S | Schriftgröße in Punkten (fließend) |
color | SolidColor | L/S | Textfarbe |
position | array | L | [x,y] Position |
fontStyle | string | L/S | „Bold“, „Italic“ usw. |
horizontalAlignment | Alignment | L/S | Alignment.LEFT, RIGHT, CENTER, JUSTIFIED |
verticalAlignment | Alignment | L/S | Alignment.TOP, BOTTOM, CENTER |
autoKerning | boolean | L/S | Automatisches Kerning |
baselineShift | number | L/S | In Punkten |
capitalization | Capitalization | L/S | Capitalization.NORMAL, UPPERCASE, SMALLCAPS |
desiredGlyphScaling | number | L/S | 50–200 % |
desiredLetterScaling | number | L/S | -100–500 % |
desiredWordScaling | number | L/S | 50–200 % |
direction | Direction | L/S | Direction.HORIZONTAL oder Direction.VERTICAL |
leading | number | L/S | Zeilenabstand in Punkten (0 = automatisch) |
letterSpacing | number | L/S | -100–500 % |
ligatures | boolean | L/S | Ligaturen |
maximumGlyphScaling | number | L/S | 50–200 % |
maximumLetterScaling | number | L/S | -100–500 % |
maximumWordScaling | number | L/S | 50–200 % |
strikeThrough | boolean | L/S | Durchgestrichen |
tracking | number | L/S | Zeichenabstand in Einheiten (0 = automatisch) |
underline | boolean | L/S | Unterstrichen |
useAutoLeading | boolean | L/S | Automatischer Zeilenabstand |
wordSpacing | number | L/S | Wortabstand (ähnlich letterSpacing) |
SmartObject — Smart-Objekt-Ebene
Eigenschaften
| Eigenschaft | Beschreibung |
|---|---|
linked | boolean |
linkedFile | File |
bounds | array |
Methoden
| Methode | Beschreibung |
|---|---|
replaceContents(url) | Eingebettete Datei durch neue URL ersetzen |
load | Photopea-Erweiterung — Erzwingt das Laden (für verknüpfte Dateien) |
unlink | Photopea-Erweiterung — Verknüpfung aufheben (eingebettet) |
Selection — Auswahlobjekt
Eigenschaften
| Eigenschaft | Typ | Beschreibung |
|---|---|---|
bounds | array | [x1,y1,x2,y2] in Pixeln |
solid | boolean | Ist nicht leer |
Methoden
| Methode | Beschreibung |
|---|---|
clear() | Inhalt löschen |
fill(color) | Mit SolidColor füllen |
stroke(color, width, location, blendMode, opacity, preserveTransparency) | Umriss zeichnen |
contract(by) | Verkleinern |
expand(by) | Erweitern |
feather(by) | Weichzeichnen |
smooth(by) | Glätten |
grow(by) | Vergrößern |
load(channelName) | CSD aus angegebenem Kanal laden |
intersect(channelName) | Mit Kanal-CSD schneiden |
invert() | Umkehren |
makeWorkPath(tolerance) | In Arbeitspfad umwandeln |
select(region, type, feather) | Nach Region auswählen (Array von {x,y}-Punkten) |
store(channelName) | In neuem Kanal speichern |
SolidColor — Farbrepräsentation
var color = new SolidColor();
color.rgb.red = 255; color.rgb.green = 100; color.rgb.blue = 0;
// Oder:
var color = { rgb: { red: 0, green: 255, blue: 0 } };
Eigenschaften: .rgb (Objekt mit red/green/blue), .cmyk, .hsl, .gray, .lab.
BlendMode — Konstanten
BlendMode.NORMAL, MULTIPLY, SCREEN, OVERLAY, DIFFERENCE, EXCLUSION, DARKEN, LIGHTEN, COLORDODGE, COLORBURN, LINEARDODGE, LINEARBURN, HARDLIGHT, SOFTLIGHT, VIVIDLIGHT, LINEARLIGHT, PINLIGHT, HARDMIX, DISSOLVE, DIVIDE, ADD, SUBTRACT, HUE, SATURATION, COLOR, LUMINOSITY, PASSTHROUGH, DARKERCOLOR, LIGHTERCOLOR, LIVELINESS, LUMINOSITY_CONTRAST, LINEAR_BURN (BC), LINEAR_BURN_2 (LCC), MIXTURE;
Filter-API
Verwenden Sie layer.applyFilter(name, settings).
settings ist ein Objekt — die Eigenschaften variieren pro Filter.
Unschärfe-Filter
applyFilter("BLUR", {}) — Weichzeichnen
applyFilter("BLUR_MORE", {}) — Stärker weichzeichnen
applyFilter("BOX_BLUR", {radius: 0.5}) — Box-Weichzeichner
applyFilter("BLUR_GAUSSIAN", {radius: 0.5}) — Gaußscher Weichzeichner
applyFilter("LENS_BLUR", {radius: ...}) — Linsenunschärfe
applyFilter("MOTION_BLUR", {distance: 0, angle: 30}) — Bewegungsunschärfe
applyFilter("RADIAL_BLUR", {amount: 10, method: "spin"|"zoom", quality: "best"|"good"|"draft"}) — Radialer Weichzeichner
applyFilter("SHAPE_BLUR", {shape: "...", radius: 10}) — Form-Weichzeichner
applyFilter("SMART_BLUR", {radius: 2, threshold: 25, quality: "LOW"|"MEDIUM"|"HIGH", mode: "NORMAL"|"EDGE_ONLY"|"OVERLAY_EDGE"}) — Selektiver Weichzeichner
applyFilter("SURFACE_BLUR", {radius: 2, threshold: 25}) — Oberflächen-Weichzeichner
Rausch-Filter
applyFilter("ADD_NOISE", {distribution: "uniform"|"gaussian", monochromatic: false, amount: 1.0}) — Rauschen hinzufügen
applyFilter("DESPECKLE", {}) — Entflecken
applyFilter("DUST_AND_SCRATCHES", {radius: 1, threshold: 0}) — Staub und Kratzer
applyFilter("MEDIAN", {radius: 1}) — Median
applyFilter("REDUCE_NOISE", {strength: 1, preserveDetails: false, reduceColorNoise: 0, sharpenDetails: false}) — Rauschen reduzieren
Scharfzeichnungs-Filter
applyFilter("SHARPEN", {}) — Scharfzeichnen
applyFilter("SHARPEN_EDGES", {}) — Kanten scharfzeichnen
applyFilter("SHARPEN_MORE", {}) — Stärker scharfzeichnen
applyFilter("SMART_SHARPEN", {amount: 100, radius: 1.0, noise: 0, shadowFade: 0, highlightFade: 0, shadowWidth: 5, highlightWidth: 5, remove: "BLUR"|"GAUSSIAN_BLUR"|"MOTION_BLUR"|"LENS_BLUR", angle: 0}) — Selektives Scharfzeichnen
applyFilter("UNSHARP_MASK", {amount: 50, radius: 1.0, threshold: 0}) — Unscharf maskieren
Verzerrungs-Filter
applyFilter("DISPLACE", {scale: 10, horizontal: 1, vertical: 1, stretchToFit: true, repeatPixels: false}) — Verschiebungseffekt
applyFilter("GLASS", {distortion: 5, smoothness: 3, scaling: 100, invert: false, texture: "..."|"BLOCKS"|"CANVAS"|"FROSTED"|"TINYLENS"|"LOAD_TEXTURE"}) — Glas-Effekt
applyFilter("OCEAN_RIPPLE", {size: 9, magnitude: 9}) — Meereswellen
applyFilter("PINCH", {amount: 50}) — Verzerrung (positiv = hinein, negativ = heraus)
applyFilter("POLAR_COORDINATES", {rectangular: true}) — Polarkoordinaten
applyFilter("RIPPLE", {amount: 100, size: "SMALL"|"MEDIUM"|"LARGE"}) — Welle
applyFilter("SHEAR", {curve: [[0,0.5],[0.5,0],[1,0.5]], repeat: "wrap"|"repeat", undefined: false}) — Schere
applyFilter("SPHERIZE", {amount: 50}) — Sphärisieren
applyFilter("TWIRL", {angle: 60}) — Wirbel
applyFilter("WAVE", {generators: 5, minWavelength: 10, maxWavelength: 120, minAmplitude: 5, maxAmplitude: 35, scale: [100,100], type: "sine"|"triangle"|"square", repeat: "warp"|"repeat", undefined: false}) — Welle
applyFilter("ZIGZAG", {amount: 10, ridges: 10, style: "around_center"|"out_from_center"|"pond_ripples"}) — Zickzack
Pixel-Filter
applyFilter("COLOR_HALFTONE", {maxRadius: 8, angles: [108,162,90,45]}) — Farbhalbton
applyFilter("CRYSTALLIZE", {cellSize: 10}) — Kristallisieren
applyFilter("FACET", {}) — Facette
applyFilter("FRAGMENT", {}) — Fragment
applyFilter("MEZZOTINT", {type: "..."}) — Mezzotinto
applyFilter("MOSAIC", {cellSize: 10}) — Mosaik
applyFilter("POINTILLIZE", {cellSize: 5}) — Punktieren
Render-Filter
applyFilter("CLOUDS", {}) — Wolken
applyFilter("DIFFERENCE_CLOUDS", {}) — Differenzwolken
applyFilter("FIBERS", {variance: 16, strength: 4}) — Fasern
applyFilter("LENS_FLARE", {brightness: 100, x: 0.5, y: 0.5, lens: "50_300"|"35"|"105"|"MOVIE"}) — Blendenfleck
applyFilter("LIGHTING_EFFECTS", {...}) — Beleuchtungseffekte
Stilisierungs-Filter
applyFilter("DIFFUSE", {mode: "NORMAL"|"LIGHTEN_ONLY"|"DARKEN_ONLY", anisotropy: 1}) — Diffuses Licht
applyFilter("EMBOSS", {angle: 135, height: 3, amount: 100}) — Prägen
applyFilter("EXTRUDE", {type: "blocks"|"pyramids", size: 30, depth: 30, random: true, solidFront: false, maskIncomplete: true}) — Extrudieren
applyFilter("FIND_EDGES", {}) — Kanten suchen
applyFilter("GLOWING_EDGES", {edgeWidth: 1, edgeBrightness: 0, smoothness: 1}) — Leuchtende Kanten
applyFilter("SOLARIZE", {}) — Solarisieren
applyFilter("TILES", {number: 10, maxOffset: 10, fill: "Background"|"Foreground"|"InverseImage"|"Unchanged"}) — Kacheln
applyFilter("TRACE_CONTOUR", {level: 128, edge: "lower"|"upper"}) — Kontourlinie nachziehen
applyFilter("WIND", {method: "wind"|"blast"|"stagger", direction: "right"|"left"|"up"|"down"}) — Wind
Video-Filter
applyFilter("NTSC_COLORS", {}) — NTSC-Farben
applyFilter("DEINTERLACE", {method: "duplicate"|"interpolation"}) — Zeilenentflechtung
Sonstige Filter
applyFilter("CUSTOM", {matrix: [0,0,0,0,0,0,1,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0], scale: 1, offset: 0}) — Benutzerdefiniert
applyFilter("HIGH_PASS", {radius: 6}) — Hochpass
applyFilter("MAXIMUM", {radius: 2}) — Maximum
applyFilter("MINIMUM", {radius: 1}) — Minimum
applyFilter("OFFSET", {horizontal: 0, vertical: 0, repeat: "wrap"|"repeat"|"setToBackground"}) — Verschiebung
applyFilter("RECOLOR", {}) — Neu einfärben
applyFilter("SHADOWS_HIGHLIGHTS", {shadowAmount: 35, tonalWidth: 50, radius: 30, highlightAmount: 0}) — Tiefen/Lichter
applyFilter("EQUALIZE", {}) — Tonwertangleichung
Weitere Objekte
Channel
| Eigenschaft | Beschreibung |
|---|---|
name | Kanalkomp.: "rot", "grün", "blau" usw. |
kind | "COMPONENT" für rot/grün/blau, "MASK" für benutzerdefiniert |
visible | Sichtbarkeit |
opacity | 0–100 |
histogram | 256-Elemente-Array |
Guide
| Eigenschaft | Beschreibung |
|---|---|
direction | Direction.HORIZONTAL oder Direction.VERTICAL |
value | Position (in Linealeinheiten) |
HistoryState
| Eigenschaft | Beschreibung |
|---|---|
name | String |
target | Document, ArtLayer, Selection, Channel |
source | HistoryState |
LayerComp
| Eigenschaft | Beschreibung |
|---|---|
name | String |
comment | String |
appearance | boolean |
position | boolean |
visibility | boolean |
selected | boolean |
active | boolean |
Methoden: apply(), delete(), duplicate(), recapture().
PathItem
| Eigenschaft | Beschreibung |
|---|---|
name | String |
kind | PathKind |
subPathItems | Array von SubPathItem |
SubPathItem
| Eigenschaft | Beschreibung |
|---|---|
closed | boolean |
pathPoints | Array von PathPoint |
PathPoint
| Eigenschaft | Beschreibung |
|---|---|
anchor | Array [x,y] |
leftDirection | // |
rightDirection | // |
kind | PointKind (SMOOTH/CORNER) |
Wichtige Photopea-Scripting-Hinweise
-
Immer zuerst Linealeinheiten speichern und auf Pixel setzen. Standard ist Zoll — viele APIs (bounds, resize, position) arbeiten in Linealeinheiten.
-
Ebenenzugriff ist nullbasiert:
doc.layers[0]= unterste Ebene. -
Stapelverarbeitung: Öffnen Sie mehrere URLs mit
openFromURL; Photopea öffnet alle nebeneinander. Wechseln Sie Dokumente überapp.activeDocument = docoder verwenden Siedoc.id. -
Kein direkter DOM-Zugriff von Skripten — kein
document.querySelector; verwendetapp.echoToOE, um Daten an den Host zurückzugeben. -
Asynchrone Wartezeit: Nach dem Laden von Assets oder dem Öffnen von Dokumenten müssen Skripte möglicherweise kurz warten, bis die Verarbeitung abgeschlossen ist. Das Muster
addImageAndWaitoben zeigt, wie man dies robust handhabt. -
Fehlerbehandlung:
runScriptwird abgelehnt, wenn Ihr Skript einen unbehandelten Fehler auslöst. Verwenden Sie immer Try-Catch innerhalb Ihres Skript-Strings oder behandeln Sie den abgelehnten Promise auf der Host-Seite.