TypeScript/JavaScript API 參考文件 @microsoft/winappcli。
每個 CLI 指令都以非同步函式形式提供，捕捉 stdout/stderr 並回傳一個型別化的結果。
MSIX 身份、Electron 除錯身份及建置工具的輔助工具也會匯出。
安裝
npm install @microsoft/winappcli
快速入門
import { init, packageApp, certGenerate } from '@microsoft/winappcli';
// Initialize a new project with defaults
await init({ useDefaults: true });
// Generate a dev certificate
await certGenerate({ install: true });
// Package the built app
await packageApp({ inputFolder: './dist', cert: './devcert.pfx' });
常見的類型
每個 CLI 指令包裝器都接受延伸 CommonOptions 的 options 物件，並回傳 Promise<WinappResult>。
CommonOptions
大多數指揮部共用的基礎選項。
| 房產 | 類型 | 為必填項目 | Description |
|---|---|---|---|
quiet |
boolean \| undefined |
No | 抑制進度訊息。 |
verbose |
boolean \| undefined |
No | 啟用冗長輸出。 |
cwd |
string \| undefined |
No | CLI 程序的工作目錄（預設為 process.cwd（））。 |
WinappResult
由每個命令封裝器回傳的結果。
| 房產 | 類型 | 為必填項目 | Description |
|---|---|---|---|
exitCode |
number |
Yes | 程序退出代碼（成功時總是 0，擲出非零）。 |
stdout |
string |
Yes | 擷取標準輸出。 |
stderr |
string |
Yes | 捕捉標準錯誤。 |
CLI 指令包裝器
這些函式會包裝原生 winapp 的 CLI 指令。 所有選項都接受 CommonOptions （quiet， verbose， cwd）。
certGenerate()
建立一個自簽憑證，僅供本地測試使用。 Publisher 必須與清單相符（如果 --manifest 提供或 Package.appxmanifest 在工作目錄中，則自動推斷）。 輸出：devcert.pfx（預設密碼：「password」）。 生產時，請從受信任的 CA 取得憑證。 用「cert install」來信任這台機器。
function certGenerate(options?: CertGenerateOptions): Promise<WinappResult>
選項：
| 房產 | 類型 | 為必填項目 | Description |
|---|---|---|---|
exportCer |
boolean \| undefined |
No | 匯出.pfx的同時，附帶一個.cer檔案（僅限公鑰） |
ifExists |
IfExists \| undefined |
No | 當輸出檔存在時的行為：'error'（失敗，預設）、'skip'（保持存在）或「覆寫」（替換） |
install |
boolean \| undefined |
No | 生成之後將憑證安裝到本地機器儲存 |
json |
boolean \| undefined |
No | 格式輸出為 JSON |
manifest |
string \| undefined |
No | 前往 Package.appxmanifest 或 appxmanifest.xml 檔案的路徑，以提取發行者資訊。 |
output |
string \| undefined |
No | 產生的 PFX 檔案輸出路徑 |
password |
string \| undefined |
No | 產生的 PFX 檔案密碼 |
publisher |
string \| undefined |
No | 產生憑證的 Publisher 名稱。 若未特別說明，則會從清單檔案推斷。 |
validDays |
number \| undefined |
No | 證書有效天數 |
同時接受 CommonOptions （quiet， verbose， cwd）。
certInfo()
顯示證書細節（主題、指紋、有效期限）。 這對於在簽署前確認證明是否符合你的清單很有幫助。
function certInfo(options: CertInfoOptions): Promise<WinappResult>
選項：
| 房產 | 類型 | 為必填項目 | Description |
|---|---|---|---|
certPath |
string |
Yes | 憑證檔案路徑（PFX） |
json |
boolean \| undefined |
No | 格式輸出為 JSON |
password |
string \| undefined |
No | PFX 檔案的密碼 |
同時接受 CommonOptions （quiet， verbose， cwd）。
certInstall()
信任這台機器上的憑證（需要管理員管理）。 在安裝以開發憑證簽署的 MSIX 套件前執行。 範例：winapp cert install ./devcert.pfx。 每張證書僅需一次。
function certInstall(options: CertInstallOptions): Promise<WinappResult>
選項：
| 房產 | 類型 | 為必填項目 | Description |
|---|---|---|---|
certPath |
string |
Yes | 憑證檔案（PFX 或 CER）的路徑 |
force |
boolean \| undefined |
No | 即使憑證已存在，也要強制安裝 |
password |
string \| undefined |
No | PFX 檔案的密碼 |
同時接受 CommonOptions （quiet， verbose， cwd）。
createDebugIdentity()
啟用套件識別碼以便除錯，無需建立完整 MSIX。 在開發過程中測試 Windows API（推播通知、共享目標等）所必需的。 範例：winapp create-debug-identity ./myapp.exe。 需要目前目錄中包含 Package.appxmanifest 或 appxmanifest.xml，或是透過 --manifest 傳遞。 在更改清單或資產後重新執行。
function createDebugIdentity(options?: CreateDebugIdentityOptions): Promise<WinappResult>
選項：
| 房產 | 類型 | 為必填項目 | Description |
|---|---|---|---|
entrypoint |
string \| undefined |
No | 需要以身份碼或入口腳本執行的 .exe 路徑。 |
keepIdentity |
boolean \| undefined |
No | 請保持清單中的套件身份不變，並且不要在套件名稱和應用程式 ID 後加上「.debug」。 |
manifest |
string \| undefined |
No | 到 Package.appxmanifest 或 appxmanifest.xml 的路徑 |
noInstall |
boolean \| undefined |
No | 建立套件後不要安裝。 |
同時接受 CommonOptions （quiet， verbose， cwd）。
createExternalCatalog()
產生一個 CodeIntegrityExternal.cat 目錄檔案，包含指定目錄中可執行檔案的雜湊值。 與 MSIX 稀疏套件清單中的 TrustedLaunch 旗標（AllowExternalContent）一起使用，允許執行套件中未包含的外部檔案。
function createExternalCatalog(options: CreateExternalCatalogOptions): Promise<WinappResult>
選項：
| 房產 | 類型 | 為必填項目 | Description |
|---|---|---|---|
inputFolder |
string |
Yes | 包含可執行檔案進行處理的輸入資料夾清單（以分號分隔） |
computeFlatHashes |
boolean \| undefined |
No | 產生目錄時包含平面哈希值 |
ifExists |
IfExists \| undefined |
No | 輸出檔已存在時的行為 |
output |
string \| undefined |
No | 輸出目錄文件路徑。 若未指定，則使用預設 CodeIntegrityExternal.cat 名稱。 |
recursive |
boolean \| undefined |
No | 包含來自子目錄中的檔案 |
usePageHashes |
boolean \| undefined |
No | 產生目錄時請包含頁面雜湊值 |
同時接受 CommonOptions （quiet， verbose， cwd）。
getWinappPath()
列印 .winapp 目錄的路徑。 共用快取位置使用 --global，或在 project-local .winapp 資料夾中省略。 對於需要參考已安裝套件的建置腳本非常有用。
function getWinappPath(options?: GetWinappPathOptions): Promise<WinappResult>
選項：
| 房產 | 類型 | 為必填項目 | Description |
|---|---|---|---|
global |
boolean \| undefined |
No | 取得全域的 .winapp 目錄，而不是本地 |
同時接受 CommonOptions （quiet， verbose， cwd）。
init()
從這裡開始，如何初始化需要設定的 Windows 應用程式。 設定 Windows 應用程式開發所需的一切：建立 Package.appxmanifest 預設資產、下載 Windows SDK 和 Windows 應用程式 SDK 套件，並產生投影。 當 SDK 套件被管理（--setup-sdks stable/preview/experimental）時，也會建立 winapp.yaml 來釘選版本以「還原」/「更新」;如果 --setup-sdks 為 none（例如帶自家 SDK 綁定的 Rust/Tauri 專案），則不會產生 winapp.yaml。 預設為互動式（使用 --use-default 跳過提示）。 如果你複製了一個已經有 winapp.yaml 的倉庫，請改用「還原」。 如果你只需要 manifest，可以用 'manifest generate';如果需要開發憑證來簽字，就用「cert generate」。
function init(options?: InitOptions): Promise<WinappResult>
選項：
| 房產 | 類型 | 為必填項目 | Description |
|---|---|---|---|
baseDirectory |
string \| undefined |
No | Winapp 工作區的基礎/根目錄，供使用者或安裝使用。 |
configDir |
string \| undefined |
No | 目錄用以讀取/儲存設定（預設：目前目錄） |
configOnly |
boolean \| undefined |
No | 只處理設定檔操作（缺少設定檔則建立，存在則驗證）。 跳過套件安裝和其他工作區設定步驟。 |
ignoreConfig |
boolean \| undefined |
No | 不要用設定檔來管理版本 |
noGitignore |
boolean \| undefined |
No | 不要更新 .gitignore 檔案 |
setupSdks |
SdkInstallMode \| undefined |
No | SDK 安裝模式：「stable」（預設）、 「preview」、「experimental」或「none」（跳過 SDK 安裝） |
useDefaults |
boolean \| undefined |
No | 不要顯示任何提示，並對所有提示使用預設設定 |
同時接受 CommonOptions （quiet， verbose， cwd）。
manifestAddAlias()
在 Package.appxmanifest 中新增執行別名（uap5：AppExecutionAlias）。 這讓使用者能透過輸入別名名稱，從命令列啟動已封裝的應用程式。 預設情況下，別名是從可執行檔屬性推斷（例如 $targetnametoken$.exe 變成 $targetnametoken$.exe 別名）。
function manifestAddAlias(options?: ManifestAddAliasOptions): Promise<WinappResult>
選項：
| 房產 | 類型 | 為必填項目 | Description |
|---|---|---|---|
appId |
string \| undefined |
No | 用來新增別名的應用程式 ID（預設：第一個應用程式元素） |
manifest |
string \| undefined |
No | 路徑至 Package.appxmanifest 或 appxmanifest.xml 檔案（預設：搜尋目前目錄） |
name |
string \| undefined |
No | 別名（例如「myapp.exe」）。 預設：從清單中的可執行檔屬性推斷。 |
同時接受 CommonOptions （quiet， verbose， cwd）。
manifestGenerate()
在沒有完整專案設定的情況下建立 Package.appxmanifest。 當你只需要清單和映像資產（不需要 SDK 或憑證）時就用。 完整設定時，改用「init」。 範本：「打包」（完整 MSIX）、「稀疏」（需要 Windows API 的桌面應用程式）。
function manifestGenerate(options?: ManifestGenerateOptions): Promise<WinappResult>
選項：
| 房產 | 類型 | 為必填項目 | Description |
|---|---|---|---|
directory |
string \| undefined |
No | 目錄用來生成 manifest 文件 |
description |
string \| undefined |
No | 安裝時及 Windows 設定中顯示的人類可讀應用程式說明 |
executable |
string \| undefined |
No | 應用程式執行檔的路徑。 預設： <套件名稱>.exe |
ifExists |
IfExists \| undefined |
No | 當輸出檔存在時的行為：'error'（失敗，預設）、'skip'（保持存在）或「覆寫」（替換） |
logoPath |
string \| undefined |
No | Logo 影像檔案的路徑 |
packageName |
string \| undefined |
No | 套件名稱（預設：資料夾名稱） |
publisherName |
string \| undefined |
No | Publisher CN（預設：CN=<目前使用者>） |
template |
ManifestTemplates \| undefined |
No | 清單範本類型：「packaged」（完整 MSIX 應用程式，預設）或「sparse」（具有套件識別的桌面應用程式，用於 Windows API）。 |
version |
string \| undefined |
No | 應用程式版本為 Major.Minor.Build.Revision 格式（例如 1.0.0.0）。 |
同時接受 CommonOptions （quiet， verbose， cwd）。
manifestUpdateAssets()
從單一來源圖片為 Package.appxmanifest 中引用的圖片產生新素材。 原始影像至少要是 400x400 像素。
function manifestUpdateAssets(options: ManifestUpdateAssetsOptions): Promise<WinappResult>
選項：
| 房產 | 類型 | 為必填項目 | Description |
|---|---|---|---|
imagePath |
string |
Yes | 來源圖片檔案的路徑（SVG、PNG、ICO、JPG、BMP、GIF） |
lightImage |
string \| undefined |
No | 淺色主題變體的來源影像路徑（SVG、PNG、ICO、JPG、BMP、GIF） |
manifest |
string \| undefined |
No | 路徑至 Package.appxmanifest 或 appxmanifest.xml 檔案（預設：搜尋目前目錄） |
同時接受 CommonOptions （quiet， verbose， cwd）。
packageApp()
從你建置好的應用程式建立 MSIX 安裝程式。 在建置完你的應用程式後再執行。 包裝需要一個清單（Package.appxmanifest 或 appxmanifest.xml）。它必須位於當前工作目錄中、以 --manifest 提供，或在輸入資料夾中。 使用 --cert devcert.pfx 來簽署測試。 範例：winapp package ./dist --manifest Package.appxmanifest --cert ./devcert.pfx
function packageApp(options: PackageOptions): Promise<WinappResult>
選項：
| 房產 | 類型 | 為必填項目 | Description |
|---|---|---|---|
inputFolder |
string |
Yes | 輸入資料夾與套件配置 |
cert |
string \| undefined |
No | 簽署憑證的路徑（若提供將自動簽署） |
certPassword |
string \| undefined |
No | 憑證密碼（預設：password） |
executable |
string \| undefined |
No | 相對於輸入資料夾的執行檔路徑。 |
generateCert |
boolean \| undefined |
No | 產生新的開發證書 |
installCert |
boolean \| undefined |
No | 將憑證安裝到機器 |
manifest |
string \| undefined |
No | AppX 清單檔案的路徑（預設：自動偵測輸入資料夾或目前目錄） |
name |
string \| undefined |
No | 套件名稱（預設：來自清單） |
output |
string \| undefined |
No | 產生的套件的 msix 檔案名稱（預設為<名稱><版本><arch>.msix；如無法確定版本或架構，則依序退回至<名稱><版本>.msix、<名稱><arch>.msix 或<名稱>.msix） |
publisher |
string \| undefined |
No | 用於憑證產生的發行者名稱 |
selfContained |
boolean \| undefined |
No | 捆綁 Windows 應用程式 SDK 執行環境以實現自包含部署 |
skipPri |
boolean \| undefined |
No | 跳過 PRI 檔案產生 |
同時接受 CommonOptions （quiet， verbose， cwd）。
restore()
在複製倉庫後或 .winapp/ 資料夾不見時使用。 從現有的 winapp.yaml 重新安裝 SDK 套件，且不更改版本。 需要 'winapp.yaml'（由 'init' 建立）。 要檢查是否有更新的 SDK 版本，請改用「更新」。
function restore(options?: RestoreOptions): Promise<WinappResult>
選項：
| 房產 | 類型 | 為必填項目 | Description |
|---|---|---|---|
baseDirectory |
string \| undefined |
No | Winapp 工作區的 Base/root 目錄 |
configDir |
string \| undefined |
No | 讀取設定的目錄（預設：目前目錄） |
同時接受 CommonOptions （quiet， verbose， cwd）。
run()
建立套件版面，註冊應用程式，並啟動套件中的應用程式。
function run(options: RunOptions): Promise<WinappResult>
選項：
| 房產 | 類型 | 為必填項目 | Description |
|---|---|---|---|
inputFolder |
string |
Yes | 輸入資料夾，包含要執行的應用程式 |
args |
string \| undefined |
No | 用來傳遞給應用程式的命令列參數 |
clean |
boolean \| undefined |
No | 在重新部署前，先移除現有套件的應用程式資料（LocalState、設定等）。 預設情況下，應用程式資料會在重新部署過程中被保留。 |
debugOutput |
boolean \| undefined |
No | 擷取 OutputDebugString 訊息，並從啟動的應用程式中捕捉 first-chance 例外。 同一時間只能連接一個除錯器，因此無法同時使用其他除錯器（如 Visual Studio、VS Code）。 如果要附加不同的除錯器，請改用 --no-launch。 不能和 --no-launch 或 --json 合併使用。 |
detach |
boolean \| undefined |
No | 啟動應用程式後立即返回，不要等它退出。 對於需要在啟動後與應用程式互動的 CI/自動化來說很有用。 會把 PID 列印成標準碼（或用 --json 格式的 JSON）。 |
json |
boolean \| undefined |
No | 格式輸出為 JSON |
manifest |
string \| undefined |
No | Package.appxmanifest 的檔案路徑（預設：自動偵測自輸入資料夾或當前目錄） |
noLaunch |
boolean \| undefined |
No | 只建立除錯身份並註冊套件，無需啟動應用程式 |
outputAppxDirectory |
string \| undefined |
No | 鬆散佈局套件的輸出目錄。 若未指定，則會使用輸入資料夾目錄中名為 AppX 的目錄。 |
symbols |
boolean \| undefined |
No | 從 Microsoft Symbol Server 下載符號，以獲得更豐富的原生當機分析。 僅用於 --debug-output。 首先執行時下載符號並快取到本地;後續執行會使用快取。 |
unregisterOnExit |
boolean \| undefined |
No | 在應用程式退出後取消註冊開發套件。 只會移除在開發模式下註冊的套件。 |
withAlias |
boolean \| undefined |
No | 啟動應用程式時，請使用其執行別名，而非藉由 AUMID 進行啟用。 應用程式在目前的終端機中運行，繼承了 stdin/stdout/stderr。 需要在清單中定義 uap5：ExecutionAlias。 使用「winapp manifest add-alias」來為清單新增執行別名。 |
同時接受 CommonOptions （quiet， verbose， cwd）。
sign()
對 MSIX 套件或執行檔進行程式碼簽署。 範例：winapp sign ./app.msix ./devcert.pfx。 使用 --timestamp 表示生產建置在憑證過期後仍有效。 'package' 指令可以自動用 --cert 簽名。
function sign(options: SignOptions): Promise<WinappResult>
選項：
| 房產 | 類型 | 為必填項目 | Description |
|---|---|---|---|
filePath |
string |
Yes | 要簽署的檔案/套件路徑 |
certPath |
string |
Yes | 憑證檔案路徑（PFX 格式） |
password |
string \| undefined |
No | 憑證密碼 |
timestamp |
string \| undefined |
No | 時間戳伺服器網址 |
同時接受 CommonOptions （quiet， verbose， cwd）。
store()
執行 Microsoft Store 開發者 CLI 指令。 如果尚未下載，此指令將下載Microsoft Store開發者CLI。 想了解更多關於 Microsoft Store Developer CLI 的資訊，請點此：https://aka.ms/msstoredevcli
function store(options?: StoreOptions): Promise<WinappResult>
選項：
| 房產 | 類型 | 為必填項目 | Description |
|---|---|---|---|
storeArgs |
string[] \| undefined |
No | 這些論點將傳遞給 Microsoft Store 開發者 CLI。 |
同時接受 CommonOptions （quiet， verbose， cwd）。
tool()
直接執行 Windows SDK 工具（makeappx、signtool、makepri 等）。 必要時自動下載建構工具。 大多數任務偏好使用像「package」或「sign」這類高階指令。 範例：winapp 工具 makeappx pack /d ./folder /p ./out.msix
function tool(options?: ToolOptions): Promise<WinappResult>
選項：
| 房產 | 類型 | 為必填項目 | Description |
|---|---|---|---|
toolArgs |
string[] \| undefined |
No | 要傳遞給 SDK 工具的參數，例如 ['makeappx'， 'pack'， '/d'， './folder'， '/p'， './out.msix']。 |
同時接受 CommonOptions （quiet， verbose， cwd）。
uiClick()
透過滑鼠模擬的字條搜尋或文字搜尋來點擊元素。 適用於不支援 InvokePattern 的元素（例如欄位標頭、清單項目）。 使用 --double 代表雙擊，使用 --right 代表右擊。
function uiClick(options?: UiClickOptions): Promise<WinappResult>
選項：
| 房產 | 類型 | 為必填項目 | Description |
|---|---|---|---|
selector |
string \| undefined |
No | 語意識別符（例如 btn-minimize-d1a0）或按照名稱或 AutomationId 搜尋的文字 |
app |
string \| undefined |
No | 目標應用程式（程序名稱、視窗標題或 PID）。 如果有歧義，會列出視窗。 |
double |
boolean \| undefined |
No | 請雙擊而非單擊 |
json |
boolean \| undefined |
No | 格式輸出為 JSON |
right |
boolean \| undefined |
No | 請用右鍵點擊代替左鍵 |
window |
number \| undefined |
No | 目標視窗由 HWND 建立（穩定 handle 來自列表輸出）。 優先於 --app。 |
同時接受 CommonOptions （quiet， verbose， cwd）。
uiFocus()
使用 UIA SetFocus 將鍵盤焦點移至指定元素。
function uiFocus(options?: UiFocusOptions): Promise<WinappResult>
選項：
| 房產 | 類型 | 為必填項目 | Description |
|---|---|---|---|
selector |
string \| undefined |
No | 語意識別符（例如 btn-minimize-d1a0）或按照名稱或 AutomationId 搜尋的文字 |
app |
string \| undefined |
No | 目標應用程式（程序名稱、視窗標題或 PID）。 如果有歧義，會列出視窗。 |
json |
boolean \| undefined |
No | 格式輸出為 JSON |
window |
number \| undefined |
No | 目標視窗由 HWND 建立（穩定 handle 來自列表輸出）。 優先於 --app。 |
同時接受 CommonOptions （quiet， verbose， cwd）。
uiGetFocused()
在目標應用程式中顯示目前有鍵盤焦點的元素。
function uiGetFocused(options?: UiGetFocusedOptions): Promise<WinappResult>
選項：
| 房產 | 類型 | 為必填項目 | Description |
|---|---|---|---|
app |
string \| undefined |
No | 目標應用程式（程序名稱、視窗標題或 PID）。 如果有歧義，會列出視窗。 |
json |
boolean \| undefined |
No | 格式輸出為 JSON |
window |
number \| undefined |
No | 目標視窗由 HWND 建立（穩定 handle 來自列表輸出）。 優先於 --app。 |
同時接受 CommonOptions （quiet， verbose， cwd）。
uiGetProperty()
從元素讀取 UIA 屬性值。 若要指定單一屬性，請使用 --property；若要應用於所有屬性，則省略該選項。
function uiGetProperty(options?: UiGetPropertyOptions): Promise<WinappResult>
選項：
| 房產 | 類型 | 為必填項目 | Description |
|---|---|---|---|
selector |
string \| undefined |
No | 語意識別符（例如 btn-minimize-d1a0）或按照名稱或 AutomationId 搜尋的文字 |
app |
string \| undefined |
No | 目標應用程式（程序名稱、視窗標題或 PID）。 如果有歧義，會列出視窗。 |
json |
boolean \| undefined |
No | 格式輸出為 JSON |
property |
string \| undefined |
No | 要閱讀或篩選的屬性名稱 |
window |
number \| undefined |
No | 目標視窗由 HWND 建立（穩定 handle 來自列表輸出）。 優先於 --app。 |
同時接受 CommonOptions （quiet， verbose， cwd）。
uiGetValue()
讀取元素的當前值。 嘗試 TextPattern（RichEditBox、Document）、ValuePattern（TextBox、ComboBox、滑桿），然後是名稱（標籤）。 使用方法： winapp 使用者界面 get-value <selector> -a <app>
function uiGetValue(options?: UiGetValueOptions): Promise<WinappResult>
選項：
| 房產 | 類型 | 為必填項目 | Description |
|---|---|---|---|
selector |
string \| undefined |
No | 語意識別符（例如 btn-minimize-d1a0）或按照名稱或 AutomationId 搜尋的文字 |
app |
string \| undefined |
No | 目標應用程式（程序名稱、視窗標題或 PID）。 如果有歧義，會列出視窗。 |
json |
boolean \| undefined |
No | 格式輸出為 JSON |
window |
number \| undefined |
No | 目標視窗由 HWND 建立（穩定 handle 來自列表輸出）。 優先於 --app。 |
同時接受 CommonOptions （quiet， verbose， cwd）。
uiInspect()
查看 UI 元素樹，包含語意欄位、元素類型、名稱與界限。
function uiInspect(options?: UiInspectOptions): Promise<WinappResult>
選項：
| 房產 | 類型 | 為必填項目 | Description |
|---|---|---|---|
selector |
string \| undefined |
No | 語意識別符（例如 btn-minimize-d1a0）或按照名稱或 AutomationId 搜尋的文字 |
ancestors |
boolean \| undefined |
No | 從指定的元素向上遍歷到樹的根節點 |
app |
string \| undefined |
No | 目標應用程式（程序名稱、視窗標題或 PID）。 如果有歧義，會列出視窗。 |
depth |
number \| undefined |
No | 樹木檢查深度 |
hideDisabled |
boolean \| undefined |
No | 隱藏禁用元素使其不在輸出中顯示 |
hideOffscreen |
boolean \| undefined |
No | 將畫面外元素從輸出中隱藏 |
interactive |
boolean \| undefined |
No | 只顯示互動式/可調用的元素（按鈕、連結、輸入、清單項目）。 將預設深度增加到 8。 |
json |
boolean \| undefined |
No | 格式輸出為 JSON |
window |
number \| undefined |
No | 目標視窗由 HWND 建立（穩定 handle 來自列表輸出）。 優先於 --app。 |
同時接受 CommonOptions （quiet， verbose， cwd）。
uiInvoke()
透過 slug 或文字搜尋來啟動元素。 依序嘗試 InvokePattern、TogglePattern、SelectionItemPattern 和 ExpandCollapsePattern。
function uiInvoke(options?: UiInvokeOptions): Promise<WinappResult>
選項：
| 房產 | 類型 | 為必填項目 | Description |
|---|---|---|---|
selector |
string \| undefined |
No | 語意識別符（例如 btn-minimize-d1a0）或按照名稱或 AutomationId 搜尋的文字 |
app |
string \| undefined |
No | 目標應用程式（程序名稱、視窗標題或 PID）。 如果有歧義，會列出視窗。 |
json |
boolean \| undefined |
No | 格式輸出為 JSON |
window |
number \| undefined |
No | 目標視窗由 HWND 建立（穩定 handle 來自列表輸出）。 優先於 --app。 |
同時接受 CommonOptions （quiet， verbose， cwd）。
uiListWindows()
列出所有可見視窗及其句柄、標題、程序和大小。 請使用 -a 依應用程式名稱篩選。 用 HWND 搭配 -w 鎖定特定視窗。
function uiListWindows(options?: UiListWindowsOptions): Promise<WinappResult>
選項：
| 房產 | 類型 | 為必填項目 | Description |
|---|---|---|---|
app |
string \| undefined |
No | 目標應用程式（程序名稱、視窗標題或 PID）。 如果有歧義，會列出視窗。 |
json |
boolean \| undefined |
No | 格式輸出為 JSON |
同時接受 CommonOptions （quiet， verbose， cwd）。
uiScreenshot()
將目標視窗或元素擷取為 PNG 影像。 當存在多個視窗（例如對話框）時，會將每個視窗擷取到獨立的檔案。 使用 --json 時，會回傳檔案路徑和尺寸。 使用 -capture-screen 來顯示彈出視窗的疊加層。
function uiScreenshot(options?: UiScreenshotOptions): Promise<WinappResult>
選項：
| 房產 | 類型 | 為必填項目 | Description |
|---|---|---|---|
selector |
string \| undefined |
No | 語意識別符（例如 btn-minimize-d1a0）或按照名稱或 AutomationId 搜尋的文字 |
app |
string \| undefined |
No | 目標應用程式（程序名稱、視窗標題或 PID）。 如果有歧義，會列出視窗。 |
captureScreen |
boolean \| undefined |
No | 從螢幕擷取（包含彈出視窗/疊加層）取代視窗渲染。 先將視窗顯示在最前面。 |
json |
boolean \| undefined |
No | 格式輸出為 JSON |
output |
string \| undefined |
No | 儲存輸出到檔案路徑（例如截圖） |
window |
number \| undefined |
No | 目標視窗由 HWND 建立（穩定 handle 來自列表輸出）。 優先於 --app。 |
同時接受 CommonOptions （quiet， verbose， cwd）。
uiScroll()
使用 ScrollPattern 滾動容器元素。 使用 --direction 可以逐步捲動，或使用 ---to 來跳到頂部或底部。
function uiScroll(options?: UiScrollOptions): Promise<WinappResult>
選項：
| 房產 | 類型 | 為必填項目 | Description |
|---|---|---|---|
selector |
string \| undefined |
No | 語意識別符（例如 btn-minimize-d1a0）或按照名稱或 AutomationId 搜尋的文字 |
app |
string \| undefined |
No | 目標應用程式（程序名稱、視窗標題或 PID）。 如果有歧義，會列出視窗。 |
direction |
string \| undefined |
No | 捲動方向：上、下、左、右 |
json |
boolean \| undefined |
No | 格式輸出為 JSON |
to |
string \| undefined |
No | 捲動到位置：頂部、底部 |
window |
number \| undefined |
No | 目標視窗由 HWND 建立（穩定 handle 來自列表輸出）。 優先於 --app。 |
同時接受 CommonOptions （quiet， verbose， cwd）。
uiScrollIntoView()
使用 UIA ScrollItemPattern 將指定的元素捲入可見區域。
function uiScrollIntoView(options?: UiScrollIntoViewOptions): Promise<WinappResult>
選項：
| 房產 | 類型 | 為必填項目 | Description |
|---|---|---|---|
selector |
string \| undefined |
No | 語意識別符（例如 btn-minimize-d1a0）或按照名稱或 AutomationId 搜尋的文字 |
app |
string \| undefined |
No | 目標應用程式（程序名稱、視窗標題或 PID）。 如果有歧義，會列出視窗。 |
json |
boolean \| undefined |
No | 格式輸出為 JSON |
window |
number \| undefined |
No | 目標視窗由 HWND 建立（穩定 handle 來自列表輸出）。 優先於 --app。 |
同時接受 CommonOptions （quiet， verbose， cwd）。
uiSearch()
在元素樹中搜尋與文字查詢相符的元素。 回傳所有帶有語意條的匹配。
function uiSearch(options?: UiSearchOptions): Promise<WinappResult>
選項：
| 房產 | 類型 | 為必填項目 | Description |
|---|---|---|---|
selector |
string \| undefined |
No | 語意識別符（例如 btn-minimize-d1a0）或按照名稱或 AutomationId 搜尋的文字 |
app |
string \| undefined |
No | 目標應用程式（程序名稱、視窗標題或 PID）。 如果有歧義，會列出視窗。 |
json |
boolean \| undefined |
No | 格式輸出為 JSON |
max |
number \| undefined |
No | 最大搜尋結果 |
window |
number \| undefined |
No | 目標視窗由 HWND 建立（穩定 handle 來自列表輸出）。 優先於 --app。 |
同時接受 CommonOptions （quiet， verbose， cwd）。
uiSetValue()
使用 UIA ValuePattern 在元素上設定一個值。 適用於 TextBox、ComboBox、Slider 及其他可編輯的控制項。 Usage： winapp UI set-value selector value -a <> app<><>
function uiSetValue(options?: UiSetValueOptions): Promise<WinappResult>
選項：
| 房產 | 類型 | 為必填項目 | Description |
|---|---|---|---|
selector |
string \| undefined |
No | 語意識別符（例如 btn-minimize-d1a0）或按照名稱或 AutomationId 搜尋的文字 |
value |
string \| undefined |
No | 要設定的數值（TextBox/ComboBox 的文字，滑桿的數字） |
app |
string \| undefined |
No | 目標應用程式（程序名稱、視窗標題或 PID）。 若有歧義，會列出視窗。 |
json |
boolean \| undefined |
No | 格式輸出為 JSON |
window |
number \| undefined |
No | 透過 HWND（列表輸出的穩定 handle）識別目標視窗。 優先於 --app。 |
同時接受 CommonOptions （quiet， verbose， cwd）。
uiStatus()
連接到目標應用程式並顯示連線資訊。
function uiStatus(options?: UiStatusOptions): Promise<WinappResult>
選項：
| 房產 | 類型 | 為必填項目 | Description |
|---|---|---|---|
app |
string \| undefined |
No | 目標應用程式（程序名稱、視窗標題或 PID）。 如果有歧義，會列出視窗。 |
json |
boolean \| undefined |
No | 格式輸出為 JSON |
window |
number \| undefined |
No | 目標視窗由 HWND（從列表輸出中取得的穩定 handle）建立。 優先於 --app。 |
同時接受 CommonOptions （quiet， verbose， cwd）。
uiWaitFor()
等待元素出現、消失，或屬性達到目標值。 以 100 毫秒為間隔進行輪詢，直到條件達成或逾時。
function uiWaitFor(options?: UiWaitForOptions): Promise<WinappResult>
選項：
| 房產 | 類型 | 為必填項目 | Description |
|---|---|---|---|
selector |
string \| undefined |
No | 語意識別符（例如 btn-minimize-d1a0）或按照名稱或 AutomationId 搜尋的文字 |
app |
string \| undefined |
No | 目標應用程式（程序名稱、視窗標題或 PID）。 如果有歧義，會列出視窗。 |
contains |
boolean \| undefined |
No | 使用子字串匹配 --value，而非完全匹配 |
gone |
boolean \| undefined |
No | 等待元素消失而非出現 |
json |
boolean \| undefined |
No | 格式輸出為 JSON |
property |
string \| undefined |
No | 要閱讀或篩選的屬性名稱 |
timeout |
number \| undefined |
No | 超時時間（毫秒） |
value |
string \| undefined |
No | 等待元素值等於這個字串。 使用智能後備措施（TextPattern -> ValuePattern -> 名稱）。 將 ---property 結合，以檢查特定房產。 |
window |
number \| undefined |
No | 目標視窗由 HWND 建立（穩定 handle 來自列表輸出）。 優先於 --app。 |
同時接受 CommonOptions （quiet， verbose， cwd）。
unregister()
取消註冊一個側載的開發包。 僅移除在開發模式下註冊的套件（例如透過「winapp run」或「create-debug-identity」）。
function unregister(options?: UnregisterOptions): Promise<WinappResult>
選項：
| 房產 | 類型 | 為必填項目 | Description |
|---|---|---|---|
force |
boolean \| undefined |
No | 跳過安裝位置目錄檢查，即使套件是從其他專案樹註冊，也要取消註冊 |
json |
boolean \| undefined |
No | 格式輸出為 JSON |
manifest |
string \| undefined |
No | Package.appxmanifest 路徑（預設：自動偵測從目前目錄） |
同時接受 CommonOptions （quiet， verbose， cwd）。
update()
檢查並安裝更新的 SDK 版本。 更新 winapp.yaml 到最新版本並重新安裝套件。 需要現有的 winapp.yaml（由 'init' 建立）。 使用 --setup-sdks 預覽版來預覽 SDK。 若要重新安裝目前版本而不更新，請改用「還原」。
function update(options?: UpdateOptions): Promise<WinappResult>
選項：
| 房產 | 類型 | 為必填項目 | Description |
|---|---|---|---|
setupSdks |
SdkInstallMode \| undefined |
No | SDK 安裝模式：「stable」（預設）、 「preview」、「experimental」或「none」（跳過 SDK 安裝） |
同時接受 CommonOptions （quiet， verbose， cwd）。
公用程式函數
execWithBuildTools()
執行一個指令，並將 BuildTools 的 bin 路徑加入 PATH 環境
function execWithBuildTools(command: string, options?: ExecSyncOptions): string | Buffer<ArrayBufferLike>
參數：
| 參數 | 類型 | 為必填項目 | Description |
|---|---|---|---|
command |
string |
Yes | 執行命令 |
options |
ExecSyncOptions |
No | 傳遞給 execSync 的選項（可選） |
返回值： execSync 的輸出
addMsixIdentityToExe()
將 appxmanifest.xml 檔案中的套件身份資訊加入執行檔的內嵌清單
function addMsixIdentityToExe(exePath: string, appxManifestPath?: string | undefined, options?: MsixIdentityOptions): Promise<MsixIdentityResult>
參數：
| 參數 | 類型 | 為必填項目 | Description |
|---|---|---|---|
exePath |
string |
Yes | 可執行檔路徑 |
appxManifestPath |
string \| undefined |
No | 包含套件識別資料的 appxmanifest.xml 檔案路徑 |
options |
MsixIdentityOptions |
No | 選用設定 |
addElectronDebugIdentity()
為 Electron 除錯流程新增封包識別碼
function addElectronDebugIdentity(options?: MsixIdentityOptions): Promise<ElectronDebugIdentityResult>
參數：
| 參數 | 類型 | 為必填項目 | Description |
|---|---|---|---|
options |
MsixIdentityOptions |
No | 設定選項 |
clearElectronDebugIdentity()
透過從備份還原，清除/移除 Electron 除錯程序中的套件身份
function clearElectronDebugIdentity(options?: MsixIdentityOptions): Promise<ClearElectronDebugIdentityResult>
參數：
| 參數 | 類型 | 為必填項目 | Description |
|---|---|---|---|
options |
MsixIdentityOptions |
No | 設定選項 |
getGlobalWinappPath()
取得全域 .winapp 目錄的路徑
function getGlobalWinappPath(): string
退貨： 完整路徑通往全球 .winapp 目錄
getLocalWinappPath()
取得本地 .winapp 目錄的路徑
function getLocalWinappPath(): string
退貨： 本地 .winapp 目錄的完整路徑
Node.js CLI 指令
這些指令僅透過 npx winapp node <subcommand> 提供，且不會匯出為程式化函式。
node create-addon
為 Electron 專案產生原生外掛檔案。 支援 C++（node-gyp）及 C#（node-api-dotnet）範本。
npx winapp node create-addon [options]
選項：
| Flag | Description |
|---|---|
--name <name> |
附加元件名稱（預設依範本而定） |
--template <type> |
附加元件範本： cpp 或 cs （預設： cpp） |
--verbose |
啟用冗長輸出 |
註： 必須從 Electron 專案的根節點執行（包含
package.json的目錄）。
範例：
npx winapp node create-addon
npx winapp node create-addon --name myAddon
npx winapp node create-addon --template cs --name MyCsAddon
node add-electron-debug-identity
利用稀疏封裝為 Electron 除錯流程新增封包識別碼。 建立 的 electron.exe備份，產生稀疏的 MSIX 清單，為可執行檔新增身份，並註冊稀疏套件。 需要一個 Package.appxmanifest（可以使用 winapp init 或 winapp manifest generate 來建立）。
npx winapp node add-electron-debug-identity [options]
選項：
| Flag | Description |
|---|---|
--manifest <path> |
自訂 Package.appxmanifest 的路徑（預設：Package.appxmanifest 在目前的目錄中） |
--no-install |
建立套件後不要安裝 |
--keep-identity |
保持顯現身份 as-is，不要加上 .debug 後綴 |
--verbose |
啟用冗長輸出 |
註： 必須從 Electron 專案的根節點執行（包含
node_modules/electron的目錄）。 要撤銷，請使用npx winapp node clear-electron-debug-identity。
範例：
npx winapp node add-electron-debug-identity
npx winapp node add-electron-debug-identity --manifest ./custom/Package.appxmanifest
node clear-electron-debug-identity
將套件身份從 Electron 除錯過程中移除。 還原從 add-electron-debug-identity 建立的 electron.exe 備份，並移除備份檔案。
npx winapp node clear-electron-debug-identity [options]
選項：
| Flag | Description |
|---|---|
--verbose |
啟用冗長輸出 |
註： 必須從 Electron 專案的根節點執行（包含
node_modules/electron的目錄）。
範例：
npx winapp node clear-electron-debug-identity
類型參考
ExecSyncOptions
為了方便從 Node.js 重新匯出。 請參考 Node.js 文件。
MsixIdentityOptions
| 房產 | 類型 | 為必填項目 | Description |
|---|---|---|---|
verbose |
boolean \| undefined |
No | |
noInstall |
boolean \| undefined |
No | |
keepIdentity |
boolean \| undefined |
No | |
manifest |
string \| undefined |
No |
MsixIdentityResult
| 房產 | 類型 | 為必填項目 | Description |
|---|---|---|---|
success |
boolean |
Yes |
ElectronDebugIdentityResult
| 房產 | 類型 | 為必填項目 | Description |
|---|---|---|---|
success |
boolean |
Yes | |
electronExePath |
string |
Yes | |
backupPath |
string |
Yes | |
manifestPath |
string |
Yes | |
assetsDir |
string |
Yes |
ClearElectronDebugIdentityResult
| 房產 | 類型 | 為必填項目 | Description |
|---|---|---|---|
success |
boolean |
Yes | |
electronExePath |
string |
Yes | |
restoredFromBackup |
boolean |
Yes |
CallWinappCliOptions
| 房產 | 類型 | 為必填項目 | Description |
|---|---|---|---|
exitOnError |
boolean \| undefined |
No |
CallWinappCliResult
| 房產 | 類型 | 為必填項目 | Description |
|---|---|---|---|
exitCode |
number |
Yes |
CallWinappCliCaptureOptions
| 房產 | 類型 | 為必填項目 | Description |
|---|---|---|---|
cwd |
string \| undefined |
No | CLI 程序的工作目錄（預設為 process.cwd（）） |
CallWinappCliCaptureResult
| 房產 | 類型 | 為必填項目 | Description |
|---|---|---|---|
exitCode |
number |
Yes | |
stdout |
string |
Yes | |
stderr |
string |
Yes |
GenerateCppAddonOptions
| 房產 | 類型 | 為必填項目 | Description |
|---|---|---|---|
name |
string \| undefined |
No | |
projectRoot |
string \| undefined |
No | |
verbose |
boolean \| undefined |
No |
GenerateCppAddonResult
| 房產 | 類型 | 為必填項目 | Description |
|---|---|---|---|
success |
boolean |
Yes | |
addonName |
string |
Yes | |
addonPath |
string |
Yes | |
needsTerminalRestart |
boolean |
Yes | |
files |
string[] |
Yes |
GenerateCsAddonOptions
| 房產 | 類型 | 為必填項目 | Description |
|---|---|---|---|
name |
string \| undefined |
No | |
projectRoot |
string \| undefined |
No | |
verbose |
boolean \| undefined |
No |
GenerateCsAddonResult
| 房產 | 類型 | 為必填項目 | Description |
|---|---|---|---|
success |
boolean |
Yes | |
addonName |
string |
Yes | |
addonPath |
string |
Yes | |
needsTerminalRestart |
boolean |
Yes | |
files |
string[] |
Yes |
IfExists
IfExists 價值觀。
type IfExists = "error" | "overwrite" | "skip"
SdkInstallMode
SdkInstallMode 的參數值。
type SdkInstallMode = "stable" | "preview" | "experimental" | "none"
ManifestTemplates
ManifestTemplates 的價值觀。
type ManifestTemplates = "packaged" | "sparse"
CertGenerateOptions
| 房產 | 類型 | 為必填項目 | Description |
|---|---|---|---|
exportCer |
boolean \| undefined |
No | 匯出一個.cer檔案（僅限公鑰），與 .pfx 一起 |
ifExists |
IfExists \| undefined |
No | 當輸出檔存在時的行為：'error'（失敗，預設）、'skip'（保持存在）或「覆寫」（替換） |
install |
boolean \| undefined |
No | 生成之後將憑證安裝到本地機器儲存 |
json |
boolean \| undefined |
No | 格式輸出為 JSON |
manifest |
string \| undefined |
No | 前往 Package.appxmanifest 或 appxmanifest.xml 檔案的路徑，以擷取發行者資訊。 |
output |
string \| undefined |
No | 產生的 PFX 檔案輸出路徑 |
password |
string \| undefined |
No | 產生的 PFX 檔案密碼 |
publisher |
string \| undefined |
No | 產生憑證的 Publisher 名稱。 若未特別說明，則會從清單推斷。 |
validDays |
number \| undefined |
No | 證書有效天數 |
quiet |
boolean \| undefined |
No | 抑制進度訊息。 |
verbose |
boolean \| undefined |
No | 啟用冗長輸出。 |
cwd |
string \| undefined |
No | CLI 程序的工作目錄（預設為 process.cwd（））。 |
CertInfoOptions
| 房產 | 類型 | 為必填項目 | Description |
|---|---|---|---|
certPath |
string |
Yes | 憑證檔案路徑（PFX） |
json |
boolean \| undefined |
No | 格式輸出為 JSON |
password |
string \| undefined |
No | PFX 檔案的密碼 |
quiet |
boolean \| undefined |
No | 抑制進度訊息。 |
verbose |
boolean \| undefined |
No | 啟用冗長輸出。 |
cwd |
string \| undefined |
No | CLI 程序的工作目錄（預設為 process.cwd（））。 |
CertInstallOptions
| 房產 | 類型 | 為必填項目 | Description |
|---|---|---|---|
certPath |
string |
Yes | 憑證檔案（PFX 或 CER）的路徑 |
force |
boolean \| undefined |
No | 即使憑證已存在，也要強制安裝 |
password |
string \| undefined |
No | PFX 檔案的密碼 |
quiet |
boolean \| undefined |
No | 抑制進度訊息。 |
verbose |
boolean \| undefined |
No | 啟用冗長輸出。 |
cwd |
string \| undefined |
No | CLI 程序的工作目錄（預設為 process.cwd（））。 |
CreateDebugIdentityOptions
| 房產 | 類型 | 為必填項目 | Description |
|---|---|---|---|
entrypoint |
string \| undefined |
No | 需要以身份碼或入口腳本執行的 .exe 路徑。 |
keepIdentity |
boolean \| undefined |
No | 請保持清單中的套件身份不變，並且不要在套件名稱和應用程式 ID 後加上「.debug」。 |
manifest |
string \| undefined |
No | 到 Package.appxmanifest 或 appxmanifest.xml 的路徑 |
noInstall |
boolean \| undefined |
No | 建立套件後不要安裝。 |
quiet |
boolean \| undefined |
No | 抑制進度訊息。 |
verbose |
boolean \| undefined |
No | 啟用冗長輸出。 |
cwd |
string \| undefined |
No | CLI 程序的工作目錄（預設為 process.cwd（））。 |
CreateExternalCatalogOptions
| 房產 | 類型 | 為必填項目 | Description |
|---|---|---|---|
inputFolder |
string |
Yes | 包含可執行檔案進行處理的輸入資料夾清單（以分號分隔） |
computeFlatHashes |
boolean \| undefined |
No | 產生目錄時包含平面哈希值 |
ifExists |
IfExists \| undefined |
No | 輸出檔已存在時的行為 |
output |
string \| undefined |
No | 輸出目錄文件路徑。 若未指定，則使用預設 CodeIntegrityExternal.cat 名稱。 |
recursive |
boolean \| undefined |
No | 包含來自子目錄中的檔案 |
usePageHashes |
boolean \| undefined |
No | 產生目錄時請包含頁面雜湊值 |
quiet |
boolean \| undefined |
No | 抑制進度訊息。 |
verbose |
boolean \| undefined |
No | 啟用冗長輸出。 |
cwd |
string \| undefined |
No | CLI 程序的工作目錄（預設為 process.cwd（））。 |
GetWinappPathOptions
| 房產 | 類型 | 為必填項目 | Description |
|---|---|---|---|
global |
boolean \| undefined |
No | 取得全域的 .winapp 目錄，而不是本地 |
quiet |
boolean \| undefined |
No | 抑制進度訊息。 |
verbose |
boolean \| undefined |
No | 啟用冗長輸出。 |
cwd |
string \| undefined |
No | CLI 程序的工作目錄（預設為 process.cwd（））。 |
InitOptions
| 房產 | 類型 | 為必填項目 | Description |
|---|---|---|---|
baseDirectory |
string \| undefined |
No | Winapp 工作區的基礎/根目錄，供使用者或安裝使用。 |
configDir |
string \| undefined |
No | 目錄用以讀取/儲存設定（預設：目前目錄） |
configOnly |
boolean \| undefined |
No | 只處理設定檔操作（缺少設定檔則建立，存在則驗證）。 跳過套件安裝和其他工作區設定步驟。 |
ignoreConfig |
boolean \| undefined |
No | 不要用設定檔來管理版本 |
noGitignore |
boolean \| undefined |
No | 不要更新 .gitignore 檔案 |
setupSdks |
SdkInstallMode \| undefined |
No | SDK 安裝模式：「stable」（預設）、 「preview」、「experimental」或「none」（跳過 SDK 安裝） |
useDefaults |
boolean \| undefined |
No | 不要顯示任何提示，並對所有提示使用預設設定 |
quiet |
boolean \| undefined |
No | 抑制進度訊息。 |
verbose |
boolean \| undefined |
No | 啟用冗長輸出。 |
cwd |
string \| undefined |
No | CLI 程序的工作目錄（預設為 process.cwd（））。 |
ManifestAddAliasOptions
| 房產 | 類型 | 為必填項目 | Description |
|---|---|---|---|
appId |
string \| undefined |
No | 用來新增別名的應用程式 ID（預設：第一個應用程式元素） |
manifest |
string \| undefined |
No | 路徑至 Package.appxmanifest 或 appxmanifest.xml 檔案（預設：搜尋目前目錄） |
name |
string \| undefined |
No | 別名（例如「myapp.exe」）。 預設：從清單中的可執行檔屬性推斷。 |
quiet |
boolean \| undefined |
No | 抑制進度訊息。 |
verbose |
boolean \| undefined |
No | 啟用冗長輸出。 |
cwd |
string \| undefined |
No | CLI 程序的工作目錄（預設為 process.cwd（））。 |
ManifestGenerateOptions
| 房產 | 類型 | 為必填項目 | Description |
|---|---|---|---|
directory |
string \| undefined |
No | 目錄用來生成 manifest 文件 |
description |
string \| undefined |
No | 安裝時及 Windows 設定中顯示的人類可讀應用程式說明 |
executable |
string \| undefined |
No | 應用程式執行檔的路徑。 預設： <套件名稱>.exe |
ifExists |
IfExists \| undefined |
No | 當輸出檔存在時的行為：'error'（失敗，預設）、'skip'（保持存在）或「覆寫」（替換） |
logoPath |
string \| undefined |
No | Logo 影像檔案的路徑 |
packageName |
string \| undefined |
No | 套件名稱（預設：資料夾名稱） |
publisherName |
string \| undefined |
No | Publisher CN（預設：CN=<目前使用者>） |
template |
ManifestTemplates \| undefined |
No | 清單範本類型：「packaged」（完整 MSIX 應用程式，預設）或「sparse」（具有套件識別的桌面應用程式，用於 Windows API）。 |
version |
string \| undefined |
No | 應用程式版本為 Major.Minor.Build.Revision 格式（例如 1.0.0.0）。 |
quiet |
boolean \| undefined |
No | 抑制進度訊息。 |
verbose |
boolean \| undefined |
No | 啟用冗長輸出。 |
cwd |
string \| undefined |
No | CLI 程序的工作目錄（預設為 process.cwd（））。 |
ManifestUpdateAssetsOptions
| 房產 | 類型 | 為必填項目 | Description |
|---|---|---|---|
imagePath |
string |
Yes | 來源圖片檔案的路徑（SVG、PNG、ICO、JPG、BMP、GIF） |
lightImage |
string \| undefined |
No | 淺色主題變體（SVG、PNG、ICO、JPG、BMP、GIF）的來源影像路徑 |
manifest |
string \| undefined |
No | 路徑至 Package.appxmanifest 或 appxmanifest.xml 檔案（預設：搜尋目前目錄） |
quiet |
boolean \| undefined |
No | 抑制進度訊息。 |
verbose |
boolean \| undefined |
No | 啟用冗長輸出。 |
cwd |
string \| undefined |
No | CLI 程序的工作目錄（預設為 process.cwd（））。 |
PackageOptions
| 房產 | 類型 | 為必填項目 | Description |
|---|---|---|---|
inputFolder |
string |
Yes | 輸入資料夾與套件配置 |
cert |
string \| undefined |
No | 簽署憑證的路徑（若提供將自動簽署） |
certPassword |
string \| undefined |
No | 憑證密碼（預設：password） |
executable |
string \| undefined |
No | 相對於輸入資料夾的執行檔路徑。 |
generateCert |
boolean \| undefined |
No | 產生新的開發證書 |
installCert |
boolean \| undefined |
No | 將憑證安裝到機器 |
manifest |
string \| undefined |
No | AppX 清單檔案的檔案路徑（預設：自動偵測來自輸入的資料夾或目前目錄） |
name |
string \| undefined |
No | 套件名稱（預設：來自清單） |
output |
string \| undefined |
No | 產生套件的輸出 msix 檔案名稱（預設為 |
publisher |
string \| undefined |
No | 用於憑證產生的發行者名稱 |
selfContained |
boolean \| undefined |
No | 捆綁 Windows 應用程式 SDK 執行環境以實現自包含部署 |
skipPri |
boolean \| undefined |
No | 跳過 PRI 檔案產生 |
quiet |
boolean \| undefined |
No | 抑制進度訊息。 |
verbose |
boolean \| undefined |
No | 啟用冗長輸出。 |
cwd |
string \| undefined |
No | CLI 程序的工作目錄（預設為 process.cwd（））。 |
RestoreOptions
| 房產 | 類型 | 為必填項目 | Description |
|---|---|---|---|
baseDirectory |
string \| undefined |
No | Winapp 工作區的 Base/root 目錄 |
configDir |
string \| undefined |
No | 讀取設定的目錄（預設：目前目錄） |
quiet |
boolean \| undefined |
No | 抑制進度訊息。 |
verbose |
boolean \| undefined |
No | 啟用冗長輸出。 |
cwd |
string \| undefined |
No | CLI 程序的工作目錄（預設為 process.cwd（））。 |
RunOptions
| 房產 | 類型 | 為必填項目 | Description |
|---|---|---|---|
inputFolder |
string |
Yes | 輸入資料夾，包含要執行的應用程式 |
args |
string \| undefined |
No | 用來傳遞給應用程式的命令列參數 |
clean |
boolean \| undefined |
No | 在重新部署前，先移除現有套件的應用程式資料（LocalState、設定等）。 預設情況下，應用程式資料會在重新部署過程中被保留。 |
debugOutput |
boolean \| undefined |
No | 擷取從啟動的應用程式中傳送的 OutputDebugString 訊息和 first-chance 例外。 同一時間只能連接一個除錯器，因此無法同時使用其他除錯器（如 Visual Studio、VS Code）。 如果需要附加不同的除錯器，可以改用 --no-launch。 不能和 --no-launch 或 --json 合併使用。 |
detach |
boolean \| undefined |
No | 啟動應用程式後立即返回，不要等它退出。 對於需要在啟動後與應用程式互動的 CI/自動化來說很有用。 會把 PID 列印成標準碼（或用 --json 格式的 JSON）。 |
json |
boolean \| undefined |
No | 格式輸出為 JSON |
manifest |
string \| undefined |
No | 到 Package.appxmanifest 的路徑（預設：自動偵測輸入資料夾或目前目錄） |
noLaunch |
boolean \| undefined |
No | 只建立除錯身份並註冊套件，無需啟動應用程式 |
outputAppxDirectory |
string \| undefined |
No | 靈活配置包的輸出目錄。 若未指定，則會使用輸入資料夾目錄中名為 AppX 的目錄。 |
symbols |
boolean \| undefined |
No | 從 Microsoft Symbol Server 下載符號，以獲得更豐富的原生當機分析。 僅適用於 --debug-output。 首先執行時下載符號並快取到本地;後續執行會使用快取。 |
unregisterOnExit |
boolean \| undefined |
No | 應用程式退出後取消註冊開發套件。 只會移除在開發模式下註冊的套件。 |
withAlias |
boolean \| undefined |
No | 啟動應用程式時，請使用執行別名，而不是 AUMID 激活。 應用程式在目前的終端機中運行，繼承了 stdin/stdout/stderr。 需要在清單中加入 uap5：ExecutionAlias。 使用「winapp manifest add-alias」來為清單新增執行別名。 |
quiet |
boolean \| undefined |
No | 抑制進度訊息。 |
verbose |
boolean \| undefined |
No | 啟用冗長輸出。 |
cwd |
string \| undefined |
No | CLI 程序的工作目錄（預設為 process.cwd（））。 |
SignOptions
| 房產 | 類型 | 為必填項目 | Description |
|---|---|---|---|
filePath |
string |
Yes | 要簽署的檔案/套件路徑 |
certPath |
string |
Yes | 憑證檔案路徑（PFX 格式） |
password |
string \| undefined |
No | 憑證密碼 |
timestamp |
string \| undefined |
No | 時間戳伺服器網址 |
quiet |
boolean \| undefined |
No | 抑制進度訊息。 |
verbose |
boolean \| undefined |
No | 啟用冗長輸出。 |
cwd |
string \| undefined |
No | CLI 程序的工作目錄（預設為 process.cwd（））。 |
StoreOptions
| 房產 | 類型 | 為必填項目 | Description |
|---|---|---|---|
storeArgs |
string[] \| undefined |
No | 這些論點將傳遞給 Microsoft Store 開發者 CLI。 |
quiet |
boolean \| undefined |
No | 抑制進度訊息。 |
verbose |
boolean \| undefined |
No | 啟用冗長輸出。 |
cwd |
string \| undefined |
No | CLI 程序的工作目錄（預設為 process.cwd（））。 |
ToolOptions
| 房產 | 類型 | 為必填項目 | Description |
|---|---|---|---|
toolArgs |
string[] \| undefined |
No | 要傳遞給 SDK 工具的參數，例如 ['makeappx'， 'pack'， '/d'， './folder'， '/p'， './out.msix']。 |
quiet |
boolean \| undefined |
No | 抑制進度訊息。 |
verbose |
boolean \| undefined |
No | 啟用冗長輸出。 |
cwd |
string \| undefined |
No | CLI 程序的工作目錄（預設為 process.cwd（））。 |
UiClickOptions
| 房產 | 類型 | 為必填項目 | Description |
|---|---|---|---|
selector |
string \| undefined |
No | 語義子串（例如 btn-minimize-d1a0）或以名稱/自動化ID搜尋的文字 |
app |
string \| undefined |
No | 目標應用程式（程序名稱、視窗標題或 PID）。 如果有歧義，會列出窗戶。 |
double |
boolean \| undefined |
No | 請雙擊而非單擊 |
json |
boolean \| undefined |
No | 格式輸出為 JSON |
right |
boolean \| undefined |
No | 請用右鍵點擊代替左鍵 |
window |
number \| undefined |
No | 目標視窗以 HWND 為標識（穩定的窗口控制碼來源自列表輸出）。 優先於 --app。 |
quiet |
boolean \| undefined |
No | 抑制進度訊息。 |
verbose |
boolean \| undefined |
No | 啟用冗長輸出。 |
cwd |
string \| undefined |
No | CLI 程序的工作目錄（預設為 process.cwd（））。 |
UiFocusOptions
| 房產 | 類型 | 為必填項目 | Description |
|---|---|---|---|
selector |
string \| undefined |
No | 語義子串（例如 btn-minimize-d1a0）或以名稱/自動化ID搜尋的文字 |
app |
string \| undefined |
No | 目標應用程式（程序名稱、視窗標題或 PID）。 如果有歧義，會列出窗戶。 |
json |
boolean \| undefined |
No | 格式輸出為 JSON |
window |
number \| undefined |
No | 目標視窗以 HWND 為標識（穩定的窗口控制碼來源自列表輸出）。 優先於 --app。 |
quiet |
boolean \| undefined |
No | 抑制進度訊息。 |
verbose |
boolean \| undefined |
No | 啟用冗長輸出。 |
cwd |
string \| undefined |
No | CLI 程序的工作目錄（預設為 process.cwd（））。 |
UiGetFocusedOptions
| 房產 | 類型 | 為必填項目 | Description |
|---|---|---|---|
app |
string \| undefined |
No | 目標應用程式（程序名稱、視窗標題或 PID）。 如果有歧義，會列出窗戶。 |
json |
boolean \| undefined |
No | 格式輸出為 JSON |
window |
number \| undefined |
No | 目標視窗以 HWND 為標識（穩定的窗口控制碼來源自列表輸出）。 優先於 --app。 |
quiet |
boolean \| undefined |
No | 抑制進度訊息。 |
verbose |
boolean \| undefined |
No | 啟用冗長輸出。 |
cwd |
string \| undefined |
No | CLI 程序的工作目錄（預設為 process.cwd（））。 |
UiGetPropertyOptions
| 房產 | 類型 | 為必填項目 | Description |
|---|---|---|---|
selector |
string \| undefined |
No | 語義子串（例如 btn-minimize-d1a0）或以名稱/自動化ID搜尋的文字 |
app |
string \| undefined |
No | 目標應用程式（程序名稱、視窗標題或 PID）。 如果有歧義，會列出窗戶。 |
json |
boolean \| undefined |
No | 格式輸出為 JSON |
property |
string \| undefined |
No | 要閱讀或篩選的屬性名稱 |
window |
number \| undefined |
No | 目標視窗以 HWND 為標識（穩定的窗口控制碼來源自列表輸出）。 優先於 --app。 |
quiet |
boolean \| undefined |
No | 抑制進度訊息。 |
verbose |
boolean \| undefined |
No | 啟用冗長輸出。 |
cwd |
string \| undefined |
No | CLI 程序的工作目錄（預設為 process.cwd（））。 |
UiGetValueOptions
| 房產 | 類型 | 為必填項目 | Description |
|---|---|---|---|
selector |
string \| undefined |
No | 語意字串（例如 btn-minimize-d1a0）或使用名稱/automationId 搜尋的文字 |
app |
string \| undefined |
No | 目標應用程式（程序名稱、視窗標題或 PID）。 如果有歧義，會列出視窗。 |
json |
boolean \| undefined |
No | 格式輸出為 JSON |
window |
number \| undefined |
No | 目標視窗由 HWND 建立（穩定 handle 來自列表輸出）。 優先於 --app。 |
quiet |
boolean \| undefined |
No | 抑制進度訊息。 |
verbose |
boolean \| undefined |
No | 啟用冗長輸出。 |
cwd |
string \| undefined |
No | CLI 程序的工作目錄（預設為 process.cwd（））。 |
UiInspectOptions
| 房產 | 類型 | 為必填項目 | Description |
|---|---|---|---|
selector |
string \| undefined |
No | 語意字元（例如 btn-minimize-d1a0）或依名稱/自動化ID進行搜尋的文字 |
ancestors |
boolean \| undefined |
No | 從指定的元素向上遍歷到樹的根節點 |
app |
string \| undefined |
No | 目標應用程式（程序名稱、視窗標題或 PID）。 如果有歧義，會列出視窗。 |
depth |
number \| undefined |
No | 樹木檢查深度 |
hideDisabled |
boolean \| undefined |
No | 隱藏禁用元素使其不在輸出中顯示 |
hideOffscreen |
boolean \| undefined |
No | 將畫面外元素從輸出中隱藏 |
interactive |
boolean \| undefined |
No | 只顯示互動式/可調用的元素（按鈕、連結、輸入、清單項目）。 將預設深度增加到 8。 |
json |
boolean \| undefined |
No | 格式輸出為 JSON |
window |
number \| undefined |
No | 目標視窗由 HWND 建立（穩定 handle 來自列表輸出）。 優先於 --app。 |
quiet |
boolean \| undefined |
No | 隱藏進度訊息。 |
verbose |
boolean \| undefined |
No | 啟用冗長輸出。 |
cwd |
string \| undefined |
No | CLI 程序的工作目錄（預設為 process.cwd（））。 |
UiInvokeOptions
| 房產 | 類型 | 為必填項目 | Description |
|---|---|---|---|
selector |
string \| undefined |
No | 語意字條（例如 btn-minimize-d1a0）或以名稱/automationId 搜尋的文字 |
app |
string \| undefined |
No | 目標應用程式（程序名稱、視窗標題或 PID）。 列出窗口以解決歧義。 |
json |
boolean \| undefined |
No | 格式輸出為 JSON |
window |
number \| undefined |
No | 目標視窗由 HWND 建立（穩定 handle 來自列表輸出）。 優先於 --app。 |
quiet |
boolean \| undefined |
No | 抑制進度訊息。 |
verbose |
boolean \| undefined |
No | 啟用冗長輸出。 |
cwd |
string \| undefined |
No | CLI 程序的工作目錄（預設為 process.cwd（））。 |
UiListWindowsOptions
| 房產 | 類型 | 為必填項目 | Description |
|---|---|---|---|
app |
string \| undefined |
No | 目標應用程式（程序名稱、視窗標題或 PID）。 如果存在歧義，會列出視窗。 |
json |
boolean \| undefined |
No | 格式輸出為 JSON |
quiet |
boolean \| undefined |
No | 隱藏進度訊息。 |
verbose |
boolean \| undefined |
No | 啟用冗長輸出。 |
cwd |
string \| undefined |
No | CLI 程序的工作目錄（預設為 process.cwd（））。 |
UiScreenshotOptions
| 房產 | 類型 | 為必填項目 | Description |
|---|---|---|---|
selector |
string \| undefined |
No | 語意識別碼（例如 btn-minimize-d1a0）或根據名稱或自動化ID搜尋的文字 |
app |
string \| undefined |
No | 目標應用程式（程序名稱、視窗標題或 PID）。 如果有歧義，會列出視窗。 |
captureScreen |
boolean \| undefined |
No | 從螢幕擷取（包含彈出視窗/疊加層）取代視窗渲染。 先將視窗顯示在最前面。 |
json |
boolean \| undefined |
No | 格式輸出為 JSON |
output |
string \| undefined |
No | 儲存輸出到檔案路徑（例如截圖） |
window |
number \| undefined |
No | 目標視窗通過 HWND 確定（穩定的句柄來自列表輸出）。 優先於 --app。 |
quiet |
boolean \| undefined |
No | 抑制進度訊息。 |
verbose |
boolean \| undefined |
No | 啟用冗長輸出。 |
cwd |
string \| undefined |
No | CLI 程序的工作目錄（預設為 process.cwd（））。 |
UiScrollOptions
| 房產 | 類型 | 為必填項目 | Description |
|---|---|---|---|
selector |
string \| undefined |
No | 語意字條（例如 btn-minimize-d1a0）或以名稱/automationId 搜尋的文字 |
app |
string \| undefined |
No | 目標應用程式（程序名稱、視窗標題或 PID）。 如果有歧義，會列出視窗。 |
direction |
string \| undefined |
No | 捲動方向：上、下、左、右 |
json |
boolean \| undefined |
No | 格式輸出為 JSON |
to |
string \| undefined |
No | 捲動到位置：頂部、底部 |
window |
number \| undefined |
No | 目標視窗由 HWND 建立（穩定 handle 來自列表輸出）。 優先於 --app。 |
quiet |
boolean \| undefined |
No | 隱藏進度訊息。 |
verbose |
boolean \| undefined |
No | 啟用冗長輸出。 |
cwd |
string \| undefined |
No | CLI 程序的工作目錄（預設為 process.cwd（））。 |
UiScrollIntoViewOptions
| 房產 | 類型 | 為必填項目 | Description |
|---|---|---|---|
selector |
string \| undefined |
No | 語意片段（例如 btn-minimize-d1a0）或根據名稱/automationId 搜尋的文字 |
app |
string \| undefined |
No | 目標應用程式（程序名稱、視窗標題或 PID）。 如果有歧義，會列出視窗。 |
json |
boolean \| undefined |
No | 格式輸出為 JSON |
window |
number \| undefined |
No | 透過 HWND（列表輸出的穩定 handle）來鎖定目標視窗。 該指令優先於 --app。 |
quiet |
boolean \| undefined |
No | 隱藏進度消息。 |
verbose |
boolean \| undefined |
No | 啟用冗長輸出。 |
cwd |
string \| undefined |
No | CLI 程序的工作目錄（預設為 process.cwd（））。 |
UiSearchOptions
| 房產 | 類型 | 為必填項目 | Description |
|---|---|---|---|
selector |
string \| undefined |
No | 語義字串（例如 btn-minimize-d1a0）或以名稱/automationId 搜尋的文字 |
app |
string \| undefined |
No | 目標應用程式（程序名稱、視窗標題或 PID）。 當有不明確情況時，會列出視窗。 |
json |
boolean \| undefined |
No | 格式輸出為 JSON |
max |
number \| undefined |
No | 最大搜尋結果 |
window |
number \| undefined |
No | 目標視窗使用 HWND 來指定（穩定的 handle 來自列表輸出）。 此設定優先於 --app。 |
quiet |
boolean \| undefined |
No | 抑制進度訊息。 |
verbose |
boolean \| undefined |
No | 啟用冗長輸出。 |
cwd |
string \| undefined |
No | CLI 程序的工作目錄（預設為 process.cwd（））。 |
UiSetValueOptions
| 房產 | 類型 | 為必填項目 | Description |
|---|---|---|---|
selector |
string \| undefined |
No | 語義短句（例如 btn-minimize-d1a0）或按名稱/automationId 搜尋的文字 |
value |
string \| undefined |
No | 要設定的數值（TextBox/ComboBox 的文字，滑桿的數字） |
app |
string \| undefined |
No | 目標應用程式（程序名稱、視窗標題或 PID）。 如果有歧義，會列出視窗。 |
json |
boolean \| undefined |
No | 格式輸出為 JSON |
window |
number \| undefined |
No | 目標視窗由 HWND 建立（穩定 handle 來自列表輸出）。 優先於 --app。 |
quiet |
boolean \| undefined |
No | 抑制進度訊息。 |
verbose |
boolean \| undefined |
No | 啟用冗長輸出。 |
cwd |
string \| undefined |
No | CLI 程序的工作目錄（預設為 process.cwd（））。 |
UiStatusOptions
| 房產 | 類型 | 為必填項目 | Description |
|---|---|---|---|
app |
string \| undefined |
No | 目標應用程式（程序名稱、視窗標題或 PID）。 如果有歧義，會列出視窗。 |
json |
boolean \| undefined |
No | 格式輸出為 JSON |
window |
number \| undefined |
No | 透過 HWND 取得目標視窗（穩定把柄來自列表輸出）。 優先於 --app。 |
quiet |
boolean \| undefined |
No | 隱藏進度訊息。 |
verbose |
boolean \| undefined |
No | 啟用冗長輸出。 |
cwd |
string \| undefined |
No | CLI 程序的工作目錄（預設為 process.cwd（））。 |
UiWaitForOptions
| 房產 | 類型 | 為必填項目 | Description |
|---|---|---|---|
selector |
string \| undefined |
No | 語義子串（例如 btn-minimize-d1a0）或以名稱/自動化ID搜尋的文字 |
app |
string \| undefined |
No | 目標應用程式（程序名稱、視窗標題或 PID）。 如果有歧義，會列出窗戶。 |
contains |
boolean \| undefined |
No | 使用子字串匹配 --value，而非完全匹配 |
gone |
boolean \| undefined |
No | 等待元素消失而非出現 |
json |
boolean \| undefined |
No | 格式輸出為 JSON |
property |
string \| undefined |
No | 要閱讀或篩選的屬性名稱 |
timeout |
number \| undefined |
No | 以毫秒計時 |
value |
string \| undefined |
No | 等待元素值等於這個字串。 使用智慧回退機制（TextPattern -> ValuePattern -> 名稱）。 將 ---property 結合，以檢查特定房產。 |
window |
number \| undefined |
No | 目標視窗以 HWND 為標識（穩定的窗口控制碼來源自列表輸出）。 優先於 --app。 |
quiet |
boolean \| undefined |
No | 抑制進度訊息。 |
verbose |
boolean \| undefined |
No | 啟用冗長輸出。 |
cwd |
string \| undefined |
No | CLI 程序的工作目錄（預設為 process.cwd（））。 |
UnregisterOptions
| 房產 | 類型 | 為必填項目 | Description |
|---|---|---|---|
force |
boolean \| undefined |
No | 跳過安裝位置目錄檢查，即使套件是從其他專案樹註冊，也要取消註冊 |
json |
boolean \| undefined |
No | 格式輸出為 JSON |
manifest |
string \| undefined |
No | Package.appxmanifest 的路徑（預設：自動偵測自目前目錄） |
quiet |
boolean \| undefined |
No | 抑制進度訊息。 |
verbose |
boolean \| undefined |
No | 啟用冗長輸出。 |
cwd |
string \| undefined |
No | CLI 程序的工作目錄（預設為 process.cwd（））。 |
UpdateOptions
| 房產 | 類型 | 為必填項目 | Description |
|---|---|---|---|
setupSdks |
SdkInstallMode \| undefined |
No | SDK 安裝模式：「stable」（預設）、 「preview」、「experimental」或「none」（跳過 SDK 安裝） |
quiet |
boolean \| undefined |
No | 隱藏進度訊息。 |
verbose |
boolean \| undefined |
No | 啟用冗長輸出。 |
cwd |
string \| undefined |
No | CLI 程序的工作目錄（預設為 process.cwd（））。 |
