Scripting Adobe Illustrator

Guide expert pour automatiser Adobe Illustrator via ExtendScript (JavaScript/JSX). Cette skill couvre le modèle d'objet de scripting d'Illustrator, tous les objets API majeurs, les patterns de code et les bonnes pratiques pour écrire des scripts .jsx de qualité production.

Ressources Groupées

• references/object-model-quick-reference.md : À utiliser comme référence rapide pour le modèle d'objet de scripting d'Illustrator, les types de documents et d'éléments de page courants, et les concepts DOM connexes pendant l'écriture ou le débogage de scripts.
• scripts/ : Contient des exemples de scripts d'automation Illustrator que vous pouvez utiliser comme points de départ ou patterns d'implémentation pour des tâches courantes telles que la manipulation de documents, les exports, le traitement par lots et l'utilisation du DOM. Consultez et adaptez ces exemples quand vous avez besoin de patterns JSX fonctionnels ou pour comparer les comportements lors du débogage.

Quand utiliser cette Skill

• Écrire de nouveaux scripts d'automation Illustrator (fichiers .jsx ou .js)
• Déboguer ou corriger le code ExtendScript Illustrator existant
• Manipuler des documents, calques, éléments de page, chemins, texte ou couleurs par programmation
• Traiter par lots des fichiers Illustrator ou générer des œuvres à partir de données
• Exporter des documents vers différents formats (PDF, SVG, PNG, EPS, etc.)
• Travailler avec le DOM d'Illustrator (Application, Document, Layer, PathItem, TextFrame, etc.)
• Créer des graphiques pilotés par les données en utilisant des variables et datasets
• Automatiser les workflows d'impression avec des options d'impression scriptées

Prérequis

• Adobe Illustrator CC ou version ultérieure installé
• Connaissances JavaScript basiques (ExtendScript est basé sur ES3 avec extensions Adobe)
• Les scripts sont exécutés via Fichier > Scripts > Autres Scripts, le menu Scripts, ou placés dans le dossier Scripts de démarrage
• L'ExtendScript Toolkit (ESTK) ou un éditeur de texte quelconque peut être utilisé pour écrire des fichiers .jsx

Environnement de Scripting

Langage et Extensions de Fichiers

Cette skill se concentre sur ExtendScript/JavaScript comme option multi-plateforme la plus largement utilisée.

Exécution de Scripts

• Menu Scripts : Fichier > Scripts liste les scripts du dossier scripts de l'application
• Autres Scripts : Fichier > Scripts > Autres Scripts pour parcourir et exécuter n'importe quel fichier .jsx
• Scripts de démarrage : Placez les scripts dans le dossier Scripts de démarrage pour les exécuter automatiquement au lancement
• Directive target : Commencez les scripts avec #target illustrator lors de l'exécution depuis ESTK ou des outils externes
• Directive #targetengine : Utilisez #targetengine "session" pour persister les variables entre les exécutions de script

Conventions de Nommage (JavaScript)

• Les objets et propriétés utilisent camelCase : activeDocument, pathItems, textFrames
• Le global app référence l'objet Application
• Les indices de collections sont basés sur zéro : documents[0] est le document actif
• Utilisez la propriété typename pour identifier les types d'objets au moment de l'exécution

Aperçu du Modèle d'Objet

Le DOM d'Illustrator suit une hiérarchie de containment stricte :

Application (app)
├── activeDocument / documents[]
│   ├── layers[]
│   │   ├── pageItems[] (toutes les œuvres)
│   │   ├── pathItems[]
│   │   ├── compoundPathItems[]
│   │   ├── textFrames[]
│   │   ├── placedItems[]
│   │   ├── rasterItems[]
│   │   ├── meshItems[]
│   │   ├── pluginItems[]
│   │   ├── graphItems[]
│   │   ├── symbolItems[]
│   │   ├── nonNativeItems[]
│   │   ├── legacyTextItems[]
│   │   └── groupItems[]
│   ├── artboards[]
│   ├── views[]
│   ├── selection (tableau d'éléments sélectionnés)
│   ├── swatches[], spots[], gradients[], patterns[]
│   ├── graphicStyles[], brushes[], symbols[]
│   ├── textFonts[] (via app.textFonts)
│   ├── stories[], characterStyles[], paragraphStyles[]
│   ├── variables[], datasets[]
│   └── inkList[], printOptions
├── preferences
├── printerList[]
└── textFonts[]

Objets de Haut Niveau

• Application (app) : L'objet racine. Fournit un accès aux documents, préférences, polices et imprimantes. Propriétés clés : activeDocument, documents, textFonts, printerList, userInteractionLevel, version.
• Document : Représente un fichier .ai ouvert. Propriétés clés : layers, pageItems, selection, activeLayer, width, height, rulerOrigin, documentColorSpace. Méthodes clés : saveAs(), exportFile(), close(), print().
• Layer : Un calque de dessin. Propriétés clés : pageItems, pathItems, textFrames, visible, locked, opacity, name, zOrderPosition, color.

Unités de Mesure et Coordonnées

Unités

Toutes les valeurs de l'API de scripting utilisent les points (72 points = 1 pouce). Convertissez d'autres unités :

Le kerning, le tracking et les propriétés aki utilisent les unités em (millièmes d'em, proportionnels à la taille de la police).

Système de Coordonnées

• Pour les documents scriptés, l'origine (0,0) se trouve en bas à gauche de la planche
• X augmente de gauche à droite ; Y augmente de bas en haut
• La propriété position d'un élément de page est l'angle supérieur gauche de sa boîte englobante comme [x, y]
• Largeur/hauteur maximum d'un élément de page : 16 348 points

Limites des Éléments d'Art

Chaque élément de page possède trois rectangles englobants :

• geometricBounds : Exclut la largeur du trait [left, top, right, bottom]
• visibleBounds : Inclut la largeur du trait
• controlBounds : Inclut les points de contrôle/direction

Travailler avec des Documents

Création et Ouverture

// Créer un nouveau document
var doc = app.documents.add();

// Créer avec un preset
var preset = new DocumentPreset();
preset.width = 612;  // 8,5 pouces
preset.height = 792; // 11 pouces
preset.colorMode = DocumentColorSpace.CMYK;
var doc = app.documents.addDocument("Print", preset);

// Ouvrir un fichier existant
var fileRef = new File("/path/to/file.ai");
var doc = app.open(fileRef);

Enregistrement et Export

// Enregistrer au format Illustrator
var saveOpts = new IllustratorSaveOptions();
saveOpts.compatibility = Compatibility.ILLUSTRATOR17; // CC
doc.saveAs(new File("/path/to/output.ai"), saveOpts);

// Exporter en PDF
var pdfOpts = new PDFSaveOptions();
pdfOpts.compatibility = PDFCompatibility.ACROBAT7;
pdfOpts.preserveEditability = false;
doc.saveAs(new File("/path/to/output.pdf"), pdfOpts);

// Exporter en PNG
var pngOpts = new ExportOptionsPNG24();
pngOpts.horizontalScale = 300;
pngOpts.verticalScale = 300;
pngOpts.transparency = true;
doc.exportFile(new File("/path/to/output.png"), ExportType.PNG24, pngOpts);

// Exporter en SVG
var svgOpts = new ExportOptionsSVG();
svgOpts.fontType = SVGFontType.OUTLINEFONT;
doc.exportFile(new File("/path/to/output.svg"), ExportType.SVG, svgOpts);

Travailler avec des Chemins et des Formes

Méthodes de Formes Intégrées

La collection pathItems fournit des méthodes pratiques pour les formes courantes :

var doc = app.activeDocument;
var layer = doc.activeLayer;

// Rectangle : rectangle(top, left, width, height)
var rect = layer.pathItems.rectangle(500, 100, 200, 150);

// Rectangle arrondi : roundedRectangle(top, left, width, height, hRadius, vRadius)
var rrect = layer.pathItems.roundedRectangle(500, 100, 200, 150, 20, 20);

// Ellipse : ellipse(top, left, width, height)
var oval = layer.pathItems.ellipse(400, 200, 100, 100);

// Polygone : polygon(centerX, centerY, radius, sides)
var hex = layer.pathItems.polygon(300, 300, 50, 6);

// Étoile : star(centerX, centerY, radius, innerRadius, points)
var star = layer.pathItems.star(300, 300, 50, 25, 5);

Chemins Libres Utilisant des Tableaux de Coordonnées

var doc = app.activeDocument;
var path = doc.pathItems.add();
path.setEntirePath([[100, 100], [200, 200], [300, 100]]);
path.closed = false;
path.stroked = true;
path.strokeWidth = 2;

Chemins Libres Utilisant des Objets PathPoint

var doc = app.activeDocument;
var path = doc.pathItems.add();

var point1 = path.pathPoints.add();
point1.anchor = [100, 100];
point1.leftDirection = [100, 100];
point1.rightDirection = [150, 150];
point1.pointType = PointType.SMOOTH;

var point2 = path.pathPoints.add();
point2.anchor = [300, 100];
point2.leftDirection = [250, 150];
point2.rightDirection = [300, 100];
point2.pointType = PointType.SMOOTH;

path.closed = false;

Propriétés de Chemin

var item = doc.pathItems[0];
item.filled = true;
item.stroked = true;
item.strokeWidth = 1.5;
item.strokeCap = StrokeCap.ROUNDENDCAP;
item.strokeJoin = StrokeJoin.ROUNDENDJOIN;
item.opacity = 80;
item.closed = true;

Travailler avec les Couleurs

Objets Couleur

// Couleur RVB (valeurs 0-255)
var red = new RGBColor();
red.red = 255;
red.green = 0;
red.blue = 0;

// Couleur CMYK (valeurs 0-100)
var cyan = new CMYKColor();
cyan.cyan = 100;
cyan.magenta = 0;
cyan.yellow = 0;
cyan.black = 0;

// Niveaux de gris (0-100, 0 = noir)
var gray = new GrayColor();
gray.gray = 50;

// Couleur Lab
var lab = new LabColor();
lab.l = 50;
lab.a = 20;
lab.b = -30;

// Pas de couleur (transparent)
var none = new NoColor();

Application des Couleurs

var item = doc.pathItems[0];
item.fillColor = red;
item.strokeColor = cyan;

// Remplissage dégradé
var gradient = doc.gradients.add();
gradient.type = GradientType.LINEAR;
gradient.gradientStops[0].color = red;
gradient.gradientStops[1].color = cyan;

var gradColor = new GradientColor();
gradColor.gradient = gradient;
item.fillColor = gradColor;

Couleurs Spot et Échantillons

// Créer une couleur spot
var spot = doc.spots.add();
spot.name = "My Spot Color";
spot.color = red; // Définition de couleur de base

var spotColor = new SpotColor();
spotColor.spot = spot;
spotColor.tint = 100;

item.fillColor = spotColor;

// Accéder à un échantillon par nom
var swatch = doc.swatches.getByName("PANTONE 185 C");
item.fillColor = swatch.color;

Travailler avec le Texte

Types de Cadres de Texte

var doc = app.activeDocument;

// Texte de point
var pointText = doc.textFrames.add();
pointText.contents = "Hello World!";
pointText.position = [100, 500];

// Texte de zone (texte à l'intérieur d'un chemin)
var rectPath = doc.pathItems.rectangle(500, 100, 200, 100);
var areaText = doc.textFrames.areaText(rectPath);
areaText.contents = "Text inside a rectangle shape.";

// Texte de chemin (texte le long d'un chemin)
var curvePath = doc.pathItems.add();
curvePath.setEntirePath([[50, 300], [150, 400], [250, 300]]);
var pathText = doc.textFrames.pathText(curvePath);
pathText.contents = "Text on a path";

Formatage de Caractères et de Paragraphes

var tf = doc.textFrames[0];
var textRange = tf.textRange;

// Attributs de caractère
var charAttr = textRange.characterAttributes;
charAttr.size = 24;           // Taille de police en points
charAttr.textFont = app.textFonts.getByName("ArialMT");
charAttr.fillColor = red;
charAttr.tracking = 50;       // Unités em
charAttr.horizontalScale = 100;
charAttr.verticalScale = 100;
charAttr.baselineShift = 0;

// Attributs de paragraphe
var paraAttr = textRange.paragraphAttributes;
paraAttr.justification = Justification.CENTER;
paraAttr.firstLineIndent = 0;
paraAttr.leftIndent = 0;
paraAttr.spaceBefore = 0;
paraAttr.spaceAfter = 0;

Accès au Contenu Textuel

var tf = doc.textFrames[0];

// Accéder aux sous-plages
var firstChar = tf.characters[0];
var firstWord = tf.words[0];
var firstPara = tf.paragraphs[0];
var firstLine = tf.lines[0];

// Modifier des plages spécifiques
tf.words[0].characterAttributes.size = 36;
tf.paragraphs[0].paragraphAttributes.justification = Justification.LEFT;

Liaison de Cadres de Texte

var frame1 = doc.textFrames.areaText(path1);
var frame2 = doc.textFrames.areaText(path2);

// Lier les cadres pour que le texte s'écoule de frame1 vers frame2
frame1.nextFrame = frame2;

// Les histoires (stories) représentent le texte complet sur les cadres liés
var storyCount = doc.stories.length;
var fullText = doc.stories[0].textRange.contents;

Travailler avec les Calques

var doc = app.activeDocument;

// Créer un calque
var newLayer = doc.layers.add();
newLayer.name = "Background";
newLayer.visible = true;
newLayer.locked = false;
newLayer.opacity = 100;

// Accéder aux calques existants
var topLayer = doc.layers[0];
var layerByName = doc.layers.getByName("Background");

// Déplacer des éléments entre les calques
var item = doc.pathItems[0];
item.move(newLayer, ElementPlacement.PLACEATBEGINNING);

// Réorganiser les calques
newLayer.zOrder(ZOrderMethod.SENDTOBACK);

Travailler avec les Sélections

// Obtenir la sélection actuelle
var sel = app.activeDocument.selection;

// Itérer sur les éléments sélectionnés
for (var i = 0; i < sel.length; i++) {
    var item = sel[i];
    // Vérifier le type avec typename
    if (item.typename === "PathItem") {
        item.fillColor = red;
    } else if (item.typename === "TextFrame") {
        item.contents = "Modified";
    }
}

// Sélectionner un élément par programmation
doc.pathItems[0].selected = true;

// Désélectionner tout
doc.selection = null;

Travailler avec les Symboles

// Placer une instance de symbole
var sym = doc.symbols.getByName("MySymbol");
var instance = doc.symbolItems.add(sym);
instance.position = [200, 400];

// Accéder à la définition de symbole
var symDef = instance.symbol;

// Rompre le lien avec le symbole (développer en art régulier)
instance.breakLink();

Transformations

var item = doc.pathItems[0];

// Tourner 45 degrés autour du centre
item.rotate(45);

// Redimensionner à 50% de largeur, 75% de hauteur
item.resize(50, 75);

// Translater (déplacer) de 100 points vers la droite et 50 points vers le haut
item.translate(100, 50);

// Utiliser une matrice de transformation
var matrix = app.getIdentityMatrix();
matrix = app.concatenateRotationMatrix(matrix, 30);
matrix = app.concatenateScaleMatrix(matrix, 150, 150);
item.transform(matrix);

Travailler avec les Planches

var doc = app.activeDocument;

// Accéder aux planches
var ab = doc.artboards[0];
var rect = ab.artboardRect; // [left, top, right, bottom]

// Créer une nouvelle planche
var newAB = doc.artboards.add([0, 0, 612, 792]); // Taille Lettre
newAB.name = "Page 2";

// Définir la planche active
doc.artboards.setActiveArtboardIndex(1);

Graphiques Pilotés par les Données (Variables et Datasets)

// Les variables lient les éléments de document aux champs de données
var v = doc.variables.add();
v.kind = VariableKind.TEXTUAL;
v.name = "headline";

// Lier un cadre de texte à la variable
var tf = doc.textFrames[0];
tf.contentVariable = v;

// Créer des datasets pour le contenu par lots
var ds = doc.dataSets.add();
ds.name = "Version 1";
// Le dataset capture les liaisons de variables actuelles

// Basculer les datasets pour échanger le contenu
doc.dataSets[0].display();

Impression

var doc = app.activeDocument;
var opts = new PrintOptions();

opts.printPreset = "Default";

// Options de papier
var paperOpts = new PrintPaperOptions();
paperOpts.name = "Letter";
opts.paperOptions = paperOpts;

// Options de travail
var jobOpts = new PrintJobOptions();
jobOpts.copies = 1;
jobOpts.designation = PrintArtworkDesignation.VISIBLELAYERS;
opts.jobOptions = jobOpts;

doc.print(opts);

Niveaux d'Interaction de l'Utilisateur

Contrôlez si Illustrator affiche des dialogues lors de l'exécution du script :

// Supprimer tous les dialogues
app.userInteractionLevel = UserInteractionLevel.DONTDISPLAYALERTS;

// Effectuer les opérations qui pourraient afficher des dialogues...
doc.close(SaveOptions.DONOTSAVECHANGES);

// Restaurer l'affichage des dialogues
app.userInteractionLevel = UserInteractionLevel.DISPLAYALERTS;

Travailler avec les Méthodes (Spécifique à JavaScript)

Lors de l'appel de méthodes avec plusieurs paramètres optionnels, utilisez undefined pour ignorer les paramètres du milieu :

// rotate(angle, [changePositions], [changeFillPatterns], [changeFillGradients], ...)
item.rotate(30, undefined, undefined, true);

Patterns Courants

Itérer Tous les Éléments de Page dans un Document

function processAllItems(doc) {
    for (var i = 0; i < doc.pageItems.length; i++) {
        var item = doc.pageItems[i];
        // Traiter en fonction du type
        switch (item.typename) {
            case "PathItem":
                // gérer le chemin
                break;
            case "TextFrame":
                // gérer le texte
                break;
            case "GroupItem":
                // gérer le groupe (peut contenir des éléments imbriqués)
                break;
        }
    }
}

Traiter des Fichiers en Lots dans un Dossier

var folder = Folder.selectDialog("Select folder of .ai files");
if (folder) {
    var files = folder.getFiles("*.ai");
    for (var i = 0; i < files.length; i++) {
        var doc = app.open(files[i]);
        // Traiter chaque document...
        doc.close(SaveOptions.DONOTSAVECHANGES);
    }
}

Gestion des Erreurs

try {
    var doc = app.activeDocument;
    var layer = doc.layers.getByName("NonExistentLayer");
} catch (e) {
    alert("Error: " + e.message);
    // e.message, e.line, e.fileName disponibles
}

Dépannage

• "undefined is not an object" : Signifie généralement que la collection est vide ou que l'index est hors limites. Vérifiez .length avant d'accéder aux éléments.
• Le script s'exécute mais rien ne change visuellement : Appelez app.redraw() pour forcer une actualisation de l'écran après les modifications.
• Incompatibilité d'espace colorimétrique : L'espace colorimétrique du document (RVB vs CMYK) doit correspondre aux objets couleur. Utilisez doc.documentColorSpace pour vérifier.
• La position semble incorrecte : Rappelez-vous que les documents scriptés utilisent une origine en bas à gauche avec Y augmentant vers le haut. La propriété position est l'angle supérieur gauche de la boîte englobante.
• Le texte n'apparaît pas : Assurez-vous que le cadre de texte a une taille non nulle. Pour le texte de point, définissez position ; pour le texte de zone, fournissez un chemin valide à areaText().
• Chemins de fichiers sur Windows : Utilisez les barres obliques (/) ou les barres obliques inverses doubles (\\) dans les chaînes de chemin, ou utilisez le constructeur de l'objet File.
• Les boîtes de dialogue interrompent les scripts par lots : Définissez app.userInteractionLevel = UserInteractionLevel.DONTDISPLAYALERTS avant les opérations par lots.
• Les collections utilisent getByName() : De nombreux objets de collection supportent getByName("name") qui lève une erreur s'il n'est pas trouvé ; enveloppez dans try/catch.

Référence des Constantes de Scripting

Constantes énumération courantes utilisées dans l'API :

Référence Complète des Objets JavaScript (Liste Complète des Objets API)

L'API JavaScript d'Illustrator contient les objets suivants, regroupés par catégorie :

Objets Cœur

Application, Document, Documents, DocumentPreset, Layer, Layers, PageItem, PageItems, View, Views, Preferences

Objets Chemin et Forme

PathItem, PathItems, PathPoint, PathPoints, CompoundPathItem, CompoundPathItems, GroupItem, GroupItems

Objets Texte

TextFrame, TextRange, TextRanges, TextPath, Characters, Words, Paragraphs, Lines, InsertionPoint, InsertionPoints, Story, Stories, CharacterAttributes, ParagraphAttributes, CharacterStyle, CharacterStyles, ParagraphStyle, ParagraphStyles, TextFont, TextFonts, TabStopInfo

Objets Couleur

RGBColor, CMYKColor, GrayColor, LabColor, NoColor, SpotColor, Spot, Spots, PatternColor, GradientColor, Color, Gradient, Gradients, GradientStop, GradientStops

Objets Échantillon et Style

Swatch, Swatches, SwatchGroup, SwatchGroups, GraphicStyle, GraphicStyles, Pattern, Patterns, Brush, Brushes

Objets Symbole

Symbol, Symbols, SymbolItem, SymbolItems

Objets Planche

Artboard, Artboards

Objets Placé et Raster

PlacedItem, PlacedItems, RasterItem, RasterItems, MeshItem, MeshItems, GraphItem, GraphItems, PluginItem, PluginItems, NonNativeItem, NonNativeItems, LegacyTextItem, LegacyTextItems

Objets Pilotés par les Données

Variable, Variables, Dataset, Datasets

Objets Matrice et Transformation

Matrix

Objets Étiquette

Tag, Tags

Objets Traçage

TracingObject, TracingOptions

Options d'Enregistrement et d'Export

IllustratorSaveOptions, EPSSaveOptions, PDFSaveOptions, FXGSaveOptions, ExportOptionsAutoCAD, ExportOptionsFlash, ExportOptionsGIF, ExportOptionsJPEG, ExportOptionsPhotoshop, ExportOptionsPNG8, ExportOptionsPNG24, ExportOptionsSVG, ExportOptionsTIFF

Options d'Ouverture

OpenOptions, OpenOptionsAutoCAD, OpenOptionsFreeHand, OpenOptionsPhotoshop, PDFFileOptions, PhotoshopFileOptions

Objets Impression

PrintOptions, PrintJobOptions, PrintPaperOptions, PrintColorManagementOptions, PrintColorSeparationOptions, PrintCoordinateOptions, PrintFlattenerOptions, PrintFontOptions, PrintPageMarksOptions, PrintPostScriptOptions, Printer, PrinterInfo, Paper, PaperInfo, PPDFile, PPDFileInfo, Ink, InkInfo, Screen, ScreenInfo, ScreenSpotFunction

Options d'Image et Rastérisation

ImageCaptureOptions, RasterEffectOptions, RasterizeOptions

Références

• Journal des Modifications - Changements récents de l'API de scripting (CC 2020 a ajouté Document.getPageItemFromUuid et PageItem.uuid ; CC 2017 a ajouté Application.getIsFileOpen)
• Guide de Scripting Illustrator - Documentation complète maintenue par la communauté