脚本

PixPin 脚本用 JavaScript 调用截图、贴图和窗口操作。你可以把重复步骤保存成一个动作，再用快捷键、托盘菜单或命令行触发。「脚本」是手册中的说明章节，软件内的编辑入口在「配置 → 快捷键/动作」。

哪些事情适合用脚本Copy Anchor Link

如果只想换一个快捷键、调整托盘入口或避开某个程序，直接使用快捷键/动作设置即可。脚本适合需要组合操作或指定参数的情况。

创建并运行第一个脚本Copy Anchor Link

pixpin.screenShot(ShotAction.Pin);

测试会真正执行脚本。选择另一项预设会覆盖编辑框内容，取消窗口也不会撤回已经测试执行的操作。系统内置动作的脚本不能修改；需要变体时，另建一个自定义动作。

从命令行执行Copy Anchor Link

-r 后面放脚本文本，-f 后面放脚本文件路径。PixPin 已经运行时，请求会交给现有实例；首次启动时会等待初始化完成再执行。

Windows PowerShell，将程序路径换成实际安装位置：

& 'D:/Apps/PixPin/PixPin.exe' -r 'pixpin.screenShot(ShotAction.Copy);'
& 'D:/Apps/PixPin/PixPin.exe' -f 'D:/Scripts/capture.js'

macOS 终端，以下假设应用安装在「应用程序」目录：

"/Applications/PixPin.app/Contents/MacOS/PixPin" -r 'pixpin.screenShot(ShotAction.Copy);'
"/Applications/PixPin.app/Contents/MacOS/PixPin" -f '/Users/yourname/Scripts/capture.js'

文件里只写 JavaScript，不写代码块标记；含中文时建议保存为带 BOM 的 UTF-8 文本。较长脚本优先使用 -f，可以减少终端引号、反斜杠和 $ 的转义问题。路径含空格时保留外层引号。

命令行返回不代表截图、识别或保存已经完成；这个入口也不会把脚本最后一行的值作为结构化结果返回给调用方。macOS 自动化调用不会为交互截图主动弹出权限引导，请先在软件内完成屏幕录制和辅助功能授权。

支持的语法与运行方式Copy Anchor Link

脚本区接受 JavaScript。接口名和常量名区分大小写，例如必须写 pixpin.screenShot，不能改成 pixpin.screenshot。

当前版本的脚本环境不支持可选链 ?. 和 async/await，也不能在普通脚本中使用 import / export。需要判空时用 if，需要分步骤操作时使用 PixPin 提供的接口。

环境没有浏览器的 window、document、fetch，也没有 Node.js 的 require、process 和 fs；没有提供 setTimeout。不要直接粘贴依赖网页、Node.js 或第三方包的示例。这里的“对象支持”也不表示一个普通对象能代替接口要求的矩形。

顺序执行，不等待手动操作Copy Anchor Link

JavaScript 语句按顺序执行，但打开截图窗口的调用只负责启动操作，不等待你完成框选。因此，想“截图后贴图”，直接写 pixpin.screenShot(ShotAction.Pin)；不要把开始截图、读取剪贴板贴图简单写成前后两行。

脚本引擎会复用，尽量把临时变量放进函数中，避免多次运行相互影响。本文的多行示例使用立即执行的函数：

(function () {
  var width = 640;
  var height = 480;
  var rect = pixpin.genRectUnderCursor(width, height);
  pixpin.directScreenShot(rect, ShotAction.Copy);
})();

函数最后的 () 表示立即执行。不要用无限循环等待截图结束；这会占住界面执行线程。console.log(...) 可用于日志输出，但编辑窗口没有交互式控制台。

全局对象、参数与返回值Copy Anchor Link

普通数值、布尔值和字符串直接填写；文件列表用字符串数组。文件名建议使用绝对路径；JavaScript 路径字符串可写 D:/Images/example.png，若使用反斜杠则写 D:\\Images\\example.png。

矩形请通过以下三个接口生成，并原样传给后续接口：

坐标与尺寸按屏幕逻辑坐标理解，宽、高应为正数；多屏布局下坐标可以为负。鼠标附近空间不足时，genRectUnderCursor 会按比例缩小区域以适应屏幕。导出图像的像素尺寸还受显示缩放和保存设置影响。不要把 {x: 100, y: 100, width: 640, height: 480} 直接传入需要矩形的接口，它不会按这些字段生成截图区域。

接口返回 true 通常表示请求被接受，不表示用户已经完成交互；不同接口的返回语义见后面的表格。没有返回值的接口不能用于判断保存是否成功。

可以直接改用的示例Copy Anchor Link

截取活动窗口并复制Copy Anchor Link

先把要截取的程序切到前台，再用全局快捷键触发此动作。它立即取图，不出现手动框选流程。

pixpin.directScreenShotSpRect(
  PixConst.SpRectActiveWindow,
  ShotAction.Copy
);

在编辑窗口点击「测试脚本」时，活动窗口可能正是配置窗口；判断效果时，应应用动作后从目标程序触发。

固定选区，再手动微调Copy Anchor Link

先开始普通截图，再把选区设为屏幕坐标 (100, 100)、大小 640 × 480。你仍可在工具栏标注或调整选区。

(function () {
  if (pixpin.screenShotAndEdit()) {
    pixpin.setScreenShotRect(100, 100, 640, 480);
    pixpin.setScreenShotRectRadius(4 / 3);
  }
})();

setScreenShotRectRadius 的名字容易误解：这里设置的是宽高比，不是圆角半径。无需固定比例时，删除最后一行。

直接截图，按时间命名保存Copy Anchor Link

此例直接截取鼠标所在屏幕。运行前把路径换成自己的保存目录；macOS 可使用 /Users/yourname/Pictures/... 形式的路径。

(function () {
  var rect = pixpin.getSpRect(PixConst.SpRectScreenUnderMouse);
  pixpin.directScreenShotAndSaveTo(
    rect,
    "D:/Captures/PixPin_$yyyy-MM-dd_HH-mm-ss$.png"
  );
})();

时间占位符由保存功能展开，写法见路径与文件名变量。该接口遇到同名文件会自动添加数字后缀，且不显示保存通知；它没有返回保存路径或成功标志。

一次贴出多个参考文件Copy Anchor Link

把数组里的路径替换成已存在的文件。可以按相同格式继续添加条目。

(function () {
  var files = [
    "D:/Reference/layout.png",
    "D:/Reference/colors.png"
  ];
  if (!pixpin.pinFromFiles(files)) {
    throw new Error("没有找到可贴出的文件，请检查路径。");
  }
})();

接口会跳过不存在的文件；空数组或所有路径都不存在时返回 false。返回 true 表示已有文件交给贴图功能处理，不保证每一种文件格式都能显示为图片。

延时三秒，再开始截图Copy Anchor Link

有倒计时提示、可取消的写法最简洁：

pixpin.delayScreenShotWithTips(3);

需要指定位置和尺寸时，使用下面的接口。参数从左到右是：秒数、是否指定位置、横坐标、纵坐标、是否指定尺寸、宽、高、保留参数、宽高比。

pixpin.delayScreenShot(3, true, 100, 100, true, 640, 480, 0, 4 / 3);

用同一个动作切换状态Copy Anchor Link

下面把当前禁用状态取反：启用时暂停其他全局快捷键，再按一次恢复。

pixpin.disableShortcuts(!pixpin.isDisableShortcuts());

该动作的按键可用于解除这种主动禁用；它仍受忽略程序名单和 Windows 全屏游戏状态限制。

自定义接口速查Copy Anchor Link

以下列出可用于普通动作脚本的用户操作接口。表中的 rect 必须来自区域生成接口，action 使用 ShotAction，方括号表示可省略的参数，实际代码不写方括号。

截图与区域Copy Anchor Link

本表省略重复的 pixpin. 前缀；例如实际调用应写 pixpin.screenShotAndCopy()。直接截图不会因传入 Edit、ImageEdit、LongShot 或 GifShot 而进入对应编辑或录制界面；需要这些交互流程时使用 screenShot(action) 或下面的专用接口。

延时、长截图与录屏Copy Anchor Link

delayScreenShot 的 hasPos 与 hasSize 都为 true 时使用指定矩形；只有 hasSize 为 true 时按鼠标位置生成指定大小；未指定尺寸时保留手动框选。radius 当前未参与处理，填 0；ratio 为正数时设置宽高比，不需要时填 -1。

这些接口负责打开或控制相关窗口，不表示自动滚动已经完成、视频已经导出。长截图和录屏的后续操作仍按各自界面执行。

贴图与批量管理Copy Anchor Link

系统命令与其他操作Copy Anchor Link

runSystem 和 runSystemSync 直接启动程序，不自动经过终端解释器。管道、重定向和 shell 内置命令不会自动生效；有这类需求时，显式指定对应平台的解释器。命令字符串不能为空。

例如启动计算器，Windows 可用 pixpin.runSystem("calc")；macOS 可用 pixpin.runSystem("/usr/bin/open -a Calculator")。下面演示如何读取同步命令结果，命令请换成当前系统中实际存在的程序：

(function () {
  var result = pixpin.runSystemSync("cmd /c ver"); // Windows 示例
  console.log(result.code, result.output, result.error);
})();

同步等待会暂时占用 PixPin 界面；当前实现使用约 30 秒的默认等待上限，没有单独返回“超时”字段，也不能仅凭 code 判断进程是否正常启动。需要立即返回时使用 runSystem。

区域与动作常量Copy Anchor Link

PixConst：要截哪里Copy Anchor Link

区域取决于执行时的窗口、鼠标和历史状态。没有有效窗口或历史时，不要假定仍能获得可用区域。

ShotAction：选区之后做什么Copy Anchor Link

以下写法都带 ShotAction. 前缀，例如 ShotAction.QuickSave。

常量只是选择已有功能，不改变它的运行条件；复制、保存、识别仍可能受现有设置或交互窗口影响。

出错时从哪里检查Copy Anchor Link

脚本错误可以用 try / catch 捕获，但返回 false 与“没有返回值”都不是自动抛出的异常。调试时先运行一项操作，再逐步加上参数和组合步骤；不要把“没有报错”当成每个结果都已完成。

相关文章Copy Anchor Link