《Electron 45.2.3 内核解剖》第 9 章 NativeWindow:一个窗口的四个身体

3 阅读1小时+

《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 世界的全部。它做三类事,混在一起容易看不清:

  1. 装饰:BrowserWindow.prototype._init,约 70 行。它在 C++ 构造完成之后、用户拿到对象之前执行。
  2. 静态方法:fromId、getAllWindows、getFocusedWindow、fromWebContents、fromBrowserView。这些是"查表"操作,C++ 侧的 BaseWindow 已经有 fromId/getAllWindows,BrowserWindow 在此基础上加类型过滤。
  3. 转发: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++?三个理由:

  1. ...args 的可变参数透传在 gin 里很贵。 C++ 侧要处理 gin::Arguments,把 N 个参数逐个转成 v8::Local<v8::Value>,再调 webContents 的方法。JS 的 ...args 是语言原生能力,零成本。
  2. this.webContents 可能为空。 窗口销毁后 webContents 是 null,JS 层调 this.webContents.loadURL() 会抛 TypeError: Cannot read properties of null——这个错误信息对用户是可理解的。C++ 层得自己判空并构造错误消息。
  3. 这些方法的语义完全属于 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);
}

第一个构造函数做四件事,第二个再做两件。按发生顺序排:

#位置动作
1130读 title,置 title_set_from_api_
2137读 parent,存成 v8::Global
3143若 webPreferences.offscreen,强制 frame = false
4151NativeWindow::Create(GetID(), options, parent_native)
5153window_->AddObserver(this)
6155SetContentView(View::Create(isolate))
7174→176InitWithArgs(args):建 JS wrapper,调 _init
8177window()->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 变成可回收。

那"某个事件"是什么?两条路:

  1. 窗口被关闭:OnWindowClosed 里 PostTask(GetDestroyClosure())(9.2.6);
  2. 进程退出: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)
3INT_MAX 处理maxWidth: -1 表示"无上限"
4ClampSize 并把结果写回用户给的初始尺寸可能违反约束
5设置 position 或 center必须在尺寸之后:居中要用最终尺寸算
6Windows 上 SetPosition 调两次已知 workaround(issue #10862)
7SetClosable / SetMovable平台样式位
8SetHasShadow
9SetOpacity
10SetAlwaysOnTop
11fullscreenable 的推导fullscreen: false 在 mac 上隐含 fullscreenable: false
12SetFullScreenable必须在 fullscreen 之前
13RestoreWindowState(options)必须在 fullscreen/kiosk 之前,见 9.3.10
14SetFullScreen(true)(若 fullscreen 且未从状态恢复)
15SetResizable
16SetSkipTaskbar
17SetKiosk在 resizable 之后:kiosk 隐含不可 resize
18SetVibrancy(mac)/ SetBackgroundMaterial(win)
19SetBackgroundColor在 vibrancy 之后:IsTranslucent() 需要知道 vibrancy 状态
20SetTitle标题的默认值来自 Browser::Get()->GetName()
21SaveWindowState()把恢复后的状态写回,覆盖掉的旧值
22Show()(若 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 有两条调用路径:

  1. 平台真的关了窗口(views::WidgetObserver::OnWidgetDestroyed);
  2. 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_谁清除
正常falsefalse—
恢复 bounds 中truefalse本函数末尾
恢复显示模式中truetrueNotifyWindowMaximize / 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_WIDGETWidget调用方
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 三处设置:

  1. transparent() || has_client_frame() → kTranslucent。透明窗口必须半透明合成;客户端边框需要抗锯齿边缘,也要半透明。
  2. Linux 上 !has_frame() 也设 kTranslucent。注释:
// Resize handles and shadows on frameless windows need translucent insets.

无框窗口的缩放热区在窗口边缘外几个像素,那些像素必须能透出下面的内容,否则用户会看到一个不透明的边框条。

  1. 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_ 已经加进去之后。 顺序是:

  1. BaseWindow 构造(第一步):SetContentView(View::Create(isolate)) → main_view_ 里有 [0] content_view_;
  2. 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):边框 inset
  • GetMinimumSizeForWindow() / 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() 但窗口没关"是常见问题。按可能性排:

#原因判据解法
1close 监听器 preventDefault()加日志看有没有进 close检查自己的代码
2beforeunload 返回非空DevTools 里看是否有对话框检查页面的 beforeunload
3isClosable() === falsewin.isClosable()setClosable(true)
4macOS 全屏过渡中只有 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 监听器计数不为 1listenerCount
关窗口卡住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,几次显示器查询
每个额外 WebContentsView30–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