Chikoo's Blog

📋 属性 (Properties)

🪟 窗口尺寸与位置

• width (int) – 窗口宽度。

• height (int) – 窗口高度。

• min_width (int) – 最小宽度。

• min_height (int) – 最小高度。

• max_width (int) – 最大宽度。

• max_height (int) – 最大高度。

• left (int) – 窗口左边缘距屏幕左边缘的距离（虚拟像素）。

• top (int) – 窗口上边缘距屏幕顶部边缘的距离（虚拟像素）。

• alignment (Alignment) – 窗口对齐方式。

🎨 窗口外观与样式

• bgcolor (str) – 窗口背景色，设置 TRANSPARENT 可配合 page.bgcolor 实现透明窗口。

• opacity (float) – 窗口不透明度，范围 0.0（完全透明）~ 1.0（完全不透明）。

• shadow (bool) – 是否显示窗口阴影（macOS/Windows；Windows 上需 frameless=False）。

• title_bar_hidden (bool) – 是否隐藏标题栏（需配合 WindowDragArea 实现拖拽）。

• title_bar_buttons_hidden (bool) – 是否隐藏标题栏按钮（仅 macOS）。

• frameless (bool) – 是否无边框。

• icon (str) – 窗口图标文件路径（仅 Windows，需 .ico 格式）。

• badge_label (str) – 设置徽章标签（仅 macOS）。

🔧 窗口状态与行为

• visible (bool) – 窗口是否可见（可用于隐藏窗口启动）。

• focused (bool) – 是否聚焦（设为 True 可将窗口置于焦点）。

• maximized (bool) – 是否最大化。

• minimized (bool) – 是否最小化。

• full_screen (bool) – 是否全屏。

• resizable (bool) – 是否可调整大小（默认 True）。

• movable (bool) – 是否可移动（仅 macOS）。

• always_on_top (bool) – 是否始终置顶。

• always_on_bottom (bool) – 是否始终置底（Linux/Windows）。

• skip_task_bar (bool) – 是否在任务栏/Dock 中隐藏。

• prevent_close (bool) – 设为 True 拦截关闭信号，用于实现退出确认。

• progress_bar (float) – 在任务栏（Windows）或 Dock（macOS）上显示进度条，范围 0.0 ~ 1.0。

• ignore_mouse_events (bool) – 是否忽略鼠标事件，传递给下方窗口，有焦点时仍接收键盘事件。

⚙️ 方法 (Methods)

• center() – 将窗口移动到屏幕中央。

• close() – 关闭窗口。

• destroy() – 强制销毁窗口，配合 prevent_close=True 可实现退出确认逻辑。

• to_front() – 将窗口置于最前（聚焦并显示在顶部）。

• start_dragging() – 开始拖拽窗口（常用于自定义标题栏区域）。

• start_resizing(edge) – 开始调整窗口大小，需指定边缘方向（如 WindowResizeEdge.RIGHT）。

📡 事件 (Events)

• on_event – 窗口状态变化时触发（包括窗口大小变化、位置移动、最大化、最小化、恢复、焦点变化等）。事件类型通过 WindowEventType 枚举定义，包含以下状态：

• CLOSE / FOCUS / BLUR / HIDE / SHOW

• MAXIMIZE / UNMAXIMIZE / MINIMIZE / RESTORE

• RESIZE / RESIZED / MOVE / MOVED

• ENTER_FULL_SCREEN / LEAVE_FULL_SCREEN