《Electron 45.2.3 内核解剖》第 9 章 NativeWindow:一个窗口的四个身体
一个人有四个身体,听起来是玄学。Electron 的窗口确实有四个,而且它们的寿命不同步——这是本章要讲的全部内容。
一个窗口的四个身体
├─ JS 层 BrowserWindow(browser-window.ts,233 行)
│ 你说的 "window" 就是它;用户的代码只认识这个对象
├─ API 层 api::BaseWindow / api::BrowserWindow(gin 包装,1636 + 395 行)
│ 它把 JS 的属性访问翻译成 C++ 调用,同时管理 JS 对象的存活
├─ 抽象层 electron::NativeWindow(native_window.h 662 行)
│ 88 个纯虚函数;把"窗口"抽象成一个与平台无关的接口
└─ 平台层 NativeWindowViews(2140 行)→ views::Widget → HWND / GtkWindow
或 NativeWindowMac(1900 行)→ NSWindow
它才是真正被操作系统认识的那个东西
第四层还有一个分叉,这是本章后半部分的主题:Linux 与 Windows 走 views::Widget,macOS 直接控 NSWindow。 所以严格说不是四个身体,是"四个半"——第三层的下半截在不同平台上换了骨架。
这四层之间的关系不是简单的调用转发。如果只是转发,BrowserWindow 就应该是 NativeWindow 的直接绑定,不需要 browser-window.ts 那 233 行 JS,也不需要 api::BaseWindow 那一层。真实情况是每一层都在解决上一层看不见的问题:
| 层 | 只有它能做的事 |
|---|---|
| JS | 事件转发到 app、unresponsive 的双定时器、把 17 个方法镜像到 webContents、fromId 的类型判别 |
| API | 用 WeakMap 让 C++ 对象能被 GC、DeleteSoon 保证析构不在原生栈上、EmitEventSoon 避免 JS 在焦点切换中途重入 |
| 抽象 | 88 个纯虚函数定义"窗口该有什么能力"、33 个 Notify* 把平台事件分发给观察者、窗口状态持久化 |
| 平台 | views::Widget::InitParams 的九个字段、WIDGET_OWNS_NATIVE_WIDGET 的所有权语义、GWL_STYLE 位运算 |
本章的组织方式就是这四层,从最外层向内走,最后回到生命周期的时序。贯穿全章的一个问题:new BrowserWindow() 这一行执行完,四个身体分别处在什么状态? 到 9.6 会给出完整的答案。
9.1 第一身体:browser-window.ts
9.1.1 233 行里的三类代码
这个文件是 BrowserWindow 在 JS 世界的全部。它做三类事,混在一起容易看不清:
- 装饰:
BrowserWindow.prototype._init,约 70 行。它在 C++ 构造完成之后、用户拿到对象之前执行。 - 静态方法:
fromId、getAllWindows、getFocusedWindow、fromWebContents、fromBrowserView。这些是"查表"操作,C++ 侧的BaseWindow已经有fromId/getAllWindows,BrowserWindow在此基础上加类型过滤。 - 转发:17 个
prototype方法,全部一行,透传给this.webContents。
文件开头只有三行值得先看:
browser-window.ts:1
import { BaseWindow, WebContents, BrowserView } from 'electron/main';
import type { BrowserWindow as BWT } from 'electron/main';
const { BrowserWindow } = process._linkedBinding('electron_browser_window') as { BrowserWindow: typeof BWT };
第一行是值导入(BaseWindow 要用),第二行是类型导入(只为了给 BWT 起个别名),第三行从 linked binding 里取真身。
注意 import type 与 import 的区别在这里不是风格问题:electron/main 的别名指向 lib/browser/api/exports/electron.ts(第 8 章 8.3.2),它的 42 个属性都是惰性 getter。import type 在编译后被抹掉,不产生任何 getter 触发;而 import { BaseWindow } 会在模块求值时触发 BaseWindow 的 getter——这是必须的,因为下面要用 BaseWindow.fromId。
as { BrowserWindow: typeof BWT } 这个类型断言也说明了 _linkedBinding 的类型是 any:C++ 侧注入的对象没有类型信息,唯一的真相在 typings/ 的 .d.ts 里。类型是声明出来的,不是推导出来的。
9.1.2 _init:C++ 构造之后的第二段构造
_init 不是构造函数。它在 BrowserWindow 的 C++ 构造函数末尾被调用(InitWithArgs 的机制,9.2 会讲),此时对象已经有了 id、webContents、contentView 这些 C++ 属性,但用户还没拿到引用。
这个"中途插入"的位置决定了它能做什么、不能做什么:
- 能改 JS 侧的属性描述符、注册事件监听、往
app上转发事件; - 不能改 C++ 已经读取过的构造参数——
options已经被NativeWindow的构造函数消费完了。
第一件事是冻结 id:
browser-window.ts:12
const id = this.id;
Object.defineProperty(this, 'id', {
value: id,
writable: false
});
this.id 是 getter,返回 weak_map_id()(9.2.8)。冻结的理由写在注释里:
// Set ID at construction time so it's accessible after
// underlying window destruction.
"底层窗口销毁后仍可访问"。win.id 在 win.isDestroyed() === true 之后还能读,这在实践中有用:日志、错误上报、Map 的键。如果 id 是活 getter,读它会调到一个已经 MarkDestroyed() 的对象上,行为取决于 MarkDestroyed 的实现(它把 internal field 0 置空,GetAlignedPointerFromInternalField 返回 nullptr,然后 gin 的 Unwrap 会失败)。
Object.defineProperty 不带 configurable: true,所以默认 false——id 一旦定义就不可改、不可删。这与第 8 章 8.9.2 讲的 52 个模块属性是同一种决策:框架给自己留的确定性能被用户破坏,就不叫确定性。
9.1.3 两类事件转发:app 上的汇总
browser-window.ts:18
this.on('blur', (event: Electron.Event) => {
app.emit('browser-window-blur', event, this);
});
this.on('focus', (event: Electron.Event) => {
app.emit('browser-window-focus', event, this);
});
app 上有 browser-window-created、browser-window-blur、browser-window-focus、browser-window-focus 这几个汇总事件。它们的存在是为了让应用不必给每个窗口挂监听:多窗口应用想知道"现在哪个窗口被聚焦了",用 app.on('browser-window-focus') 比给每个 new BrowserWindow() 后手动挂 on('focus') 更不容易漏。
注意参数顺序:(event, window)。第一个是 Event 对象,第二个是窗口。这个顺序与 webContents 上的事件一致((event, ...args)),也与 Node 的惯例一致。
browser-window-created 的第三个参数形状不一样:
browser-window.ts:64
app.emit('browser-window-created', { preventDefault() {} }, this);
第一个参数是一个鸭子类型的假 Event,只有一个 preventDefault 方法,而且这个方法是空实现——它什么都不做。
这是有意为之还是历史遗留?看 app 的文档:browser-window-created 不可取消。那么这个 preventDefault 存在的唯一理由是让监听者的签名统一:所有 app 上的窗口事件都是 (event, window),如果这个事件的第一个参数是 null 或 undefined,监听者写 (event, win) => event.preventDefault() 就会在运行时崩。给一个空实现,崩溃变成无操作。
代价是撒谎:代码看起来"可以取消",实际不能。这是一种在 API 兼容性压力下的常见妥协,值得记一笔——读源码时看到"有名无实"的方法,先想它是不是为了签名兼容。
9.1.4 unresponsive 的双定时器:50ms 与 5000ms
这是整个文件里唯一有真正逻辑的地方,也是最容易被误读的地方:
browser-window.ts:23
let unresponsiveEvent: NodeJS.Timeout | null = null;
const emitUnresponsiveEvent = () => {
unresponsiveEvent = null;
if (!this.isDestroyed() && this.isEnabled()) {
this.emit('unresponsive');
}
};
this.webContents.on('unresponsive', () => {
if (!unresponsiveEvent) {
unresponsiveEvent = setTimeout(emitUnresponsiveEvent, 50);
}
});
this.webContents.on('responsive', () => {
if (unresponsiveEvent) {
clearTimeout(unresponsiveEvent);
unresponsiveEvent = null;
}
this.emit('responsive');
});
this.on('close', (event) => {
queueMicrotask(() => {
if (!unresponsiveEvent && !event?.defaultPrevented) {
unresponsiveEvent = setTimeout(emitUnresponsiveEvent, 5000);
}
});
});
this.webContents.on('destroyed', () => {
if (unresponsiveEvent) clearTimeout(unresponsiveEvent);
unresponsiveEvent = null;
});
四个监听器,一个共享变量。三种时序:
时序一:渲染进程卡住。 webContents 发 unresponsive → 起一个 50ms 定时器 → 50ms 内如果来了 responsive,取消定时器;没来,就 this.emit('unresponsive')。
为什么要延迟 50ms?因为 Chromium 的"无响应"判定本身有滞后,紧接着可能就恢复了。50ms 是一个去抖窗口:短到用户察觉不到延迟,长到能过滤掉"卡一下又好了"的抖动。
时序二:窗口关闭时卡住。 close 事件触发 → queueMicrotask 里检查:如果当前没有待发的 unresponsive,且 close 没被 preventDefault → 起一个 5000ms 定时器。
这里的 queueMicrotask 是关键。close 事件的同步阶段正是监听者调 event.preventDefault() 的时候。如果立刻判断 event.defaultPrevented,会读到 false(用户还没来得及阻止)。微任务在所有同步监听者跑完之后执行,此时 defaultPrevented 是最终值。
5000ms 的语义:用户点了关闭按钮,beforeunload 处理器卡住了渲染进程,窗口关不掉。5 秒后发 unresponsive,让应用有机会提示用户"这个页面卡住了,要不要强制关闭"。
时序三:responsive 无条件转发。 注意 this.emit('responsive') 在 if 外面——即使没有待发的 unresponsive(unresponsiveEvent 是 null),也照样转发 responsive。所以应用可能收到"没收到 unresponsive 却收到 responsive"的事件对。这是故意的不对称:responsive 是"现在好了"的陈述,不需要前置条件。
emitUnresponsiveEvent 里的 !this.isDestroyed() && this.isEnabled() 双重检查也是必要的:一个窗口可能在 50ms 内被销毁(定时器还在跑),或者被 setEnabled(false) 禁用(禁用的窗口不该报"无响应",它本来就不接受输入)。
这四段代码共同的模式是:所有异步路径都必须在触发点重新检查状态。 定时器捕获的只是"50ms 前发生了什么",不是"现在是什么状态"。
9.1.5 fromId 与 constructor.name:一个隐藏的强耦合
browser-window.ts:75
const isBrowserWindow = (win: any) => {
return win && win.constructor.name === 'BrowserWindow';
};
BrowserWindow.fromId = (id: number) => {
const win = BaseWindow.fromId(id);
return isBrowserWindow(win) ? (win as any as BWT) : null;
};
BaseWindow.fromId 返回的是任何 BaseWindow 子类的实例——BrowserWindow 只是其中一种。BrowserWindow.fromId 要过滤出自己这一类。
注意 isBrowserWindow 的实现有一个副作用:win && ... 在 win 为 null 时返回的是 null 而不是 false。后面用三元 ? : 判断,null 走 falsy 分支,所以行为正确;但如果有人把它改成 if (isBrowserWindow(win) === false),就会漏掉 null。一个 && 写法的返回值类型不一致,是这类小工具函数的通病。
过滤手段是 constructor.name === 'BrowserWindow'。不是 instanceof,不是 Symbol.hasInstance,不是 C++ 侧的类型标签。
为什么?因为 gin 包装的 C++ 对象没有可供 instanceof 使用的原型链身份。BrowserWindow 是 BaseWindow 的子类模板(CreateConstructor(..., BaseWindow::GetConstructorTemplate(isolate))),两个模板的 prototype 有继承关系,instanceof 理论上可用。但 BaseWindow.fromId 返回的是 从 WeakMap 里取的 JS wrapper,它的原型链取决于它被创建时用的是哪个模板——如果哪天两个模板被合并或替换,instanceof 会静默失效。
而 constructor.name 依赖的是:① BuildPrototype 里 prototype->SetClassName("BrowserWindow");② rolldown 的 keepNames(第 8 章 8.3.5)。两者少一个,这个判断就永远返回 false,BrowserWindow.fromId() 永远返回 null。
这是一个跨三层的契约:C++ 的 SetClassName + 构建期的 keepNames + JS 的这一行判断。 任何一环断掉,症状都是"fromId 返回 null",而不会有任何报错。第 8 章说过 keepNames 存在的理由是 BrowserWindow.name 是 API 的一部分,这里给出了它最直接的消费者。
9.1.6 getAllWindows 与 getFocusedWindow 的过滤差异
browser-window.ts:84
BrowserWindow.getAllWindows = () => {
return BaseWindow.getAllWindows().filter(isBrowserWindow) as any[] as BWT[];
};
getAllWindows 用同一个 isBrowserWindow 过滤。所以如果应用里既有 BrowserWindow 又有单独的 BaseWindow(Electron 30+ 支持),BrowserWindow.getAllWindows() 只返回前者。这符合直觉。
getFocusedWindow 的判据更多一层:
browser-window.ts:90
BrowserWindow.getFocusedWindow = () => {
for (const window of BrowserWindow.getAllWindows()) {
if (!window.isDestroyed() && window.webContents && !window.webContents.isDestroyed()) {
if (window.isFocused() || window.webContents.isDevToolsFocused()) return window;
}
}
return null;
};
四个条件串起来:窗口没销毁、webContents 存在、webContents 没销毁、窗口聚焦或 DevTools 聚焦。
第三个条件 !window.webContents.isDestroyed() 是防御性的:窗口还在但页面已销毁的状态是可能的(webContents.destroy() 之后窗口不自动关闭)。此时 window.isFocused() 可能还是 true,但返回一个没有页面的窗口给调用者是没意义的。
"DevTools 聚焦"算作窗口聚焦,这是一个产品决策:开发者把焦点放在 DevTools 上时,他心里的"当前窗口"仍然是那个被调试的窗口。如果不加这一条,getFocusedWindow() 在调试时会返回 null,很多依赖它的代码(比如"在当前窗口打开链接")会失效。
9.1.7 17 个转发方法:为什么不能省
browser-window.ts:109
BrowserWindow.prototype.loadURL = function (...args) {
return this.webContents.loadURL(...args);
};
loadURL、getURL、loadFile、reload、send、openDevTools、closeDevTools、isDevToolsOpened、isDevToolsFocused、toggleDevTools、inspectElement、inspectSharedWorker、inspectServiceWorker、showDefinitionForSelection、capturePage、getBackgroundThrottling、setBackgroundThrottling——17 个。
这些在 C++ 侧的 BrowserWindow 里一个都没有实现(electron_api_browser_window.cc:355 的 BuildPrototype 只加了三个:focusOnWebView、blurWebView、webContents)。全部在 JS 层转发。
为什么不放进 C++?三个理由:
...args的可变参数透传在 gin 里很贵。 C++ 侧要处理gin::Arguments,把 N 个参数逐个转成v8::Local<v8::Value>,再调webContents的方法。JS 的...args是语言原生能力,零成本。this.webContents可能为空。 窗口销毁后webContents是null,JS 层调this.webContents.loadURL()会抛TypeError: Cannot read properties of null——这个错误信息对用户是可理解的。C++ 层得自己判空并构造错误消息。- 这些方法的语义完全属于
webContents。window.loadURL只是"我的页面的 loadURL",没有任何窗口特有的逻辑要加。
第 8 章讲过"薄壳模块"的概念,这里是同一个模式的另一面:能用 JS 表达的东西不留到 C++。代价是 BrowserWindow.prototype 上有 17 个函数对象,每个窗口实例共享(在 prototype 上,不是每个实例一份),内存代价可以忽略。
9.1.8 _browserViews:一个正在被淘汰的数组
_init 里初始化了 this._browserViews = [],addBrowserView/removeBrowserView/getBrowserView(s)/setTopBrowserView 五个方法维护它。
browser-window.ts:178
BrowserWindow.prototype.addBrowserView = function (browserView: BrowserView) {
if (this._browserViews.includes(browserView)) return;
const ownerWindow = browserView.ownerWindow;
if (ownerWindow && ownerWindow !== this) {
ownerWindow.removeBrowserView(browserView);
}
this.contentView.addChildView(browserView.webContentsView);
browserView.ownerWindow = this;
browserView.webContents._setOwnerWindow(this);
this._browserViews.push(browserView);
};
四个动作:去重(已在数组里就直接返回)、夺所有权(从原窗口移除)、挂到 contentView、双向绑定(ownerWindow 与 _setOwnerWindow)。
"夺所有权"这几行值得注意:同一个 BrowserView 被加到第二个窗口时,先从第一个窗口移除,而不是报错。这让"把视图从一个窗口搬到另一个窗口"变成一次 addBrowserView 调用。
BrowserView 在 Electron 30 被标记为 deprecated,替代品是 WebContentsView + contentView.addChildView()。所以 _browserViews 这个数组是过渡期的兼容层:它维护的是"这个窗口上有哪些旧的 BrowserView",而新的 WebContentsView 直接进 contentView 的子视图列表,不进这个数组。
这解释了一个常见的困惑:win.getBrowserViews() 返回的数组不包含你用 win.contentView.addChildView(new WebContentsView()) 加的视图。两个世界,两套记录。
closed 事件里的清理也印证了这一点:
browser-window.ts:59
this.on('closed', () => {
this._browserViews.forEach((b) => b.webContents?.close({ waitForBeforeUnload: true }));
});
只关 _browserViews 里的,因为新的 WebContentsView 的 webContents 由它自己管理(窗口关闭时 contentView 销毁子视图,子视图析构时销毁自己的 webContents)。
9.2 第二身体:api::BaseWindow
9.2.1 一次构造的六个阶段
api::BaseWindow 有两个构造函数,一个是另一个的延续:
electron_api_base_window.cc:130
BaseWindow::BaseWindow(v8::Isolate* isolate, const gin_helper::Dictionary& options) {
// ... 见下
}
// electron_api_base_window.cc:174
BaseWindow::BaseWindow(gin::Arguments* args, const gin_helper::Dictionary& options)
: BaseWindow(args->isolate(), options) {
InitWithArgs(args);
// Init window after everything has been setup.
window()->InitFromOptions(options);
}
第一个构造函数做四件事,第二个再做两件。按发生顺序排:
| # | 位置 | 动作 |
|---|---|---|
| 1 | 130 | 读 title,置 title_set_from_api_ |
| 2 | 137 | 读 parent,存成 v8::Global |
| 3 | 143 | 若 webPreferences.offscreen,强制 frame = false |
| 4 | 151 | NativeWindow::Create(GetID(), options, parent_native) |
| 5 | 153 | window_->AddObserver(this) |
| 6 | 155 | SetContentView(View::Create(isolate)) |
| 7 | 174→176 | InitWithArgs(args):建 JS wrapper,调 _init |
| 8 | 177 | window()->InitFromOptions(options):真正显示窗口 |
阶段 4 到阶段 8 之间隔着一个 JS 世界。 InitWithArgs 会创建 wrapper,然后调用 BrowserWindow.prototype._init(9.1.2)。也就是说:C++ 对象已经存在,原生窗口已经创建(views::Widget::Init 已经跑完),但窗口还没定位、没设标题、没显示——此时 JS 代码开始执行。
这个顺序是所有"构造期可见"现象的根源:
new BrowserWindow({ width: 800, show: false })
// _init 里能读 this.webContents、this.id、this.contentView
// 但 win.isVisible() 还是 false,win.getBounds() 是构造时的 800x600
_init 里如果调 this.setSize(1000, 700),会先生效,然后 InitFromOptions 里的尺寸约束把它 clamp 回来——因为 InitFromOptions 在后面。"构造参数优先"在这里不是设计选择,是执行顺序的副产品。
9.2.2 阶段 3:为什么 offscreen 必须无框
electron_api_base_window.cc:146
gin_helper::Dictionary web_preferences;
bool offscreen;
if (options.Get(options::kWebPreferences, &web_preferences) &&
web_preferences.Get(options::kOffscreen, &offscreen) && offscreen) {
const_cast<gin_helper::Dictionary&>(options).Set(options::kFrame, false);
}
const_cast 说明 options 本来是 const——它被改了一次,改的是 frame。
为什么离屏渲染必须无框?因为 OSR(Off-Screen Rendering)的定义是"页面渲染到一个你可以拿走的缓冲区,不经过窗口系统的合成器"。如果窗口有原生边框,边框由操作系统绘制,OSR 的缓冲区里就没有它;此时 capturePage() 或 paint 事件给的图与用户在窗口里看到的就不一致。
更要紧的是:有框窗口的 contentView 尺寸 ≠ 窗口尺寸(差一个标题栏高度)。OSR 的 OnPaint 拿到的尺寸来自 webContents 的视图,如果视图尺寸依赖原生 frame 的 inset,而 frame 又不在缓冲区里,最终图片的宽高比就错了。
强制 frame: false 把两者对齐:无框窗口的 contentView 就是整个窗口,OSR 缓冲区与窗口 1:1。
这个改写发生在 NativeWindow::Create 之前,所以 has_frame_ 读到的已经是 false。顺序在这里是正确性的一部分,不能挪到后面。
9.2.3 阶段 7:InitWithArgs 与 _init 的调用点
InitWithArgs 是 gin 的通用机制,BaseWindow 没有重写它。它的作用是:把 C++ 对象与 JS wrapper 关联(InitWith),然后把剩余的构造参数交给 gin_helper 的约定——如果 prototype 上有一个叫 _init 的方法,就调用它。
这就是 BrowserWindow.prototype._init 的调用来源。BaseWindow 自己没有 _init,所以 new BaseWindow() 不会执行那 70 行。
这里存在一个不对称:BaseWindow 的 JS 层是空的,BrowserWindow 的 JS 层有 233 行。 前者能直接用,后者需要先加载 browser-window.ts。
这也解释了一个错误信息的来源:
new BrowserWindow() // 在 app ready 之前
// Error: Cannot create BrowserWindow before app is ready
这个检查在 BrowserWindow::New(electron_api_browser_window.cc:322):
if (!Browser::Get()->is_ready()) {
thrower.ThrowError("Cannot create BrowserWindow before app is ready");
return nullptr;
}
注意它在 New 里,不在构造函数里。New 是 gin 的工厂函数,在分配对象之前被调用。所以"app 未 ready"时根本不会创建 C++ 对象,不会有半成品需要清理。这是"把检查放在最早可能的位置"的一个正面例子。
9.2.4 self_ref_:为什么 C++ 对象要抓住自己的 JS wrapper
electron_api_base_window.cc:194
void BaseWindow::InitWith(v8::Isolate* isolate, v8::Local<v8::Object> wrapper) {
gin_helper::TrackableObject<BaseWindow>::InitWith(isolate, wrapper);
// Reference this object in case it got garbage collected.
self_ref_.Reset(isolate, wrapper);
}
self_ref_ 是一个 v8::Global<v8::Value>,指向自己的 wrapper。这形成了循环引用:C++ 对象持有 JS 对象的强引用,JS 对象的 internal field 持有 C++ 对象的裸指针。
正常情况下这是内存泄漏的经典形状。这里不泄漏,因为循环被手工打破:
electron_api_base_window.cc:182
BaseWindow::~BaseWindow() {
CloseImmediately();
base::SingleThreadTaskRunner::GetCurrentDefault()->DeleteSoon(FROM_HERE, window_.release());
// Remove global reference so the JS object can be garbage collected.
self_ref_.Reset();
}
self_ref_.Reset() 在析构里。所以顺序是:某个事件触发 Destroy() → 析构 → 释放 self_ref_ → JS wrapper 变成可回收。
那"某个事件"是什么?两条路:
- 窗口被关闭:
OnWindowClosed里PostTask(GetDestroyClosure())(9.2.6); - 进程退出:
CleanedUpAtExit的机制(TrackableObjectBase继承它)。
如果没有 self_ref_,会发生什么?new BrowserWindow() 之后如果用户不保存引用:
new BrowserWindow({ width: 800 })
// 没有任何变量指向它
JS 的 GC 会发现这个 wrapper 不可达,回收它。wrapper 的 internal field 里那个 C++ 指针就悬垂了——但原生窗口还在屏幕上!用户看到一个无法用 JS 控制的窗口,点关闭按钮会调到已释放的 C++ 对象。
self_ref_ 的作用就是让 JS wrapper 活得和 C++ 对象一样久。这是一个"反向的 GC 根":不是 JS 决定 C++ 的寿命,是 C++ 决定 JS 的寿命。
第 7 章讲过 TrackableObject 的 MarkDestroyed() 把 internal field 0 置空。这三者(self_ref_、MarkDestroyed、RemoveFromWeakMap)是同一套生命周期协议的三个部件:
| 部件 | 时机 | 效果 |
|---|---|---|
self_ref_ 存在 | 构造完成 | JS wrapper 不被 GC |
MarkDestroyed() | OnWindowClosed | 之后任何方法调用都视为"已销毁" |
self_ref_.Reset() | C++ 析构 | JS wrapper 可被 GC |
中间那段"已销毁但未回收"的窗口,就是用户能观察到 win.isDestroyed() === true 而 win 对象仍然可读的状态。它不是 bug,是协议里的一个合法阶段。
9.2.5 DeleteSoon:析构不能在原生栈上
electron_api_base_window.cc:186
base::SingleThreadTaskRunner::GetCurrentDefault()->DeleteSoon(FROM_HERE, window_.release());
window_ 是 std::unique_ptr<NativeWindow>。release() 放弃所有权,DeleteSoon 在下一个任务里 delete。
为什么不直接让 unique_ptr 析构?注释给了理由:
// Destroy the native window in next tick because the native code might be
// iterating all windows.
"原生代码可能正在遍历所有窗口"。典型场景是 WindowList::CloseAllWindows():
window_list.cc:78
std::vector<base::WeakPtr<NativeWindow>> weak_windows = ConvertToWeakPtrVector(GetInstance()->windows_);
for (const auto& window : weak_windows) {
if (window && !window->IsClosed())
window->Close();
}
它先把 raw_ptr 转成 WeakPtr 再遍历——这一手是为了"遍历中窗口被删"的安全。但即使这样,Close() 内部如果同步销毁了窗口,windows_ 这个 vector 就会在遍历中途被改写(RemoveWindow 里 std::erase),而 weak_windows 是复制出来的,安全;可如果有别的代码正在用 raw_ptr 直接遍历 windows_,就会踩到已释放内存。
DeleteSoon 把"销毁"推到当前任务之后,保证任何同步遍历都能走完。
这个模式在 Electron 里反复出现,第 8 章 8.5.6 的 thread_local loader、第 7 章的 SecondWeakCallback 的 DeleteSoon 都是同一个思路:销毁延迟一个任务,换取"当前栈上的所有指针仍然有效"。
代价是"销毁不是即时的"。win.destroy() 之后立刻检查原生资源,可能发现它还在。这也是为什么 BrowserWindow 有一个显式的 MarkDestroyed()(逻辑标记)与真正的析构分开——逻辑死亡与物理死亡是两个时刻。
9.2.6 OnWindowClosed:六步的顺序不能换
electron_api_base_window.cc:207
void BaseWindow::OnWindowClosed() {
weak_factory_.InvalidateWeakPtrs();
RemoveFromWeakMap();
window_->RemoveObserver(this);
MarkDestroyed();
window_->FlushWindowState();
Emit("closed");
parent_window_.Reset();
base::SingleThreadTaskRunner::GetCurrentDefault()->PostTask(FROM_HERE, GetDestroyClosure());
}
七步(上面代码里是七行有效语句)。逐条问"能不能换位置":
① InvalidateWeakPtrs() 必须第一。 注释:
// Invalidate weak ptrs before the Javascript object is destroyed,
// there might be some delayed emit events which shouldn't be triggered after this.
EmitEventSoon(9.2.7)投递的任务持有 weak_factory_.GetWeakPtr()。InvalidateWeakPtrs() 让这些已经投递但还没执行的任务全部失效。如果放在 Emit("closed") 之后,closed 的监听者里可能触发一个 EmitEventSoon,它会被投递出去并在之后执行——此时窗口已经"关闭",却又收到 blur 之类的事件。
② RemoveFromWeakMap() 第二。 之后 BaseWindow.fromId(id) 返回 null。这是"已关闭"对外可见的第一个信号。放在 Emit("closed") 之前,是因为监听者里可能调 fromId。
③ RemoveObserver 第三。 原生窗口不再通知这个 API 对象。
④ MarkDestroyed() 第四。 internal field 置空,之后 IsDestroyed() 为真。放在 Emit 之前很关键:监听者里调 win.isDestroyed() 必须得到 true。 如果反过来,监听者会以为窗口还活着并尝试操作它。
⑤ FlushWindowState() 第五。 把待写的窗口状态(9.3.10)落盘。必须在 Emit("closed") 之前,因为监听者可能立刻读文件或者崩溃。
⑥ Emit("closed") 第六。 用户的 closed 监听器在这里跑。此时:弱指针失效、fromId 查不到、isDestroyed() 为真、状态已保存。四件事都完成了,才通知用户。
⑦ PostTask(GetDestroyClosure()) 最后。 真正的 C++ 析构再晚一个任务。注意用的是 PostTask 而不是 DeleteSoon——GetDestroyClosure() 内部会调 Destroy(),而 Destroy() 走的是 TrackableObjectBase 的通用路径(第 7 章 7.13 讲过),它有一整套 DisallowJavascriptExecutionScope 的保护。
七步的顺序是按"对外可见性递增"排的:先让内部状态一致,再让查询接口失效,最后通知用户。任何一步提前,用户就会看到一个不一致的世界。
9.2.7 EmitEventSoon:为什么 blur/focus 是异步的
electron_api_base_window.h:314
template <typename... Args>
void EmitEventSoon(std::string_view eventName) {
content::GetUIThreadTaskRunner({})->PostTask(
FROM_HERE,
base::BindOnce(base::IgnoreResult(&BaseWindow::Emit<Args...>),
weak_factory_.GetWeakPtr(), eventName));
}
OnWindowBlur、OnWindowFocus、OnWindowStateRestored 用的是它,而不是直接 Emit。其它二十几个通知都是同步 Emit。
为什么偏偏这三个异步?
blur/focus 是重入风险最高的两个事件。 它们由平台的焦点切换触发。平台在切换焦点时,内部处在一个"正在进行中的状态迁移"里:Linux 的 PlatformWindow 正在处理 OnWindowFocusChanged,macOS 的 NSWindow 正在 becomeKeyWindow 中途,Windows 的 WM_SETFOCUS 还在消息处理里。
此时如果同步 Emit('focus'),用户的 JS 代码可能在监听器里做任何事:win.blur()、win.focus()、win.close()、创建新窗口、打开模态对话框。在原生栈中间调用原生 API 是未定义行为的温床——比如在 becomeKeyWindow 里面再次 makeKeyWindow。
PostTask 把 JS 的执行推到当前原生事件处理完之后,此时焦点切换已经稳定。用户看到的 focus 事件依然是"这个窗口被聚焦了",只是晚了不到一个 tick。
EmitEventSoon 用的弱指针是另一半设计。 如果窗口在任务执行前被销毁,weak_factory_ 失效,BindOnce 不会调用 Emit。一个已关闭的窗口不会收到任何延迟的 focus/blur——这就是 9.2.6 第一步必须 InvalidateWeakPtrs() 的原因。
base::IgnoreResult 也是必要的:Emit 返回 bool(表示是否 preventDefault),而 BindOnce 的返回类型要匹配 OnceClosure。忽略返回值在这里是安全的——这些事件不可取消。
对比一下 OnWindowShow 与 OnWindowHide,它们是同步的:
electron_api_base_window.cc:272
void BaseWindow::OnWindowShow() {
Emit("show");
}
void BaseWindow::OnWindowHide() {
Emit("hide");
}
show / hide 不像 focus 那样处在平台状态机的中途:窗口已经显示(或隐藏)完了,通知只是一个陈述。用户在监听器里调 win.hide() 会形成一次新的、完整的状态迁移,而不是插入到正在进行的迁移里。
"哪些事件该异步"这个问题没有通用答案,它取决于平台在发这个通知时是否处在不可重入的中间态。 这是 Electron 里少数必须按平台语义逐个判断的地方之一。
9.2.8 TrackableObject:WeakMap 与 MarkDestroyed 的配合
trackable_object.h:70
static T* FromWeakMapID(v8::Isolate* isolate, int32_t id) {
if (!weak_map_) return nullptr;
v8::HandleScope scope(isolate);
v8::MaybeLocal<v8::Object> object = weak_map_->Get(isolate, id);
if (object.IsEmpty()) return nullptr;
T* self = nullptr;
gin::ConvertFromV8(isolate, object.ToLocalChecked(), &self);
return self;
}
weak_map_ 的类型是 electron::KeyWeakMap<int32_t>*,每个模板实例一份(static 成员,leaked on purpose)。KeyWeakMap 是第 7 章讲过的"用 JS 的 WeakMap 实现的 weak map"——键是一个 int32_t(包装成 JS 数字),值是 wrapper 对象。
它的关键性质:值不会被强引用。所以 fromId 查到一个对象,如果那个对象除了 WeakMap 之外没有别的引用,下一次 GC 就会回收它。这看起来会让 fromId 时好时坏。
不会,因为 self_ref_(9.2.4)。只要窗口活着,self_ref_ 就强引用着 wrapper,WeakMap 里那条记录也就一直有效。
MarkDestroyed 是这个协议的另一半:
trackable_object.h:51
void MarkDestroyed() {
v8::HandleScope scope(gin_helper::Wrappable<T>::isolate());
v8::Local<v8::Object> wrapper = gin_helper::Wrappable<T>::GetWrapper();
if (!wrapper.IsEmpty()) {
wrapper->SetAlignedPointerInInternalField(0, nullptr, v8::kEmbedderDataTypeTagDefault);
gin_helper::WrappableBase::wrapper_.ClearWeak();
}
}
两个动作:internal field 0 置空、wrapper 的弱引用清除(变成强引用)。
第二个动作容易被忽略。WrappableBase::wrapper_ 默认是一个 v8::Global 但弱的(这就是"弱回调两遍协议"的起点,第 7 章 7.13)。ClearWeak() 之后它变强了。
为什么"销毁"反而要变强?因为 MarkDestroyed 之后,对象进入"已销毁但可能被用户持有"的状态。此时如果 wrapper 被 GC,win.isDestroyed() 就没法调了(对象都没了,谈不上方法调用)。变强引用保证:用户手里的 win 变量在 closed 之后仍然是一个可用对象,只是所有方法都会失败。
这构成了一个完整的、用户在 JS 侧能感知的三态:
| 状态 | isDestroyed() | 方法调用 | id |
|---|---|---|---|
| 活着 | false | 正常 | 可读 |
| 已关闭未回收 | true | 抛 Object has been destroyed | 可读(9.1.2 冻结) |
| 已回收 | — | win 是 null/不可达 | 不可达 |
第二态是 Electron 里最常见的报错来源,也是最容易被误解的:报错不是"对象不存在",是"对象存在但它的原生部分不存在了"。 这两者的区别决定了排查方向。
9.2.9 SetBounds 的部分更新
electron_api_base_window.cc:502
void BaseWindow::SetBounds(v8::Local<v8::Object> partial, gin::Arguments* const args) {
// Any of x, y, width and height may be left out and keeps its current value.
gin_helper::Dictionary dict(args->isolate(), partial);
std::optional<float> x, y, width, height;
if (!ReadCoordinate(dict, "x", &x) || ... ) { args->ThrowError(); return; }
gfx::RectF bounds(window_->GetBounds());
if (x) bounds.set_x(*x);
if (y) bounds.set_y(*y);
if (width) bounds.set_width(*width);
if (height) bounds.set_height(*height);
bool animate = false;
args->GetNext(&animate);
window_->SetBounds(gfx::ToRoundedRect(bounds), animate);
}
三个设计点:
① 用 std::optional<float> 而不是 int。 所以能区分"没传"与"传了 0"。win.setBounds({ x: 0 }) 是把 x 设为 0,不是"保持不变"。
② 用 gfx::RectF 累积再取整。 注释说"rounding 与 gfx::Rect 的转换器一致"。逐个取整会产生累积误差:x=10.5, width=100.5 分开取整是 11 + 101,一起取整是 x=11, right=111(宽度 100)。后者才是"用户想要的那个矩形"。
③ bool animate 从第二个参数读。 注意 args->GetNext(&animate) 是在读完第一个参数(partial 对象)之后——gin::Arguments 有游标,GetNext 顺序消费。所以 win.setBounds({x: 0}, true) 的第二个参数被读成 animate。
animate 在 Linux 与 Windows 上基本是空操作(只有 macOS 的部分 API 支持动画),但它必须被消费——否则 gin::Arguments 会认为有多余参数,某些版本会抛错。
9.2.10 约 180 个方法:API 面是怎么长出来的
BuildPrototype 是一串 .SetMethod<&BaseWindow::Xxx>("xxx"),从 1400 行一直排到 1600 行。数一下:约 180 个方法 + 属性,其中带 #if BUILDFLAG(IS_MAC) / IS_WIN 条件的大约 40 个。
平台专属的方法直接不出现在其他平台的 prototype 上。所以:
// 在 Linux 上
typeof win.setWindowButtonVisibility // 'undefined'
不是"存在但抛错",是不存在。这个选择让特性检测变得可靠:if (win.setWindowButtonVisibility) 能正确判断平台能力。
代价是类型定义必须按平台分。typings/electron.d.ts 里这些方法被标了 @platform darwin,但 TypeScript 不做平台条件编译——win.setWindowButtonVisibility() 在 Linux 上编译通过、运行时报 not a function。这是 Electron 类型系统的一个已知缺口,没有优雅的解法(除非给每个平台发一份 .d.ts)。
9.3 第三身体:electron::NativeWindow
9.3.1 88 个纯虚函数:一个刻意宽大的接口
native_window.h:61
class NativeWindow : public views::WidgetDelegate {
public:
~NativeWindow() override;
...
virtual void SetContentView(views::View* view) = 0;
virtual void Close() = 0;
virtual void CloseImmediately() = 0;
...
统计这个头文件:88 个 = 0,134 个 virtual,33 个 NotifyWindow* 方法,662 行。
88 个纯虚意味着这是一个接口类,不是"大部分能复用、少数要覆盖"的基类。NativeWindowViews 与 NativeWindowMac 各自实现 105 个 override(native_window_views.h 计数),它们之间共享的代码只有 native_window.cc 那 1209 行(约 60 个非虚的默认实现)。
这个设计有一个代价和一个收益。
代价:加一个平台相关的 API,要改三个地方(纯虚声明、两个实现)。实际开发中这个成本很明显,比如 SetWindowButtonVisibility(macOS 的交通灯按钮)出现在 6 个虚函数里,Linux 与 Windows 各自实现成空函数或 NOTIMPLEMENTED()。
收益:"这个平台不支持它"这件事在类型系统里是明确的。 如果 NativeWindow 提供默认空实现(像 SetMenu 那样 virtual void SetMenu(ElectronMenuModel* menu) {}),那么"忘记实现"与"有意不实现"在代码里长得一样。纯虚强制每个平台表态。
实际的分布很有意思:88 个纯虚里,有约 30 个是平台独有的(#if BUILDFLAG(IS_MAC) 块内),在另一个平台上根本不是虚函数——连声明都不存在。所以两个实现的接口面并不完全一致,它们各自是本平台能力的完整表达。
9.3.2 继承 views::WidgetDelegate:一个必须回答的问题
native_window.h:61
class NativeWindow : public views::WidgetDelegate {
WidgetDelegate 是 Chromium views 框架里的"窗口内容提供者"。它要回答:这个窗口的标题是什么、内容视图是哪个、最小尺寸是多少、关闭时怎么办。
NativeWindow 实现了其中一部分:
native_window.h:500
views::Widget* GetWidget() override;
const views::Widget* GetWidget() const override;
只有两个。 而 WidgetDelegate 有几十个虚函数。
为什么只实现这两个?因为其余的由 NativeWindowClientView 与 RootView 承担了。views::Widget 问"你的 client view 是什么",答案由 CreateClientView 给出(native_window_views.cc:2003):
views::ClientView* NativeWindowViews::CreateClientView(views::Widget* widget) {
return new NativeWindowClientView{widget, &root_view_, this};
}
WidgetDelegate 的默认实现返回一个标准 ClientView;Electron 换成一个自己的,它持有 RootView 的引用。这是"用组合替代继承"的一处:窗口的布局逻辑在 RootView 里,NativeWindow 只做转发。
GetWidget() 有两个版本(const 与非 const),这是 C++ 的常规做法,但在这里有一个具体用途:
native_window.cc:827
views::Widget* NativeWindow::GetWidget() { return widget(); }
const views::Widget* NativeWindow::GetWidget() const { return widget(); }
两个都返回 widget_.get()。const 版本不能调非 const 的 widget()(虽然 widget() 本身是 const 方法,返回非 const 指针),所以严格说只需要一个。写成两个是为了满足基类的两个纯虚声明。
9.3.3 构造函数:8 个 const 成员
native_window.cc:91
NativeWindow::NativeWindow(const int32_t base_window_id,
const gin_helper::Dictionary& options,
NativeWindow* parent)
: base_window_id_{base_window_id},
title_bar_style_{options.ValueOrDefault(options::kTitleBarStyle, TitleBarStyle::kNormal)},
transparent_{options.ValueOrDefault(options::kTransparent, false)},
enable_larger_than_screen_{options.ValueOrDefault(options::kEnableLargerThanScreen, false)},
is_modal_{parent != nullptr && options.ValueOrDefault(options::kModal, false)},
has_frame_{options.ValueOrDefault(options::kFrame, true) &&
title_bar_style_ == TitleBarStyle::kNormal} {
六个在初始化列表里,加 has_client_frame_(类内初始化,见下)与 window_id_(类内 ++next_id_),一共 8 个 const 成员。
const 在这里是一份契约:窗口创建之后,这些属性不可变。 不是因为改不了,是因为"改一半会很危险":
transparent_改了之后,原生窗口的opacity已经设了kTranslucent,改这个 bool 不会改回原生状态;has_frame_改了之后,views::Widget的remove_standard_frame已经生效,边框已经画/没画;title_bar_style_改了之后,views::Widget的非客户区视图已经建好。
如果这些是普通成员,某个 SetXxx 方法顺手改一下,就会造成"JS 状态与原生状态分离"。用 const 把这条路堵死,强制所有可变属性走平台 API,而不是改内存。
has_frame_ 的推导值得单独看:
native_window.cc:102-103
has_frame_{options.ValueOrDefault(options::kFrame, true) &&
title_bar_style_ == TitleBarStyle::kNormal}
frame: true 且 titleBarStyle: 'normal' 才算有框。所以:
new BrowserWindow({ frame: true, titleBarStyle: 'hidden' })
// has_frame_ === false
这解释了一个常见困惑:为什么设了 titleBarStyle: 'hidden' 之后 win.setWindowButtonVisibility() 还能用(macOS 的交通灯还在),但 frame 概念上已经是"无框"了。titleBarStyle 不是"改边框样式",是"我去画边框"。 hidden / hiddenInset / customButtonsOnHover 三个值都意味着"系统边框不要了,我来"。
is_modal_ 的推导也有一个细节:
is_modal_{parent != nullptr && options.ValueOrDefault(options::kModal, false)}
没有父窗口就不可能是模态。 modal: true 单独用是无效的——模态的语义是"阻塞父窗口",没有父窗口就没有可阻塞的对象。
has_client_frame_ 是类内初始化的:
native_window.h:547
const bool has_client_frame_ = PlatformHasClientFrame();
native_window.cc:1174
bool NativeWindow::PlatformHasClientFrame() {
#if defined(USE_OZONE)
// Ozone X11 likes to prefer custom frames,
// but we don't need them unless on Wayland.
static const bool has_client_frame =
!ui::OzonePlatform::GetInstance()
->GetPlatformRuntimeProperties()
.supports_server_side_window_decorations;
return has_client_frame;
#else
return false;
#endif
}
static const 的原因:这是一个运行期才能确定的平台属性(Wayland 不做服务端装饰,X11 做),但一个进程内不会变。所以查一次就够。
has_client_frame 的含义是"窗口有标准边框,但由客户端绘制"。这只在 Wayland 上成立:Wayland 的协议不提供系统标题栏,应用必须自己画。X11 上 supports_server_side_window_decorations 为 true,has_client_frame 为 false。
这个 bool 在后续代码里被用在三个地方:remove_standard_frame 的判断、params.opacity 的设置、ContentBoundsToWindowBounds 的提前返回。一个平台属性影响三个不同层面,这就是为什么它必须在构造时定死。
9.3.4 InitFromOptions:22 个动作的顺序
这是整个 NativeWindow 里最长的方法(native_window.cc:178–305,约 128 行)。按顺序列:
| # | 动作 | 为什么在这个位置 |
|---|---|---|
| 1 | 读 useContentSize | 决定后面所有尺寸操作的单位 |
| 2 | 合并 min/max 约束(保留平台已有的) | 平台可能已在构造函数里设了约束(enable_larger_than_screen) |
| 3 | INT_MAX 处理 | maxWidth: -1 表示"无上限" |
| 4 | ClampSize 并把结果写回 | 用户给的初始尺寸可能违反约束 |
| 5 | 设置 position 或 center | 必须在尺寸之后:居中要用最终尺寸算 |
| 6 | Windows 上 SetPosition 调两次 | 已知 workaround(issue #10862) |
| 7 | SetClosable / SetMovable | 平台样式位 |
| 8 | SetHasShadow | |
| 9 | SetOpacity | |
| 10 | SetAlwaysOnTop | |
| 11 | fullscreenable 的推导 | fullscreen: false 在 mac 上隐含 fullscreenable: false |
| 12 | SetFullScreenable | 必须在 fullscreen 之前 |
| 13 | RestoreWindowState(options) | 必须在 fullscreen/kiosk 之前,见 9.3.10 |
| 14 | SetFullScreen(true)(若 fullscreen 且未从状态恢复) | |
| 15 | SetResizable | |
| 16 | SetSkipTaskbar | |
| 17 | SetKiosk | 在 resizable 之后:kiosk 隐含不可 resize |
| 18 | SetVibrancy(mac)/ SetBackgroundMaterial(win) | |
| 19 | SetBackgroundColor | 在 vibrancy 之后:IsTranslucent() 需要知道 vibrancy 状态 |
| 20 | SetTitle | 标题的默认值来自 Browser::Get()->GetName() |
| 21 | SaveWindowState() | 把恢复后的状态写回,覆盖掉的旧值 |
| 22 | Show()(若 show 不为 false) | 最后一步 |
六处顺序依赖,每一处都是踩过的坑:
第 5 步在 4 之后。 Center() 要用窗口尺寸算中心。如果先居中再设尺寸,居中位置就错了。
第 11 步的 fullscreen: false 特例。 代码:
native_window.cc:252-256
bool fullscreenable = true;
bool fullscreen = false;
if (options.Get(options::kFullscreen, &fullscreen) && !fullscreen) {
// Disable fullscreen button if 'fullscreen' is specified to false.
#if BUILDFLAG(IS_MAC)
fullscreenable = false;
#endif
}
options.Get(options::kFullScreenable, &fullscreenable);
fullscreen: false 在 macOS 上隐含 fullscreenable: false(绿色按钮变灰)。Windows 与 Linux 上没有这个隐含关系。然后 options.Get(kFullScreenable, ...) 允许用户显式覆盖——所以 { fullscreen: false, fullscreenable: true } 是合法的,结果是可以全屏但初始不全屏。
这个 #if 是平台语义差异的直接体现:macOS 的全屏按钮是窗口控件的一部分,禁用它有视觉反馈;Windows 的最大化按钮与全屏是两回事。
第 13 步的位置是最讲究的。 注释:
// Restore window state (bounds and display mode) at this point in
// initialization. We deliberately restore bounds before display modes
// (fullscreen/kiosk) since the target display for these states depends on the
// window's initial bounds. Also, restoring here ensures we respect min/max
// width/height and fullscreenable constraints.
三个理由:① 显示模式的目标显示器取决于窗口的初始 bounds(在哪个屏幕上全屏);② 此处已设过 min/max,恢复的尺寸会被约束;③ 此处已设过 fullscreenable,如果它是 false,恢复成全屏会被拒。
第 19 步在 18 之后,因为 IsTranslucent() 会读 vibrancy_ / background_material_:
native_window.cc:870
bool NativeWindow::IsTranslucent() const {
if (transparent()) return true;
#if BUILDFLAG(IS_MAC)
if (!vibrancy_.empty()) return true;
#endif
#if BUILDFLAG(IS_WIN)
if (!background_material_.empty() && background_material_ != "none") return true;
#endif
return false;
}
所以 new BrowserWindow({ vibrancy: 'under-window' }) 会自动得到透明背景色(SK_ColorTRANSPARENT),因为 SetBackgroundColor 里的逻辑是:
native_window.cc:295-296
} else if (IsTranslucent()) {
background_color = SK_ColorTRANSPARENT;
}
如果顺序反了(先设背景色再设 vibrancy),IsTranslucent() 还是 false,背景色就是白的,vibrancy 效果被白色盖住。这是一个只靠跑起来才能发现的 bug,因为没有任何报错。
第 21 步 SaveWindowState() 在 22 之前。 先把"恢复后、约束后"的最终状态写回存储,再显示。如果反过来,Show() 触发的 resize 会通过 DebouncedSaveWindowState 写一个中间态。
第 22 步最后。 在此之前窗口是隐藏的(views::Widget 创建时不显示)。所有设置都在隐藏状态下完成,用户看不到闪烁。
9.3.5 尺寸约束的两份副本
native_window.h:513
// Minimum and maximum size.
std::optional<extensions::SizeConstraints> size_constraints_;
// Same as above but stored as content size, we are storing 2 types of size
// constraints because converting between them will cause rounding errors
// on HiDPI displays on some environments.
std::optional<extensions::SizeConstraints> content_size_constraints_;
两份约束,互斥:SetSizeConstraints 会 content_size_constraints_.reset(),SetContentSizeConstraints 会 size_constraints_.reset()。所以任何时刻最多一份有值。
为什么不能只存一份然后按需转换?
native_window.cc:377
extensions::SizeConstraints NativeWindow::GetSizeConstraints() const {
if (size_constraints_) return *size_constraints_;
if (!content_size_constraints_) return {};
// Convert content size constraints to window size constraints.
extensions::SizeConstraints constraints;
if (content_size_constraints_->HasMaximumSize()) {
gfx::Rect max_bounds = ContentBoundsToWindowBounds(
gfx::Rect(content_size_constraints_->GetMaximumSize()));
constraints.set_maximum_size(max_bounds.size());
}
...
}
转换是有损的:内容尺寸 → 窗口尺寸要加边框,窗口尺寸 → 内容尺寸要减边框,而边框尺寸本身是浮点数(HiDPI 下 0.5px 很常见)。来回转换两次,1000 → 1000.5 → 1000(或 999)的误差就出现了。
GetContentSizeConstraints 的注释把这个代价写明了:
// Note that we are not caching the results, because Chromium reccalculates
// window frame size everytime when min/max sizes are passed, and we must
// do the same otherwise the resulting size with frame included will be wrong.
不缓存。每次都要重新算,因为 Chromium 每次都在重算。这个"必须每次都算"的要求与"我们存了两份以避免转换"的初衷看起来矛盾,但两者管的是不同的事:
- 存两份:避免"用户设内容尺寸 → 存成窗口尺寸 → 读内容尺寸"这条往返链的误差累积;
- 不缓存:每次从当前 frame 重算,因为 frame 尺寸会变(换主题、改 DPI、切显示器)。
一个管"跨调用的一致性",一个管"与 Chromium 的一致性"。
native_window.cc:400 的注释还给出了一个平台差异:
// Windows/Linux:
// The return value of GetContentSizeConstraints will be passed to Chromium
// to set min/max sizes of window. Note that we are returning content size
// instead of window size because that is what Chromium expects, see the
// comment of |WidgetSizeIsClientSize| in Chromium's codebase to learn more.
//
// macOS:
// The min/max sizes are set directly by calling NSWindow's methods.
Chromium 在 Windows/Linux 上认为 Widget 的尺寸是客户区尺寸(WidgetSizeIsClientSize),macOS 上认为它是窗口尺寸。所以同一个 GetContentSizeConstraints(),在两个平台上被不同的消费者用不同的方式解释。Electron 的抽象层必须同时满足两边。
9.3.6 坐标转换:三个平台,三种做法
内容坐标 ↔ 窗口坐标的转换是窗口系统里最容易出错的地方。Electron 把它做成两个纯虚:
virtual gfx::Rect ContentBoundsToWindowBounds(const gfx::Rect& bounds) const = 0;
virtual gfx::Rect WindowBoundsToContentBounds(const gfx::Rect& bounds) const = 0;
macOS:
native_window_mac.mm:1634
gfx::Rect NativeWindowMac::ContentBoundsToWindowBounds(const gfx::Rect& bounds) const {
if (has_frame()) {
gfx::Rect window_bounds([window_ frameRectForContentRect:bounds.ToCGRect()]);
int frame_height = window_bounds.height() - bounds.height();
window_bounds.set_y(window_bounds.y() - frame_height);
return window_bounds;
} else {
return bounds;
}
}
Cocoa 的坐标系原点在左下,frameRectForContentRect: 返回的矩形原点已经是窗口左下角。而 Electron/Chromium 用的 gfx::Rect 原点在左上。所以 set_y(y - frame_height) 把"左下原点"翻成"左上原点"。
反过来的 WindowBoundsToContentBounds 是 + frame_height。一对互为逆运算的偏移,方向相反,符号相反。 这种代码没法靠推理写对,只能靠对着文档和实测。
Windows/Linux(views):
native_window_views.cc:1797
gfx::Rect NativeWindowViews::ContentBoundsToWindowBounds(const gfx::Rect& bounds) const {
if (!has_frame() && !has_client_frame())
return bounds;
gfx::Rect window_bounds(bounds);
if (auto* ncv = widget()->non_client_view()) {
#if BUILDFLAG(IS_WIN)
HWND hwnd = GetAcceleratedWidget();
gfx::Rect dpi_bounds = DIPToScreenRect(hwnd, bounds);
window_bounds = ScreenToDIPRect(hwnd, ncv->GetWindowBoundsForClientBounds(dpi_bounds));
#else
// X11 / Wayland 分支
#endif
}
...
}
三个差异:
① 无框窗口直接返回,不做转换。macOS 上判的是 has_frame(),这里判的是 !has_frame() && !has_client_frame()——因为 Wayland 的"客户端边框"是有边框的,不能跳过。
② 经过 DIP ↔ 物理像素的往返(Windows)。DIPToScreenRect 把 DIP 换算成物理像素,交给 GetWindowBoundsForClientBounds(Win32 的 AdjustWindowRectEx),再 ScreenToDIPRect 换回来。为什么不能直接在 DIP 里算?因为边框宽度是物理像素的整数(Win32 的 SM_CXSIZEFRAME 是物理像素),在 DIP 里算会引入分数边框。
③ 依赖 non_client_view() 存在。它只在 views::Widget 初始化之后才有。所以这个转换在构造早期是无效的——InitFromOptions 里第 4 步 ClampSize 调它时,widget()->Init 已经跑过了(在 NativeWindowViews 构造函数里,早于 InitFromOptions)。
这就是为什么 NativeWindowViews 的构造函数里要 widget()->Init(...),而 InitFromOptions 在之后被调用:坐标转换需要 non_client_view,non_client_view 需要 Widget::Init。
9.3.7 39 个回调,33 个 Notify*:从平台到 JS 的唯一通道
native_window_observer.h:28-30 119 行,39 个虚回调(29 个 OnWindow* + 10 个其他)。全部是空实现 {},只有 NativeWindow 会调它们。
而 native_window.h 里的 NotifyWindow* 方法只有 33 个。两个数字不等,原因有三:
- 一个通知触发多个回调(
NotifyWindowCloseButtonClicked→WillCloseWindow+OnCloseButtonClicked); - 有些回调不在
NotifyWindow*命名下(UpdateWindowControlsOverlay、OnExecuteAppCommand、RequestPreferredWidth); - 有些
Notify*是纯虚或带副作用,不是简单转发(NotifyWindowEnterFullScreen还要清恢复标记)。
模式统一到可以用脚本生成:
native_window.cc:590
void NativeWindow::NotifyWindowBlur() {
observers_.Notify(&NativeWindowObserver::OnWindowBlur);
}
observers_ 的声明有一处细节:
native_window.h:590
base::ObserverList<NativeWindowObserver,
false,
base::ObserverListReentrancyPolicy::kAllowReentrancy>
observers_;
三个模板参数:不检查空(false)、允许重入(kAllowReentrancy)、元素类型。
允许重入是必须的。NotifyWindowCloseButtonClicked 会依次通知两个方法:
native_window.cc:550
void NativeWindow::NotifyWindowCloseButtonClicked() {
bool prevent_default = false;
observers_.Notify(&NativeWindowObserver::WillCloseWindow, &prevent_default);
if (prevent_default) {
WindowList::WindowCloseCancelled(this);
return;
}
observers_.Notify(&NativeWindowObserver::OnCloseButtonClicked, &prevent_default);
if (prevent_default) return;
CloseImmediately();
}
两轮询问。 第一轮问"要不要关"(WillCloseWindow),第二轮问"怎么关"(OnCloseButtonClicked)。
第一轮对应 JS 的 close 事件:
electron_api_base_window.cc:201
void BaseWindow::WillCloseWindow(bool* prevent_default) {
if (Emit("close")) {
*prevent_default = true;
}
}
用户的 win.on('close', e => e.preventDefault()) 在这里生效。如果阻止了,WindowList::WindowCloseCancelled(this) 通知观察者"这次关闭被取消了"——WindowListObserver::OnWindowCloseCancelled 是给"应用级关闭流程"用的(比如 macOS 的 Cmd+Q 中止)。
第二轮 OnCloseButtonClicked 是 BrowserWindow 特有的:
electron_api_browser_window.cc:159
void BrowserWindow::OnCloseButtonClicked(bool* prevent_default) {
*prevent_default = true;
if (!web_contents() || !api_web_contents_) return;
api_web_contents_->NotifyUserActivation();
if (web_contents()->NeedToFireBeforeUnloadOrUnloadEvents()) {
web_contents()->DispatchBeforeUnload(false /* auto_cancel */);
} else {
web_contents()->Close();
}
}
它无条件 *prevent_default = true,然后自己去走 beforeunload 流程。这是一处容易误读的代码:看上去"总是阻止关闭",实际是"把关闭的责任从 NativeWindow 转交给 webContents"。
为什么?因为点关闭按钮时,正确的顺序是:先问页面要不要走(beforeunload),页面同意后才关窗口。 如果让 NativeWindow 直接 CloseImmediately(),beforeunload 就被跳过了。
NotifyUserActivation() 那一行是为了满足浏览器的用户激活要求——beforeunload 对话框只在有用户激活时才会显示。点按钮本身就是一次激活,但 Chromium 的状态里不认这个点击(它没经过渲染进程),所以手工补一次。
9.3.8 NotifyWindowClosed 的幂等
native_window.cc:568
void NativeWindow::NotifyWindowClosed() {
if (is_closed_) return;
is_closed_ = true;
observers_.Notify(&NativeWindowObserver::OnWindowClosed);
WindowList::RemoveWindow(this);
}
is_closed_ 的检查不是防御性编程,是必需的。NotifyWindowClosed 有两条调用路径:
- 平台真的关了窗口(
views::WidgetObserver::OnWidgetDestroyed); NativeWindow的析构函数里:
native_window.cc:169
NativeWindow::~NativeWindow() {
// It's possible that the windows gets destroyed before it's closed, in that
// case we need to ensure the Widget delegate gets destroyed and
// OnWindowClosed message is still notified.
if (widget_->widget_delegate())
widget_->OnNativeWidgetDestroyed();
NotifyWindowClosed();
}
注释说得很清楚:"窗口可能在关闭之前就被销毁"(比如进程退出时直接 DestroyAllWindows)。此时第一条路径没走过,is_closed_ 还是 false,析构里的 NotifyWindowClosed() 补上一次。
如果两条路径都走了,is_closed_ 挡住第二次。没有这个 bool,WindowList::RemoveWindow 会被调两次——第二次时 windows_ 里已经没有这个指针,std::erase 是安全的(返回 0),但 if (windows.empty()) 那个判断会再次触发 OnWindowAllClosed,导致 window-all-closed 事件发两次,应用可能重复退出。
一个 bool 挡住了"事件发两次"这种最难查的 bug。 这类幂等标记在生命周期代码里到处都是,它们的价值与代码量成反比。
9.3.9 窗口状态持久化:一个跨会话的状态机
windowStatePersistence 是 Electron 40+ 的功能,在 NativeWindow 里有约 400 行实现。这是全类最复杂的部分,因为它要处理"保存的几何信息在下次启动时可能完全无效"。
保存侧的四个守卫:
native_window.cc:903
void NativeWindow::SaveWindowState() {
if (!window_state_persistence_enabled_ || is_being_restored_ ||
is_transitioning_fullscreen())
return;
gfx::Rect bounds = GetBounds();
if (bounds.width() == 0 || bounds.height() == 0) {
LOG(WARNING) << "Window state not saved - window bounds are invalid";
return;
}
...
四个 return:功能未启用、正在恢复中、正在全屏过渡、尺寸为零。
第三个 is_transitioning_fullscreen() 挡的是"全屏动画中途"的尺寸。全屏切换是一个多帧过程,中途的尺寸是无意义的中间值。
第四个挡的是最小化:最小化窗口的 GetBounds() 在很多平台上返回 (0,0,0,0) 或屏幕尺寸。如果不挡,最小化后关闭应用,下次启动窗口就是 0x0。
接着是"非正常状态时保存旧值":
native_window.cc:941-944
if (!IsNormal() && existing_prefs) {
std::optional<int> left = existing_prefs->FindInt(electron::kLeft);
...
if (left && top && right && bottom) {
bounds = gfx::Rect(*left, *top, *right - *left, *bottom - *top);
}
}
窗口全屏/最大化/最小化时,GetBounds() 返回的是"当前显示的尺寸",不是用户想要的"还原后尺寸"。所以读回上一次存的普通状态尺寸,覆盖当前值。
显示的匹配:
native_window.cc:920-921
const display::Display display = screen->GetDisplayMatching(bounds);
if (hasInvalidDisplay(display)) { ... return; }
GetDisplayMatching 找与 bounds 重叠最多的显示器。hasInvalidDisplay 挡两种情况:显示器 ID 是默认值(无物理显示器,比如 CI 环境),或者尺寸是 0。
native_window.cc:84
bool hasInvalidDisplay(const display::Display& display) {
return display.id() == display::kDefaultDisplayId ||
display.size().width() == 0 || display.size().height() == 0;
}
为什么要检查? 注释给了 Chromium 源码的链接:无物理显示器时 GetDisplayMatching 返回一个 1920x1080 的假显示器。如果拿它算工作区并保存,下次启动窗口就会被摆到一个不存在的位置。
恢复侧:按曼哈顿距离找目标显示器
native_window.cc:1037
int min_displacement = std::numeric_limits<int>::max();
for (const auto& candidate : screen->GetAllDisplays()) {
gfx::Rect test_bounds = saved_bounds;
test_bounds.AdjustToFit(candidate.work_area());
int displacement = std::abs(test_bounds.x() - saved_bounds.x()) +
std::abs(test_bounds.y() - saved_bounds.y());
if (displacement < min_displacement) {
min_displacement = displacement;
display = candidate;
}
}
对每个显示器:把保存的 bounds 夹进它的工作区,测量移动了多少(曼哈顿距离),选移动最少的那个。
这个算法的性质:如果保存的位置完全在某个显示器内,距离为 0,就选它;如果跨两个显示器,选重叠多的;如果一个都不沾,选"最近"的。
比"选重叠面积最大的"好在哪?重叠面积对"完全在屏幕外"的情况无解(全是 0)。曼哈顿距离在这种情况下仍然有序。
恢复的 clamp 数学:
native_window.cc:1156
const int min_y = work_area.y() + kMinVisibleHeight - saved_bounds.height();
const int min_x = work_area.x() + kMinVisibleWidth - saved_bounds.width();
const int max_y = work_area.bottom() - kMinVisibleHeight;
const int max_x = work_area.right() - kMinVisibleWidth;
if (min_x >= max_x || min_y >= max_y) {
saved_bounds.AdjustToFit(work_area);
} else {
saved_bounds.set_y(std::clamp(saved_bounds.y(), min_y, max_y));
saved_bounds.set_x(std::clamp(saved_bounds.x(), min_x, max_x));
}
目标:至少 100x100 的窗口可见。 kMinVisibleHeight = kMinVisibleWidth = 100(native_window.h:630)。
min_y = work_area.y() + 100 - height:如果 y 小于这个值,窗口顶部被切掉太多(可见高度不足 100)。
max_y = work_area.bottom() - 100:如果 y 大于这个值,窗口底部被切掉太多。
min_x >= max_x 的边界情况:当工作区比窗口还小(小屏 + 大窗口),两个约束矛盾,此时直接 AdjustToFit(缩放到工作区大小)。
macOS 上走另一个分支,更激进:
#if BUILDFLAG(IS_MAC)
// On mac, we want to be aggressive about repositioning windows that are
// partially offscreen.
saved_bounds.AdjustToFit(work_area);
#else
macOS 用户习惯"窗口可以部分在屏幕外"(尤其是外接显示器拔掉之后),所以直接整个拉回来。Linux/Windows 用户习惯"窗口可以拖到屏幕边缘外一点",所以只保证 100x100 可见。
这个差异不是技术限制,是平台用户习惯。 一段 #if 背后是一个 UX 决策。
9.3.10 is_being_restored_ 的三态
窗口状态恢复最容易出 bug 的地方是"恢复过程中触发的保存"。恢复 bounds 会触发 resize/move 事件,这些事件调用 DebouncedSaveWindowState,把中间态写回去,覆盖掉刚读出来的值。
is_being_restored_ 就是挡这个的。但它的生命周期比想象中长:
native_window.cc:1067
is_being_restored_ = true;
if (restore_bounds_) {
RestoreBounds(display, saved_work_area, saved_bounds);
}
if (restore_display_mode_) {
restore_display_mode_callback_ = base::BindOnce(...);
} else {
is_being_restored_ = false;
}
三个状态:
| 状态 | is_being_restored_ | awaiting_restore_display_mode_transition_ | 谁清除 |
|---|---|---|---|
| 正常 | false | false | — |
| 恢复 bounds 中 | true | false | 本函数末尾 |
| 恢复显示模式中 | true | true | NotifyWindowMaximize / NotifyWindowEnterFullScreen |
第三个状态是最麻烦的,因为显示模式的切换是异步的:
native_window.cc:1082
restore_display_mode_callback_ = base::BindOnce(
[](NativeWindow* window, base::DictValue prefs) {
bool transition_initiated = true;
if (auto kiosk = prefs.FindBool(electron::kKiosk); kiosk && *kiosk) {
window->awaiting_restore_display_mode_transition_ = true;
window->SetKiosk(true);
} else if (auto fs = prefs.FindBool(electron::kFullscreen); fs && *fs) {
window->awaiting_restore_display_mode_transition_ = true;
window->SetFullScreen(true);
} else if (auto max = prefs.FindBool(electron::kMaximized); max && *max) {
window->awaiting_restore_display_mode_transition_ = true;
window->Maximize();
} else {
transition_initiated = false;
}
if (!transition_initiated)
window->is_being_restored_ = false;
},
base::Unretained(this), window_preferences->Clone());
回调用 base::Unretained(this),而 NativeWindow 有 weak_factory_。这是一个有意的选择:回调的生命周期被严格限制在窗口存活期内(restore_display_mode_callback_ 是成员,析构时一起销毁),所以不需要弱指针。
回调不在 RestoreWindowState 里立刻执行,而是在 Show() 之后:
native_window.cc:1112
void NativeWindow::FlushPendingDisplayMode() {
if (restore_display_mode_callback_) {
std::move(restore_display_mode_callback_).Run();
}
}
谁调 FlushPendingDisplayMode?OnWindowShow。所以:
new BrowserWindow({ show: false, windowStatePersistence: { displayMode: true } })
// 窗口不显示,全屏状态也不恢复
win.show()
// 此时才恢复全屏
这解决了"隐藏窗口无法进入全屏"的问题。 一个 show: false 的窗口调用 SetFullScreen(true) 在很多平台上是无效的(没有原生窗口可全屏),所以必须推迟到显示之后。
macOS 的异步性还多一层:SetFullScreen 触发的是一个动画,动画结束才有 NotifyWindowEnterFullScreen。所以清除标记的位置在 Notify* 里:
native_window.cc:662
void NativeWindow::NotifyWindowEnterFullScreen() {
if (awaiting_restore_display_mode_transition_) {
awaiting_restore_display_mode_transition_ = false;
is_being_restored_ = false;
}
...
}
NotifyWindowMaximize 里也是同样的两行。两个不同的通知,同一段清除逻辑,因为"恢复成什么"不同,但"恢复完成"这个事实相同。
9.3.11 NonClientHitTest:三层判定
窗口的"非客户区"是标题栏、边框这些由系统绘制(或 Electron 绘制)的部分。鼠标在这些区域的行为(拖动、缩放)与客户区不同。
native_window.cc:749
int NativeWindow::NonClientHitTest(const gfx::Point& point) {
#if !BUILDFLAG(IS_MAC)
if ((!has_frame() || has_client_frame()) && IsResizable()) {
...
auto* frame_view = widget()->non_client_view()->frame_view();
if (auto* frame = views::AsViewClass<ResizableFrameView>(frame_view)) {
int border_hit = frame->ResizingBorderHitTest(point);
if (border_hit != HTNOWHERE) return border_hit;
}
}
#endif
if (widget()->IsFullscreen()) return HTNOWHERE;
for (DraggableRegionProvider* provider : draggable_region_providers_) {
int hit = provider->NonClientHitTest(point);
if (hit != HTNOWHERE) return hit;
}
return HTNOWHERE;
}
第一层:缩放边框。 只在"无框或有客户端边框"且"可缩放"时检查。ResizableFrameView 在 Windows 上是 FramelessView,Linux 上是 ElectronFrameViewLinux:
native_window.cc:757-758
#if BUILDFLAG(IS_WIN)
using ResizableFrameView = FramelessView;
#else
using ResizableFrameView = ElectronFrameViewLinux;
#endif
TODO(mitchchn) 的注释说"以前两个平台都继承 FramelessView,想恢复一个跨平台接口"。这是平台实现分叉后的技术债。
第二层:全屏时全部穿透。 if (widget()->IsFullscreen()) return HTNOWHERE; 注释给了 issue:
// This is to disable dragging in HTML5 full screen mode.
// Details: https://github.com/electron/electron/issues/41002
HTML5 全屏时,页面里的 -webkit-app-region: drag 区域不该还能拖窗口(全屏窗口没有"拖动"的概念)。直接返回 HTNOWHERE 让所有点击落到页面。
第三层:可拖拽区域。 draggable_region_providers_ 是一个 std::list<raw_ptr<DraggableRegionProvider>>,里面装着 WebContentsView(9.4 会讲它怎么注册)。
BrowserWindow 的构造里有这一行:
electron_api_browser_window.cc:73
window()->AddDraggableRegionProvider(web_contents_view.get());
所以主 webContents 的 -webkit-app-region 是窗口拖拽区域的来源。每个 WebContentsView 都可以注册自己,NonClientHitTest 按注册顺序问过去。
顺序有意义:先问边框,再问全屏,最后问区域。如果先问区域,全屏时页面里的拖拽区会先生效,第二层的保护就失效了。
9.3.12 背景节流:一个集合而不是一个 bool
native_window.h:434
void AddBackgroundThrottlingSource(BackgroundThrottlingSource* source);
void RemoveBackgroundThrottlingSource(BackgroundThrottlingSource* source);
void UpdateBackgroundThrottlingState();
内部是一个 absl::flat_hash_set<BackgroundThrottlingSource*>:
native_window.cc:811
void NativeWindow::UpdateBackgroundThrottlingState() {
if (!widget() || !widget()->GetCompositor()) return;
bool enable_background_throttling = true;
for (const auto* source : background_throttling_sources_) {
if (!source->GetBackgroundThrottling()) {
enable_background_throttling = false;
break;
}
}
widget()->GetCompositor()->SetBackgroundThrottling(enable_background_throttling);
}
"任一来源要求不节流,就不节流"——逻辑 AND。
为什么是集合?因为同一个窗口上可能有多方都想控制:
webContents.setBackgroundThrottling(false)(用户 API);webContents.setBackgroundThrottling(true)恢复;WebContentsView自己的设置;- DevTools 打开时。
如果用一个 bool,最后调用的那个赢,前面的设置被静默覆盖。用集合,每一方在"进入"时插一个 source,"离开"时移除,最后的状态由全体投票决定。
Add 里的 DCHECK(result.second) 与 Remove 里的 DCHECK(result == 1) 是配套的断言:同一个 source 不能加两次,也不能移除不存在的。这两个 DCHECK 在 release 构建里被编译掉,所以运行期的错误不会有提示——这是"只在开发期抓 bug"的典型取舍。
UpdateBackgroundThrottlingState 的第一个 if 也值得注意:widget()->GetCompositor() 可能为空。这个函数在 AddBackgroundThrottlingSource 里被调用,可能在窗口还没初始化合成器时发生。空检查避免了早期崩溃,代价是"早期的设置不会立即生效"——但下一次 Add/Remove 会重算,所以最终一致。
9.3.13 NativeWindowRelay:从 WebContents 反查窗口
native_window.h:640
class NativeWindowRelay : public content::WebContentsUserData<NativeWindowRelay> {
public:
static void CreateForWebContents(content::WebContents*, base::WeakPtr<NativeWindow>);
NativeWindow* GetNativeWindow() const { return native_window_.get(); }
WEB_CONTENTS_USER_DATA_KEY_DECL();
private:
base::WeakPtr<NativeWindow> native_window_;
};
content::WebContentsUserData 是 Chromium 的机制:给一个 WebContents 挂一块任意数据,通过 UserDataKey() 找回。
NativeWindowRelay 挂的是一个 WeakPtr<NativeWindow>。所以"给定一个 WebContents,找到它的窗口"这条路径是:
electron_platform_passkeys_authenticator_mac.mm:142-143
auto* relay = NativeWindowRelay::FromWebContents(web_contents);
NativeWindow* window = relay ? relay->GetNativeWindow() : nullptr;
为什么用 UserData 而不是在 WebContents 里加字段? 因为 content::WebContents 是 Chromium 的类,Electron 不能改它(虽然打了 58 个 node 补丁和 241 个 chromium 补丁,但改 WebContents 的成员是最后手段)。UserData 是 Chromium 专门为 embedder 留的扩展点。
为什么存 WeakPtr 而不是裸指针? 因为 NativeWindow 可能在 WebContents 之后销毁。WebContentsView 可以脱离窗口存在(从窗口移除之后仍然持有 webContents),此时 relay->GetNativeWindow() 返回 nullptr,调用方必须处理。
这个 nullptr 是一个真实存在的状态,不是理论上的:
base-window.md:81-84
const view = new WebContentsView()
win.contentView.addChildView(view)
win.contentView.removeChildView(view)
// 此时 view 还在,但它没有窗口
view.webContents.loadURL('https://example.com') // 能跑,但没有可见的窗口
9.4 第四身体:views::Widget 与平台窗口
9.4.1 NativeWindowViews 的三个父类
native_window_views.h:52
class NativeWindowViews : public NativeWindow,
private views::WidgetObserver,
private ui::EventHandler {
一个 public 继承(实现抽象接口),两个 private 继承(接收回调)。
views::WidgetObserver:窗口的创建、销毁、bounds 变化、可见性变化。OnWidgetDestroyed是NotifyWindowClosed的来源之一。ui::EventHandler:键盘事件。窗口级快捷键(Cmd+W之类)在这里拦。
private 继承是 C++ 里"实现继承"的写法:不暴露基类的接口,只借用它的虚函数回调。用 private 而不是 public 是一个明确的表态——NativeWindowViews 不是一个 WidgetObserver,它只是需要收到通知。
9.4.2 InitParams 的九个字段
native_window_views.cc:291
using InitParams = views::Widget::InitParams;
auto params = InitParams{InitParams::WIDGET_OWNS_NATIVE_WIDGET,
InitParams::TYPE_WINDOW};
params.bounds = bounds;
params.delegate = this;
params.remove_standard_frame = !has_frame() || has_client_frame();
if (transparent() || has_client_frame())
params.opacity = InitParams::WindowOpacity::kTranslucent;
#if BUILDFLAG(IS_LINUX)
if (!has_frame())
params.opacity = InitParams::WindowOpacity::kTranslucent;
#endif
if (IsTranslucent() && !has_frame())
params.shadow_type = InitParams::ShadowType::kNone;
if (bool val; options.Get(options::kFocusable, &val) && !val)
params.activatable = InitParams::Activatable::kNo;
#if BUILDFLAG(IS_WIN)
if (parent)
params.parent = parent->GetNativeWindow();
params.native_widget = new ElectronDesktopNativeWidgetAura{this, widget()};
#elif BUILDFLAG(IS_LINUX)
params.wm_role_name = "browser-window";
params.wm_class_name = base::ToLowerASCII(name);
params.wm_class_class = name;
if (app_id) params.wayland_app_id = *app_id;
auto* native_widget = new views::DesktopNativeWidgetAura(widget());
params.native_widget = native_widget;
params.desktop_window_tree_host = new ElectronDesktopWindowTreeHostLinux{this, widget(), native_widget};
#endif
widget()->Init(std::move(params));
widget()->SetNativeWindowProperty(kNativeWindowKey.c_str(), this);
widget()->OnSizeConstraintsChanged();
逐字段:
WIDGET_OWNS_NATIVE_WIDGET 是第一个模板参数,也是 InitParams 的构造函数第一参数。它表达的所有权关系是:views::Widget 拥有 NativeWidget,不拥有自己。
这句话需要拆开。views::Widget 是跨平台抽象,NativeWidget 是平台实现(Windows 的 DesktopNativeWidgetAura,macOS 的 NativeWidgetMac)。所有权有三种组合:
| 选项 | 谁拥有 NativeWidget | 谁拥有 Widget |
|---|---|---|
WIDGET_OWNS_NATIVE_WIDGET | Widget | 调用方 |
NATIVE_WIDGET_OWNS_WIDGET | 调用方 | NativeWidget |
CLIENT_OWNS_WIDGET | 都不拥有 | 调用方 |
Electron 选第一种,因为 widget_ 在 NativeWindow 里是 std::unique_ptr<views::Widget>。所以链条是:NativeWindow 拥有 Widget,Widget 拥有 NativeWidget,NativeWidget 拥有平台窗口(HWND / GtkWindow)。
这解释了 9.2.5 的 DeleteSoon(window_) 为什么是"从外向内"的销毁。 最外层死了,里面三层依次析构。反过来不行——如果 NativeWidget 先死而 Widget 还在,Widget 会持有一个悬垂的 native_widget_。
TYPE_WINDOW 是窗口类型。views 里有 TYPE_WINDOW(普通窗口)、TYPE_POPUP(无边框弹出)、TYPE_MENU、TYPE_BUBBLE、TYPE_DRAG 等。TYPE_WINDOW 意味着有标题栏、可缩放、出现在任务栏——具体行为由平台实现。
有意思的是无框窗口仍然用 TYPE_WINDOW。TYPE_POPUP 才是"无边框无标题栏"的类型,但它同时也没有任务栏图标、没有窗口菜单、不能 Alt+Tab 切换。Electron 的无框窗口要保留这些,所以选 TYPE_WINDOW + remove_standard_frame。
remove_standard_frame = !has_frame() || has_client_frame():无框或有客户端边框,都要求 views 不要画标准边框。区别在于:前者完全由 Electron 画(或者什么都不画),后者由 Electron 画一个"看起来像系统边框"的边框。
opacity 三处设置:
transparent() || has_client_frame()→kTranslucent。透明窗口必须半透明合成;客户端边框需要抗锯齿边缘,也要半透明。- Linux 上
!has_frame()也设kTranslucent。注释:
// Resize handles and shadows on frameless windows need translucent insets.
无框窗口的缩放热区在窗口边缘外几个像素,那些像素必须能透出下面的内容,否则用户会看到一个不透明的边框条。
IsTranslucent() && !has_frame()→shadow_type = kNone。注释:
// The given window is most likely not rectangular since it is translucent and
// has no standard frame, don't show a shadow for it.
阴影是矩形窗口的产物。 一个不规则形状的透明窗口如果画系统阴影,会出现"方形阴影围着一个圆形窗口"的荒谬效果。
activatable 对应 focusable: false。这个字段在 Windows 上对应 WS_EX_NOACTIVATE,在 Linux 上对应 _NET_WM_STATE 里不给焦点,在 macOS 上对应 NSWindow 的 canBecomeKeyWindow 返回 NO。
params.parent 只在 Windows 上设。Linux 的父子关系通过 X11 的 _NET_WM_STATE_MODAL 与窗口类型表达(下面会看到),macOS 通过 addChildWindow:ordered: 表达。
native_widget 与 desktop_window_tree_host 是最深的一层。两个平台各自 new 一个派生类:
- Windows:
ElectronDesktopNativeWidgetAura{this, widget()},持有NativeWindowViews*。 - Linux:
views::DesktopNativeWidgetAura(widget())加ElectronDesktopWindowTreeHostLinux{this, widget(), native_widget}。
为什么 Linux 要两个对象而 Windows 只要一个?
因为 Linux 的 DesktopNativeWidgetAura 是通用的(Aura 的桌面窗口),而"窗口树宿主"(DesktopWindowTreeHost)才是与 X11/Wayland 打交道的部分。Electron 需要定制后者(UpdateFrameHints、AddAdditionalInitProperties、SetWindowIcons),所以派生它。Windows 上 DesktopNativeWidgetAura 本身就承担了两者,所以只需派生它。
这个差异直接导致两个平台的代码路径不同:Linux 的很多逻辑在 ElectronDesktopWindowTreeHostLinux 里,Windows 的在 ElectronDesktopNativeWidgetAura 里。读代码时找"某个行为在哪实现",必须先知道平台。
widget()->SetNativeWindowProperty(kNativeWindowKey.c_str(), this) 是反查表:
native_window.h:506
static inline constexpr base::cstring_view kNativeWindowKey = "__ELECTRON_NATIVE_WINDOW__";
// native_window.cc:310
NativeWindow* NativeWindow::FromWidget(const views::Widget* widget) {
DCHECK(widget);
return static_cast<NativeWindow*>(widget->GetNativeWindowProperty(kNativeWindowKey.c_str()));
}
views::Widget 有一个"任意属性"表(SetNativeWindowProperty / GetNativeWindowProperty),Electron 把 this 存进去。所以任何拿到 Widget* 的地方(比如 WebContentsView 的 view()->GetWidget())都能反查回 NativeWindow。
这解决了一个跨模块的定位问题:WebContentsView 只知道自己挂在一个 views::Widget 上,不知道自己属于哪个 NativeWindow。FromWidget 是唯一的桥。
SetNativeWindowProperty 的 key 用 __ELECTRON_NATIVE_WINDOW__ 这种全大写下划线包裹的形式,是为了避免与 Chromium 自己的属性 key 冲突。这是一个约定而非机制——Chromium 没有命名空间隔离,只能靠命名习惯。
9.4.3 三层视图:RootView / main_view / content_view
Electron 的窗口内部有三个 view 层次,名字很容易混:
views::Widget
└─ NativeWindowClientView(CreateClientView 返回)
└─ RootView(BoxLayout vertical)
├─ MenuBar(可选,菜单栏)
└─ main_view_(一个普通 views::View,BoxLayout 的 flex=1)
└─ content_view_(NativeWindow::content_view_,指向用户设的内容视图)
└─ WebContentsView 的 InspectableWebContentsView
RootView 的构造函数把布局定死:
root_view.cc:29
RootView::RootView(NativeWindow* window)
: window_{raw_ref<NativeWindow>::from_ptr(window)},
main_view_{raw_ref<views::View>::from_ptr(
AddChildView(std::make_unique<views::View>()))} {
set_owned_by_client(OwnedByClientPassKey{});
views::BoxLayout* layout =
SetLayoutManager(std::make_unique<views::BoxLayout>(
views::BoxLayout::Orientation::kVertical));
main_view_->SetUseDefaultFillLayout(true);
layout->SetFlexForView(&main_view_.get(), 1);
}
垂直 BoxLayout,main_view_ 的 flex 是 1。所以菜单栏占它需要的高度,剩下的全给 main_view_。
set_owned_by_client(OwnedByClientPassKey{}) 是一个有趣的细节:views::View 默认由父视图拥有(AddChildView 时转移所有权)。set_owned_by_client 声明"这个视图的生命周期由外部管理"。OwnedByClientPassKey 是一个只能由 views 内部构造的令牌,防止误用。
RootView 的生命周期由 NativeWindowViews 的成员 root_view_ 管理(它是一个值成员,不是指针)。所以这行是必须的——否则 AddChildView(std::make_unique<views::View>()) 让 RootView 自己成为 Widget 的子视图的同时,又有一个成员变量持有它,双重所有权。
这是一个 C++ 里很典型的"两层所有权"问题:视图树需要一个指针才能挂上去,但对象的生命周期由另一个对象管。owned_by_client 就是在说"视图树只借指针,不管生死"。
NativeWindow::SetContentView 的实现(虚函数,views 版):
native_window_views.cc:567
void NativeWindowViews::SetContentView(views::View* view) {
if (views::View* old_view = content_view()) {
set_content_view(nullptr);
focused_view_ = nullptr;
if (old_view->owned_by_client())
root_view_.GetMainView()->RemoveChildView(old_view);
else
root_view_.GetMainView()->RemoveChildViewT(old_view);
}
set_content_view(view);
focused_view_ = view;
root_view_.GetMainView()->AddChildViewRaw(content_view());
FlushPendingRootLayout(root_view_.GetMainView());
}
三个 API 名字对应三种所有权:RemoveChildView(不删,返回指针)、RemoveChildViewT(删,返回 unique_ptr)、AddChildViewRaw(不转移所有权)。
AddChildViewRaw 是必须的:content_view_ 是 raw_ptr<views::View>,所有权在别处(BrowserWindow 的 api::View 或 WebContentsView)。如果这里用 AddChildView,视图树会以为它拥有这个视图,销毁时 double free。
focused_view_ 的记录是为了窗口重新获得焦点时恢复焦点:
native_window_views.cc:577
// native_window_views.cc:567 的 SetContentView 内
focused_view_ = view;
一个窗口失去焦点再获得焦点,焦点应该回到之前聚焦的那个子视图。focused_view_ 就是这个记忆。
FlushPendingRootLayout 强制立即布局:
native_window.cc:320
void NativeWindow::FlushPendingRootLayout(views::View* view) {
view->InvalidateLayout();
if (views::Widget* widget = view->GetWidget())
widget->LayoutRootViewIfNecessary();
}
InvalidateLayout 只是标记"需要重新布局",真正布局发生在下一个帧。LayoutRootViewIfNecessary 立即执行。为什么需要立即?
因为 SetContentView 之后紧接着可能有代码要读新视图的 bounds(比如 WebContents 的尺寸、capturePage 的区域)。如果还是旧布局,读到的尺寸是错的。这一行把"下一帧才正确"变成"现在就对"。
9.4.4 GetContentsView 的命名陷阱
NativeWindow 有两个名字很像的方法:
native_window.h:385-387
views::Widget* widget() const { return widget_.get(); }
views::View* content_view() const { return content_view_; } // 用户设的内容视图
// 平台实现提供
virtual views::View* GetContentsView(); // NativeWindowViews 返回 root_view_.GetMainView()
GetContentsView() 不是 content_view() 的 getter。它返回的是 main_view_——装 content_view_ 的那个容器。
BrowserWindow 的构造里有一段注释专门解释这个混乱:
electron_api_browser_window.cc:90
// Install the content view after BaseWindow's JS code is initialized.
// The WebContentsView is added a sibling of BaseWindow's contentView (before
// it in the paint order) so that any views added to BrowserWindow's
// contentView will be painted on top of the BrowserWindow's WebContentsView.
// See https://github.com/electron/electron/pull/41256.
// Note that |GetContentsView|, confusingly, does not refer to the same thing
// as |BaseWindow::GetContentView|.
window()->GetContentsView()->AddChildViewAt(web_contents_view->view(), 0);
AddChildViewAt(..., 0) 插到索引 0,也就是最底层。 所以绘制顺序是:
main_view_ 的子树(自底向上):
[0] WebContentsView 的 InspectableWebContentsView ← 底层
[1] content_view_(BaseWindow 的 contentView) ← 上层
用户往 win.contentView 里加的视图,会画在 WebContents 上面。这就是 <webview> 标签、BrowserView 叠加层的实现基础——它们是 contentView 的子视图,盖在主页面之上。
PR #41256 之前,WebContentsView 是 contentView 的子视图,用户加的任何东西都会跟 WebContents 混在一起排队列。改成兄弟关系之后,图层顺序由索引决定,可预测。
注意 AddChildViewAt(..., 0) 是在 content_view_ 已经加进去之后。 顺序是:
BaseWindow构造(第一步):SetContentView(View::Create(isolate))→main_view_里有[0] content_view_;BrowserWindow构造(第二步):AddChildViewAt(web_contents_view->view(), 0)→ 插入后变成[0] web_contents, [1] content_view_。
如果顺序反过来(先插 WebContents,再 SetContentView),SetContentView 会 RemoveChildView(old_view) 再 AddChildViewRaw,结果 content_view_ 变成 [1]——恰好也是对的。但这是巧合,不是设计。 两个构造函数的执行顺序(BaseWindow 先,BrowserWindow 后)才是真正的保证。
9.4.5 Windows 的样式位:一段手工的位运算
无框窗口在 Windows 上不能真的"没有样式"——那样会失去最小化动画、任务栏行为、Aero Snap。所以 Electron 手工拼 GWL_STYLE:
native_window_views.cc:395
if (!has_frame()) {
DWORD frame_style = WS_CAPTION | WS_OVERLAPPED;
if (CanResize()) frame_style |= WS_THICKFRAME;
if (minimizable_) frame_style |= WS_MINIMIZEBOX;
if (maximizable_ && CanResize()) frame_style |= WS_MAXIMIZEBOX;
if (!thick_frame_) {
frame_style &= ~(WS_THICKFRAME | WS_CAPTION);
rounded_corner_ = false;
} else {
options.Get(options::kRoundedCorners, &rounded_corner_);
}
::SetWindowLong(GetAcceleratedWidget(), GWL_STYLE, frame_style);
SetRoundedCorners(rounded_corner_);
}
四个位:
WS_CAPTION:有标题栏。即使无框也要设,因为它同时控制"窗口可以被拖动"与"有最小化/最大化动画"。真正的边框由remove_standard_frame让 views 不画。WS_OVERLAPPED:顶层窗口。WS_THICKFRAME:可缩放(鼠标能拖边缘)。WS_MINIMIZEBOX/WS_MAXIMIZEBOX:任务栏右键菜单里的项,以及点击标题栏按钮。
maximizable_ && CanResize() 的联合条件:一个不可缩放的窗口不能最大化(最大化本质是"缩放到屏幕")。
thick_frame_ 为 false 时,把 WS_THICKFRAME | WS_CAPTION 都清掉,同时 rounded_corner_ = false——没有厚边框就不可能有圆角,因为圆角是 DWM 对厚边框的装饰。透明窗口强制 thick_frame_ = false(构造函数里),这就是"透明窗口不能有圆角"的原因。
SetRoundedCorners 在 Windows 11 上通过 DwmSetWindowAttribute(DWMWA_WINDOW_CORNER_PREFERENCE) 实现,Windows 10 上是空操作。这一行代码在 10 和 11 上的行为不同,但调用方不需要知道。
9.4.6 Linux 的 _NET_WM_STATE:在窗口映射之前
native_window_views.cc:355
if (x11_util::IsX11()) {
// Before the window is mapped the SetWMSpecState can not work, so we have
// to manually set the _NET_WM_STATE.
std::vector<x11::Atom> state_atom_list;
if (fullscreen) {
state_atom_list.push_back(x11::GetAtom("_NET_WM_STATE_FULLSCREEN"));
}
if (parent) {
window_type = "dialog";
if (is_modal())
state_atom_list.push_back(x11::GetAtom("_NET_WM_STATE_MODAL"));
}
if (!state_atom_list.empty()) {
auto* connection = x11::Connection::Get();
connection->SetArrayProperty(
static_cast<x11::Window>(GetAcceleratedWidget()),
x11::GetAtom("_NET_WM_STATE"), x11::Atom::ATOM, state_atom_list);
}
if (!window_type.empty())
SetWindowType(static_cast<x11::Window>(GetAcceleratedWidget()), window_type);
}
注释是整段的关键:"窗口映射(mapped)之前无法用 SetWMSpecState,所以手工设 _NET_WM_STATE"。
X11 的窗口状态有两种设法的:发送 _NET_WM_STATE 客户端消息(要求窗口已经映射),或者直接设属性(任何时候都行)。SetWMSpecState 走前者,所以在 widget()->Init 之后、窗口显示之前调它是无效的。
Electron 直接 SetArrayProperty——绕过窗口管理器,把属性写进去。窗口管理器在映射时会读这个属性,于是从一开始就是全屏。
_NET_WM_STATE_MODAL 这一条只在 parent && is_modal() 时加。模态在 X11 上是提示而非强制:窗口管理器可以不理会。这与 Windows 的 EnableWindow(parent, FALSE) 有本质区别。
window_type = "dialog":有父窗口的一律是 dialog 类型。这是一个经验规则——大部分窗口管理器对 dialog 的装饰更少(没有最大化按钮)、层级更高(总是浮在父窗口上)。
9.4.7 ElectronDesktopWindowTreeHostLinux:平台桥的四个钩子
electron_desktop_window_tree_host_linux.h:36
class ElectronDesktopWindowTreeHostLinux
: public views::DesktopWindowTreeHostLinux,
private ui::DeviceScaleFactorObserver {
它覆盖的方法按继承来源分三组:
来自 DesktopWindowTreeHostLinux:
UpdateFrameHints():更新窗口装饰的提示(哪个角是圆的、阴影多大)OnWidgetInitDone():Widget 初始化完成SetWindowIcons(window_icon, app_icon):两个图标分开设Show(show_state, restore_bounds):显示DispatchEvent(event):事件分发
来自 ui::PlatformWindowDelegate:
CalculateInsetsInDIP(window_state):边框 insetGetMinimumSizeForWindow()/GetMaximumSizeForWindow():返回std::optional<gfx::Size>OnBoundsChanged(BoundsChange):bounds 变化,带原因OnWindowStateChanged(old, new):状态变化OnWindowTiledStateChanged(tiled_edges):平铺状态(新的 Wayland 特性)
来自 ui::NativeThemeObserver / OnDeviceScaleFactorChanged:
- 主题变化、DPI 变化
CalculateInsetsInDIP 是最能说明问题的一个。它返回 gfx::Insets——窗口边框占多少像素。在 Wayland 上,客户端边框的 inset 由 Electron 自己算(因为边框是它画的);在 X11 上,由窗口管理器决定,这个函数返回 0(服务端装饰不计入客户区)。
同一个方法,在两个 X11 会话里的行为可能不同,取决于窗口管理器是否支持服务端装饰。 这就是为什么 has_client_frame_ 要在构造时查一次 supports_server_side_window_decorations。
OnDeviceScaleFactorChanged 有一个具体的后果:窗口从一个 100% DPI 的显示器拖到 200% 的显示器,尺寸约束要重算(内容尺寸不变,窗口尺寸变),图标要重选(hi-res 版本)。这个回调是所有"跨显示器"bug 的源头,因为它触发的重算路径极多。
GetMinimumSizeForWindow 返回 std::optional 而不是 gfx::Size,语义是"我可能没有约束"。返回 std::nullopt 表示"不限制",与返回 gfx::Size(0, 0) 不同——后者在 views 里会被当成"最小尺寸是 0"。
9.4.8 ElectronDesktopNativeWidgetAura:Windows 侧的对应物
Windows 上没有 DesktopWindowTreeHost 这一层(DesktopNativeWidgetAura 自己就是宿主),所以定制的部分都压在 ElectronDesktopNativeWidgetAura 里。它构造时接收两个参数:
native_window_views.cc:319
params.native_widget = new ElectronDesktopNativeWidgetAura{this, widget()};
NativeWindowViews* 与 views::Widget*。前者用来查 Electron 的窗口状态,后者是 views 的窗口。
两个指针指向协作关系的两端。 Widget 不知道 NativeWindowViews 的存在,NativeWindowViews 需要 Widget 做一切事情。所以派生类同时持有两者,充当胶水。
这个模式在 Linux 上是三分:NativeWindowViews + DesktopNativeWidgetAura + ElectronDesktopWindowTreeHostLinux,后两个互相引用,第一个引用第二个。平台架构的复杂度直接决定了 Electron 要写几个派生类。
9.5 平台分叉:macOS 为什么不走 views
9.5.1 三个实现,一个工厂
native_window_views.cc:2133-2137
// native_window_views.cc:2133(Windows / Linux)
std::unique_ptr<NativeWindow> NativeWindow::Create(
const int32_t base_window_id,
const gin_helper::Dictionary& options,
NativeWindow* parent) {
return std::make_unique<NativeWindowViews>(base_window_id, options, parent);
}
native_window_mac.mm:1888-1895
// native_window_mac.mm:1888(macOS)
std::unique_ptr<NativeWindow> NativeWindow::Create(
const int32_t base_window_id,
const gin_helper::Dictionary& options,
NativeWindow* parent) {
if (remote_cocoa::ApplicationHost* application_host =
NativeWindowMacRemote::ApplicationHostFromOptions(options)) {
return std::make_unique<NativeWindowMacRemote>(base_window_id, options, parent, application_host);
}
return std::make_unique<NativeWindowMac>(base_window_id, options, parent);
}
两个 .cc 文件里各有一个 NativeWindow::Create,链接期只有一个生效(GN 按平台选源文件)。这是 Electron 里最常见的平台分派方式:不用 #if 写在同一个函数里,而是整文件替换。
macOS 比另外两个平台多一层:NativeWindowMacRemote。所以严格说不是"两个实现",是三个。
9.5.2 NativeWindowMac:直接握 NSWindow
native_window_mac.h:32
class NativeWindowMac : public NativeWindow,
public ui::NativeThemeObserver,
public display::DisplayObserver {
两个额外的 public 继承,都是 Chromium 的通知接口:主题变化、显示器配置变化。这两个在 views 版里由 NativeWindowViews 的两个 private 父类覆盖了(WidgetObserver + EventHandler,以及 ElectronDesktopWindowTreeHostLinux 的 NativeThemeObserver)。
所以 mac 版的类自己承担了"接收平台通知"的职责,因为它没有 views 那一层帮忙转发。
Close() 的差异最能说明问题:
native_window_mac.mm:349
void NativeWindowMac::Close() {
if (!IsClosable()) { WindowList::WindowCloseCancelled(this); return; }
if (is_transitioning_fullscreen()) {
SetHasDeferredWindowClose(true);
return;
}
RemoveChildFromParentWindow();
while (!child_windows_.empty()) {
NativeWindow* child = child_windows_.back();
child->RemoveChildFromParentWindow();
}
while (NSWindow* sheet = [window_ attachedSheet]) {
[window_ endSheet:sheet];
}
DCHECK_EQ([[window_ sheets] count, 0UL);
bool should_notify = is_modal() && parent() && IsVisible();
[window_ performClose:nil];
if (should_notify) {
NotifyWindowCloseButtonClicked();
}
}
对比 views 版:
native_window_views.cc:582
void NativeWindowViews::Close() {
if (!IsClosable()) { WindowList::WindowCloseCancelled(this); return; }
widget()->Close();
}
views 版只有三行,mac 版有三十行。 因为 widget()->Close() 会走 views 的关闭流程(其中包含 WidgetDelegate::CanClose → 最终调到 NativeWindow::NotifyWindowCloseButtonClicked),而 NSWindow 没有这套东西。
mac 版要手工处理的四件事:
① 全屏过渡中途不能关。 SetHasDeferredWindowClose(true) 记录一个待办,等过渡结束再关。这是 macOS 特有的:全屏是一个动画,动画中途 performClose 会导致窗口卡在一个半死不活的状态。
② 先解除父子关系。 一个子窗口如果还挂在父窗口上,父窗口关闭时子窗口的 NSWindow 可能已经被释放。所以先把所有 child 解绑。
③ 关掉所有 sheet。 注释:
// If a sheet is attached to the window when we call
// [window_ performClose:nil], the window won't close properly
// even after the user has ended the sheet.
sheet 是 macOS 的"附着在窗口上的模态面板"(比如保存对话框)。它存在时 performClose 会失败,而且没有任何错误——窗口就是不动。
④ 手工补 NotifyWindowCloseButtonClicked。 注释:
// Closing a sheet doesn't trigger windowShouldClose,
// so we need to manually call it ourselves here.
[window_ performClose:nil] 对一个 sheet 不会触发 windowShouldClose: 委托方法,所以 views/Electron 那条"先问再关"的链路没走。手工补一次。
should_notify 的条件 is_modal() && parent() && IsVisible() 精确到令人不安:只有"可见的、有父窗口的模态窗口"才需要补。因为 sheet 只在这种情况下存在。
这三十行是"平台语义与框架抽象对不上"的代价。 views 提供了统一的 Widget::Close(),但它在 macOS 上不够用,因为 Cocoa 的关闭流程有一堆 views 不管的边界情况。
9.5.3 NativeWindowMacRemote:窗口在另一个进程里
native_window_mac_remote.h:36
// A window whose NSWindow lives in an app shim process (see
// api::AppShimHost), so the Dock, Mission Control and the window server
// attribute it to the shim instead of this app. There is no NSWindow of it in
// this process to message, so everything goes through views::Widget, which
// forwards to the shim over remote_cocoa's Mojo interfaces. What those
// interfaces have no call for is not supported and is a no-op here; see
// docs/api/app-shim-host.md for the list.
class NativeWindowMacRemote : public NativeWindow,
private views::WidgetObserver {
这段注释是全书里信息密度最高的几段之一,逐句拆:
"NSWindow 活在 app shim 进程里"——所以 NativeWindowMacRemote 没有 NSWindow* 成员。所有需要 [window_ xxx] 的操作都做不了。
"Dock、Mission Control、窗口服务器把它归属到 shim,而不是这个应用"——这是这个功能存在的理由。macOS 上"一个 .app 在 Dock 里只有一个图标",如果一个应用要开多个"独立窗口"(像 Chrome 的 PWA 窗口),系统会把它们都归到主应用。app shim 是 Chrome 发明的解法:为每个 PWA 生成一个小的 .app(shim),它有自己的 bundle id 和 Dock 图标,真正的渲染进程还是主应用。
"所以一切走 views::Widget,它通过 remote_cocoa 的 Mojo 接口转发给 shim"——views::Widget 在 macOS 上的实现是 NativeWidgetMac,它有一个"远程"模式:通过 Mojo 把窗口操作发给另一个进程的 NativeWidgetNSWindow。
"那些接口没有对应调用的东西就是不支持,在这里是空操作"——所以 NativeWindowMacRemote 里大量的方法是 NOTIMPLEMENTED() 或空实现。
这个文件的版权头值得单独看一眼:
// Copyright (c) 2026 Anthropic, PBC.
不是 GitHub Inc.,不是 Electron 的常规版权头。这是 2026 年由 Anthropic 贡献的新文件,实现 app shim 支持。这个细节说明一件事:Electron 的平台层仍在演进,而且演进的方向是"把窗口从进程里搬出去"。
NativeWindow::IsInAppShim() 这个虚函数就是为了它:
native_window.h:88
// macOS: whether the window's NSWindow is in an app shim's process. What
// GetNativeWindow() names is then a stand-in that is never on screen, and
// nothing may be attached to it.
virtual bool IsInAppShim() const;
默认返回 false(native_window.cc:331),NativeWindowMacRemote 覆盖成 true。
用到它的地方有一个典型的例子:
native_window_mac.mm:1580
bool NativeWindowMac::AddTabbedWindow(NativeWindow* window) {
// A window in an app shim is another process's: only a stand-in for it is
// here.
if (window->IsInAppShim())
return false;
...
}
"标签页合并"要求两个窗口在同一个进程里(addTabbedWindow: 传的是 NSWindow*)。app shim 的窗口在另一个进程,这里只有一个占位对象,传过去就是错的。所以直接返回 false。
这个 if 的存在说明:跨进程窗口不是一个透明的抽象,它会在很多地方漏出来。 每漏一处,就要加一个判断。
ApplicationHostFromOptions 是入口:
static remote_cocoa::ApplicationHost* ApplicationHostFromOptions(const gin_helper::Dictionary& options);
从 options.appShim 里取。所以 JS 侧是:
app-shim-host.md:38
const win = new BrowserWindow({ appShim: shim })
没有 appShim 就走普通的 NativeWindowMac。同一个 new BrowserWindow(),可能造出三种不同的对象。 这是本章"四个身体"说法的一个修正:在 macOS + app shim 的情况下,第四个身体根本不在这个进程里。
9.5.4 titleBarStyle 的三值只在 mac 上存在
native_window.cc:55
template <>
struct Converter<electron::NativeWindow::TitleBarStyle> {
static bool FromV8(v8::Isolate* isolate, v8::Local<v8::Value> val,
electron::NativeWindow::TitleBarStyle* out) {
std::string title_bar_style;
if (!ConvertFromV8(isolate, val, &title_bar_style)) return false;
if (title_bar_style == "hidden") {
*out = TitleBarStyle::kHidden;
#if BUILDFLAG(IS_MAC)
} else if (title_bar_style == "hiddenInset") {
*out = TitleBarStyle::kHiddenInset;
} else if (title_bar_style == "customButtonsOnHover") {
*out = TitleBarStyle::kCustomButtonsOnHover;
#endif
} else {
return false;
}
return true;
}
};
hidden 三平台通用,hiddenInset 与 customButtonsOnHover 只在 mac 上被接受。
不接受的后果是 return false——ValueOrDefault 会退回默认值 kNormal,不报错。所以:
new BrowserWindow({ titleBarStyle: 'hiddenInset' })
// 在 Windows 上:静默变成 normal,有边框
这是一个静默失败。为什么不抛错?因为跨平台应用的代码通常是这样写的:
new BrowserWindow({ titleBarStyle: process.platform === 'darwin' ? 'hiddenInset' : 'hidden' })
抛错会让这种写法在非 mac 上崩掉。返回 false 让 ValueOrDefault 兜底,代价是"拼错了也发现不了"。
TitleBarStyle 的枚举只有四个值(kNormal、kHidden、kHiddenInset、kCustomButtonsOnHover),而 mac 的 NSWindow 有更多样式(NSWindowStyleMaskFullSizeContentView、titlebarAppearsTransparent 等)。Electron 把它们收敛成四个,其余用 vibrancy、trafficLightPosition、titleBarOverlay 单独控制。
这个收敛是有意的:枚举值越多,跨平台的行为差异越难描述。四个值里只有一个通用,这个比例本身就在说"标题栏是平台差异最大的部分"。
9.6 生命周期:四个身体怎么死
9.6.1 三条入口,一条主干
用户能触发的"关窗口"有三条路:
| 入口 | 起点 | 是否走 beforeunload |
|---|---|---|
win.close() | JS,主动 | 是 |
| 点标题栏关闭按钮 | 平台 | 是 |
win.destroy() | JS,强制 | 否 |
前两条最终汇合到同一条主干。第三条是短路。
win.close() 的完整链路(8 个阶段):
① JS: win.close()
→ BaseWindow::Close() [api:427]
② NativeWindow::Close() [views:578]
→ widget()->Close()
③ views: Widget::Close()
→ WidgetDelegate::CanClose()
→ NativeWindow::NotifyWindowCloseButtonClicked() [native_window.cc:550]
④ 第一轮:WillCloseWindow → Emit("close") ← 用户的 close 监听器
⑤ 第二轮:OnCloseButtonClicked → DispatchBeforeUnload
→ 用户的 beforeunload 监听器
⑥ WebContents::Close() → CloseImmediately()
→ NativeWindow::CloseImmediately() → widget()->CloseNow()
⑦ views: 原生窗口销毁 → OnWidgetDestroyed
→ NativeWindow::NotifyWindowClosed() [native_window.cc:568]
→ BaseWindow::OnWindowClosed() [api:207]
⑧ 七步清理 + PostTask(GetDestroyClosure()) → C++ 析构 → self_ref_.Reset()
第 ② 步到第 ③ 步之间有一次"所有权移交"。 NativeWindowViews::Close() 只是 widget()->Close(),它不再管后续。是否真的关,由 views 回调 CanClose() 决定——而 CanClose() 的默认实现会调 NotifyWindowCloseButtonClicked(),那才是 Electron 的逻辑入口。
这个间接层是必要的:widget()->Close() 可以来自很多地方(Electron、Chromium 的某个组件、系统的窗口菜单),它们都应该走同一套"先问再关"。把逻辑放在 CanClose() 里,等于给所有来源装了一个统一的闸门。
9.6.2 close() 与 destroy() 的阶段对照
| 阶段 | close() | destroy() |
|---|---|---|
close 事件 | 发,可取消 | 不发 |
beforeunload | 发,可取消 | 不发 |
webContents 销毁 | 是(Close() 内部) | 是(Destroy() 强制) |
| 窗口状态保存 | 是(FlushWindowState) | 是 |
closed 事件 | 发 | 发 |
NativeWindow 析构 | 延迟一个任务 | 延迟一个任务 |
destroy() 的实现只有一行:
electron_api_base_window.cc:422
void BaseWindow::CloseImmediately() {
window_->CloseImmediately();
}
而 NativeWindowViews::CloseImmediately() 是 widget()->CloseNow():
native_window_views.cc:588
void NativeWindowViews::CloseImmediately() {
widget()->CloseNow();
}
CloseNow() 跳过 CanClose(),直接销毁。所以 close 事件、beforeunload 全部跳过。
这个差异是 destroy() 存在的理由。 一个页面卡在 beforeunload 里(比如弹了对话框但用户没点),close() 会永远不返回;destroy() 是唯一的出路。
代价:destroy() 之后 webContents 的 unload 也不会跑,页面里没保存的数据丢失,localStorage 的写入可能没落盘。destroy() 是一个"我确定要放弃这些"的声明。
9.6.3 反向路径:WebContents 先死
前面讲的都是窗口主动关。还有一条反向的:
electron_api_browser_window.cc:119
void BrowserWindow::WebContentsDestroyed() {
api_web_contents_ = nullptr;
CloseImmediately();
}
BrowserWindow 观察自己的 webContents(Observe(api_web_contents_->web_contents()))。页面被销毁时(用户调 win.webContents.close(),或者页面自己 window.close()),窗口跟着关。
这是一条"内容决定容器"的规则:BrowserWindow 的存在意义是"装一个 webContents 的窗口",内容没了,容器也没有存在的必要。
对比 BaseWindow:它不观察 webContents,因为它的内容视图可以是任意 views::View。所以:
const win = new BaseWindow()
win.contentView.addChildView(new WebContentsView())
// 这个 WebContentsView 的 webContents 被销毁,窗口不会关
BrowserWindow 是一个"恰好只装一个 webContents"的特化,这个特化把两者的生命周期绑在了一起。 这是 9.1.1 那张表里"JS 层做的事"之外,C++ 层多出来的一条耦合。
反向还有一层。BrowserWindow 的析构:
electron_api_browser_window.cc:105
BrowserWindow::~BrowserWindow() {
if (api_web_contents_) {
// Cleanup the observers if user destroyed this instance directly instead of
// gracefully closing content::WebContents.
api_web_contents_->RemoveObserver(this);
api_web_contents_->Destroy();
}
}
注释说"用户直接销毁了这个实例,而不是优雅地关闭 WebContents"。此时要主动 Destroy() 掉 webContents——否则窗口没了,页面还在后台跑着(有定时器、有网络请求)。
这里有一个不对称:WebContentsDestroyed 里把 api_web_contents_ 置空再关窗口;析构里检查 api_web_contents_ 是否还非空再销毁它。两个方向的置空/检查,构成了一个"谁先死"的握手。
9.6.4 window-all-closed 的时序
window_list.cc:56
void WindowList::RemoveWindow(NativeWindow* window) {
auto& windows = GetInstance()->windows_;
std::erase(windows, window);
if (windows.empty())
GetObservers().Notify(&WindowListObserver::OnWindowAllClosed);
}
OnWindowAllClosed 在 windows_ 变成空的那一刻发。谁在监听?ElectronBrowserMainParts。
而 lib/browser/init.ts:89-91 里有这样一段:
app.on('window-all-closed', () => {
if (process.listenerCount('window-all-closed') === 1) {
app.quit();
}
});
=== 1 是关键。这个框架自带的监听器自己算一个,所以 === 1 意味着"没有用户监听器"。用户只要注册了 app.on('window-all-closed', ...),count 就是 2,框架不退出。
这是一个"默认行为可被监听覆盖"的模式。它的实现依赖一个脆弱的事实:框架的监听器必须先注册,且用户不能移除它。
如果用户写 app.removeAllListeners('window-all-closed'),count 变 0,=== 1 不成立,应用永不退出。这是一个可触发的死锁,但没有防护——框架假设用户不会这么做。
时序上还有一个坑:OnWindowAllClosed 在 RemoveWindow 里发,而 RemoveWindow 在 NotifyWindowClosed 里被调。也就是说,window-all-closed 在最后一个窗口的 NotifyWindowClosed 中途触发,早于 BaseWindow::OnWindowClosed。
顺序:
NativeWindow::NotifyWindowClosed()
├─ if (is_closed_) return; is_closed_ = true;
├─ observers_.Notify(OnWindowClosed) → BaseWindow::OnWindowClosed() [七步]
└─ WindowList::RemoveWindow(this)
└─ if (windows_.empty()) → OnWindowAllClosed → app 'window-all-closed'
observers_.Notify(OnWindowClosed) 在 RemoveWindow 之前(native_window.cc:568–573)。所以 BaseWindow::OnWindowClosed 的七步已经跑完(包括 Emit("closed")),然后才是 window-all-closed。
这对用户可见的行为有一个具体影响:
win.on('closed', () => console.log('A'));
app.on('window-all-closed', () => console.log('B'));
// 输出:A 然后 B
closed 先于 window-all-closed。 这个顺序让"在 closed 里做清理"的代码有机会在应用退出前完成。
但 BaseWindow::OnWindowClosed 的最后一步是 PostTask(GetDestroyClosure())——C++ 析构在下一个任务。所以 window-all-closed 触发时,最后一个窗口的 C++ 对象还活着,只是 is_destroyed 为真。
app.quit() 会调 WindowList::CloseAllWindows(),此时列表已经空了,什么也不做,然后走退出流程。而那个待执行的 GetDestroyClosure() 可能在退出流程中被 CleanedUpAtExit 抢先处理。
这个"析构任务与退出流程赛跑"的窗口期是真实存在的,也是为什么 BaseWindow 要继承 CleanedUpAtExit——保证不管谁先到,self_ref_ 都会被释放。
9.6.5 三个悬垂位置
窗口销毁过程中,有三个指针会在某个瞬间变成悬垂,每一个都对应一个具体的防护。
① window_(unique_ptr<NativeWindow>)与 api_web_contents_
BaseWindow::OnWindowClosed 里 window_->FlushWindowState() 之后还有 window_->RemoveObserver(this)——等等,RemoveObserver 在前面。顺序是:
electron_api_base_window.cc:211-216
weak_factory_.InvalidateWeakPtrs();
RemoveFromWeakMap();
window_->RemoveObserver(this); // ← 最后一个操作 window_ 的地方(除了 Flush)
MarkDestroyed();
window_->FlushWindowState();
Emit("closed");
Emit("closed") 之后不再碰 window_。而 window_ 要等 DeleteSoon 才释放。所以从 Emit("closed") 到析构之间,window_ 仍然有效但已经"逻辑死亡"。
防护是"不再使用",不是"检查"。这是刻意的:如果七步之后还有代码碰 window_,那就是设计错误。
② api_web_contents_(base::WeakPtr<api::WebContents>)
用弱指针。WebContentsDestroyed() 里置空,FocusIsInAnotherView() 等处都先检查:
electron_api_browser_window.cc:201
bool BrowserWindow::FocusIsInAnotherView() {
#if BUILDFLAG(IS_MAC)
return false;
#else
auto* focus_manager = window()->widget()->GetFocusManager();
auto* focused = focus_manager ? focus_manager->GetFocusedView() : nullptr;
auto* primary = window()->primary_web_contents_view();
return focused && primary && !primary->Contains(focused);
#endif
}
注意这里用的是 window()->primary_web_contents_view()(一个 views::ViewTracker,第 7 章讲过),不用 api_web_contents_。因为它要问的是"焦点在哪个 view",而 view 可能在没有 api_web_contents_ 的情况下还存在。
③ parent_(base::WeakPtr<NativeWindow>)
native_window.h:583
// The parent window. Held weakly because the parent may be destroyed
// before this window (e.g. a modal child whose parent is destroy()ed).
base::WeakPtr<NativeWindow> parent_;
注释直接给了场景:父窗口被 destroy() 时,子窗口还在。如果 parent_ 是裸指针,之后任何 parent_->xxx 都是 UAF。
弱指针把"父窗口没了"变成"parent_.get() 返回 nullptr"。调用方要处理这一种情况:
native_window.cc:498
bool NativeWindow::AddTabbedWindow(NativeWindow* window) {
return true; // for non-Mac platforms
}
这个没用到 parent_。真正用到的地方在 GetChildWindows / SetParentWindow 与 mac 的 RemoveChildFromParentWindow。
child_windows_ 用的是 std::list<raw_ptr<NativeWindow>>——裸指针。为什么子窗口用裸指针而父窗口用弱指针?
因为子窗口的生命周期受父窗口控制(CloseImmediately 里先关所有 child),而父窗口的生命周期不受子窗口控制。弱指针放在"可能先死"的一侧,这是这套设计的规则。
9.6.6 关不掉的窗口:六种原因
"我调了 win.close() 但窗口没关"是常见问题。按可能性排:
| # | 原因 | 判据 | 解法 |
|---|---|---|---|
| 1 | close 监听器 preventDefault() | 加日志看有没有进 close | 检查自己的代码 |
| 2 | beforeunload 返回非空 | DevTools 里看是否有对话框 | 检查页面的 beforeunload |
| 3 | isClosable() === false | win.isClosable() | setClosable(true) |
| 4 | macOS 全屏过渡中 | 只有 mac,且正在切全屏 | 等过渡结束 |
| 5 | 有 sheet 附着(mac) | 有打开的模态面板 | 先关 sheet |
| 6 | 窗口已 isDestroyed() | 调 close() 无效果 | 已经关了 |
第 3 条的实现:
native_window_views.cc:582
void NativeWindowViews::Close() {
if (!IsClosable()) {
WindowList::WindowCloseCancelled(this);
return;
}
widget()->Close();
}
setClosable(false) 之后 close() 是静默失败的——不抛错,不发事件,只是 WindowCloseCancelled(这个通知只给应用级流程用,用户的 close 监听器收不到)。
第 2 条的机制值得展开。beforeunload 的返回值决定是否阻止:
window.onbeforeunload = (e) => {
e.preventDefault();
e.returnValue = ''; // 现代浏览器只要求 returnValue 非空
};
在 Electron 里,这个行为取决于 webPreferences。默认情况下 beforeunload 会阻止关闭,但不弹对话框(Electron 不实现 Chromium 的原生 beforeunload 对话框)。所以用户看到的是"点了关闭,什么都没发生",没有任何提示。
这是一处容易踩的坑:页面的 beforeunload 阻止了关闭,但用户看不到原因。 应用需要自己处理——在 close 事件里检测,或者改用 will-prevent-unload 事件:
web-contents.md:466
win.webContents.on('will-prevent-unload', (event) => {
// 这里可以自己弹确认框,然后 event.preventDefault() 强制关闭
})
9.6.7 CloseImmediately 的递归:子窗口
electron_api_browser_window.cc:229
void BrowserWindow::CloseImmediately() {
// Close all child windows before closing current window.
for (BaseWindow* child : GetChildWindows())
child->window()->CloseImmediately();
BaseWindow::CloseImmediately();
}
先关所有子窗口,用 CloseImmediately 而不是 Close。 两个选择都有理由:
- 先关子:父窗口的
NSWindow/HWND销毁时,子窗口如果还挂着,平台可能崩溃或泄漏。 - 用
CloseImmediately:子窗口的beforeunload不该阻塞父窗口的关闭。父窗口被强制销毁时,子窗口没有"活下去"的选项。
递归的深度是任意的(子窗口可以有子窗口),但实际应用中很少超过两层。没有深度限制,也没有循环检测——如果 A.parent = B 且 B.parent = A,这里会栈溢出。这个情况在构造时被 IsParentValid 挡住了(9.2.1 阶段 2 之后的检查),但 setParentWindow() 运行期调用是否会形成环,没有检查。
9.7 失败模式手册
窗口问题的特点是现象明确、原因分散。按现象列:
| 现象 | 最可能的原因 | 定位方法 |
|---|---|---|
| 白屏但窗口在 | webContents 没加载 / show: false 后忘 show() | win.webContents.getURL() |
| 窗口出现但尺寸不对 | InitFromOptions 里的 ClampSize 生效 | win.getSize() vs win.getContentSize() |
| 窗口位置在屏幕外 | 状态恢复匹配到错误显示器 | 看 userData/Local State 的 windowStates |
| 透明窗口全黑 | 没设 backgroundColor: '#00000000' | 见下 |
| 无框窗口拖不动 | -webkit-app-region: drag 缺失或被全屏禁用 | NonClientHitTest 三层 |
| 圆角不生效 | thickFrame: false 或透明窗口 | 9.4.5 |
setBounds 尺寸差几个像素 | 窗口坐标 vs 内容坐标 | 用 setContentBounds |
| 关闭后进程不退出 | window-all-closed 监听器计数不为 1 | listenerCount |
| 关窗口卡住 | beforeunload 阻止 | will-prevent-unload |
win.isDestroyed() 但方法还能调 | 处于"已销毁未回收"态 | 9.2.8 的三态表 |
| macOS 全屏后布局错乱 | 内容尺寸与窗口尺寸在过渡中不一致 | 监听 enter-full-screen 后重算 |
titleBarOverlay 高度不对 | titlebar_overlay_height_ 只在构造时读 | 需要重建窗口 |
三条最值得记的:
"透明窗口全黑" 是最常见的窗口问题。原因是三层透明度只设了一层:
new BrowserWindow({
transparent: true,
backgroundColor: '#00000000', // ① 窗口背景
webPreferences: { transparent: true } // ② 不需要,但页面背景要自己设
})
/* ③ 页面背景 */
html, body { background: transparent; }
三处任一没设,结果都是黑的(或白的)。①决定原生窗口的合成方式(kTranslucent),②决定 WebContents 的背景,③决定页面自己的绘制。 缺一处,另外两处的透明就白设了。
"setBounds 差几个像素" 是坐标系统的问题。setBounds 是窗口坐标(含边框),setContentBounds 是内容坐标(不含边框)。在一个有框窗口上:
win.setBounds({ width: 800, height: 600 })
win.getContentSize() // [784, 561] 之类,取决于边框
两个 API 都对,但用户想要的通常是后者。 这也是为什么 useContentSize: true 这个构造选项存在——它让 width/height 从一开始就按内容尺寸解释。
"关闭后进程不退出" 除了 window-all-closed 的计数问题,还有两个原因:有未关闭的 WebContents(比如一个没有窗口的 WebContentsView),或者有活跃的 setInterval。前者要看 webContents.getAllWebContents(),后者要靠 process._getActiveHandles()。
9.8 性能账本
窗口创建是应用启动路径上最重的一步。下面是一组量级估计——不是本机实测,而是从各阶段涉及的子系统(views::Widget::Init、渲染进程启动、Blink 初始化、首帧合成)的公开数据与该版本代码路径推出来的,用于判断"哪个阶段值得优化",不用于性能断言:
| 阶段 | 量级 | 说明 |
|---|---|---|
new BrowserWindow() 到构造返回 | 8–20 ms | 含 views::Widget::Init、原生窗口创建 |
| 到首帧可见 | 40–120 ms | 含渲染进程启动、Blink 初始化、首帧合成 |
show: false 省下的 | 约 0(只是不映射) | 但省下了首帧的合成 |
| 窗口状态恢复 | 1–3 ms | 读一次 Local State,几次显示器查询 |
每个额外 WebContentsView | 30–90 ms | 一个新的渲染进程 |
三条推论:
show: false + 延迟 show() 是启动优化的标准手法,但它省的不是窗口创建,是首帧。 窗口的 C++ 对象已经建好,views::Widget 已经 Init,原生窗口已经创建(只是不可见)。真正的收益是"用户不会看到一个白窗口"。
ready-to-show 事件是这个优化的正确落点,它在首帧准备好之后发:
browser-window.md:44-45
const win = new BrowserWindow({ show: false })
win.once('ready-to-show', () => win.show())
用 loadURL 的 Promise 不行——它 resolve 的时候首帧可能还没合成。
多窗口应用的瓶颈不在窗口,在渲染进程。 每个 BrowserWindow 默认带一个独立的渲染进程(site-per-process 的后果),30–90ms 的启动成本。如果应用要开 10 个窗口,就是 300–900ms。这就是为什么"用一个窗口 + 多个 WebContentsView"在 Electron 里是常见的性能手法——但每个 WebContentsView 也是一个渲染进程,省不下来。
真正省的是 webPreferences: { affinity }(已废弃)之类的共享进程方案,以及 utilityProcess 里的 worker。
9.9 练习题
9.1(入门) 在主进程执行下面两行,分别解释结果:
browser-window.md:44-46
const win = new BrowserWindow({ show: false })
win.webContents === require('electron').webContents // 这是模块吗?
typeof win.loadURL === 'function' && !('loadURL' in win.webContents.constructor.prototype)
第二行的意思:win.loadURL 是 BrowserWindow.prototype 上的转发函数,不是 webContents 的原生方法。验证 win.loadURL !== win.webContents.loadURL,并解释 9.1.7 为什么要在 JS 层做这个转发。
9.2(入门) 用 win.getBounds() 与 win.getContentBounds() 对比一个 frame: true 的窗口,算出边框宽度。再改成 titleBarStyle: 'hidden',看差值变化(9.3.3)。
9.3(初级) 构造一个 { width: 100, height: 100, minWidth: 500 } 的窗口,观察实际尺寸。解释 InitFromOptions 第 4 步的 ClampSize 为什么让 minWidth 赢(9.3.4)。
9.4(初级) 写一个 close 监听器里 preventDefault() 的应用,然后试 win.destroy()。列出两者跳过的阶段(9.6.2)。
9.5(进阶) 复现"透明窗口全黑":只设 transparent: true,不设 backgroundColor。然后逐层补上三处透明,观察每补一处的变化(9.7)。
9.6(进阶) 在 NativeWindow::NonClientHitTest 里加一行日志,给一个带 -webkit-app-region: drag 的区域,分别在窗口模式与 HTML5 全屏模式下点击,观察返回值差异(9.3.11)。
9.7(进阶) 打开 windowStatePersistence,把窗口拖到第二显示器,关闭应用,拔掉第二显示器,重启。解释 RestoreBounds 里为什么用曼哈顿距离而不是重叠面积(9.3.9)。
9.8(深入) 在 BaseWindow::OnWindowClosed 里把 MarkDestroyed() 移到 Emit("closed") 之后,写一个在 closed 里调 win.isDestroyed() 的监听器,观察返回值变化。解释为什么这个顺序是"对外可见性递增"(9.2.6)。
9.9(深入) 注释掉 self_ref_.Reset(),用 new BrowserWindow() 不保存引用,反复执行 1000 次,观察内存增长与窗口数量。解释这个"反向 GC 根"的作用(9.2.4)。
9.10(挑战) 给 NativeWindow 加一个纯虚函数 SetCornerRadius(int),在三个实现里分别用 DwmSetWindowAttribute、X11 的 shape 扩展、NSWindow 的 contentView.layer.cornerRadius 实现。记录你改了几处、哪些平台只能做成空操作(9.3.1)。
9.11(挑战) 读 native_window_mac_remote.h,列出它没有实现(或 NOTIMPLEMENTED())的方法。推断哪些是"Mojo 接口没有对应调用",哪些是"实现了但没意义"(9.5.3)。
9.10 下一章预告
第 10 章《BaseWindow、BrowserWindow 与 WebContentsView:一个窗口能装什么》接住本章的三条尾巴。
尾巴一:9.4.4 说过,GetContentsView() 返回的是 main_view_,不是 content_view_。那个"两层容器"的结构是 BaseWindow 与 BrowserWindow 分家的基础——BaseWindow 只填 content_view_,BrowserWindow 还要往 main_view_ 里插一个 WebContentsView。第 10 章会把这两种填法画成两棵树,并解释为什么 BrowserWindow 的 contentView 是空的(用户加的东西在 WebContents 之上)。
尾巴二:9.3.13 的 NativeWindowRelay 让 WebContents 能找到窗口。反过来,"一个 WebContents 属于哪个 BrowserWindow"这个问题有三条不同的答案(relay、ownerWindow、getOwnerBrowserWindow()),它们在某些状态下不一致。第 10 章会给出这三个答案的一致性条件。
尾巴三:9.5.1 说 macOS 多一层 NativeWindowMacRemote。第 10 章会讲另一处跨进程:<webview> 的 guest 实例。一个 <webview> 元素在宿主页面里,它的内容是另一个 WebContents,可能在不同进程——这是比 app shim 更老、更常见的一种"跨进程窗口"。
一句话预告第 10 章的立论:Electron 的"窗口"其实是一个可以装任意视图的容器,BrowserWindow 只是它最常用的一个配置——而这个配置把三个独立对象(窗口、内容视图、WebContents)的生命周期绑成了一个。
9.11 本章源码落点索引
下列位置全部来自本仓库源码树,按实现层归集;每个
路径:行号指向该文件中与本章论述对应的声明或实现行,可逐条复核。
- 浏览器进程 C++ 层:
native_window_mac_remote.mm:46 native_window_views_win.cc:49 electron_api_base_window_mac.mm:15 electron_api_browser_window.h:14 electron_api_web_contents.cc:249 electron_api_web_contents.h:61 electron_api_web_contents_impl.cc:19 electron_api_web_contents_mac.mm:16 -
electron_api_web_contents_view.cc:38 electron_api_web_contents_view.h:17 child_web_contents_tracker.cc:13 child_web_contents_tracker.h:16 electron_web_contents_utility_handler_impl.cc:23 electron_web_contents_utility_handler_impl.h:15 extended_web_contents_observer.h:13 inspectable_web_contents.cc:111 -
inspectable_web_contents.h:28 inspectable_web_contents_delegate.h:12 inspectable_web_contents_view.cc:37 inspectable_web_contents_view.h:18 inspectable_web_contents_view_delegate.cc:10 - shell 其余实现:
native_window_converter.h:14 - API 文档与类型:
web-contents-view.md:5 - JS 门面与运行时:
base-window.ts:4 web-contents.ts:20