有界 QuickJS 執行環境

HPDFQuickJS 與 HPDFQuickJSStatic 在 Win32 與 Win64 上公開同一套由應用程式掌控的 JavaScript 求值 API

選擇部署模式

• HPDFQuickJS 載入 ABI 中立的 quickjs.dll 橋接層，QuickJS 值留在 C 程式碼內
• HPDFQuickJSStatic 把平台專屬的 OMF 目標檔連結進應用程式，不需要執行期 DLL
• 不要在同一個程式裡同時使用兩個單元，因為它們發布相同的公開型別名稱

DLL 繫結接受明確路徑、HOTPDF_QUICKJS_DLL 環境變數值，或從執行檔上層目錄中找到的平台目錄

預設建置把橋接層放在 Lib\thirdparty\QuickJS\bin\Win32\quickjs.dll 或 Lib\thirdparty\QuickJS\bin\Win64\quickjs.dll

在 Linux x86-64 上，HPDFQuickJS 會載入由 tools/Build-HotPDFQuickJSLinux.sh 建置的原生 libhpdfquickjs.so 橋接層；明確路徑與環境變數沿用相同的所有權與 ABI 規則

Linux 預設探找會檢查執行檔目錄與 Lib/thirdparty/QuickJS/bin/Linux64；原生靜態 OMF 部署仍是 Windows 專屬

求值腳本

uses
  HPDFQuickJS;

var
  Engine: THPDFQuickJS;
  EvalResult: THPDFQuickJSResult;
begin
  Engine := THPDFQuickJS.Create;
  try
    if not Engine.Available then
      raise Exception.Create(Engine.LoadError);
    EvalResult := Engine.Eval('JSON.stringify([1, 2, 3].map(x => x * 2))');
    if not EvalResult.Success then
      raise Exception.Create(EvalResult.Error);
  finally
    Engine.Free;
  end;
end;

Eval 把最終的 JavaScript 值轉成 UTF-8 文字，回傳 Delphi 字串時保留 Unicode

EvalInt 與 EvalFloat 提供嚴格的數值轉換，不會讓引擎值跨越 ABI 邊界

執行限制

Limits := THPDFQuickJSLimits.CreateDefault;
Limits.MemoryBytes := 32 * 1024 * 1024;
Limits.StackBytes := 64 * 1024;
Limits.MaxScriptBytes := 256 * 1024;
Limits.TimeoutMs := 250;
Limits.MaxInterruptChecks := 250000;
Engine := THPDFQuickJS.Create(Limits);

預設允許 64 MiB 引擎記憶體、64 KiB 堆疊、1 MiB UTF-8 腳本、一秒牆鐘時間與一百萬次中斷檢查

Win32 靜態執行環境把不小於零的堆疊預算請求封頂在 48 KiB，以留在編譯器安全的遞迴邊界內；DLL 與 Win64 模式則直接採用請求值

記憶體與堆疊限制對整個執行環境生效，腳本、時間與中斷限制則按每次求值套用

狀態與復原

• qjsSuccess 表示已轉換的結果
• qjsScriptError 表示語法錯誤、被丟出的值與轉換失敗
• qjsTimeLimit 與 qjsInterruptLimit 區分兩種執行預算
• qjsBusy、qjsInvalidArgument、qjsResourceError 與 qjsUnavailable 保留基礎設施失敗

被拒絕或中斷的求值會清掉未決例外與緩衝區，同一引擎執行個體之後仍可執行有效的腳本

單一引擎執行個體不可重入；每個並行工作者各用一個執行個體

XFA 表單腳本

XFA 攤平引擎只有在明確設定 THotPDF.XFAJavaScriptEnabled 時才重用此執行環境；它提供受限的資料外觀、原生帶型別陣列、經驗證的執行個體請求，且沒有檔案、程序、瀏覽器或網路物件

TXFAFormScriptOptions.JavaScriptEvaluator 可轉接靜態執行環境，不必把靜態 QuickJS 物件塞進每個 HotPDF 應用程式

參見 有界 XFA FormCalc 與 JavaScript

可重現的執行環境建置

powershell -ExecutionPolicy Bypass -File Lib\thirdparty\build-quickjs-runtime.ps1

建置指令碼從隨附原始碼產出兩組靜態目標檔與兩個橋接 DLL，接著執行環境矩陣為 Win32 與 Win64 編譯並演練靜態與 DLL 探測