@microsoft/winappcli的 TypeScript/JavaScript API 参考。
每个 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 的选项对象，并返回 Promise<WinappResult>。
CommonOptions
大多数命令共享的基本选项。
| 财产 | 类型 | 必需 | Description |
|---|---|---|---|
quiet |
boolean \| undefined |
否 | 禁止显示进度消息。 |
verbose |
boolean \| undefined |
否 | 启用详细输出。 |
cwd |
string \| undefined |
否 | CLI 进程的工作目录（默认为 process.cwd（））。 |
WinappResult
每个命令封装器返回的结果。
| 财产 | 类型 | 必需 | Description |
|---|---|---|---|
exitCode |
number |
是的 | 进程退出代码（成功时始终为 0 – 非零抛出异常）。 |
stdout |
string |
是的 | 捕获的标准输出。 |
stderr |
string |
是的 | 捕获标准误差。 |
CLI 命令包装器
这些函数封装本机 winapp CLI（命令行接口） 命令。 所有接受 CommonOptions （quiet， ， verbosecwd） 。
certGenerate()
仅创建用于本地测试的自签名证书。 Publisher必须与清单匹配（如果 --manifest 提供或 Package.appxmanifest 位于工作目录中，则自动推断）。 输出：devcert.pfx（默认密码：“password”）。 对于生产，请从受信任的 CA 获取证书。 使用“cert install”命令在此计算机上安装并信任证书。
function certGenerate(options?: CertGenerateOptions): Promise<WinappResult>
选项：
| 财产 | 类型 | 必需 | Description |
|---|---|---|---|
exportCer |
boolean \| undefined |
否 | 将.cer文件（仅公钥）与 .pfx 一起导出 |
ifExists |
IfExists \| undefined |
否 | 输出文件存在时的行为：“error”（失败、默认值）、“skip”（保留现有文件）或“overwrite”（替换） |
install |
boolean \| undefined |
否 | 生成后将证书安装到本地计算机存储 |
json |
boolean \| undefined |
否 | 将输出格式设置为 JSON |
manifest |
string \| undefined |
否 | Package.appxmanifest 或 appxmanifest.xml 文件的路径，用于从中提取发布者信息 |
output |
string \| undefined |
否 | 生成的 PFX 文件的输出路径 |
password |
string \| undefined |
否 | 生成的 PFX 文件的密码 |
publisher |
string \| undefined |
否 | 生成的证书的发布者名称。 如果未指定，将从清单推断出来。 |
validDays |
number \| undefined |
否 | 证书有效天数 |
也接受 CommonOptions （quiet， ， verbosecwd） 。
certInfo()
显示证书详细信息（使用者、指纹、到期）。 在签名之前，验证证书与清单是否匹配非常有用。
function certInfo(options: CertInfoOptions): Promise<WinappResult>
选项：
| 财产 | 类型 | 必需 | Description |
|---|---|---|---|
certPath |
string |
是的 | 证书文件的路径（PFX） |
json |
boolean \| undefined |
否 | 将输出格式设置为 JSON |
password |
string \| undefined |
否 | PFX 文件的密码 |
也接受 CommonOptions （quiet， ， verbosecwd） 。
certInstall()
信任此计算机上的证书（需要管理员）。 在安装使用开发证书签名的 MSIX 包之前运行。 示例：winapp 证书安装 ./devcert.pfx。 每个证书只需要一次。
function certInstall(options: CertInstallOptions): Promise<WinappResult>
选项：
| 财产 | 类型 | 必需 | Description |
|---|---|---|---|
certPath |
string |
是的 | 证书文件的路径（PFX 或 CER） |
force |
boolean \| undefined |
否 | 强制安装，即使证书已存在 |
password |
string \| undefined |
否 | PFX 文件的密码 |
也接受 CommonOptions （quiet， ， verbosecwd） 。
createDebugIdentity()
启用包标识进行调试，而无需创建完整的 MSIX。 在开发期间测试Windows API（推送通知、共享目标等）时需要。 示例：winapp create-debug-identity ./myapp.exe。 需要当前目录中的 Package.appxmanifest 或 appxmanifest.xml，或者通过 --manifest 传递。 更改清单或 Assets/ 目录后重新运行。
function createDebugIdentity(options?: CreateDebugIdentityOptions): Promise<WinappResult>
选项：
| 财产 | 类型 | 必需 | Description |
|---|---|---|---|
entrypoint |
string \| undefined |
否 | 运行时需要附带身份验证或入口点脚本的 .exe 文件路径。 |
keepIdentity |
boolean \| undefined |
否 | 将包标识从清单中原样保留，不要将“.debug”追加到包名称和应用程序 ID 中。 |
manifest |
string \| undefined |
否 | Package.appxmanifest 或 appxmanifest.xml 的路径 |
noInstall |
boolean \| undefined |
否 | 创建后不要安装包。 |
也接受 CommonOptions （quiet， ， verbosecwd） 。
createExternalCatalog()
使用指定目录中的可执行文件哈希生成 CodeIntegrityExternal.cat 目录文件。 与 MSIX 稀疏包清单（AllowExternalContent）中的 TrustedLaunch 标志一起使用，以允许执行包中不包含的外部文件。
function createExternalCatalog(options: CreateExternalCatalogOptions): Promise<WinappResult>
选项：
| 财产 | 类型 | 必需 | Description |
|---|---|---|---|
inputFolder |
string |
是的 | 包含要处理的可执行文件的输入文件夹列表（用分号分隔） |
computeFlatHashes |
boolean \| undefined |
否 | 生成目录时包括平面哈希 |
ifExists |
IfExists \| undefined |
否 | 输出文件已存在时的行为 |
output |
string \| undefined |
否 | 输出目录文件路径。 如果未指定，则使用默认 CodeIntegrityExternal.cat 名称。 |
recursive |
boolean \| undefined |
否 | 包含子目录中的文件 |
usePageHashes |
boolean \| undefined |
否 | 生成目录时包括页哈希 |
也接受 CommonOptions （quiet， ， verbosecwd） 。
getWinappPath()
打印 .winapp 目录的路径。 对共享缓存位置使用 --global，或省略项目本地 .winapp 文件夹。 对于需要引用已安装包的生成脚本非常有用。
function getWinappPath(options?: GetWinappPathOptions): Promise<WinappResult>
选项：
| 财产 | 类型 | 必需 | Description |
|---|---|---|---|
global |
boolean \| undefined |
否 | 获取全局 .winapp 目录而不是本地目录 |
也接受 CommonOptions （quiet， ， verbosecwd） 。
init()
在这里开始用所需的设置初始化Windows应用程序。 设置Windows应用开发所需的所有内容：使用默认资产创建 Package.appxmanifest、下载Windows SDK 和Windows 应用 SDK包，并生成投影。 当 SDK 包通过 --setup-sdks stable/preview/experimental 进行管理时，还会创建 winapp.yaml，以固定 'restore' 和 'update' 的版本；如果使用 --setup-sdks none（例如，对于自带 SDK 绑定的 Rust/Tauri 项目），则不会创建 winapp.yaml。 默认启用交互功能（使用 --use-defaults 可跳过提示）。 如果克隆了已具有 winapp.yaml 的存储库，请使用“恢复”命令。 如果只需要清单，请使用“清单生成”;如果需要用于代码签名的开发证书，请使用“证书生成”。
function init(options?: InitOptions): Promise<WinappResult>
选项：
| 财产 | 类型 | 必需 | Description |
|---|---|---|---|
baseDirectory |
string \| undefined |
否 | winapp 工作区的基/根目录，供使用或安装。 |
configDir |
string \| undefined |
否 | 要读取/存储配置的目录（默认值：当前目录） |
configOnly |
boolean \| undefined |
否 | 仅处理配置文件的操作（如果缺少，则创建；如果存在，则验证）。 跳过包安装和其他工作区安装步骤。 |
ignoreConfig |
boolean \| undefined |
否 | 不要将配置文件用于版本管理 |
noGitignore |
boolean \| undefined |
否 | 不要更新 .gitignore 文件 |
setupSdks |
SdkInstallMode \| undefined |
否 | SDK 安装模式：“stable”（默认值）、“预览”、“实验”或“none”（跳过 SDK 安装） |
useDefaults |
boolean \| undefined |
否 | 不提示，默认使用所有提示的默认值 |
也接受 CommonOptions （quiet， ， verbosecwd） 。
manifestAddAlias()
将执行别名（uap5：AppExecutionAlias）添加到 Package.appxmanifest。 这允许通过键入别名从命令行启动打包的应用。 默认情况下，别名是从可执行文件属性推断的（例如，$targetnametoken$.exe 变为 $targetnametoken$.exe 别名）。
function manifestAddAlias(options?: ManifestAddAliasOptions): Promise<WinappResult>
选项：
| 财产 | 类型 | 必需 | Description |
|---|---|---|---|
appId |
string \| undefined |
否 | 要向其添加别名的应用程序 ID（默认值：第一个应用程序元素） |
manifest |
string \| undefined |
否 | Package.appxmanifest 或 appxmanifest.xml 文件的路径（默认值：搜索当前目录） |
name |
string \| undefined |
否 | 别名（例如，'myapp.exe'）。 默认值：从清单中的可执行文件属性推断。 |
也接受 CommonOptions （quiet， ， verbosecwd） 。
manifestGenerate()
在没有完整项目设置的情况下创建 Package.appxmanifest。 仅当需要清单和映像资产（无 SDK、无证书）时使用。 对于完整设置，请改用“init”。 模板：“打包”（完整的 MSIX）、“稀疏”（需要Windows API 的桌面应用）。
function manifestGenerate(options?: ManifestGenerateOptions): Promise<WinappResult>
选项：
| 财产 | 类型 | 必需 | Description |
|---|---|---|---|
directory |
string \| undefined |
否 | 要在其中生成清单的目录 |
description |
string \| undefined |
否 | 安装和Windows设置中显示的人工可读应用说明 |
executable |
string \| undefined |
否 | 应用程序的可执行文件的路径。 默认值： <包名称>.exe |
ifExists |
IfExists \| undefined |
否 | 输出文件存在时的行为：“error”（失败、默认值）、“skip”（保留现有文件）或“overwrite”（替换） |
logoPath |
string \| undefined |
否 | 徽标图像文件的路径 |
packageName |
string \| undefined |
否 | 包名称（默认：文件夹名称） |
publisherName |
string \| undefined |
否 | Publisher CN （默认值：CN=<当前用户>） |
template |
ManifestTemplates \| undefined |
否 | 清单模板类型：“打包”（完整的 MSIX 应用、默认值）或“稀疏”（具有适用于 Windows API 的包标识的桌面应用） |
version |
string \| undefined |
否 | 应用版本采用 Major.Minor.Build.Revision 格式（例如 1.0.0.0）。 |
也接受 CommonOptions （quiet， ， verbosecwd） 。
manifestUpdateAssets()
为 Package.appxmanifest 中引用的图像从单个源映像生成新资产。 源图像应至少为 400x400 像素。
function manifestUpdateAssets(options: ManifestUpdateAssetsOptions): Promise<WinappResult>
选项：
| 财产 | 类型 | 必需 | Description |
|---|---|---|---|
imagePath |
string |
是的 | 源图像文件的路径（SVG、PNG、ICO、JPG、BMP、GIF） |
lightImage |
string \| undefined |
否 | 浅色主题变体的源图像路径（SVG、PNG、ICO、JPG、BMP、GIF） |
manifest |
string \| undefined |
否 | Package.appxmanifest 或 appxmanifest.xml 文件的路径（默认值：搜索当前目录） |
也接受 CommonOptions （quiet， ， verbosecwd） 。
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 |
是的 | 具有包布局的输入文件夹 |
cert |
string \| undefined |
否 | 签名证书的路径（如果提供，将会自动签名） |
certPassword |
string \| undefined |
否 | 证书密码（默认值：密码） |
executable |
string \| undefined |
否 | 相对于输入文件夹的可执行文件的路径。 |
generateCert |
boolean \| undefined |
否 | 生成新的开发证书 |
installCert |
boolean \| undefined |
否 | 将证书安装到计算机 |
manifest |
string \| undefined |
否 | AppX 清单文件的路径（默认值：从输入文件夹或当前目录自动检测） |
name |
string \| undefined |
否 | 包名（默认值：从清单中获取） |
output |
string \| undefined |
否 | 生成包的输出 msix 文件名（默认为<name><version><arch>.msix；如果无法确定版本或架构，则依次回退为 <name><version>.msix、<name><arch>.msix 或 <name>.msix） |
publisher |
string \| undefined |
否 | 生成证书的发布者名称 |
selfContained |
boolean \| undefined |
否 | 用于独立部署的捆绑Windows 应用 SDK运行时 |
skipPri |
boolean \| undefined |
否 | 跳过 PRI 文件生成 |
也接受 CommonOptions （quiet， ， verbosecwd） 。
restore()
克隆存储库或缺少 .winapp/ 文件夹后使用。 从现有的 winapp.yaml 重新安装 SDK 包，而无需更改版本。 需要 winapp.yaml（由“init”创建）。 若要检查更新的 SDK 版本，请改用“更新”。
function restore(options?: RestoreOptions): Promise<WinappResult>
选项：
| 财产 | 类型 | 必需 | Description |
|---|---|---|---|
baseDirectory |
string \| undefined |
否 | winapp 工作区的基/根目录 |
configDir |
string \| undefined |
否 | 要从中读取配置的目录（默认值：当前目录） |
也接受 CommonOptions （quiet， ， verbosecwd） 。
run()
创建打包布局、注册应用程序并启动打包的应用程序。
function run(options: RunOptions): Promise<WinappResult>
选项：
| 财产 | 类型 | 必需 | Description |
|---|---|---|---|
inputFolder |
string |
是的 | 包含要运行的应用的输入文件夹 |
args |
string \| undefined |
否 | 要传递给应用程序的命令行参数 |
clean |
boolean \| undefined |
否 | 重新部署之前，请删除现有包的应用程序数据（LocalState、设置等）。 默认情况下，应用程序数据会在重新部署之间保留。 |
debugOutput |
boolean \| undefined |
否 | 从启动的应用程序中捕获 OutputDebugString 消息和首次机会异常。 一次只能有一个调试器附加到进程，因此不能同时使用其他调试器（Visual Studio，VS Code）。 如果需要附加其他调试器，请改用 --no-launch。 不能与 --no-launch 或 --json 结合使用。 |
detach |
boolean \| undefined |
否 | 启动应用程序并立即返回，无需等待它退出。 在启动后需要与应用交互的 CI/自动化非常有用。 将 PID 打印到 stdout（或使用 --json 在 JSON 中）。 |
json |
boolean \| undefined |
否 | 将输出格式设置为 JSON |
manifest |
string \| undefined |
否 | Package.appxmanifest 的路径（默认值：从输入文件夹或当前目录自动检测） |
noLaunch |
boolean \| undefined |
否 | 仅创建调试标识并注册包而不启动应用程序 |
outputAppxDirectory |
string \| undefined |
否 | 松散布局包的输出目录。 如果未指定，将使用输入文件夹目录中名为 AppX 的目录。 |
symbols |
boolean \| undefined |
否 | 从 Microsoft Symbol Server 下载符号，以便进行更丰富的本机故障分析。 仅用于 --debug-output。 首先运行下载符号并将其缓存在本地;后续运行使用缓存。 |
unregisterOnExit |
boolean \| undefined |
否 | 请在应用程序退出后注销开发包。 仅删除在开发模式下注册的包。 |
withAlias |
boolean \| undefined |
否 | 使用其执行别名而不是 AUMID 激活启动应用。 应用在当前终端中运行，继承了 stdin/stdout/stderr。 清单中需要 uap5：ExecutionAlias。 使用“winapp manifest add-alias”将执行别名添加到清单。 |
也接受 CommonOptions （quiet， ， verbosecwd） 。
sign()
对 MSIX 包或可执行文件进行代码签名。 示例：winapp sign ./app.msix ./devcert.pfx。 对生产版本使用 --timestamp 在证书过期后保持有效。 “package”命令可以使用 --cert 自动签名。
function sign(options: SignOptions): Promise<WinappResult>
选项：
| 财产 | 类型 | 必需 | Description |
|---|---|---|---|
filePath |
string |
是的 | 要签名的文件/包的路径 |
certPath |
string |
是的 | 证书文件的路径（PFX 格式） |
password |
string \| undefined |
否 | 证书密码 |
timestamp |
string \| undefined |
否 | 时间戳服务器地址 |
也接受 CommonOptions （quiet， ， verbosecwd） 。
store()
运行 Microsoft Store 开发人员 CLI 命令。 此命令将下载Microsoft Store开发人员 CLI（如果尚未下载）。 在此处了解有关Microsoft Store开发人员 CLI 的详细信息：https://aka.ms/msstoredevcli
function store(options?: StoreOptions): Promise<WinappResult>
选项：
| 财产 | 类型 | 必需 | Description |
|---|---|---|---|
storeArgs |
string[] \| undefined |
否 | 要传递给Microsoft Store开发人员 CLI 的参数。 |
也接受 CommonOptions （quiet， ， verbosecwd） 。
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 |
否 | 要传递给 SDK 工具的参数，例如 ['makeappx'、'pack'、'/d'、'./folder'、'/p'、'./out.msix']。 |
也接受 CommonOptions （quiet， ， verbosecwd） 。
uiClick()
使用鼠标模拟单击元素或文本搜索。 适用于不支持 InvokePattern 的元素（例如列标题、列表项）。 使用 --double 表示双击，--right 表示右键单击。
function uiClick(options?: UiClickOptions): Promise<WinappResult>
选项：
| 财产 | 类型 | 必需 | Description |
|---|---|---|---|
selector |
string \| undefined |
否 | 语义 slug（例如 btn-minimize-d1a0）或根据名称/AutomationId 进行搜索的文本 |
app |
string \| undefined |
否 | 目标应用（进程名称、窗口标题或 PID）。 如果有歧义，列出窗口。 |
double |
boolean \| undefined |
否 | 进行双击而不是单击 |
json |
boolean \| undefined |
否 | 将输出格式设置为 JSON |
right |
boolean \| undefined |
否 | 执行右键单击而不是左键单击 |
window |
number \| undefined |
否 | 通过 HWND 获取目标窗口（来自列表输出的稳定句柄）。 优先于 --app。 |
也接受 CommonOptions （quiet， ， verbosecwd） 。
uiFocus()
使用 UIA SetFocus 将键盘焦点移动到指定元素。
function uiFocus(options?: UiFocusOptions): Promise<WinappResult>
选项：
| 财产 | 类型 | 必需 | Description |
|---|---|---|---|
selector |
string \| undefined |
否 | 语义标识符（例如 btn-minimize-d1a0）或根据名称/automationId 搜索的文本 |
app |
string \| undefined |
否 | 目标应用（进程名称、窗口标题或 PID）。 列出窗口（如果存在歧义）。 |
json |
boolean \| undefined |
否 | 将输出格式设置为 JSON |
window |
number \| undefined |
否 | 通过 HWND 来定位目标窗口（来自列表输出的稳定句柄）。 优先于 --app。 |
也接受 CommonOptions （quiet， ， verbosecwd） 。
uiGetFocused()
显示当前在目标应用中具有键盘焦点的元素。
function uiGetFocused(options?: UiGetFocusedOptions): Promise<WinappResult>
选项：
| 财产 | 类型 | 必需 | Description |
|---|---|---|---|
app |
string \| undefined |
否 | 目标应用（进程名称、窗口标题或 PID）。 如果存在歧义，则列出窗口。 |
json |
boolean \| undefined |
否 | 将输出格式设置为 JSON |
window |
number \| undefined |
否 | HWND 的目标窗口（列表输出中的稳定句柄）。 优先于 --app。 |
也接受 CommonOptions （quiet， ， verbosecwd） 。
uiGetProperty()
从元素读取 UIA 属性值。 指定 --property 以用于单个属性，或省略以应用于所有属性。
function uiGetProperty(options?: UiGetPropertyOptions): Promise<WinappResult>
选项：
| 财产 | 类型 | 必需 | Description |
|---|---|---|---|
selector |
string \| undefined |
否 | 语义标识符（例如 btn-minimize-d1a0）或根据名称/automationId 搜索的文本 |
app |
string \| undefined |
否 | 目标应用（进程名称、窗口标题或 PID）。 如果存在歧义，则列出窗口。 |
json |
boolean \| undefined |
否 | 将输出格式设置为 JSON |
property |
string \| undefined |
否 | 要读取或筛选的属性名称 |
window |
number \| undefined |
否 | HWND 的目标窗口（列表输出中的稳定句柄）。 优先于 --app。 |
也接受 CommonOptions （quiet， ， verbosecwd） 。
uiGetValue()
从元素读取当前值。 尝试 TextPattern（RichEditBox、Document）、ValuePattern（TextBox、ComboBox、Slider），然后尝试 Name（标签）。 用法：winapp ui get-value <selector> -a <app>
function uiGetValue(options?: UiGetValueOptions): Promise<WinappResult>
选项：
| 财产 | 类型 | 必需 | Description |
|---|---|---|---|
selector |
string \| undefined |
否 | 语义标识符（例如 btn-minimize-d1a0）或根据名称/automationId 搜索的文本 |
app |
string \| undefined |
否 | 目标应用（进程名称、窗口标题或 PID）。 如果存在歧义，则列出窗口。 |
json |
boolean \| undefined |
否 | 将输出格式设置为 JSON |
window |
number \| undefined |
否 | HWND 的目标窗口（列表输出中的稳定句柄）。 优先于 --app。 |
也接受 CommonOptions （quiet， ， verbosecwd） 。
uiInspect()
查看包含语义标识符、元素类型、名称和边界的 UI 元素树。
function uiInspect(options?: UiInspectOptions): Promise<WinappResult>
选项：
| 财产 | 类型 | 必需 | Description |
|---|---|---|---|
selector |
string \| undefined |
否 | 语义标识符（例如 btn-minimize-d1a0）或根据名称/automationId 搜索的文本 |
ancestors |
boolean \| undefined |
否 | 从指定的元素向上遍历树直到根节点 |
app |
string \| undefined |
否 | 目标应用（进程名称、窗口标题或 PID）。 如果存在歧义，则列出窗口。 |
depth |
number \| undefined |
否 | 树检查深度 |
hideDisabled |
boolean \| undefined |
否 | 隐藏输出中禁用的元素 |
hideOffscreen |
boolean \| undefined |
否 | 隐藏输出中的屏幕外元素 |
interactive |
boolean \| undefined |
否 | 仅显示交互式/可调用元素（按钮、链接、输入、列表项）。 将默认深度增加到 8。 |
json |
boolean \| undefined |
否 | 将输出格式设置为 JSON |
window |
number \| undefined |
否 | HWND 的目标窗口（列表输出中的稳定句柄）。 优先于 --app。 |
也接受 CommonOptions （quiet， ， verbosecwd） 。
uiInvoke()
通过 slug 或文本搜索激活元素。 按顺序尝试 InvokePattern、TogglePattern、SelectionItemPattern 和 ExpandCollapsePattern。
function uiInvoke(options?: UiInvokeOptions): Promise<WinappResult>
选项：
| 财产 | 类型 | 必需 | Description |
|---|---|---|---|
selector |
string \| undefined |
否 | 语义标识符（例如 btn-minimize-d1a0）或根据名称/automationId 搜索的文本 |
app |
string \| undefined |
否 | 目标应用（进程名称、窗口标题或 PID）。 如果存在歧义，则列出窗口。 |
json |
boolean \| undefined |
否 | 将输出格式设置为 JSON |
window |
number \| undefined |
否 | HWND 的目标窗口（列表输出中的稳定句柄）。 优先于 --app。 |
也接受 CommonOptions （quiet， ， verbosecwd） 。
uiListWindows()
列出所有可见窗口及其 HWND、标题、进程和大小。 使用 -a 按应用名称进行筛选。 使用 HWND 和 -w 以目标为一个特定窗口。
function uiListWindows(options?: UiListWindowsOptions): Promise<WinappResult>
选项：
| 财产 | 类型 | 必需 | Description |
|---|---|---|---|
app |
string \| undefined |
否 | 目标应用（进程名称、窗口标题或 PID）。 如果存在歧义，则列出窗口。 |
json |
boolean \| undefined |
否 | 将输出格式设置为 JSON |
也接受 CommonOptions （quiet， ， verbosecwd） 。
uiScreenshot()
将目标窗口或元素捕获为 PNG 图像。 当存在多个窗口（例如对话框）时，将每个窗口捕获到单独的文件中。 使用 --json，返回文件路径和维度。 对弹出窗口覆盖使用 --capture-screen。
function uiScreenshot(options?: UiScreenshotOptions): Promise<WinappResult>
选项：
| 财产 | 类型 | 必需 | Description |
|---|---|---|---|
selector |
string \| undefined |
否 | 语义标识符（例如 btn-minimize-d1a0）或根据名称/automationId 搜索的文本 |
app |
string \| undefined |
否 | 目标应用（进程名称、窗口标题或 PID）。 如果存在歧义，则列出窗口。 |
captureScreen |
boolean \| undefined |
否 | 从屏幕捕获（包括弹出窗口/覆盖），而不是窗口渲染。 首先将窗口置于前台。 |
json |
boolean \| undefined |
否 | 将输出格式设置为 JSON |
output |
string \| undefined |
否 | 将输出保存到文件路径（例如屏幕截图） |
window |
number \| undefined |
否 | HWND 的目标窗口（列表输出中的稳定句柄）。 优先于 --app。 |
也接受 CommonOptions （quiet， ， verbosecwd） 。
uiScroll()
使用 ScrollPattern 滚动容器元素。 使用 --direction 逐步滚动，或使用 --to 一键跳转到顶部/底部。
function uiScroll(options?: UiScrollOptions): Promise<WinappResult>
选项：
| 财产 | 类型 | 必需 | Description |
|---|---|---|---|
selector |
string \| undefined |
否 | 语义标识符（例如 btn-minimize-d1a0）或根据名称/automationId 搜索的文本 |
app |
string \| undefined |
否 | 目标应用（进程名称、窗口标题或 PID）。 如果存在歧义，则列出窗口。 |
direction |
string \| undefined |
否 | 滚动方向：向上、向下、向左、向右滚动 |
json |
boolean \| undefined |
否 | 将输出格式设置为 JSON |
to |
string \| undefined |
否 | 滚动至位置：顶部和底部 |
window |
number \| undefined |
否 | HWND 的目标窗口（列表输出中的稳定句柄）。 优先于 --app。 |
也接受 CommonOptions （quiet， ， verbosecwd） 。
uiScrollIntoView()
使用 UIA ScrollItemPattern 将指定的元素滚动到可见区域。
function uiScrollIntoView(options?: UiScrollIntoViewOptions): Promise<WinappResult>
选项：
| 财产 | 类型 | 必需 | Description |
|---|---|---|---|
selector |
string \| undefined |
否 | 语义标识符（例如 btn-minimize-d1a0）或根据名称/automationId 搜索的文本 |
app |
string \| undefined |
否 | 目标应用（进程名称、窗口标题或 PID）。 如果存在歧义，则列出窗口。 |
json |
boolean \| undefined |
否 | 将输出格式设置为 JSON |
window |
number \| undefined |
否 | HWND 的目标窗口（列表输出中的稳定句柄）。 优先于 --app。 |
也接受 CommonOptions （quiet， ， verbosecwd） 。
uiSearch()
在元素树中搜索与文本查询匹配的元素。 返回所有与语义短语匹配的结果。
function uiSearch(options?: UiSearchOptions): Promise<WinappResult>
选项：
| 财产 | 类型 | 必需 | Description |
|---|---|---|---|
selector |
string \| undefined |
否 | 语义标识符（例如 btn-minimize-d1a0）或根据名称/automationId 搜索的文本 |
app |
string \| undefined |
否 | 目标应用（进程名称、窗口标题或 PID）。 如果存在歧义，则列出窗口。 |
json |
boolean \| undefined |
否 | 将输出格式设置为 JSON |
max |
number \| undefined |
否 | 最多搜索结果 |
window |
number \| undefined |
否 | HWND 的目标窗口（列表输出中的稳定句柄）。 优先于 --app。 |
也接受 CommonOptions （quiet， ， verbosecwd） 。
uiSetValue()
使用 UIA ValuePattern 在元素上设置值。 适用于 TextBox、ComboBox、Slider 和其他可编辑控件。 用法：winapp ui set-value <selector><value> -a <应用>
function uiSetValue(options?: UiSetValueOptions): Promise<WinappResult>
选项：
| 财产 | 类型 | 必需 | Description |
|---|---|---|---|
selector |
string \| undefined |
否 | 语义标识符（例如 btn-minimize-d1a0）或根据名称/automationId 搜索的文本 |
value |
string \| undefined |
否 | 要设置的值（用于文本框/组合框的文本，用于滑块的数字） |
app |
string \| undefined |
否 | 目标应用（进程名称、窗口标题或 PID）。 列出窗口（如果出现歧义） |
json |
boolean \| undefined |
否 | 将输出格式设置为 JSON |
window |
number \| undefined |
否 | HWND 的目标窗口（列表输出中的稳定句柄）。 优先于 --app。 |
也接受 CommonOptions （quiet， ， verbosecwd） 。
uiStatus()
连接到目标应用并显示连接信息。
function uiStatus(options?: UiStatusOptions): Promise<WinappResult>
选项：
| 财产 | 类型 | 必需 | Description |
|---|---|---|---|
app |
string \| undefined |
否 | 目标应用（进程名称、窗口标题或 PID）。 如果有歧义，列出窗口。 |
json |
boolean \| undefined |
否 | 将输出格式设置为 JSON |
window |
number \| undefined |
否 | 通过 HWND 窗口句柄来定位目标窗口（来自列表输出的稳定句柄）。 优先于 --app。 |
也接受 CommonOptions （quiet， ， verbosecwd） 。
uiWaitFor()
等待元素出现、消失或让属性达到目标值。 每隔 100 毫秒轮询一次，直到条件满足或超时。
function uiWaitFor(options?: UiWaitForOptions): Promise<WinappResult>
选项：
| 财产 | 类型 | 必需 | Description |
|---|---|---|---|
selector |
string \| undefined |
否 | 语义标识符（例如 btn-minimize-d1a0）或按名称、AutomationId 搜索的文本 |
app |
string \| undefined |
否 | 目标应用（进程名称、窗口标题或 PID）。 列出窗口（如果有歧义）。 |
contains |
boolean \| undefined |
否 | 对于 --value，请使用子字符串匹配而不是完全匹配。 |
gone |
boolean \| undefined |
否 | 等待元素消失而不是出现 |
json |
boolean \| undefined |
否 | 将输出格式设置为 JSON |
property |
string \| undefined |
否 | 要读取或筛选的属性名称 |
timeout |
number \| undefined |
否 | 超时（以毫秒为单位） |
value |
string \| undefined |
否 | 等待元素值等于此字符串。 使用智能回退（TextPattern -> ValuePattern -> Name）。 请与 --property 搭配使用以检查特定属性。 |
window |
number \| undefined |
否 | 通过 HWND 定位目标窗口（列表输出中的稳定句柄）。 优先于 --app。 |
也接受 CommonOptions （quiet， ， verbosecwd） 。
unregister()
注销旁加载的开发包。 仅删除在开发模式下注册的包（例如，通过“winapp run”或“create-debug-identity”）。
function unregister(options?: UnregisterOptions): Promise<WinappResult>
选项：
| 财产 | 类型 | 必需 | Description |
|---|---|---|---|
force |
boolean \| undefined |
否 | 跳过安装位置目录检查并取消注册，即使包是从其他项目树注册的 |
json |
boolean \| undefined |
否 | 将输出格式设置为 JSON |
manifest |
string \| undefined |
否 | Package.appxmanifest 的路径（默认值：从当前目录自动检测） |
也接受 CommonOptions （quiet， ， verbosecwd） 。
update()
检查并安装较新的 SDK 版本。 使用最新版本更新 winapp.yaml 并重新安装包。 需要现有的 winapp.yaml（由“init”创建）。 使用 --setup-sdks 预览版 来获取预览版 SDK。 若要在不更新的情况下重新安装当前版本，请改用“还原”。
function update(options?: UpdateOptions): Promise<WinappResult>
选项：
| 财产 | 类型 | 必需 | Description |
|---|---|---|---|
setupSdks |
SdkInstallMode \| undefined |
否 | SDK 安装模式：“stable”（默认值）、“预览”、“实验”或“none”（跳过 SDK 安装） |
也接受 CommonOptions （quiet， ， verbosecwd） 。
实用函数
execWithBuildTools()
将 BuildTools 的 bin 路径添加到 PATH 环境后执行命令。
function execWithBuildTools(command: string, options?: ExecSyncOptions): string | Buffer<ArrayBufferLike>
参数：
| 参数 | 类型 | 必需 | Description |
|---|---|---|---|
command |
string |
是的 | 要执行的命令 |
options |
ExecSyncOptions |
否 | 传递给 execSync 的选项（可选） |
返回： “execSync”的输出
addMsixIdentityToExe()
将 appxmanifest.xml 文件中的包标识信息添加到可执行文件的嵌入清单
function addMsixIdentityToExe(exePath: string, appxManifestPath?: string | undefined, options?: MsixIdentityOptions): Promise<MsixIdentityResult>
参数：
| 参数 | 类型 | 必需 | Description |
|---|---|---|---|
exePath |
string |
是的 | 可执行文件的路径 |
appxManifestPath |
string \| undefined |
否 | 包含包标识数据的 appxmanifest.xml 文件的路径 |
options |
MsixIdentityOptions |
否 | 可选配置 |
addElectronDebugIdentity()
将包标识添加到 Electron 调试过程
function addElectronDebugIdentity(options?: MsixIdentityOptions): Promise<ElectronDebugIdentityResult>
参数：
| 参数 | 类型 | 必需 | Description |
|---|---|---|---|
options |
MsixIdentityOptions |
否 | 配置选项 |
clearElectronDebugIdentity()
通过从备份还原，清除/删除 Electron 调试过程中的包标识。
function clearElectronDebugIdentity(options?: MsixIdentityOptions): Promise<ClearElectronDebugIdentityResult>
参数：
| 参数 | 类型 | 必需 | Description |
|---|---|---|---|
options |
MsixIdentityOptions |
否 | 配置选项 |
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 |
保持清单身份不变，不添加 .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 调试过程中删除包标识。
electron.exe从add-electron-debug-identity创建的备份中恢复，并删除备份文件。
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 |
否 | |
noInstall |
boolean \| undefined |
否 | |
keepIdentity |
boolean \| undefined |
否 | |
manifest |
string \| undefined |
否 |
MsixIdentityResult
| 财产 | 类型 | 必需 | Description |
|---|---|---|---|
success |
boolean |
是的 |
ElectronDebugIdentityResult
| 财产 | 类型 | 必需 | Description |
|---|---|---|---|
success |
boolean |
是的 | |
electronExePath |
string |
是的 | |
backupPath |
string |
是的 | |
manifestPath |
string |
是的 | |
assetsDir |
string |
是的 |
ClearElectronDebugIdentityResult
| 财产 | 类型 | 必需 | Description |
|---|---|---|---|
success |
boolean |
是的 | |
electronExePath |
string |
是的 | |
restoredFromBackup |
boolean |
是的 |
CallWinappCliOptions
| 财产 | 类型 | 必需 | Description |
|---|---|---|---|
exitOnError |
boolean \| undefined |
否 |
CallWinappCliResult
| 财产 | 类型 | 必需 | Description |
|---|---|---|---|
exitCode |
number |
是的 |
CallWinappCliCaptureOptions
| 财产 | 类型 | 必需 | Description |
|---|---|---|---|
cwd |
string \| undefined |
否 | CLI 进程的工作目录（默认为 process.cwd（）） |
CallWinappCliCaptureResult
| 财产 | 类型 | 必需 | Description |
|---|---|---|---|
exitCode |
number |
是的 | |
stdout |
string |
是的 | |
stderr |
string |
是的 |
GenerateCppAddonOptions
| 财产 | 类型 | 必需 | Description |
|---|---|---|---|
name |
string \| undefined |
否 | |
projectRoot |
string \| undefined |
否 | |
verbose |
boolean \| undefined |
否 |
GenerateCppAddonResult
| 财产 | 类型 | 必需 | Description |
|---|---|---|---|
success |
boolean |
是的 | |
addonName |
string |
是的 | |
addonPath |
string |
是的 | |
needsTerminalRestart |
boolean |
是的 | |
files |
string[] |
是的 |
GenerateCsAddonOptions
| 财产 | 类型 | 必需 | Description |
|---|---|---|---|
name |
string \| undefined |
否 | |
projectRoot |
string \| undefined |
否 | |
verbose |
boolean \| undefined |
否 |
GenerateCsAddonResult
| 财产 | 类型 | 必需 | Description |
|---|---|---|---|
success |
boolean |
是的 | |
addonName |
string |
是的 | |
addonPath |
string |
是的 | |
needsTerminalRestart |
boolean |
是的 | |
files |
string[] |
是的 |
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 |
否 | 将.cer文件（仅公钥）与 .pfx 一起导出 |
ifExists |
IfExists \| undefined |
否 | 输出文件存在时的行为：“error”（失败、默认值）、“skip”（保留现有文件）或“overwrite”（替换） |
install |
boolean \| undefined |
否 | 生成后将证书安装到本地计算机存储 |
json |
boolean \| undefined |
否 | 将输出格式设置为 JSON |
manifest |
string \| undefined |
否 | Package.appxmanifest 或 appxmanifest.xml 文件的路径，用于从中提取发布者信息 |
output |
string \| undefined |
否 | 生成的 PFX 文件的输出路径 |
password |
string \| undefined |
否 | 生成的 PFX 文件的密码 |
publisher |
string \| undefined |
否 | 生成的证书的发布者名称。 如果未指定，将从清单推断出来。 |
validDays |
number \| undefined |
否 | 证书有效天数 |
quiet |
boolean \| undefined |
否 | 禁止显示进度消息。 |
verbose |
boolean \| undefined |
否 | 启用详细输出。 |
cwd |
string \| undefined |
否 | CLI 进程的工作目录（默认为 process.cwd（））。 |
CertInfoOptions
| 财产 | 类型 | 必需 | Description |
|---|---|---|---|
certPath |
string |
是的 | 证书文件的路径（PFX） |
json |
boolean \| undefined |
否 | 将输出格式设置为 JSON |
password |
string \| undefined |
否 | PFX 文件的密码 |
quiet |
boolean \| undefined |
否 | 禁止显示进度消息。 |
verbose |
boolean \| undefined |
否 | 启用详细输出。 |
cwd |
string \| undefined |
否 | CLI 进程的工作目录（默认为 process.cwd（））。 |
CertInstallOptions
| 财产 | 类型 | 必需 | Description |
|---|---|---|---|
certPath |
string |
是的 | 证书文件的路径（PFX 或 CER） |
force |
boolean \| undefined |
否 | 强制安装，即使证书已存在 |
password |
string \| undefined |
否 | PFX 文件的密码 |
quiet |
boolean \| undefined |
否 | 禁止显示进度消息。 |
verbose |
boolean \| undefined |
否 | 启用详细输出。 |
cwd |
string \| undefined |
否 | CLI 进程的工作目录（默认为 process.cwd（））。 |
CreateDebugIdentityOptions
| 财产 | 类型 | 必需 | Description |
|---|---|---|---|
entrypoint |
string \| undefined |
否 | 运行时需要附带身份验证或入口点脚本的 .exe 文件路径。 |
keepIdentity |
boolean \| undefined |
否 | 将包标识从清单中原样保留，不要将“.debug”追加到包名称和应用程序 ID 中。 |
manifest |
string \| undefined |
否 | Package.appxmanifest 或 appxmanifest.xml 的路径 |
noInstall |
boolean \| undefined |
否 | 创建后不要安装包。 |
quiet |
boolean \| undefined |
否 | 禁止显示进度消息。 |
verbose |
boolean \| undefined |
否 | 启用详细输出。 |
cwd |
string \| undefined |
否 | CLI 进程的工作目录（默认为 process.cwd（））。 |
CreateExternalCatalogOptions
| 财产 | 类型 | 必需 | Description |
|---|---|---|---|
inputFolder |
string |
是的 | 包含要处理的可执行文件的输入文件夹列表（用分号分隔） |
computeFlatHashes |
boolean \| undefined |
否 | 生成目录时包括平面哈希 |
ifExists |
IfExists \| undefined |
否 | 输出文件已存在时的行为 |
output |
string \| undefined |
否 | 输出目录文件路径。 如果未指定，则使用默认 CodeIntegrityExternal.cat 名称。 |
recursive |
boolean \| undefined |
否 | 包含子目录中的文件 |
usePageHashes |
boolean \| undefined |
否 | 生成目录时包括页哈希 |
quiet |
boolean \| undefined |
否 | 禁止显示进度消息。 |
verbose |
boolean \| undefined |
否 | 启用详细输出。 |
cwd |
string \| undefined |
否 | CLI 进程的工作目录（默认为 process.cwd（））。 |
GetWinappPathOptions
| 财产 | 类型 | 必需 | Description |
|---|---|---|---|
global |
boolean \| undefined |
否 | 获取全局 .winapp 目录而不是本地目录 |
quiet |
boolean \| undefined |
否 | 禁止显示进度消息。 |
verbose |
boolean \| undefined |
否 | 启用详细输出。 |
cwd |
string \| undefined |
否 | CLI 进程的工作目录（默认为 process.cwd（））。 |
InitOptions
| 财产 | 类型 | 必需 | Description |
|---|---|---|---|
baseDirectory |
string \| undefined |
否 | winapp 工作区的基/根目录，供使用或安装。 |
configDir |
string \| undefined |
否 | 要读取/存储配置的目录（默认值：当前目录） |
configOnly |
boolean \| undefined |
否 | 仅处理配置文件的操作（如果缺少，则创建；如果存在，则验证）。 跳过包安装和其他工作区安装步骤。 |
ignoreConfig |
boolean \| undefined |
否 | 不要将配置文件用于版本管理 |
noGitignore |
boolean \| undefined |
否 | 不要更新 .gitignore 文件 |
setupSdks |
SdkInstallMode \| undefined |
否 | SDK 安装模式：“stable”（默认值）、“预览”、“实验”或“none”（跳过 SDK 安装） |
useDefaults |
boolean \| undefined |
否 | 不提示，默认使用所有提示的默认值 |
quiet |
boolean \| undefined |
否 | 禁止显示进度消息。 |
verbose |
boolean \| undefined |
否 | 启用详细输出。 |
cwd |
string \| undefined |
否 | CLI 进程的工作目录（默认为 process.cwd（））。 |
ManifestAddAliasOptions
| 财产 | 类型 | 必需 | Description |
|---|---|---|---|
appId |
string \| undefined |
否 | 要向其添加别名的应用程序 ID（默认值：第一个应用程序元素） |
manifest |
string \| undefined |
否 | Package.appxmanifest 或 appxmanifest.xml 文件的路径（默认值：搜索当前目录） |
name |
string \| undefined |
否 | 别名（例如，'myapp.exe'）。 默认值：从清单中的可执行文件属性推断。 |
quiet |
boolean \| undefined |
否 | 禁止显示进度消息。 |
verbose |
boolean \| undefined |
否 | 启用详细输出。 |
cwd |
string \| undefined |
否 | CLI 进程的工作目录（默认为 process.cwd（））。 |
ManifestGenerateOptions
| 财产 | 类型 | 必需 | Description |
|---|---|---|---|
directory |
string \| undefined |
否 | 要在其中生成清单的目录 |
description |
string \| undefined |
否 | 安装和Windows设置中显示的人工可读应用说明 |
executable |
string \| undefined |
否 | 应用程序的可执行文件的路径。 默认值： <包名称>.exe |
ifExists |
IfExists \| undefined |
否 | 输出文件存在时的行为：“error”（失败、默认值）、“skip”（保留现有文件）或“overwrite”（替换） |
logoPath |
string \| undefined |
否 | 徽标图像文件的路径 |
packageName |
string \| undefined |
否 | 包名称（默认：文件夹名称） |
publisherName |
string \| undefined |
否 | Publisher CN （默认值：CN=<当前用户>） |
template |
ManifestTemplates \| undefined |
否 | 清单模板类型：“打包”（完整的 MSIX 应用、默认值）或“稀疏”（具有适用于 Windows API 的包标识的桌面应用） |
version |
string \| undefined |
否 | 应用版本采用 Major.Minor.Build.Revision 格式（例如 1.0.0.0）。 |
quiet |
boolean \| undefined |
否 | 禁止显示进度消息。 |
verbose |
boolean \| undefined |
否 | 启用详细输出。 |
cwd |
string \| undefined |
否 | CLI 进程的工作目录（默认为 process.cwd（））。 |
ManifestUpdateAssetsOptions
| 财产 | 类型 | 必需 | Description |
|---|---|---|---|
imagePath |
string |
是的 | 源图像文件的路径（SVG、PNG、ICO、JPG、BMP、GIF） |
lightImage |
string \| undefined |
否 | 浅色主题变体的源图像路径（SVG、PNG、ICO、JPG、BMP、GIF） |
manifest |
string \| undefined |
否 | Package.appxmanifest 或 appxmanifest.xml 文件的路径（默认值：搜索当前目录） |
quiet |
boolean \| undefined |
否 | 禁止显示进度消息。 |
verbose |
boolean \| undefined |
否 | 启用详细输出。 |
cwd |
string \| undefined |
否 | CLI 进程的工作目录（默认为 process.cwd（））。 |
PackageOptions
| 财产 | 类型 | 必需 | Description |
|---|---|---|---|
inputFolder |
string |
是的 | 具有包布局的输入文件夹 |
cert |
string \| undefined |
否 | 签名证书的路径（如果提供，将会自动签名） |
certPassword |
string \| undefined |
否 | 证书密码（默认值：密码） |
executable |
string \| undefined |
否 | 相对于输入文件夹的可执行文件的路径。 |
generateCert |
boolean \| undefined |
否 | 生成新的开发证书 |
installCert |
boolean \| undefined |
否 | 将证书安装到计算机 |
manifest |
string \| undefined |
否 | AppX 清单文件的路径（默认值：从输入文件夹或当前目录自动检测） |
name |
string \| undefined |
否 | 包名（默认值：从清单中获取） |
output |
string \| undefined |
否 | 生成包的输出 msix 文件名（默认为<name><version><arch>.msix；如果无法确定版本或架构，则依次回退为 <name><version>.msix、<name><arch>.msix 或 <name>.msix） |
publisher |
string \| undefined |
否 | 生成证书的发布者名称 |
selfContained |
boolean \| undefined |
否 | 用于独立部署的捆绑Windows 应用 SDK运行时 |
skipPri |
boolean \| undefined |
否 | 跳过 PRI 文件生成 |
quiet |
boolean \| undefined |
否 | 禁止显示进度消息。 |
verbose |
boolean \| undefined |
否 | 启用详细输出。 |
cwd |
string \| undefined |
否 | CLI 进程的工作目录（默认为 process.cwd（））。 |
RestoreOptions
| 财产 | 类型 | 必需 | Description |
|---|---|---|---|
baseDirectory |
string \| undefined |
否 | winapp 工作区的基/根目录 |
configDir |
string \| undefined |
否 | 要从中读取配置的目录（默认值：当前目录） |
quiet |
boolean \| undefined |
否 | 禁止显示进度消息。 |
verbose |
boolean \| undefined |
否 | 启用详细输出。 |
cwd |
string \| undefined |
否 | CLI 进程的工作目录（默认为 process.cwd（））。 |
RunOptions
| 财产 | 类型 | 必需 | Description |
|---|---|---|---|
inputFolder |
string |
是的 | 包含要运行的应用的输入文件夹 |
args |
string \| undefined |
否 | 要传递给应用程序的命令行参数 |
clean |
boolean \| undefined |
否 | 重新部署之前，请删除现有包的应用程序数据（LocalState、设置等）。 默认情况下，应用程序数据会在重新部署之间保留。 |
debugOutput |
boolean \| undefined |
否 | 从启动的应用程序中捕获 OutputDebugString 消息和首次机会异常。 一次只能有一个调试器附加到进程，因此不能同时使用其他调试器（Visual Studio，VS Code）。 如果需要附加其他调试器，请改用 --no-launch。 不能与 --no-launch 或 --json 结合使用。 |
detach |
boolean \| undefined |
否 | 启动应用程序并立即返回，无需等待它退出。 在启动后需要与应用交互的 CI/自动化非常有用。 将 PID 打印到 stdout（或使用 --json 在 JSON 中）。 |
json |
boolean \| undefined |
否 | 将输出格式设置为 JSON |
manifest |
string \| undefined |
否 | Package.appxmanifest 的路径（默认值：从输入文件夹或当前目录自动检测） |
noLaunch |
boolean \| undefined |
否 | 仅创建调试标识并注册包而不启动应用程序 |
outputAppxDirectory |
string \| undefined |
否 | 松散布局包的输出目录。 如果未指定，将使用输入文件夹目录中名为 AppX 的目录。 |
symbols |
boolean \| undefined |
否 | 从 Microsoft Symbol Server 下载符号，以便进行更丰富的本机故障分析。 仅用于 --debug-output。 首先运行下载符号并将其缓存在本地;后续运行使用缓存。 |
unregisterOnExit |
boolean \| undefined |
否 | 请在应用程序退出后注销开发包。 仅删除在开发模式下注册的包。 |
withAlias |
boolean \| undefined |
否 | 使用其执行别名而不是 AUMID 激活启动应用。 应用在当前终端中运行，继承了 stdin/stdout/stderr。 清单中需要 uap5：ExecutionAlias。 使用“winapp manifest add-alias”将执行别名添加到清单。 |
quiet |
boolean \| undefined |
否 | 禁止显示进度消息。 |
verbose |
boolean \| undefined |
否 | 启用详细输出。 |
cwd |
string \| undefined |
否 | CLI 进程的工作目录（默认为 process.cwd（））。 |
SignOptions
| 财产 | 类型 | 必需 | Description |
|---|---|---|---|
filePath |
string |
是的 | 要签名的文件/包的路径 |
certPath |
string |
是的 | 证书文件的路径（PFX 格式） |
password |
string \| undefined |
否 | 证书密码 |
timestamp |
string \| undefined |
否 | 时间戳服务器的 URL |
quiet |
boolean \| undefined |
否 | 禁止显示进度消息。 |
verbose |
boolean \| undefined |
否 | 启用详细输出。 |
cwd |
string \| undefined |
否 | CLI 进程的工作目录（默认为 process.cwd（））。 |
StoreOptions
| 财产 | 类型 | 必需 | Description |
|---|---|---|---|
storeArgs |
string[] \| undefined |
否 | 要传递给 Microsoft Store 开发人员 CLI 的参数。 |
quiet |
boolean \| undefined |
否 | 禁止显示进度消息。 |
verbose |
boolean \| undefined |
否 | 启用详细输出。 |
cwd |
string \| undefined |
否 | CLI 进程的工作目录（默认为 process.cwd（））。 |
ToolOptions
| 财产 | 类型 | 必需 | Description |
|---|---|---|---|
toolArgs |
string[] \| undefined |
否 | 要传递给 SDK 工具的参数，例如 ['makeappx'、'pack'、'/d'、'./folder'、'/p'、'./out.msix']。 |
quiet |
boolean \| undefined |
否 | 禁止显示进度消息。 |
verbose |
boolean \| undefined |
否 | 启用详细输出。 |
cwd |
string \| undefined |
否 | CLI 进程的工作目录（默认为 process.cwd（））。 |
UiClickOptions
| 财产 | 类型 | 必需 | Description |
|---|---|---|---|
selector |
string \| undefined |
否 | 语义标识符（例如 btn-minimize-d1a0）或按名称、AutomationId 搜索的文本 |
app |
string \| undefined |
否 | 目标应用（进程名称、窗口标题或 PID）。 列出窗口（如果有歧义）。 |
double |
boolean \| undefined |
否 | 请用双击代替单击 |
json |
boolean \| undefined |
否 | 将输出格式设置为 JSON |
right |
boolean \| undefined |
否 | 使用鼠标右键单击而不是左键单击 |
window |
number \| undefined |
否 | HWND 的目标窗口（列表输出中的稳定句柄）。 优先于 --app。 |
quiet |
boolean \| undefined |
否 | 禁止显示进度消息。 |
verbose |
boolean \| undefined |
否 | 启用详细输出。 |
cwd |
string \| undefined |
否 | CLI 进程的工作目录（默认为 process.cwd（））。 |
UiFocusOptions
| 财产 | 类型 | 必需 | Description |
|---|---|---|---|
selector |
string \| undefined |
否 | 语义标识符（例如 btn-minimize-d1a0）或按名称、AutomationId 搜索的文本 |
app |
string \| undefined |
否 | 目标应用（进程名称、窗口标题或 PID）。 列出窗口（如果有歧义）。 |
json |
boolean \| undefined |
否 | 将输出格式设置为 JSON |
window |
number \| undefined |
否 | HWND 的目标窗口（列表输出中的稳定句柄）。 优先于 --app。 |
quiet |
boolean \| undefined |
否 | 禁止显示进度消息。 |
verbose |
boolean \| undefined |
否 | 启用详细输出。 |
cwd |
string \| undefined |
否 | CLI 进程的工作目录（默认为 process.cwd（））。 |
UiGetFocusedOptions
| 财产 | 类型 | 必需 | Description |
|---|---|---|---|
app |
string \| undefined |
否 | 目标应用（进程名称、窗口标题或 PID）。 列出窗口（如果有歧义）。 |
json |
boolean \| undefined |
否 | 将输出格式设置为 JSON |
window |
number \| undefined |
否 | HWND 的目标窗口（列表输出中的稳定句柄）。 优先于 --app。 |
quiet |
boolean \| undefined |
否 | 禁止显示进度消息。 |
verbose |
boolean \| undefined |
否 | 启用详细输出。 |
cwd |
string \| undefined |
否 | CLI 进程的工作目录（默认为 process.cwd（））。 |
UiGetPropertyOptions
| 财产 | 类型 | 必需 | Description |
|---|---|---|---|
selector |
string \| undefined |
否 | 语义标识符（例如 btn-minimize-d1a0）或按名称、AutomationId 搜索的文本 |
app |
string \| undefined |
否 | 目标应用（进程名称、窗口标题或 PID）。 列出窗口（如果有歧义）。 |
json |
boolean \| undefined |
否 | 将输出格式设置为 JSON |
property |
string \| undefined |
否 | 要读取或筛选的属性名称 |
window |
number \| undefined |
否 | HWND 的目标窗口（列表输出中的稳定句柄）。 优先于 --app。 |
quiet |
boolean \| undefined |
否 | 禁止显示进度消息。 |
verbose |
boolean \| undefined |
否 | 启用详细输出。 |
cwd |
string \| undefined |
否 | CLI 进程的工作目录（默认为 process.cwd（））。 |
UiGetValueOptions
| 财产 | 类型 | 必需 | Description |
|---|---|---|---|
selector |
string \| undefined |
否 | 语义标识符（例如 btn-minimize-d1a0）或用于按名称或自动化ID搜索的文本 |
app |
string \| undefined |
否 | 目标应用（进程名称、窗口标题或 PID）。 在有歧义时列出窗口。 |
json |
boolean \| undefined |
否 | 将输出格式设置为 JSON |
window |
number \| undefined |
否 | 通过 HWND 确定目标窗口（表示列表输出中的稳定句柄）。 优先于 --app。 |
quiet |
boolean \| undefined |
否 | 禁止显示进度消息。 |
verbose |
boolean \| undefined |
否 | 启用详细输出。 |
cwd |
string \| undefined |
否 | CLI 进程的工作目录（默认为 process.cwd（））。 |
UiInspectOptions
| 财产 | 类型 | 必需 | Description |
|---|---|---|---|
selector |
string \| undefined |
否 | 语义标签（例如 btn-minimize-d1a0）或根据名称/automationId 搜索的文本 |
ancestors |
boolean \| undefined |
否 | 从指定的元素向上遍历树直到根节点 |
app |
string \| undefined |
否 | 目标应用（进程名称、窗口标题或 PID）。 列出窗口（如果存在歧义）。 |
depth |
number \| undefined |
否 | 树检查深度 |
hideDisabled |
boolean \| undefined |
否 | 隐藏输出中禁用的元素 |
hideOffscreen |
boolean \| undefined |
否 | 隐藏输出中的屏幕外元素 |
interactive |
boolean \| undefined |
否 | 仅显示交互式/可调用元素（按钮、链接、输入、列表项）。 将默认深度增加到 8。 |
json |
boolean \| undefined |
否 | 将输出格式设置为 JSON |
window |
number \| undefined |
否 | 使用 HWND 定位目标窗口（来自列表输出的稳定句柄）。 优先于 --app。 |
quiet |
boolean \| undefined |
否 | 禁止显示进度消息。 |
verbose |
boolean \| undefined |
否 | 启用详细输出。 |
cwd |
string \| undefined |
否 | CLI 进程的工作目录（默认为 process.cwd（））。 |
UiInvokeOptions
| 财产 | 类型 | 必需 | Description |
|---|---|---|---|
selector |
string \| undefined |
否 | 语义标识（例如 btn-minimize-d1a0）或用于按名称/自动化ID搜索的文本 |
app |
string \| undefined |
否 | 目标应用（进程名称、窗口标题或 PID）。 列出窗口（如果存在歧义）。 |
json |
boolean \| undefined |
否 | 将输出格式设置为 JSON |
window |
number \| undefined |
否 | 通过 HWND 定位目标窗口（来自列表输出的稳定句柄）。 优先于 --app。 |
quiet |
boolean \| undefined |
否 | 禁止显示进度消息。 |
verbose |
boolean \| undefined |
否 | 启用详细输出。 |
cwd |
string \| undefined |
否 | CLI 进程的工作目录（默认为 process.cwd（））。 |
UiListWindowsOptions
| 财产 | 类型 | 必需 | Description |
|---|---|---|---|
app |
string \| undefined |
否 | 目标应用（进程名称、窗口标题或 PID）。 列出窗口（如果存在歧义）。 |
json |
boolean \| undefined |
否 | 将输出格式设置为 JSON |
quiet |
boolean \| undefined |
否 | 禁止显示进度消息。 |
verbose |
boolean \| undefined |
否 | 启用详细输出。 |
cwd |
string \| undefined |
否 | CLI 进程的工作目录（默认为 process.cwd（））。 |
UiScreenshotOptions
| 财产 | 类型 | 必需 | Description |
|---|---|---|---|
selector |
string \| undefined |
否 | 语义标签（例如 btn-minimize-d1a0）或根据名称/自动化ID进行搜索的文本 |
app |
string \| undefined |
否 | 目标应用（进程名称、窗口标题或 PID）。 列出窗口（如果有歧义）。 |
captureScreen |
boolean \| undefined |
否 | 从屏幕捕获（包括弹出窗口/覆盖），而不是窗口渲染。 首先将窗口置于前台。 |
json |
boolean \| undefined |
否 | 将输出格式设置为 JSON |
output |
string \| undefined |
否 | 将输出保存到文件路径（例如屏幕截图） |
window |
number \| undefined |
否 | HWND 的目标窗口（列表输出中的稳定句柄）。 优先于 --app。 |
quiet |
boolean \| undefined |
否 | 禁止显示进度消息。 |
verbose |
boolean \| undefined |
否 | 启用详细输出。 |
cwd |
string \| undefined |
否 | CLI 进程的工作目录（默认为 process.cwd（））。 |
UiScrollOptions
| 财产 | 类型 | 必需 | Description |
|---|---|---|---|
selector |
string \| undefined |
否 | 语义slug（例如：btn-minimize-d1a0）或按名称/自动化ID搜索的文本 |
app |
string \| undefined |
否 | 目标应用（进程名称、窗口标题或 PID）。 列出窗口（如果不确定）。 |
direction |
string \| undefined |
否 | 滚动方向：向上、向下、向左、向右滚动 |
json |
boolean \| undefined |
否 | 将输出格式设置为 JSON |
to |
string \| undefined |
否 | 滚动至位置：顶部和底部 |
window |
number \| undefined |
否 | 使用HWND定位窗口（来源于列表输出的稳定句柄）。 优先于 --app。 |
quiet |
boolean \| undefined |
否 | 禁止显示进度消息。 |
verbose |
boolean \| undefined |
否 | 启用详细输出。 |
cwd |
string \| undefined |
否 | CLI 进程的工作目录（默认为 process.cwd（））。 |
UiScrollIntoViewOptions
| 财产 | 类型 | 必需 | Description |
|---|---|---|---|
selector |
string \| undefined |
否 | 语义标识符（例如 btn-minimize-d1a0）或用于按名称或自动化ID搜索的文本 |
app |
string \| undefined |
否 | 目标应用（进程名称、窗口标题或 PID）。 列出窗口（如果存在模糊的情况）。 |
json |
boolean \| undefined |
否 | 将输出格式设置为 JSON |
window |
number \| undefined |
否 | 通过 HWND 定位目标窗口（来自列表输出的稳定句柄）。 优先于 --app。 |
quiet |
boolean \| undefined |
否 | 禁止显示进度消息。 |
verbose |
boolean \| undefined |
否 | 启用详细输出。 |
cwd |
string \| undefined |
否 | CLI 进程的工作目录（默认为 process.cwd（））。 |
UiSearchOptions
| 财产 | 类型 | 必需 | Description |
|---|---|---|---|
selector |
string \| undefined |
否 | 语义 slug（例如 btn-minimize-d1a0）或按名称/automationId 搜索的文本 |
app |
string \| undefined |
否 | 目标应用（进程名称、窗口标题或 PID）。 在存在歧义时列出窗口。 |
json |
boolean \| undefined |
否 | 将输出格式设置为 JSON |
max |
number \| undefined |
否 | 最多搜索结果 |
window |
number \| undefined |
否 | 按 HWND 标识的目标窗口（在列表输出中作为稳定句柄）。 优先于 --app。 |
quiet |
boolean \| undefined |
否 | 禁止显示进度消息。 |
verbose |
boolean \| undefined |
否 | 启用详细输出。 |
cwd |
string \| undefined |
否 | CLI 进程的工作目录（默认为 process.cwd（））。 |
UiSetValueOptions
| 财产 | 类型 | 必需 | Description |
|---|---|---|---|
selector |
string \| undefined |
否 | 语义标识（例如 btn-minimize-d1a0）或按名称/automationId 搜索的文本 |
value |
string \| undefined |
否 | 要设置的值（用于文本框/组合框的文本，用于滑块的数字） |
app |
string \| undefined |
否 | 目标应用（进程名称、窗口标题或 PID）。 列出窗口（如果模糊不清）。 |
json |
boolean \| undefined |
否 | 将输出格式设置为 JSON |
window |
number \| undefined |
否 | HWND 的目标窗口（列表输出中的稳定句柄）。 优先于 --app。 |
quiet |
boolean \| undefined |
否 | 禁止显示进度消息。 |
verbose |
boolean \| undefined |
否 | 启用详细输出。 |
cwd |
string \| undefined |
否 | CLI 进程的工作目录（默认为 process.cwd（））。 |
UiStatusOptions
| 财产 | 类型 | 必需 | Description |
|---|---|---|---|
app |
string \| undefined |
否 | 目标应用（进程名称、窗口标题或 PID）。 列出窗口（如果模糊不清）。 |
json |
boolean \| undefined |
否 | 将输出格式设置为 JSON |
window |
number \| undefined |
否 | 通过 HWND 指定的目标窗口（列表输出中的稳定句柄）。 优先于 --app。 |
quiet |
boolean \| undefined |
否 | 禁止显示进度消息。 |
verbose |
boolean \| undefined |
否 | 启用详细输出。 |
cwd |
string \| undefined |
否 | CLI 进程的工作目录（默认为 process.cwd（））。 |
UiWaitForOptions
| 财产 | 类型 | 必需 | Description |
|---|---|---|---|
selector |
string \| undefined |
否 | 语义标识符（例如 btn-minimize-d1a0）或根据名称/automationId 搜索的文本 |
app |
string \| undefined |
否 | 目标应用（进程名称、窗口标题或 PID）。 如果存在歧义，则列出窗口。 |
contains |
boolean \| undefined |
否 | 对于 --value，请使用子字符串匹配而不是完全匹配。 |
gone |
boolean \| undefined |
否 | 等待元素消失而不是出现 |
json |
boolean \| undefined |
否 | 将输出格式设置为 JSON |
property |
string \| undefined |
否 | 要读取或筛选的属性名称 |
timeout |
number \| undefined |
否 | 超时（以毫秒为单位） |
value |
string \| undefined |
否 | 等待元素值等于此字符串。 使用智能回退（TextPattern -> ValuePattern -> Name）。 请与 --property 搭配使用以检查特定属性。 |
window |
number \| undefined |
否 | HWND 的目标窗口（列表输出中的稳定句柄）。 优先于 --app。 |
quiet |
boolean \| undefined |
否 | 禁止显示进度消息。 |
verbose |
boolean \| undefined |
否 | 启用详细输出。 |
cwd |
string \| undefined |
否 | CLI 进程的工作目录（默认为 process.cwd（））。 |
UnregisterOptions
| 财产 | 类型 | 必需 | Description |
|---|---|---|---|
force |
boolean \| undefined |
否 | 跳过安装位置目录检查并取消注册，即使包是从其他项目树注册的 |
json |
boolean \| undefined |
否 | 将输出格式设置为 JSON |
manifest |
string \| undefined |
否 | Package.appxmanifest 的路径（默认值：从当前目录自动检测） |
quiet |
boolean \| undefined |
否 | 禁止显示进度消息。 |
verbose |
boolean \| undefined |
否 | 启用详细输出。 |
cwd |
string \| undefined |
否 | CLI 进程的工作目录（默认为 process.cwd（））。 |
UpdateOptions
| 财产 | 类型 | 必需 | Description |
|---|---|---|---|
setupSdks |
SdkInstallMode \| undefined |
否 | SDK 安装模式：“stable”（默认值）、“预览”、“实验”或“none”（跳过 SDK 安装） |
quiet |
boolean \| undefined |
否 | 禁止显示进度消息。 |
verbose |
boolean \| undefined |
否 | 启用详细输出。 |
cwd |
string \| undefined |
否 | CLI 进程的工作目录（默认为 process.cwd（））。 |
