Compétence : Éditeur Photopea Intégré
Utilisation de photopea.js (yikuansun/PhotopeaAPI) dans les sites web et applications
Quand utiliser cette compétence
Utilisez cette compétence pour chaque tâche qui implique :
- Intégrer Photopea en tant qu'éditeur d'images dans une page web ou une application web
- Contrôler une instance Photopea intégrée depuis votre code JavaScript
- Automatiser des workflows d'édition d'images à partir d'une page hôte (ouvrir des fichiers, exécuter des scripts, exporter les résultats)
- Construire une fonctionnalité d'édition d'images dans votre produit en utilisant Photopea comme moteur
- Écrire des scripts pour manipuler des documents, des calques, du texte, des sélections, des filtres, des couleurs et des chemins
N'utilisez PAS le postMessage brut — utilisez toujours photopea.js comme couche d'abstraction.
Bibliothèque : photopea.js
photopea.js est une surcouche JavaScript basée sur les Promesses autour de l'API de messagerie Photopea Live.
Dépôt : https://github.com/yikuansun/PhotopeaAPI
Paquet npm : https://www.npmjs.com/package/photopea
Installation
CDN (sans étape de build)
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/photopea.min.js"></script>
Hébergé localement
<script src="./photopea.min.js"></script>
npm (Webpack / Vite / Rollup)
npm install photopea
import Photopea from "photopea";
API principale : la classe Photopea
| Méthode | Description |
|---|---|
Photopea.createEmbed(container) | Crée et injecte l'iframe, résout quand il est prêt |
new Photopea(window.parent) | Mode plugin : enveloppe la fenêtre parente |
pea.runScript(script) | Exécute une chaîne JS à l'intérieur de Photopea ; retourne un tableau de sorties |
pea.loadAsset(arrayBuffer) | Charge un fichier binaire (image, police, pinceau, etc.) |
pea.openFromURL(url, asSmart) | Ouvre une URL distante en tant que nouveau document ou calque d'objet dynamique |
pea.exportImage(type) | Exporte le document actif ; retourne un Blob ("png" ou "jpg") |
Toutes les méthodes retournent des Promesses — utilisez toujours await ou .then().
Étape 1 — Intégration
Le <div> conteneur doit avoir une largeur et une hauteur fixes avant d'appeler createEmbed.
<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 est prêt
});
</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" }} />;
}
Étape 2 — Ouverture de fichiers
// URL distante → nouveau document
await pea.openFromURL("https://example.com/design.psd", false);
// URL distante → calque d'objet dynamique dans le document actif
await pea.openFromURL("https://example.com/overlay.png", true);
// Fichier local (entrée utilisateur → ArrayBuffer → loadAsset)
document.getElementById("fileInput").addEventListener("change", async (e) => {
const buf = await e.target.files[0].arrayBuffer();
await pea.loadAsset(buf);
});
// URI de données Base64 via runScript
await pea.runScript(`app.open("data:image/png;base64,iVBORw0...");`);
Étape 3 — Exécution de scripts
runScript envoie une chaîne JS, retourne un tableau des valeurs app.echoToOE(...) + "done" en dernier.
const result = await pea.runScript(`app.echoToOE("hello");`);
// result → ["hello", "done"]
// Retourner des données structurées
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]);
Étape 4 — Exportation
// Blob PNG (via exportImage)
const blob = await pea.exportImage("png");
document.getElementById("preview").src = URL.createObjectURL(blob);
// Blob JPEG
const blob = await pea.exportImage("jpg");
// WebP / PSD / JPEG avec contrôle qualité 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" });
// Déclencher le téléchargement
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();
}
Chaînes de format d'exportation pour saveToOE :
| Chaîne | Format |
|---|---|
"png" | PNG sans perte |
"jpg" | JPEG par défaut |
"jpg:0.8" | JPEG qualité 0.0–1.0 |
"webp:0.7" | WebP qualité 0.0–1.0 |
"psd" | PSD complet |
"psd:true" | PSD minimisé |
"svg:true" | SVG |
Étape 5 — Chargement d'actifs
// Police
const buf = await (await fetch("https://example.com/MyFont.otf")).arrayBuffer();
await pea.loadAsset(buf);
// Maintenant utilisable dans textItem.font
// Pinceau
await pea.loadAsset(await (await fetch("Nature.ABR")).arrayBuffer());
// Dégradé
await pea.loadAsset(await (await fetch("Gradients.GRD")).arrayBuffer());
Étape 6 — Mode Plugin
// Votre page est dans l'iframe de la barre latérale de Photopea
const pea = new Photopea(window.parent);
const out = await pea.runScript(`app.echoToOE(app.activeDocument.width);`);
console.log("Largeur :", out[0]);
// Charger un actif depuis votre plugin
const buf = await (await fetch("https://my-assets.com/sticker.png")).arrayBuffer();
await pea.loadAsset(buf);
Configuration du plugin :
{
"environment": {
"plugins": [{
"name": "Mon Plugin",
"url": "https://mon-plugin.example.com",
"icon": "===https://mon-plugin.example.com/icon.png"
}]
}
}
Modèles utilitaires
addImageAndWait — insertion robuste et asynchrone de calque
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 — retourne un élément <img>
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" }));
});
}
Exemples concrets
Exemple A — Interface Ouvrir + Exporter
<input type="file" id="fileInput" accept="image/*,.psd">
<button id="exportBtn">Exporter en 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>
Exemple B — Modèle + Édition de texte + Exportation
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");
}
Exemple C — Filigrane par lots
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;
}
RÉFÉRENCE COMPLÈTE DE L'API DE SCRIPTING
Tout le code de cette section s'exécute à l'intérieur de chaînes
pea.runScript("..."). Photopea implémente l'interface de scripting JavaScript d'Adobe Photoshop CC 2015. Tout script Photoshop ciblant cette version devrait fonctionner dans Photopea.
app — Objet Application
Propriétés
| Propriété | Type | L/E | Description |
|---|---|---|---|
app.activeDocument | Document | L/E | Le document actuellement actif |
app.documents | Documents | L | Collection de tous les documents ouverts |
app.documents.length | number | L | Nombre de documents ouverts |
app.documents[i] | Document | L | Accès par index basé sur zéro |
app.foregroundColor | SolidColor | L/E | Couleur de premier plan actuelle |
app.backgroundColor | SolidColor | L/E | Couleur d'arrière-plan actuelle |
app.preferences.rulerUnits | Units | L/E | Units.PIXELS, Units.CM, Units.INCHES, Units.MM, Units.PICAS, Units.POINTS, Units.PERCENT |
app.preferences.typeUnits | TypeUnits | L/E | TypeUnits.PIXELS, TypeUnits.MM, TypeUnits.POINTS |
app.displayDialogs | DialogModes | L/E | DialogModes.NO, DialogModes.ALL, DialogModes.ERROR |
Méthodes
| Méthode | Description |
|---|---|
app.open(url) | Ouvre une URL en tant que nouveau document |
app.open(url, null, true) | Ouvre une URL en tant que calque d'objet dynamique dans le document actif |
app.echoToOE(string) | Extension Photopea — envoie une chaîne à la page hôte (capturée par runScript) |
app.showWindow("magiccut") | Extension Photopea — ouvre le panneau Coupe magique |
app.showWindow("vbitmap") | Extension Photopea — ouvre le panneau Vectoriser le bitmap |
app.UI.zoomIn() | Zoom avant |
app.UI.zoomOut() | Zoom arrière |
app.UI.fitTheArea() | Ajuster le canevas à la zone d'affichage |
app.UI.pixelToPixel() | Zoom 100% |
app.UI.switchFullscreen() | Basculer en plein écran |
app.UI.scroll(dx, dy) | Faire défiler par delta |
app.UI.scrollTo(x, y) | Faire défiler vers une position absolue |
Important : Définissez toujours les unités de règle en pixels au début de tout script qui utilise des mesures en pixels :
var savedUnits = app.preferences.rulerUnits;
app.preferences.rulerUnits = Units.PIXELS;
// ... votre code ...
app.preferences.rulerUnits = savedUnits;
Document — Objet Document
Accès via app.activeDocument ou app.documents[i].
Propriétés
| Propriété | Type | L/E | Description |
|---|---|---|---|
width | number | L | Largeur du document dans les unités de règle actuelles |
height | number | L | Hauteur du document dans les unités de règle actuelles |
resolution | number | L | DPI (pixels par pouce) |
name | string | L/E | Extension Photopea — étiquette d'affichage (pas d'étape d'historique) |
source | string | L/E | Extension Photopea — URL d'origine du fichier ou "local,X,NAME" |
mode | DocumentMode | L | DocumentMode.RGB, GRAYSCALE, CMYK, LAB, BITMAP, INDEXEDCOLOR, MULTICHANNEL |
bitsPerChannel | BitsPerChannelType | L | BitsPerChannelType.EIGHT, SIXTEEN, THIRTYTWO |
colorProfileName | string | L | Nom du profil colorimétrique intégré |
activeLayer | Layer/ArtLayer/LayerSet | L/E | Définir pour activer un calque |
currentLayer | ArtLayer | L/E | Alias pour activeLayer |
layers | Layers | L | Tous les calques de premier niveau (art + groupe) |
artLayers | ArtLayers | L | Uniquement les calques d'art de premier niveau |
layerSets | LayerSets | L | Uniquement les calques de groupe de premier niveau |
selection | Selection | L | La sélection actuelle |
channels | Channels | L | Tous les canaux |
historyStates | HistoryStates | L | Historique des annulations |
activeHistoryState | HistoryState | L/E | Position actuelle dans l'historique |
layerComps | LayerComps | L | Collection de compositions de calques |
guides | Guides | L | Collection de guides |
pathItems | PathItems | L | Chemins vectoriels |
id | number | L | Identifiant unique du document |
saved | boolean | L | Indique si le document a des modifications non sauvegardées |
quickMaskMode | boolean | L | Indique si le mode Masque rapide est actif |
backgroundLayer | ArtLayer | L | Le calque d'arrière-plan |
pixelAspectRatio | number | L | Ratio d'aspect personnalisé des pixels (0.1–10.0) |
histogram | array | L | Tableau d'histogramme de 256 éléments |
Méthodes
| Méthode | Signature | Description |
|---|---|---|
resizeImage | (w, h, res, resampleMethod) | Redimensionner les pixels de l'image. ResampleMethod : BICUBIC, BILINEAR, NEARESTNEIGHBOR, NONE, BICUBICSHARPER, BICUBICSMOOTHER |
resizeCanvas | (w, h, anchor) | Redimensionner le canevas sans mise à l'échelle. AnchorPosition : TOPLEFT, TOPCENTER, TOPRIGHT, MIDDLELEFT, MIDDLECENTER, MIDDLERIGHT, BOTTOMLEFT, BOTTOMCENTER, BOTTOMRIGHT |
rotateCanvas | (degrees) | Faire pivoter tout le canevas. Positif = horaire |
flipCanvas | (direction) | Direction.HORIZONTAL ou Direction.VERTICAL |
crop | ([x1,y1,x2,y2], angle, w, h) | Rogner le canevas. L'angle et les dimensions sont optionnels |
trim | (trimType, top, left, bottom, right) | Rogner les bords vides. TrimType : TrimType.TRANSPARENT, TrimType.TOPLEFT |
close | (SaveOptions) | Fermer le document. SaveOptions : DONOTSAVECHANGES, SAVECHANGES, PROMPTTOSAVECHANGES |
saveAs | (saveIn, docName, asCopy, extensionType) | Sauvegarder sous un nouveau fichier |
duplicate | (name, mergeLayersOnly) | Dupliquer le document |
flatten | () | Aplatir tous les calques |
mergeVisibleLayers | () | Fusionner les calques visibles |
mergeAllLayers | () | Fusionner tous les calques |
link | (layers) | Lier un tableau de calques |
suspendHistory | (hint, script) | Exécuter un script en tant qu'étape d'historique unique |
runFilter | (filterID) | Exécuter un filtre par nom. Exemples : "SPHERIZE", "GLASS", "CROP", "AUTOCONTRAST", "COLORBALANCE" |
rotateCanvasCustom | (method) | RotateMethod.BY180, CW90, CCW90, ARBITRARY |
... (tronqué pour la traduction)