wp-calypso 桌面端登录状态处理解析：Login Status Window Handler 与菜单联动机制

• 前端
• CMS

wp-calypso（WordPress.com 的 JavaScript 与 API 驱动前端）在desktop/目录下提供基于 Electron 的桌面客户端。其中desktop/app/window-handlers/login-status/目录中的 Login Status 模块承担着"跟随用户登录状态动态切换桌面端 UI 能力"的核心职责：用户登录后启用需要鉴权的菜单项与 Dock 菜单，登出后禁用并引导回登录页。本文以 login-status/README.md 为主线，结合其 index.js、会话管理器、菜单系统与 IPC 预加载层源码，完整还原这一机制的架构、数据流与实现细节，帮助读者理解 Electron 桌面应用中"登录态驱动原生 UI"的典型实现范式。

模块定位：Window Handlers 体系中的一员

在桌面应用启动流程中，主窗口打开之后会挂载一系列"窗口处理器"（Window Handlers）。根据 window-handlers/README.md 的说明：Window handlers are bits of code that run before after app has started and the main window has opened——它们是主窗口打开后运行的一段段独立逻辑，每个处理器聚焦一个横切关注点：

• Debug Tools
• External Links
• Failed To Load
• Login Status
• Notifications
• Window Saver

Login Status 即其中之一。其 README 自述职责非常聚焦：Toggles menu items that require the user to be logged in——切换那些要求用户处于登录状态的菜单项。也就是说，它负责把"用户是否已登录"这一业务状态，翻译成桌面端原生 UI 的可用/不可用切换动作。

注册时机：主窗口初始化时挂载

该处理器在应用主窗口初始化流程中被注册。在 desktop/app/mainWindow/index.js 中可以看到挂载点：

require( '../window-handlers/login-status' )( appWindow );

与 Window Handlers 目录下其他处理器一样，login-status 模块导出的是一个接收appWindow参数的工厂函数，主窗口创建完成后立即执行。这种"启动后按需注册"的设计，使每个处理器都可以独立维护、独立测试，也避免了在主流程中堆砌大量业务分支。

IPC 消息契约：user-login-status 通道

README 的 "IPC messages" 一节声明了本模块监听的消息：

• user-login-status——sent by Calypso when a user login status changes，即由 Calypso（渲染进程中的 Web 应用）在用户登录状态变化时发送。

这个通道在白名单层面有严格约束。桌面端通过 desktop/public_desktop/preload.js 中的contextBridge向渲染进程暴露受控的 IPC 能力：sendChannels数组（发送方向白名单）第 16 项即'user-login-status'，渲染进程只能通过window.electron.send( 'user-login-status', ... )发送该白名单内的通道，其余通道会被 preload 脚本直接拦截；同时receiveChannels（接收方向白名单）中还包含'request-user-login-status'，供主进程向渲染进程主动询问/广播登录状态。这种"双向通道白名单"是桌面端 IPC 安全基线的体现——未经声明的通道无法穿透 preload 层。

值得注意的实现细节是：虽然 README 声明的契约是监听user-login-statusIPC 消息，但从 index.js 的实际代码看，该模块订阅的并非ipcMain.on( 'user-login-status', ... )，而是会话管理器SessionManager上发出的 Node.js 事件（logged-in/logged-out/api:connect/api:disconnect）。这可以理解为双层设计：IPC 通道负责渲染进程与主进程间的消息契约，而主进程内部通过事件总线（EventEmitter）解耦各模块，Login Status 只需订阅会话状态事件即可，无需关心事件究竟来自 IPC 还是 Cookie 监听。

登录状态的真正来源：SessionManager 与 Cookie 监听

Login Status 本身不维护登录状态，真正的状态源是 desktop/app/lib/session/index.js 中单例化的SessionManager。它继承自 Node.js 的EventEmitter，在init()时完成两件事：

1. 启动时探测既有登录态。通过 Electron 的session.cookies.get()读取https://public-api.wordpress.com域下的wordpress_logged_inCookie（session/index.js）；若存在则置loggedIn = true并发出logged-in事件，同时把 Cookie 值（decodeURIComponent后）写入系统钥匙串（keychain）。随后依次处理wp_api_sec（Pinghub 实时连接凭据，写入钥匙串后发出api:connect）与wp_api（Notifications REST API 凭据）两个 Cookie（session/index.js）。

2. 运行时监听 Cookie 变化。订阅session.cookies.on( 'changed', ... )（session/index.js）：

• 当cookie.name === 'wordpress_logged_in'且cookie.domain === '.wordpress.com'时：
  • 若 Cookie 被移除（removed）且当前处于登录态，则置loggedIn = false、发出logged-out事件，并keychain.clear()清理全部凭据；
  • 否则视为登录，置loggedIn = true并发出logged-in事件。
• wp_api_secCookie 被移除时发出api:disconnect，存在且已登录时发出api:connect；
• wp_apiCookie 存在且已登录时写入钥匙串。

也就是说：桌面端以.wordpress.com域的wordpress_logged_inCookie 作为登录状态的唯一事实来源，无论用户是在 WebView 内通过 Calypso 登录页完成认证，还是中途登出，Cookie 变化都会经由changed事件转化为logged-in/logged-out事件，再被 Login Status 消费。这正是 README 所说"由 Calypso 在登录状态变化时发送"在实现层的落点——渲染进程内发生的登录/登出最终都会体现在 Cookie 上。

登录成功的响应：菜单、Dock 与通知连接

Login Status 的核心实现只有两个函数，却串联起桌面端三大 UI/服务面（login-status/index.js）：

module.exports = function ( appWindow ) { menu.set( app, appWindow ); SessionManager.on( 'logged-in', () => { handleLogin(); } ); SessionManager.on( 'logged-out', () => { handleLogout( appWindow ); } ); SessionManager.on( 'api:connect', () => { WPNotificationsAPI.connect(); } ); SessionManager.on( 'api:disconnect', () => { WPNotificationsAPI.disconnect(); } ); }; function handleLogin() { menu.enableLoggedInItems(); platform.setDockMenu( true ); }

登录态为真时依次执行：

1. 启用应用菜单中的登录专属项：menu.enableLoggedInItems()（详见下文菜单机制）；
2. 启用平台 Dock 菜单：platform.setDockMenu( true )，让 macOS Dock / Windows / Linux 任务栏上的快捷菜单在登录后可用；
3. 连接通知 API：api:connect事件触发WPNotificationsAPI.connect()，即 desktop/app/lib/notifications/api 中定义的推送/通知长连接模块，登录后才建立与 Pinghub 等服务的实时通道，未登录时保持断开以避免无谓请求。

注意这里模块订阅的api:connect/api:disconnect与logged-in/logged-out是两组独立事件——api:connect依赖wp_api_secCookie 的存在，与wordpress_logged_in并非严格同时发生，因此通知连接的建立/拆除独立于菜单切换，互不阻塞。

登出的响应：禁用菜单、清理 Dock、跳转登录页

function handleLogout( { view } ) { platform.setDockMenu( false ); menu.disableLoggedInItems(); view.webContents.loadURL( Config.loginURL() ); }

登出处理（login-status/index.js）与登录严格对称：

1. platform.setDockMenu( false )关闭 Dock 快捷菜单；
2. menu.disableLoggedInItems()禁用所有带requiresUser标记的菜单项；
3. view.webContents.loadURL( Config.loginURL() )将 BrowserView 导航到Config.loginURL()（登录页 URL，定义于 desktop/app/lib/config），把用户带回登录界面。

其中Config.loginURL()返回的地址随构建环境配置变化（开发/生产环境通过 config 下的配置文件区分），这就是桌面端"登出即回登录页"流程的终点。

菜单启用/禁用的底层机制：requiresUser 与 menu-setter

菜单切换并非"重建菜单"，而是基于 ElectronMenu实例的enabled标志做批量开关。整个机制分为三层：

第一层：菜单项标记。在 desktop/app/lib/menu/app-menu.js 中，"Sign Out"（退出登录）菜单项显式声明了登录依赖：

{ label: 'Sign Out', requiresUser: true, enabled: false, id: 'loggedin', click: async function () { /* ... */ }, }

requiresUser: true是一个自定义标记属性，enabled: false是初始禁用状态。该菜单项的用户登录时才会被启用，其click回调中会区分两种登出路径：若当前视图是 Calypso 页面则通过ipc.signOut( view )（desktop/app/lib/calypso-commands/index.js，向渲染进程发送signout指令）优雅登出；否则直接clearStorageData()并跳转登录 URL。主菜单模板在 desktop/app/lib/menu/main-menu.js 中组装，由 App/Edit/View/Window/Help 五个子菜单构成。

第二层：批量开关器。desktop/app/lib/menu/index.js 中的AppMenu单例提供enableLoggedInItems()/disableLoggedInItems()，内部调用 desktop/app/lib/menu-setter/index.js 的setRequiresUser( menu, enabled )。

第三层：递归遍历。menu-setter的核心逻辑（menu-setter/index.js）遍历应用菜单的每个顶层条目及其submenu子条目，凡带requiresUser属性且为真值的条目，统一把enabled设置为传入的布尔值：

function setMenuAttribute( menu, attr, enabled ) { if ( typeof menu[ attr ] !== 'undefined' && menu[ attr ] ) { menu.enabled = enabled; } }

这套机制同样复用于全屏切换：setToggleFullScreen( menu, enabled )针对fullscreen标记操作（View 菜单中的 "Toggle Full Screen" 项，见 desktop/app/lib/menu/view-menu.js）。因此，任何未来新增的"需登录才可用"菜单项，只需在模板中打上requiresUser: true标记，即可自动获得登录态联动，无需改动 Login Status 或 menu-setter 任何代码。

平台适配：setDockMenu 的跨平台分发

platform.setDockMenu( enabled )定义于 desktop/app/lib/platform/index.js。Platform单例在setMainWindow()时按当前系统加载平台处理器：macOS（./mac）、Windows（./windows）或 Linux（./linux），随后所有平台相关调用都委托给该处理器。Login Status 只调用统一的setDockMenu( boolean )，具体的 Dock 菜单装配、任务栏快捷项展示等差异被封装在各平台模块内部——这保证了登录/登出切换逻辑的跨平台一致性，也让新增平台只需实现同一组接口即可接入。

完整链路与延伸阅读

至此可以串起 Login Status 的完整数据流：

1. 用户登录/登出导致.wordpress.com域 Cookie（wordpress_logged_in、wp_api_sec等）变化；
2. SessionManager的cookies.on( 'changed' )监听器捕获变化，更新loggedIn标志、同步钥匙串，并发出logged-in/logged-out/api:connect/api:disconnect事件；
3. Login Status 处理器消费这些事件：登录时enableLoggedInItems()+setDockMenu( true )+ 连接通知 API；登出时禁用菜单、关闭 Dock 菜单并loadURL( Config.loginURL() )回到登录页；
4. 菜单系统按requiresUser标记批量切换enabled状态，通知模块随api:connect/api:disconnect建立或拆除实时通道。

对桌面端登录体系感兴趣的读者，可继续深入阅读以下仓库路径：

• 处理器实现与注册：login-status/index.js、desktop/app/mainWindow/index.js
• 会话状态与 Cookie 监听：desktop/app/lib/session/index.js
• 菜单模板、开关器与菜单项标记：desktop/app/lib/menu/app-menu.js、desktop/app/lib/menu/index.js、desktop/app/lib/menu-setter/index.js
• IPC 通道白名单与登录指令：desktop/public_desktop/preload.js、desktop/app/lib/calypso-commands/index.js
• 平台适配层：desktop/app/lib/platform/index.js
• 窗口处理器总览：window-handlers/README.md

这套"事件总线 + 标记驱动 UI 开关 + 平台封装"的模式，是 Electron 桌面应用中处理登录态这类跨渲染进程/主进程横切状态的典型范本：业务状态与 UI 表现解耦、新增登录相关菜单零成本接入、平台差异收敛到单一适配层，值得在同类桌面壳工程中复用。

• 前端
• CMS