IPTVnator 启动窗口模式全解析上次尺寸 / 最大化 / 全屏启动与 --fullscreen、F11 的底层实现【免费下载链接】iptvnator:tv: Cross-platform IPTV player application with multiple features, such as support of m3u and m3u8 playlists, favorites, TV guide, TV archive/catchup and more.项目地址: https://gitcode.com/GitHub_Trending/ip/iptvnator本文以 IPTVnatorElectron 桌面端新增的Window on startup启动窗口模式功能为主线梳理三种启动形态沿用上次尺寸、最大化、全屏、--fullscreen命令行开关的单次强制全屏语义以及 F11 全局切换全屏的实现原理。读完本文你将理解该功能从设置界面、主进程决策到原生窗口全屏过渡跟踪的完整调用链可直接在自己的 Electron 项目中复刻这套“存储设置 CLI 一次性覆盖 快捷键即时切换”的窗口管理模式。功能概览一个设置项 一个命令行开关 一个快捷键该功能对应 issue #1455在 Settings → General常规设置 中新增了“Window on startup”下拉选项允许用户决定桌面应用启动时的窗口形态选项行为normal默认以上次保存的窗口尺寸与位置启动maximized启动即最大化fullscreen启动即进入原生全屏除设置项外还提供了两条互补的使用路径命令行开关以--fullscreen启动会只对本次启动强制全屏不修改设置项——适合 HTPC/电视盒的开机自启脚本快捷键在应用内任意位置按F11即可随时切换/退出全屏。三者互不干扰设置决定默认行为CLI 开关单次覆盖F11 在运行时即时生效。设置项的持久化渲染进程表单与主进程镜像“Window on startup”是一个标准的用户设置。在类型层面它被定义在共享接口库 settings.interface.ts 中export type StartupWindowMode normal | maximized | fullscreen; export const STARTUP_WINDOW_MODES: readonly StartupWindowMode[] [ normal, maximized, fullscreen, ]; export function normalizeStartupWindowMode(value: unknown): StartupWindowMode { return STARTUP_WINDOW_MODES.includes(value as StartupWindowMode) ? (value as StartupWindowMode) : normal; }这里有两个值得注意的工程细节类型收窄发生在运行时normalizeStartupWindowMode把任何未知值包括kiosk、、数字、null等一律折叠为normal。源码注释明确指出渲染进程表单与主进程镜像共享这个归一化函数从而保证“垃圾值永远不会到达配置文件或窗口选项”。主进程侧在窗口创建之前就需要该值设置由渲染进程持久化并通过SETTINGS_UPDATE事件镜像到主进程配置文件见 settings.events.ts。之所以必须这样做是因为主窗口在渲染进程尚不存在时就要被创建——因此设置项的任何改动都只能在下一次启动时生效这是该功能“启动时”语义的根源。启动模式决策CLI 开关优先且永不持久化主进程的决策逻辑收敛在一个纯函数中位于 startup-window-mode.tsexport const FULLSCREEN_LAUNCH_SWITCH fullscreen; export function resolveStartupWindowMode(input: { cliHasFullscreenSwitch: boolean; storedMode: unknown; }): StartupWindowMode { if (input.cliHasFullscreenSwitch) { return fullscreen; } return normalizeStartupWindowMode(input.storedMode); }决策规则只有两条命令行出现--fullscreen→ 本次启动直接返回fullscreen优先级最高否则 → 读取存储的storedMode经normalizeStartupWindowMode归一化后返回。FULLSCREEN_LAUNCH_SWITCH被特意定义为裸开关名fullscreen因为app.commandLine.hasSwitch()接收的是不带短横线的名称同时源码注释说明它是通过 Electron 解析后的命令行读取的因此可以出现在 argv 的任意位置且播放列表路径提取器会跳过所有-前缀参数两者互不干扰。“永不持久化”是关键语义开关只影响本次启动下次不带它启动时回落到设置值。这一“单次覆盖”行为在 startup-window-mode.spec.ts 中被测试锁定新配置文件storedMode: undefined默认得到normal存储的normal | maximized | fullscreen均被尊重kiosk、、1、true、null、{}等手改配置值全部折叠为normal--fullscreen开关胜过任何存储模式。窗口创建从构造选项到 macOS 的两次全屏尝试决策结果在 app.ts 的initMainWindow中落地。窗口创建流程大致如下计算默认尺寸取主显示器工作区width Math.min(1280, workAreaSize.width || 1280)、height Math.min(720, workAreaSize.height || 720)同时限制minWidth: 900、minHeight: 600。合并保存的窗口边界...savedWindowBounds展开在构造选项中如果首次启动没有保存记录则center()居中显示。全屏走构造选项仅当模式为fullscreen时注入{ fullscreen: true }。窗口以show: false创建因此在首次绘制前就进入全屏避免白屏闪烁保存的普通边界仍然保留作为退出全屏后的回落位置且关闭处理器持续持久化getNormalBounds()——一次全屏会话不会污染普通边界数据。最大化延迟到ready-to-showmaximize()在隐藏窗口上会直接显示窗口Electron 文档说明所以必须等ready-to-show再执行否则渲染器绘制前会闪现空白窗口。macOS 的特殊二次尝试macOS 忽略隐藏窗口构造选项中的fullscreenNSWindow 只能在其上屏后才能切换全屏因此show()之后会再次检查isFullScreen()若未生效则通过requestFullScreen补一次请求。一次性消费macOS Dock 重建窗口不重复全屏还有一个巧妙的细节——launchFullscreenSwitchConsumed标志app.ts该开关由第一个窗口消费因此同一进程后续重建的窗口例如 macOS Dock 点击图标重建窗口只遵循存储设置。在 macOS 上关闭最后一个窗口进程仍存活Dockactivate或单实例守卫移交的二次启动会通过ensureMainWindow重建窗口。这个标志确保--fullscreen只塑造启动那一个窗口而不会让之后每次重建都进入全屏。F11 切换全屏为什么不能直接依赖isFullScreen()快捷键层面window.events.ts 中的 F11 处理调用toggleFullScreen(win)核心实现在 native-fullscreen-transitions.ts。这个模块最值得学习的是它为什么不直接读BrowserWindow.isFullScreen()做翻转其设计动机文件头部注释如下setFullScreen()是异步完成的macOS 动画、Linux 窗口管理器而 Windows 上即使事件已触发getter 仍可能返回过渡前的值若基于 getter 做翻转两次快速按 F11 会请求两次相同目标最终停在“全屏”而不是回到窗口启动全屏动画期间按 F11 也会再次请求全屏而非退出。因此实现维护了每个窗口自己的全屏状态跟踪器export const FULLSCREEN_TRANSITION_TIMEOUT_MS 2000;播种trackNativeFullScreen(win)在窗口创建后立即调用此时无过渡进行中用 getter 播种一次初始状态此后只信任enter-full-screen/leave-full-screen事件——包括应用未主动发起的过渡macOS 绿色按钮、CtrlCmdF、Windows 上 HTML 元素全屏请求记录requestFullScreen记录{ target, requestedAt }为最新的请求目标再调用setFullScreen翻转决策toggleFullScreen优先取“在途 pending 目标的取反”无在途过渡才取“跟踪状态的取反”绝不读 getter事件对账事件落到 pending 目标上则清除记录落到另一状态突发请求中较早的一个先落地自己的还在排队则保留记录下一次按键仍按用户最新意图决策超时兜底超过 2000ms 的 pending 记录被无视——没有原生过渡需要这么久。若某平台真的丢掉了排队请求记录超时后事件驱动的状态接管下次按键即可纠正。这样设计让 F11 在“启动全屏动画期间”“动画未结束时连按”“与系统手势并发”等边界场景下都保持正确。窗口状态广播原生全屏与 HTML 全屏分开跟踪F11 切换后自绘窗口控制栏需要同步状态。attachWindowStateEventsapp.ts只对 Windows/Linux 生效macOS 使用原生红绿灯按钮避免无效 IPC。它同样不在事件时重读 getterWindows 上事件触发瞬间 getter 可能仍是旧值而是播种一次后由事件逐字段修补。特别地原生OS 级与 HTML 元素全屏分开跟踪再按位或const fullscreen { native: state.isFullScreen, html: false }; // enter/leave-full-screen 更新 native // enter/leave-html-full-screen 更新 html // push 的是 native || html 的合并值原因源码注释Electron 会记住“窗口在播放器进入 HTML 全屏前已是原生全屏”播放器退出 HTML 状态时不触发leave-full-screen——若用单一标志会让控制栏在仍全屏的窗口上错误地重新出现。该设计与 F11 跟踪器同源是整套全屏体系的两条互补线路。测试与回归保障该功能在主进程侧有直接的单测覆盖startup-window-mode.spec.ts同时窗口状态与全屏相关行为也在 app.spec.ts、app-window-state.spec.ts 与 window.events.spec.ts 中验证渲染端设置表单相关逻辑见 settings-form.utils.ts 及其测试。这些测试共同锁定了“默认 normal、合法值透传、非法值折叠、开关覆盖存储”四条契约。实战小结对 HTPC / 电视大屏使用者这套组合拳的典型用法是# 常规启动跟随设置上次尺寸 / 最大化 / 全屏 iptvnator # 开机自启脚本强制本次全屏不污染设置 iptvnator --fullscreen在桌面使用时按F11随时进出全屏想改变默认启动形态到Settings → General → Window on startup修改重启后生效。更完整的 Electron 窗口与 shell 体系可参考 workspace-shell.md。对于 Electron 开发者本功能的三个实现要点值得直接借鉴决策收敛为纯函数并配单测resolveStartupWindowMode、CLI 一次性覆盖与持久化设置解耦launchFullscreenSwitchConsumed、以及用事件驱动的状态跟踪器替代 getter 驱动切换native-fullscreen-transitions.ts——后者是避免异步全屏过渡下状态错乱的关键设计。【免费下载链接】iptvnator:tv: Cross-platform IPTV player application with multiple features, such as support of m3u and m3u8 playlists, favorites, TV guide, TV archive/catchup and more.项目地址: https://gitcode.com/GitHub_Trending/ip/iptvnator创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考