Electron Display 对象详解多显示器信息结构与 screen API 实现剖析【免费下载链接】electron:electron: Build cross-platform desktop apps with JavaScript, HTML, and CSS项目地址: https://gitcode.com/GitHub_Trending/el/electronDisplay对象是 Electronscreen模块返回的核心数据结构它描述一个连接在系统上的物理显示器或虚拟/远程显示器字段涵盖几何边界、色彩深度、缩放因子、刷新率、旋转角度等全部显示器指标。本文以 Display 对象官方结构文档 为主体逐字段解析其含义与取值并结合 Electron 仓库中的 C 转换层display::Display到 JavaScript 对象的映射与screenAPI 的事件实现说明每个字段背后的数据来源帮助你在多显示器布局、高 DPI 适配、屏幕热插拔响应等场景中正确使用它。什么是 Display 对象根据 结构定义文档 的说明Display对象表示一个连接到系统的物理显示器。在 headless无头系统上可能存在一个假的Display一个Display也可能对应一个远程或虚拟显示器。这一点很重要不要假设screen.getAllDisplays()返回的一定是“真实存在”的屏幕。在无显示输出的服务器环境、或使用了虚拟显示器如远程桌面、镜像/扩展方案时你拿到的可能是虚拟或占位的Display。文档同时通过id字段约定了这类特殊值的语义id为-1表示该显示器无效或正确的id尚未确定id为-10表示该显示器是一个被分配到统一桌面的虚拟显示器virtual display assigned to a unified desktop。获取Display对象的入口是主进程的 screen 模块常用方法有方法返回值说明screen.getPrimaryDisplay()Display主显示器screen.getAllDisplays()Display[]当前所有可用显示器screen.getDisplayNearestPoint(point)Display距离给定 DIP 点最近的显示器screen.getDisplayMatching(rect)Display与给定Rectangle交集最大的显示器从源码看这四个方法在主进程中由 Screen 类 实现均委托给 Chromium 的display::Screen单例见 electron_api_screen.cc。值得注意的是其容错设计当系统已处于关闭阶段、display::Screen::Get()返回空指针时API 会回退到display::Display::GetDefaultDisplay()即GetFallbackDisplay()保证getAllDisplays()仍返回非空数组、其余方法返回一个默认显示对象而不是向 JavaScript 层抛错。Display 字段完整参考以下字段表完整继承自 官方结构文档并结合源码补充了各字段在 C 层的来源。字段类型说明accelerometerSupportstring加速度计支持情况可为available、unavailable、unknownboundsRectangle显示器的边界单位为 DIPdevice-independent pixelcolorDepthnumber每像素的位深bits per pixelcolorSpacestring色彩空间的字符串表示用于颜色转换的三维色彩对象depthPerComponentnumber每个颜色分量的位深detectedboolean若该显示器已被系统检测到则为truedisplayFrequencynumber显示器刷新率idnumber显示器唯一标识-1表示无效或 id 未知-10表示虚拟显示器internalboolean内建显示器如笔记本屏幕为true外接显示器为falselabelstring由平台决定的用户友好标签maximumCursorSizeSize最大光标尺寸单位为原生像素nativeOriginPoint显示器原点的像素坐标。仅在以像素坐标定位显示器的窗口系统如 X11上可用rotationnumber屏幕旋转角度顺时针可为0、90、180、270scaleFactornumber输出设备的像素缩放因子DPI scale factortouchSupportstring触摸支持情况可为available、unavailable、unknownmonochromeboolean是否为单色黑白显示器sizeSize显示器的整体尺寸DIPworkAreaRectangle显示器的工作区边界DIP即扣除任务栏/dock 等系统占用区域后的可用区域workAreaSizeSize工作区的尺寸DIP嵌套结构说明Rectangle包含x、y、width、height四个整型字段原点为矩形左上角Point包含x、y传入 API 时会被自动取整Size包含width、height。字段在源码中的映射从 display::Display 到 JS 对象Electron 主进程侧的Display对象并非手写拼装而是通过 gin 的 V8 转换器由 Chromium 的display::Display结构一次性生成。核心代码在 gfx_converter.cc 的Converterdisplay::Display::ToV8中每个文档字段的取值来源如下v8::Localv8::Value Converterdisplay::Display::ToV8( v8::Isolate* isolate, const display::Display val) { auto dict gin_helper::Dictionary::CreateEmpty(isolate); dict.Set(accelerometerSupport, val.accelerometer_support()); dict.Set(bounds, val.bounds()); dict.Set(colorDepth, val.color_depth()); dict.Set(colorSpace, val.GetColorSpaces() .GetRasterAndCompositeColorSpace( gfx::ContentColorUsage::kWideColorGamut) .ToString()); dict.Set(depthPerComponent, val.depth_per_component()); dict.Set(detected, val.detected()); dict.Set(displayFrequency, val.display_frequency()); dict.Set(id, val.id()); dict.Set(internal, val.IsInternal()); dict.Set(label, val.label()); dict.Set(maximumCursorSize, val.maximum_cursor_size()); dict.Set(monochrome, val.is_monochrome()); dict.Set(nativeOrigin, val.native_origin()); dict.Set(rotation, val.RotationAsDegree()); dict.Set(scaleFactor, val.device_scale_factor()); dict.Set(size, val.size()); dict.Set(workArea, val.work_area()); dict.Set(workAreaSize, val.work_area_size()); dict.Set(touchSupport, val.touch_support()); return dict.GetHandle(); }从这段转换代码可以读出几个文档未直接言明的实现细节colorSpace是宽色域栅格/合成色彩空间的字符串形式源码取的是GetColorSpaces().GetRasterAndCompositeColorSpace(gfx::ContentColorUsage::kWideColorGamut).ToString()即以宽色域Wide Color Gamut内容用途查询当前显示器的栅格化与合成色彩空间。也就是说当显示器不支持 WCG 时它反映的是该显示器实际可表示的复合色彩空间。accelerometerSupport/touchSupport的三态由 switch 收敛而来C 枚举AVAILABLE/UNAVAILABLE分别映射为字符串available/unavailable其余一切情况统一落入unknown见 gfx_converter.cc。因此在写判断逻辑时不要把“不等于available”简单等价于“不支持”unknown是一个独立的合法状态。rotation输出的是角度数值由val.RotationAsDegree()得到这与文档中“可为 0、90、180、270”的描述一致可以直接与display-metrics-changed事件配合使用。所有几何字段bounds、size、workArea等都直接透传自display::Display其单位是 DIP唯一使用物理像素的字段是nativeOrigin以及maximumCursorSize这也是 X11 环境下把 DIP 布局换算回真实屏幕像素的关键桥梁。DIP 与物理像素正确理解 bounds 和 workAreascreen 模块文档 明确了两种坐标体系这是使用Display前必须建立的概念物理屏幕点physical screen points显示器上的原始硬件像素DIPdevice-independent pixel设备无关像素按显示器 DPI 缩放的虚拟点。Display上的bounds、size、workArea、workAreaSize全部以 DIP 计。典型场景是高分屏一台 4K 显示器在 2 倍缩放下bounds.width约为 1920 而非 3840此时scaleFactor为 2。若你拿到的是原生像素例如来自maximumCursorSize或某些平台 API需要乘/除以scaleFactor才能与 DIP 体系对齐。screen 模块还提供显式的坐标换算方法跨显示器换算时尤其有用screen.screenToDipPoint(point)/screen.dipToScreenPoint(point)Windows、Linux 可用Wayland 暂不支持调用会原样返回传入点screen.screenToDipRect(window, rect)/screen.dipToScreenRect(window, rect)仅 Windows 可用DPI 缩放以window所在显示器为基准window传null时以rect最近的显示器为基准。对应的 C 实现见 electron_api_screen.ccWindows 上通过display::win::GetScreenWin()完成 DIP/像素互转window参数被解析为该窗口的 HWND 后传给 Chromium 的ScreenToDIPRect/DIPToScreenRect。实战用 Display 做多显示器窗口布局让窗口铺满主显示器工作区官方 fiddle 示例docs/fiddles/screen/演示了最典型的用法用主显示器的workAreaSize创建窗口保证窗口不会遮挡任务栏/Dockconst { app, BrowserWindow, screen } require(electron/main) let mainWindow null app.whenReady().then(() { // 创建铺满屏幕可用工作区的窗口 const primaryDisplay screen.getPrimaryDisplay() const { width, height } primaryDisplay.workAreaSize mainWindow new BrowserWindow({ width, height }) mainWindow.loadURL(https://electronjs.org) })把窗口放到外接显示器上screen 文档 中另一个示例用bounds的偏移量识别外接屏主显示器的bounds.x与bounds.y通常为 0任何非零原点即可认为是一块扩展屏const { app, BrowserWindow, screen } require(electron) let win app.whenReady().then(() { const displays screen.getAllDisplays() const externalDisplay displays.find((display) { return display.bounds.x ! 0 || display.bounds.y ! 0 }) if (externalDisplay) { win new BrowserWindow({ x: externalDisplay.bounds.x 50, y: externalDisplay.bounds.y 50 }) win.loadURL(https://github.com) } })两个值得注意的工程细节该“外接屏”判断法依赖用户把主屏放在逻辑坐标系原点若用户调整了主显示器此启发式可能失效。更稳健的做法是检查display.internal false或直接用screen.getDisplayNearestPoint(cursor)/getDisplayMatching(windowBounds)定位。new BrowserWindow({ x, y })中的x/y是 DIP 坐标与bounds的单位一致可直接相加使用无需自行换算scaleFactor。响应热插拔与分辨率变化Display是快照式的——每次调用 API 都会重新生成 JS 对象因此多显示器应用应订阅 screen 模块 的三个事件事件参数触发时机display-addednewDisplay(Display)新显示器接入display-removedoldDisplay(Display)显示器移除display-metrics-changeddisplay(Display),changedMetrics(string[])一个或多个指标发生变化changedMetrics取值为bounds、workArea、scaleFactor、rotation中变化的项例如监听缩放变化以重排窗口const { screen } require(electron/main) screen.on(display-metrics-changed, (event, display, changedMetrics) { if (changedMetrics.includes(scaleFactor) || changedMetrics.includes(bounds)) { // 重新读取 display 并调整窗口布局 const { bounds, workArea } display } })从源码看changedMetrics数组是由一个位掩码解码出来的electron_api_screen.cc 中的MetricsToArray将DISPLAY_METRIC_BOUNDS、DISPLAY_METRIC_WORK_AREA、DISPLAY_METRIC_DEVICE_SCALE_FACTOR、DISPLAY_METRIC_ROTATION四个位依次映射为bounds、workArea、scaleFactor、rotation字符串与文档列出的取值一一对应。另外这三个事件的 JS 触发都是延迟投递的C 侧的OnDisplayAdded/OnDisplaysRemoved/OnDisplayMetricsChanged回调见 electron_api_screen.cc通过PostNonNestableTask把Emit排到任务队列稍后执行避免在 Chromium 显示器观察者回调的上下文中直接触发用户 JS 造成重入问题。已知限制与适用前提平台限定nativeOrigin仅在 X11 这类以像素坐标定位显示器的窗口系统上有意义screenToDipPoint/dipToScreenPoint在 Wayland 上不支持原样返回screenToDipRect/dipToScreenRect仅 Windows 可用getCursorScreenPoint在 Wayland 上返回空点源码中x11_util::IsWayland()分支直接返回{}见 electron_api_screen.cc。渲染进程命名冲突window.screen是保留的 DOM 属性渲染进程中let { screen } require(electron)不可用官方建议在主进程使用该模块或从electron/main引入。id的特殊值-1无效/未知与-10统一桌面的虚拟显示器是文档明确约定的保留值做显示器缓存或匹配逻辑时应跳过它们。headless 环境无显示器系统上可能只有一个假Display且关闭阶段各查询方法会回退到默认显示对象GetFallbackDisplay这解释了为什么这些方法在异常时机调用也不会返回空。小结Display对象是 Electron 多显示器能力的基本单元bounds/workArea/size提供 DIP 几何信息用于窗口布局scaleFactor/rotation支撑高 DPI 与旋转适配internal/id/detected帮助区分真实内外屏与虚拟屏display-metrics-changed事件则让应用能实时响应屏幕拓扑变化。其背后是display::Display到 V8 字典的声明式转换gfx_converter.cc与 Chromiumdisplay::Screen观察者机制electron_api_screen.h阅读这几处源码即可把文档中的每个字段追溯到 Chromium 的具体取值来源。【免费下载链接】electron:electron: Build cross-platform desktop apps with JavaScript, HTML, and CSS项目地址: https://gitcode.com/GitHub_Trending/el/electron创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考