腳本

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