Photoshop脚本 文档操作

Document 对象代表一个打开的 PSD 文件。通过它可以访问画布、图层、通道等资源。ExtendScript 中所有文档操作通过全局 app 对象完成。

获取文档对象

当前活动文档

javascript 
var doc = app.activeDocument;

activeDocument 返回当前最上层的文档。如果没有文档打开，会报错，建议先判断：

javascript 
if (app.documents.length > 0) {
  var doc = app.activeDocument;
}

按索引或名称获取

javascript 
var firstDoc = app.documents[0];
var byName = app.documents["设计稿.psd"];
var count = app.documents.length; // 打开的文档数量

名称需包含扩展名（.psd、.psb、.tif 等）。

创建文档

使用 app.documents.add() 创建新文档，参数均为可选：

javascript 
var doc = app.documents.add(
  UnitValue("1920 px"),  // width
  UnitValue("1080 px"),  // height
  72,                    // resolution (ppi)
  "新文档",              // name
  NewDocumentMode.RGB,   // mode
  DocumentFill.WHITE     // initialFill
);

initialFill 可选：DocumentFill.WHITE、DocumentFill.BACKGROUNDCOLOR、DocumentFill.TRANSPARENT。

文档属性

属性类型说明
doc.namestring文件名（含扩展名）
doc.fullNameFile完整路径的 File 对象
doc.pathstring所在文件夹路径
doc.widthUnitValue宽度
doc.heightUnitValue高度
doc.resolutionnumber分辨率（ppi）
doc.modeDocumentMode颜色模式
doc.bitsPerChannelBitsPerChannelType位深度
doc.savedboolean是否已保存
doc.activeLayerArtLayer / LayerSet当前选中图层
doc.artLayersArtLayers图层集合（不含组）
doc.layerSetsLayerSets图层组集合
doc.layersLayers全部图层和组的合集
javascript 
var doc = app.activeDocument;
alert(doc.name + " — " + doc.width.as("px") + "\u00D7" + doc.height.as("px") + " @ " + doc.resolution + "ppi");

文档方法

ExtendScript 所有方法是同步的，无需 await。

调整图像大小

javascript 
doc.resizeImage(
  UnitValue("800 px"),
  UnitValue("600 px"),
  72,
  ResampleMethod.BICUBIC
);

ResampleMethod 可选：BICUBIC（默认）、NEARESTNEIGHBOR、BILINEAR、BICUBICSMOOTHER（放大）、BICUBICSHARPER（缩小）。

调整画布大小

javascript 
doc.resizeCanvas(
  UnitValue("1000 px"),
  UnitValue("800 px"),
  AnchorPosition.MIDDLECENTER
);

AnchorPosition 决定画布扩展方向：TOPLEFT、TOPCENTER、TOPRIGHT、MIDDLELEFT、MIDDLECENTER、MIDDLERIGHT、BOTTOMLEFT、BOTTOMCENTER、BOTTOMRIGHT。

裁剪

javascript 
var bounds = [
  UnitValue("100 px"),
  UnitValue("100 px"),
  UnitValue("500 px"),
  UnitValue("500 px")
];
doc.crop(bounds, 45, UnitValue("400 px"), UnitValue("400 px"));

参数依次为：边界 [left, top, right, bottom]、旋转角度、裁剪后宽度、裁剪后高度。

拼合与合并

javascript 
doc.flatten();            // 拼合所有图层
doc.mergeVisibleLayers(); // 仅合并可见图层
doc.rasterizeAllLayers(); // 栅格化所有矢量/文字图层

转换颜色模式

javascript 
doc.changeMode(ChangeMode.RGB);
doc.changeMode(ChangeMode.CMYK);
doc.changeMode(ChangeMode.GRAYSCALE);

转换色彩配置文件

javascript 
doc.convertProfile(
  "sRGB IEC61966-2.1",
  Intent.RELATIVECOLORIMETRIC,
  true,  // 黑场补偿
  true   // 仿色
);

Intent 可选：PERCEPTUAL、SATURATION、RELATIVECOLORIMETRIC、ABSOLUTECOLORIMETRIC。

关闭与保存

javascript 
doc.close(SaveOptions.DONOTSAVECHANGES);  // 不保存关闭
doc.close(SaveOptions.SAVECHANGES);        // 保存后关闭
doc.close(SaveOptions.PROMPTTOSAVECHANGES); // 提示是否保存

保存为指定格式需要使用 saveAs：

javascript 
var file = new File("C:/output/result.jpg");
var jpegOpt = new JPEGSaveOptions();
jpegOpt.quality = 10; // 1-12（Photoshop 中 0-12，12 最高质量）
jpegOpt.embedColorProfile = true;
jpegOpt.formatOptions = FormatOptions.STANDARDBASELINE;
doc.saveAs(file, jpegOpt, true, Extension.LOWERCASE);

其他保存选项：

javascript 
// PSD
var psdOpt = new PhotoshopSaveOptions();
psdOpt.alphaChannels = true;
psdOpt.layers = true;
psdOpt.spotColors = true;

// PNG
var pngOpt = new PNGSaveOptions();
pngOpt.compression = 6;
pngOpt.interlaced = false;

如果不需要自定义选项，可以直接传递类引用（new 和默认值本身）：

javascript 
doc.saveAs(file, JPEGSaveOptions, true, Extension.LOWERCASE);
// 等价于 new JPEGSaveOptions() 不加任何属性设置

包裹到单一历史步骤

javascript 
doc.suspendHistory("调整大小并转换模式", "executeAction(stringIDToTypeID('resizeImage'), ...)");

实际上更常用的方法是直接用字符串执行代码：

javascript 
doc.suspendHistory("批量处理", "var doc = app.activeDocument; doc.resizeImage(UnitValue('800 px'), UnitValue('600 px'), 72, ResampleMethod.BICUBIC); doc.changeMode(ChangeMode.RGB);");

其他常用方法

javascript 
doc.rotateCanvas(90.0);              // 旋转画布
doc.flipCanvas(Direction.HORIZONTAL); // 水平翻转
doc.trim(TrimType.TRANSPARENT, true, true, true, true); // 裁掉透明边缘
doc.revealAll();                     // 显示全部
doc.paste();                         // 粘贴剪贴板内容

综合示例

打开活动文档、调整大小、转 sRGB、保存为 JPEG：

javascript 
if (app.documents.length === 0) {
  alert("请先打开一个文档");
} else {
  var doc = app.activeDocument;
  var origName = doc.name;
  var jpegFile = new File(doc.path + "/" + origName.replace(/\.psd$/i, ".jpg"));

  // 缩小到宽 1920px（等比例）
  var scale = 1920 / doc.width.as("px");
  var newH = Math.round(doc.height.as("px") * scale);
  doc.resizeImage(UnitValue("1920 px"), UnitValue(newH + " px"), 72, ResampleMethod.BICUBICSHARPER);

  // 转 sRGB
  doc.convertProfile("sRGB IEC61966-2.1", Intent.RELATIVECOLORIMETRIC, true, true);

  // 另存为 JPEG
  var opts = new JPEGSaveOptions();
  opts.quality = 12;
  opts.embedColorProfile = true;
  doc.saveAs(jpegFile, opts, true, Extension.LOWERCASE);

  alert("处理完成: " + jpegFile.name);
}

小结

  • app.activeDocument 获取当前文档，app.documents 索引或名称访问
  • app.documents.add() 创建新文档，参数使用 UnitValue 指定尺寸
  • 所有方法均为同步调用
  • resizeImage、resizeCanvas、crop 控制画布尺寸
  • flatten、mergeVisibleLayers 管理图层合并
  • changeMode、convertProfile 管理颜色配置
  • saveAs + JPEGSaveOptions / PNGSaveOptions / PhotoshopSaveOptions 保存导出
  • suspendHistory 将多个操作归为一个历史步骤