窗口管理 (Windows)

zero-native 支持多窗口。主窗口会自动创建；辅助窗口（子窗口）可以通过 Zig 或 JavaScript 创建。

通过 Zig 创建窗口

const info = try runtime.createWindow(.{
    .label = "tools",
    .title = "Tools",
    .default_frame = zero_native.geometry.RectF.init(80, 80, 420, 320),
});
try runtime.focusWindow(info.id);

通过 JavaScript 创建窗口

js_window_api 会在 JavaScript 中暴露 window.zero.windows.* 辅助函数。当配置了运行时权限时，窗口指令仍然需要处于允许的源（Allowed Origin）并具备窗口权限（Window Permission）：

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

.security = .{
    .permissions = &app_permissions,
    .navigation = .{ .allowed_origins = &.{ "zero://app" } },
},
.js_window_api = true,

随后，JavaScript 可以在允许的源中调用辅助函数：

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

const all = await window.zero.windows.list();
await window.zero.windows.focus(win.id);
await window.zero.windows.close(win.id);

窗口类型

类型	描述
WindowId	不透明的标识符（u64）
WindowCreateOptions	用于 runtime.createWindow() 的选项：label, title, frame
WindowInfo	创建窗口后返回的信息：id, label, title, frame
WindowState	持久化的状态：id, label, title, frame, open, focused, maximized, fullscreen, scale
WindowRestorePolicy	恢复窗口布局时的策略，例如将其限制在可见屏幕范围内，或者将其置于主显示器中心

平台限制

常量	值
max_windows	16 (最大窗口数)
max_window_label_bytes	64 (窗口标签最大字节数)
max_window_title_bytes	128 (窗口标题最大字节数)

窗口状态持久化

window_state.Store 会将窗口几何尺寸持久化存储到应用状态目录中的 windows.zon 文件内。启动恢复时，将读取清单（Manifest）中的窗口标签并应用已保存的窗口位置与尺寸（Frame）；而标题将继续由 app.zon 或运行时窗口创建选项提供。

字段	描述
id	窗口 ID
label	窗口标签（用于合并匹配）
frame	位置与大小 (x, y, width, height)
maximized	窗口是否最大化
fullscreen	窗口是否全屏
scale	显示器缩放比例因子

当调用 saveWindow 时，存储库会通过匹配 label 或 id 进行合并，因此辅助窗口可以与主窗口一同被保留下来。如果在加载时发现丢失、格式错误或为空的标签记录，将被忽略，且在下一次写入文件时会被剔除。

在 app.zon 中声明窗口

.windows = .{
    .{ .label = "main", .title = "zero-native", .width = 720, .height = 480, .restore_state = true },
},