内置命令 (Builtin Commands)

zero-native 为窗口管理、分层 WebView 以及原生对话框提供了内置的桥接命令。这些命令由 RuntimeOptions 中的 builtin_bridge 策略进行控制，与应用自定义的命令是分开的。

窗口命令

命令	所需权限	描述
`zero-native.window.list`	`window`	列出所有打开的窗口
`zero-native.window.create`	`window`	创建新窗口
`zero-native.window.focus`	`window`	根据 ID 聚焦窗口
`zero-native.window.close`	`window`	根据 ID 关闭窗口

当 js_window_api 为 true 时，窗口命令可以通过 window.zero.windows.* 使用，但在配置了权限时，运行时仍会检查请求源（Origin）和窗口权限（Window permission）。如果您想要为每个命令单独配置允许的源列表，请使用显式的 builtin_bridge 策略。

WebView 命令

命令	所需权限	描述
`zero-native.webview.create`	`window`	在窗口中创建命名的 WebView
`zero-native.webview.list`	`window`	列出调用窗口中的 WebView
`zero-native.webview.setFrame`	`window`	移动或调整 WebView 尺寸
`zero-native.webview.navigate`	`window`	导航 WebView 的 URL
`zero-native.webview.setZoom`	`window`	设置页面缩放比例（0.25 至 5.0）
`zero-native.webview.setLayer`	`window`	改变原生堆叠顺序
`zero-native.webview.close`	`window`	关闭 WebView

当 js_window_api 为 true 时，WebView 命令可以通过 window.zero.webviews.* 使用。它们采用与窗口命令相同的源和窗口权限检查。WebView 的 URL 还会根据 security.navigation.allowed_origins 进行校验。特定后端不支持的操作会被拒绝，并抛出 invalid_request 错误及具体的“后端不支持（unsupported-backend）”错误消息。

若省略 windowId，运行时会默认使用发送桥接消息的窗口。如果提供了 windowId，它必须与发起调用的窗口相匹配。默认情况下子 WebView 是相互隔离的，只有在创建时指定 bridge: true 时才会接收 window.zero。启动时的初始 WebView 总是被列为 main，该标签为保留名称，不能用于创建子 WebView。

对话框命令

命令	描述
`zero-native.dialog.openFile`	显示打开文件对话框
`zero-native.dialog.saveFile`	显示保存文件对话框
`zero-native.dialog.showMessage`	显示消息提示对话框

对话框命令默认是完全拒绝（Default-Deny）的，且必须配置显式的 builtin_bridge 策略才可使用。

启用内置命令

zig

const app_permissions = [_][]const u8{zero_native.security.permission_window};

.security = .{
    .permissions = &app_permissions,
    .navigation = .{ .allowed_origins = &.{ "zero://app" } },
},
.builtin_bridge = .{
    .enabled = true,
    .commands = &.{
        .{ .name = "zero-native.window.list", .permissions = .{ "window" }, .origins = .{ "zero://app" } },
        .{ .name = "zero-native.window.create", .permissions = .{ "window" }, .origins = .{ "zero://app" } },
        .{ .name = "zero-native.webview.create", .permissions = .{ "window" }, .origins = .{ "zero://app" } },
        .{ .name = "zero-native.webview.list", .permissions = .{ "window" }, .origins = .{ "zero://app" } },
        .{ .name = "zero-native.webview.setFrame", .permissions = .{ "window" }, .origins = .{ "zero://app" } },
        .{ .name = "zero-native.webview.navigate", .permissions = .{ "window" }, .origins = .{ "zero://app" } },
        .{ .name = "zero-native.webview.setZoom", .permissions = .{ "window" }, .origins = .{ "zero://app" } },
        .{ .name = "zero-native.webview.setLayer", .permissions = .{ "window" }, .origins = .{ "zero://app" } },
        .{ .name = "zero-native.webview.close", .permissions = .{ "window" }, .origins = .{ "zero://app" } },
        .{ .name = "zero-native.dialog.openFile", .origins = .{ "zero://app" } },
        .{ .name = "zero-native.dialog.showMessage", .origins = .{ "zero://app" } },
    },
},

在 JavaScript 中使用

javascript

await window.zero.windows.create({
  label: "tools",
  title: "Tools",
  width: 420,
  height: 320,
});

const preview = await window.zero.webviews.create({
  label: "preview",
  url: "https://example.com",
  frame: { x: 24, y: 24, width: 480, height: 320 },
  layer: 10,
  bridge: false,
});

await preview.setZoom(1.25);
await preview.setLayer(20);
await preview.close();

const files = await window.zero.invoke("zero-native.dialog.openFile", {
  title: "Select a file",
  allowMultiple: true,
});

const result = await window.zero.invoke("zero-native.dialog.showMessage", {
  style: "warning",
  title: "Confirm",
  message: "Are you sure?",
  primaryButton: "Yes",
  secondaryButton: "No",
});

另请参见：适用于位置（Frame）与层级（Layer）语义的多 WebView 管理、适用于完整对话框类型参考的对话框 (Dialogs) - 暂未创建以及适用于策略细节的安全 (Security) - 暂未创建。

内置命令 (Builtin Commands) ​

窗口命令 ​

WebView 命令 ​

对话框命令 ​