Adobe Illustrator 脚本对象模型速查手册：DOM 层级、常量与单位换算实战指南

Adobe Illustrator 脚本对象模型速查手册DOM 层级、常量与单位换算实战指南【免费下载链接】awesome-copilotCommunity-contributed instructions, agents, skills, and configurations to help you make the most of GitHub Copilot.项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-copilot导读本文以 awesome-copilot 仓库中 adobe-illustrator-scripting 技能所附带的 对象模型快速参考 为核心骨架系统讲解 Illustrator ExtendScriptJavaScript/JSX的 DOM 包含层级、图稿项目类型、颜色对象、常用脚本常量与单位换算体系。读完本文你将能够在编写或调试.jsx自动化脚本时快速定位正确的集合与对象类型、选用准确的枚举常量并理解脚本坐标系与度量单位直接应用于文档批量处理、图形生成与文本操作等真实场景。一、包含层级Containment Hierarchy理解 Illustrator DOM 的骨架Illustrator 的脚本对象模型DOM遵循一条严格的包含关系链从全局的Application对象出发向下逐级访问文档、图层与各类图稿项目。快速参考文档给出的完整层级如下Application (app) └─ Document ├─ Layer │ ├─ pathItems[] → PathItem → PathPoint[] │ ├─ compoundPathItems[] → CompoundPathItem │ ├─ textFrames[] → TextFrame │ │ ├─ characters[] → TextRange (single char) │ │ ├─ words[] → TextRange (word) │ │ ├─ paragraphs[] → TextRange (paragraph) │ │ ├─ lines[] → TextRange (line) │ │ └─ insertionPoints[] │ ├─ placedItems[] → PlacedItem │ ├─ rasterItems[] → RasterItem │ ├─ meshItems[] → MeshItem │ ├─ pluginItems[] → PluginItem │ ├─ graphItems[] → GraphItem │ ├─ symbolItems[] → SymbolItem → Symbol │ ├─ groupItems[] → GroupItem (recursive pageItems) │ ├─ nonNativeItems[] → NonNativeItem │ └─ legacyTextItems[] → LegacyTextItem ├─ Artboard[] ├─ Swatch[] / Spot[] / Gradient[] / Pattern[] ├─ GraphicStyle[] / Brush[] / Symbol[] ├─ Story[] ├─ CharacterStyle[] / ParagraphStyle[] ├─ Variable[] / Dataset[] └─ View[]1.1 从app到Document脚本中全局对象app即Application是访问一切资源的根入口。技能文档 SKILL.md 进一步补充了完整的顶层结构Application之下不仅有activeDocument/documents[]还有preferences、printerList[]与textFonts[]Document除layers[]外还暴露artboards[]、views[]、selection当前选中项的数组、swatches[]/spots[]/gradients[]/patterns[]、graphicStyles[]/brushes[]/symbols[]、stories[]/characterStyles[]/paragraphStyles[]、variables[]/datasets[]以及inkList[]/printOptions。1.2 三大顶层对象的关键成员对象作用关键属性 / 方法Application(app)根对象提供文档、偏好、字体、打印机的入口activeDocument、documents、textFonts、printerList、userInteractionLevel、versionDocument代表一个打开的.ai文件layers、pageItems、selection、activeLayer、width、height、rulerOrigin、documentColorSpace方法saveAs()、exportFile()、close()、print()Layer绘制图层承载所有图稿pageItems、pathItems、textFrames、visible、locked、opacity、name、zOrderPosition、color使用提示命名规范上对象与属性一律使用camelCase如activeDocument、pathItems、textFrames集合索引起始于0documents[0]表示最前端的文档运行时可通过typename属性判别对象类型。二、图稿项目类型pageItems 成员逐类解析Layer与Document下所有可见图稿都归入pageItems集合但按具体类型分别存放在各自的集合中。快速参考文档中的类型表如下类型typename集合说明路径PathItempathItems直线、形状、自由曲线路径复合路径CompoundPathItemcompoundPathItems多条路径合并而成编组GroupItemgroupItems内部可嵌套其他 pageItems文本框架TextFrametextFrames点文本、区域文本或路径文本置入图片PlacedItemplacedItems链接的外部文件栅格图像RasterItemrasterItems嵌入的位图网格MeshItemmeshItems渐变网格对象图表GraphItemgraphItems图表对象插件项目PluginItempluginItems插件生成的图稿符号实例SymbolItemsymbolItemsSymbol的一个实例非原生项目NonNativeItemnonNativeItems外部/未知对象旧版文本LegacyTextItemlegacyTextItemsCS 之前的文本对象2.1 用typename在运行时判别类型批量处理时最稳健的做法是遍历pageItems用typename做类型分发function processAllItems(doc) { for (var i 0; i doc.pageItems.length; i) { var item doc.pageItems[i]; switch (item.typename) { case PathItem: // 处理路径 break; case TextFrame: // 处理文本 break; case GroupItem: // 处理编组可能嵌套子项目 break; } } }2.2 集合行为的两个易错点PlacedItem与RasterItem的重链接能力不同PlacedItem.file newFile可直接替换链接图像并保留父级、堆叠顺序与边界而RasterItem不暴露可写的file属性需要新建一个PlacedItem到同一父级、复制边界后再移除原栅格对象参考 SKILL.md 中的relinkOrRebuild模式。PlacedItem.file不接受 SVG设置为.svg文件会抛出Unable to set placed items file...。SVG 应走打开 → 全选复制 → 关闭 → 粘贴的路径对应placeSVG模式。2.3 文本框架的三层结构TextFrame是层级中最复杂的类型之一框架之下按粒度暴露characters[]单字符、words[]单词、paragraphs[]段落、lines[]行与insertionPoints[]插入点全部返回TextRange可以直接读写其characterAttributes与paragraphAttributesvar tf doc.textFrames[0]; var firstChar tf.characters[0]; var firstWord tf.words[0]; var firstPara tf.paragraphs[0]; var firstLine tf.lines[0]; // 修改特定范围 tf.words[0].characterAttributes.size 36; tf.paragraphs[0].paragraphAttributes.justification Justification.LEFT;多个文本框架可通过frame1.nextFrame frame2串接文本串接串接后的完整内容由Story汇总doc.stories[0].textRange.contents可一次取出全部文本——这正是查找替换脚本遍历文本的基础见后文实例。三、颜色对象模型8 种颜色类型的取值与应用颜色在 Illustrator DOM 中是独立对象赋值给fillColor/strokeColor时需构造对应色空间的颜色对象。快速参考文档的类型表如下对象色空间取值范围关键属性RGBColorRGB每通道 0-255.red、.green、.blueCMYKColorCMYK每通道 0-100.cyan、.magenta、.yellow、.blackGrayColor灰度0-100.gray0黑100白LabColorLabL: 0-100a/b: -128 至 127.l、.a、.bSpotColor专色tint 0-100.spot、.tintPatternColor图案—.pattern、.matrixGradientColor渐变—.gradient、.origin、.angleNoColor无—透明/无填充3.1 构造并应用颜色对象// RGB 颜色0-255 var red new RGBColor(); red.red 255; red.green 0; red.blue 0; // CMYK 颜色0-100 var cyan new CMYKColor(); cyan.cyan 100; cyan.magenta 0; cyan.yellow 0; cyan.black 0; // 灰度0-1000黑 var gray new GrayColor(); gray.gray 50; // Lab 颜色 var lab new LabColor(); lab.l 50; lab.a 20; lab.b -30; // 无颜色透明 var none new NoColor(); // 应用到图稿 var item doc.pathItems[0]; item.fillColor red; item.strokeColor cyan;3.2 渐变与专色两种特殊颜色对象渐变需要先在doc.gradients中创建Gradient再包装成GradientColorvar 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;专色则通过doc.spots.add()定义基色再用SpotColor指定专色与浓淡度tintvar spot doc.spots.add(); spot.name My Spot Color; spot.color red; // 基色定义 var spotColor new SpotColor(); spotColor.spot spot; spotColor.tint 100; item.fillColor spotColor;3.3 色空间匹配提醒文档色空间必须与颜色对象匹配RGB 文档用RGBColorCMYK 文档用CMYKColor否则会出现色偏或异常。可用doc.documentColorSpace检查文档色空间DocumentColorSpace.RGB/.CMYK即对应枚举。此外按名称取色板用doc.swatches.getByName(PANTONE 185 C)后直接赋swatch.color——注意getByName()找不到时会抛异常需包在try/catch中。四、常用脚本常量速查12 类枚举一次掌握枚举常量是脚本与 Illustrator 内部状态之间的桥梁。快速参考文档按功能分类列出以下逐类给出完整枚举值与用途4.1 文档与颜色DocumentColorSpace.RGB/.CMYK— 文档/新建文档色空间配合DocumentPreset.colorMode使用。4.2 文本Text对齐方式Justification.LEFT/.CENTER/.RIGHT/.FULLJUSTIFY/.FULLJUSTIFYLASTLINELEFT/.FULLJUSTIFYLASTLINECENTER/.FULLJUSTIFYLASTLINERIGHT文本类型TextType.POINTTEXT点文本/.AREATEXT区域文本/.PATHTEXT路径文本基线选项FontBaselineOption.NORMALBASELINE/.SUPERSCRIPT上标/.SUBSCRIPT下标对应应用示例字符与段落格式化var textRange tf.textRange; var charAttr textRange.characterAttributes; charAttr.size 24; // 字号单位 pt charAttr.textFont app.textFonts.getByName(ArialMT); charAttr.fillColor red; charAttr.tracking 50; // 字距em 单位 charAttr.horizontalScale 100; charAttr.verticalScale 100; charAttr.baselineShift 0; var paraAttr textRange.paragraphAttributes; paraAttr.justification Justification.CENTER; paraAttr.firstLineIndent 0; paraAttr.leftIndent 0; paraAttr.spaceBefore 0; paraAttr.spaceAfter 0;4.3 路径Paths锚点类型PointType.SMOOTH平滑点/.CORNER角点端点帽StrokeCap.BUTTENDCAP平端/.ROUNDENDCAP圆端/.PROJECTINGENDCAP投影端连接方式StrokeJoin.MITERENDJOIN斜接/.ROUNDENDJOIN圆角/.BEVELENDJOIN斜面锚点类型在自由路径绘制中与方向线配合使用var point1 path.pathPoints.add(); point1.anchor [100, 100]; point1.leftDirection [100, 100]; point1.rightDirection [150, 150]; point1.pointType PointType.SMOOTH; // 平滑点两侧方向线联动4.4 变换TransformationsTransformation枚举用于指定旋转、缩放等变换的基准点Transformation.DOCUMENTORIGIN/.BOTTOM/.BOTTOMLEFT/.BOTTOMRIGHT/.CENTER/.LEFT/.RIGHT/.TOP/.TOPLEFT/.TOPRIGHT典型用法是作为rotate()/resize()的可选scaleAbout参数。注意默认基准是Transformation.CENTERitem.resize(sx, sy)会围绕项目中心缩放若发现图稿意外重新居中请显式传入基准点或用translate(dx, dy)修正。4.5 混合模式Blend ModesBlendModes枚举覆盖 Photoshop 风格的全部混合模式BlendModes.NORMAL/.MULTIPLY/.SCREEN/.OVERLAY/.SOFTLIGHT/.HARDLIGHT/.COLORDODGE/.COLORBURN/.DARKEN/.LIGHTEN/.DIFFERENCE/.EXCLUSION/.HUE/.SATURATIONBLEND/.COLORBLEND/.LUMINOSITY4.6 元素放置Element PlacementElementPlacement用于item.move()指定目标位置ElementPlacement.PLACEATBEGINNING/.PLACEATEND/.PLACEBEFORE/.PLACEAFTER/.INSIDE例如把项目移动到图层顶部item.move(newLayer, ElementPlacement.PLACEATBEGINNING);4.7 Z 序Z-OrderZOrderMethod控制图层/项目的叠放顺序ZOrderMethod.BRINGTOFRONT置顶/.SENDTOBACK置底/.BRINGFORWARD前移一层/.SENDBACKWARD后移一层对应调用newLayer.zOrder(ZOrderMethod.SENDTOBACK);4.8 保存与导出Save / Export保存选项SaveOptions.SAVECHANGES/.DONOTSAVECHANGES/.PROMPTTOSAVECHANGES— 用于doc.close()等需要决定是否保存的场景导出类型ExportType.PNG24/.PNG8/.JPEG/.SVG/.TIFF/.PHOTOSHOP/.AUTOCAD/.FLASH/.GIF版本兼容Compatibility.ILLUSTRATOR8至.ILLUSTRATOR24如Compatibility.ILLUSTRATOR17即 CC 版本PDF 兼容PDFCompatibility.ACROBAT4至.ACROBAT8导出组合示例PNG 与 SVG// 导出 PNG24 var pngOpts new ExportOptionsPNG24(); pngOpts.horizontalScale 300; pngOpts.verticalScale 300; pngOpts.transparency true; doc.exportFile(new File(/path/to/output.png), ExportType.PNG24, pngOpts); // 导出 SVG var svgOpts new ExportOptionsSVG(); svgOpts.fontType SVGFontType.OUTLINEFONT; doc.exportFile(new File(/path/to/output.svg), ExportType.SVG, svgOpts);4.9 渐变GradientGradientType.LINEAR线性渐变/.RADIAL径向渐变— 赋值给gradient.type。4.10 变量Variables数据驱动图形Variables Datasets用于把图稿元素绑定到数据字段实现批量内容生成VariableKind.TEXTUAL文本变量/.IMAGE图像变量/.VISIBILITY可见性变量/.GRAPH图表变量var v doc.variables.add(); v.kind VariableKind.TEXTUAL; v.name headline; doc.textFrames[0].contentVariable v; // 绑定文本框架 var ds doc.dataSets.add(); ds.name Version 1; // 数据集快照当前变量绑定 doc.dataSets[0].display(); // 切换数据集以替换内容4.11 用户交互User InteractionUserInteractionLevel.DISPLAYALERTS显示对话框/.DONTDISPLAYALERTS抑制所有对话框批量脚本必须抑制对话框且执行后恢复app.userInteractionLevel UserInteractionLevel.DONTDISPLAYALERTS; // 执行可能弹窗的操作... doc.close(SaveOptions.DONOTSAVECHANGES); app.userInteractionLevel UserInteractionLevel.DISPLAYALERTS;4.12 打印PrintPrintArtworkDesignation.ALLLAYERS全部图层/.VISIBLELAYERS可见图层/.VISIBLEPRINTABLELAYERS可见且可打印图层打印选项组合配合doc.print(opts)var opts new PrintOptions(); opts.printPreset Default; var paperOpts new PrintPaperOptions(); paperOpts.name Letter; opts.paperOptions paperOpts; var jobOpts new PrintJobOptions(); jobOpts.copies 1; jobOpts.designation PrintArtworkDesignation.VISIBLELAYERS; opts.jobOptions jobOpts; doc.print(opts);五、单位换算脚本 API 的度量体系Illustrator 脚本 API 的所有数值均以点point为基准1 英寸 72 点。快速参考文档给出的换算表如下单位换算为点Points的公式英寸Inchesinches * 72厘米Centimeterscm * 28.346毫米Millimetersmm * 2.834645派卡Picaspicas * 12Em 单位(emUnits * fontSize) / 10005.1 单位应用的补充细节字符属性中的字距tracking、kerning 与aki属性使用 em 单位千分之一 em随字号比例变化这正是上表最后一行公式的用武之地。脚本化文档的坐标系原点(0,0)位于画板左下角X 自左向右增大Y 自下向上增大——与直觉中的左上角原点相反这是新手最常见的坐标错误来源。position属性表示页面项目包围盒的左上角格式为[x, y]。每个 page item 有三种包围矩形geometricBounds不含描边宽度[left, top, right, bottom]、visibleBounds含描边宽度、controlBounds含控制/方向点。页面项目的最大宽/高为 16348 点。5.2 与示例脚本结合的换算实践仓库内置脚本 create-color-grid.jsx 中var cellSize 72;注释为 1 inch——因为72点正好等于 1 英寸这正是换算表的直接体现var columns 5, rows 4; var cellSize 72; // 1 inch 72 points var gap 10; var startX 72; var startY doc.height - 72; // 从文档高度点推算起始 y for (var row 0; row rows; row) { for (var col 0; col columns; col) { var x startX col * (cellSize gap); var y startY - row * (cellSize gap); var rect layer.pathItems.rectangle(y, x, cellSize, cellSize); // ...填充颜色 } }六、速查表落地仓库内置的三个可运行脚本实例快速参考文档是字典而 scripts 目录下的三个脚本则是例句分别覆盖了导出、文本与路径/颜色三类最常用操作且与速查表中的常量一一对应。6.1 批量导出 PNGbatch-export-png.jsx文件batch-export-png.jsx该脚本把所有打开中的文档逐个导出为 PNG24集中演示了以下速查要素#target illustrator目标指令从 ESTK 或外部工具运行时指定目标应用Folder.selectDialog(...)选择输出目录ExportOptionsPNG24选项对象 ExportType.PNG24导出类型app.userInteractionLevel的保存 → 抑制 → 恢复模式DONTDISPLAYALERTSdoc.exportFile(destFile, ExportType.PNG24, pngOpts)导出调用。var pngOpts new ExportOptionsPNG24(); pngOpts.transparency true; pngOpts.artBoardClipping true; // 按画板裁切 pngOpts.horizontalScale 100; pngOpts.verticalScale 100; doc.exportFile(destFile, ExportType.PNG24, pngOpts);6.2 全局查找替换文本find-replace-text.jsx文件find-replace-text.jsx该脚本遍历当前文档所有文本框架执行查找替换体现了文本层级中框架 → 内容的最小操作面var count 0; for (var i 0; i doc.textFrames.length; i) { var tf doc.textFrames[i]; var original tf.contents; if (original.indexOf(findStr) ! -1) { tf.contents original.split(findStr).join(replaceStr); // 整体替换 count; } } alert(Replaced text in count text frame(s).);要点直接读写tf.contents即可完成全文操作无需进入characters[]/words[]粒度如需局部格式化如仅改单词字号才需要下钻到words[]等子范围。6.3 生成颜色网格create-color-grid.jsx文件create-color-grid.jsx该脚本从零新建文档与图层用双层循环生成 5×4 的彩色矩形网格集中演示了路径集合、颜色对象与坐标换算三类速查内容var color new RGBColor(); color.red Math.round((col / (columns - 1)) * 255); // 按列插值 R color.green Math.round((row / (rows - 1)) * 255); // 按行插值 G color.blue Math.round(128 Math.random() * 127); // 随机 B rect.fillColor color; rect.stroked false;同时用app.redraw()强制刷新画面——对应故障排查中脚本运行但画面无变化的解决方案。七、从速查到生产外部调用与调试要点快速参考文档解决API 是什么而 SKILL.md 补充了脚本如何在生产环境中可靠运行的关键约束这些内容与常量、坐标、文件路径等速查项直接相关arguments[]在外部启动器下不可靠经 ESTK-run或BridgeTalk.send()启动时顶层arguments[]往往只含[object BridgeTalk]无法接收调用方参数。不要依赖arguments[]传递必填输入改用边车文件sidecar file写一个已知绝对路径的文本文件脚本启动时读取或环境变量$.getenv(NAME)。$.fileName可能为空某些外部启动器尤其 ESTK-run下$.fileName为空导致相对路径解析静默失败。应从脚本依赖中剔除基于$.fileName的路径推导。必须显式保存外部调用结束后不会自动保存所有 DOM 修改后需显式调用doc.saveAs(...)或doc.save()。静默失败防御把入口包进顶层try { main(); } catch (err) { log(FATAL: err ...); }并把日志写到已知绝对路径先create()父目录可将无任何提示的失败转化为一行可检查的记录。常见错误对照undefined is not an object集合为空或索引越界先检查.lengthTarget layer cannot be modified目标图层或其祖先父编组、剪贴编组被锁定需递归清除locked/hiddenUnable to set placed items file...文件存在但格式不被PlacedItem.file接受最常见是 SVG改用打开/复制/粘贴模式Windows 路径统一用正斜杠/或双反斜杠\\或直接使用File对象构造器。结语把速查表变成你的脚本字典本文以 对象模型快速参考 为骨架完整覆盖了 Illustrator DOM 的包含层级、12 类 pageItems、8 种颜色对象、12 组常用枚举常量与单位换算表并结合 SKILL.md 的源码级细节与 scripts 目录下的三个可运行实例进行了纵深讲解。当你编写.jsx脚本时遇到该用哪个集合该选哪个枚举坐标为什么反了这类问题回到本文对应的表格即可快速定位答案。【免费下载链接】awesome-copilotCommunity-contributed instructions, agents, skills, and configurations to help you make the most of GitHub Copilot.项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-copilot创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考