【Electron Playground 系列】視窗篇

作者：Kurosaki

本文主要講解Electron 視窗的 API 和一些在開發之中遇到的問題，

官方檔案 雖然比較全面，但是要想開發一個商用級別的桌面應用必須對整個 Electron API  有較深的了解，才能應對各種需求，

1. 創建視窗

通過BrowserWindow，來 創建 或者 管理 新的瀏覽器視窗，每個瀏覽器視窗都有一個行程來管理，

1.1. 簡單創建視窗

const { BrowserWindow } = require('electron');
const win = new BrowserWindow();
win.loadURL('https://github.com');

效果如下：

1.1.2. 優化

問題：electron 的 BrowserWindow 模塊在創建時，如果沒有配置 show:false，在創建之時就會顯示出來，且默認的背景是白色；然后視窗請求 HTML，會出現視覺閃爍，

解決

const { BrowserWindow } = require('electron');
const win = new BrowserWindow({ show:false });

win.loadURL('https://github.com');

win.on('ready-to-show',()=>{
    win.show();
})

兩者對比有很大的區別

1.2. 管理視窗

所謂的管理視窗，相當于主行程可以干預視窗多少，

• 視窗的路由跳轉
• 視窗打開新的視窗
• 視窗大小、位置等
• 視窗的顯示
• 視窗型別（無邊框視窗、父子視窗）
• 視窗內 JavaScript 的 node 權限，預加載腳本等
• ....

這些個方法都存在于BrowserWindow模塊中，

1.2.1. 管理應用創建的視窗

BrowserWindow模塊在創建視窗時，會回傳 視窗實體，這些 **視窗實體 **上有許多功能方法，我們利用這些方法，管理控制這個視窗，

在這里使用Map物件來存盤這些 視窗實體，

const BrowserWindowsMap = new Map<number, BrowserWindow>()
let mainWindowId: number;

const browserWindows = new BrowserWindow({ show:false })
browserWindows.loadURL('https://github.com')
browserWindows.once('ready-to-show', () => {
  browserWindows.show()
})
BrowserWindowsMap.set(browserWindow.id, browserWindow)
mainWindowId = browserWindow.id  // 記錄當前視窗為主視窗

視窗被關閉，得把Map中的實體洗掉，

browserWindow.on('closed', () => {
  BrowserWindowsMap?.delete(browserWindowID)
})

1.2.2. 管理用戶創建的視窗

主行程可以控制視窗許多行為，這些行為會在后續文章一一列舉；以下以主行程控制視窗建立新視窗的行為為例，

使用new-window監聽新視窗創建

// 創建視窗監聽
browserWindow.webContents.on('new-window', (event, url, frameName, disposition) => {
  /** @params {string} disposition
  *  new-window : window.open呼叫
  *  background-tab: command+click
  *  foreground-tab: 右鍵點擊新標簽打開或點擊a標簽target _blank打開
  * /
})

注：關于disposition欄位的解釋，移步electron檔案、electron原始碼、chrome 原始碼

擴展new-window

經過實驗，并不是所有新視窗的建立， new-window 都能捕捉到的，

以下方式打開的視窗可以被new-window事件捕捉到

window.open('https://github.com')

<a href='https://github.com' target='__blank'>鏈接</a>

**
渲染行程中使用BrowserWindow創建新視窗，不會被 new-window事件捕捉到
**

const { BrowserWindow } = require('electron').remote
const win = new BrowserWindow()
win.loadURL('https://github.com')

_渲染行程訪問 __remote_ _，主行程需配置enableRemoteModule:true _
使用這種方式同樣可以打開一個新的視窗，但是主行程的new-window捕捉不到，

應用new-window
new-window 控制著視窗新視窗的創建，我們利用這點，可以做到很多事情；比如鏈接校驗、瀏覽器打開鏈接等等，默認瀏覽器打開鏈接代碼如下：

import { shell } from 'electron'
function openExternal(url: string) {
  const HTTP_REGEXP = /^https?:\/\//
  // 非http協議不打開，防止出現自定義協議等導致的安全問題
  if (!HTTP_REGEXP) {
    return false
  }
  try {
    await shell.openExternal(url, options)
    return true
  } catch (error) {
    console.error('open external error: ', error)
    return false
  }
}
// 創建視窗監聽
browserWindow.webContents.on('new-window', (event, url, frameName, disposition) => {
  if (disposition === 'foreground-tab') {
      // 阻止滑鼠點擊鏈接
      event.preventDefault()
      openExternal(url)
  }
})

_關于 __shell_ 模塊，可以查看官網 https://www.electronjs.org/docs/api/shell
_

1.3. 關閉視窗

**close** **事件和 ****closed** 事件
close 事件在視窗將要關閉時之前觸發，但是在 DOM 的 beforeunload 和 unload 事件之前觸發，

// 視窗注冊close事件
win.on('close',(event)=>{
	event.preventDefault()  // 阻止視窗關閉
})

closed 事件在視窗關閉后出觸發，但是此時的視窗已經被關閉了，無法通過 event.preventDefault() 來阻止視窗關閉，

win.on('closed', handler)

主行程能夠關閉視窗的 API 有很多，但都有各自的利弊，

1.3.1. win.close()

關于這個 API 的利弊

1. 如果當前視窗實體注冊并阻止close事件，將不會關閉頁面，而且也會 阻止計算機關閉（必須手動強制退出）；
2. 關閉頁面的服務，如websocket，下次打開視窗，視窗中的頁面會 重新渲染；
3. 通過這個API觸發的close事件在 unload 和 beforeunload之前觸發，通過這點可以實作 關閉時觸發彈窗；

完整代碼在github：electron-playground

4. 會被closed事件捕捉到，

1.3.2. win.destroy()

1. 強制退出，無視close事件（即：無法通過event.preventDefault()來阻止）；
2. 關閉頁面，以及頁面內的服務，下次打開視窗，視窗中的頁面會重新渲染；
3. 會被closed事件捕捉到，

1.3.3. win.hide()

這個隱藏視窗，

1. 隱藏視窗，會觸發hide和blur事件，同樣也是可以通過event.preventDefault()來阻止
2. 只是隱藏視窗，通過win.show()，可以將視窗顯現，并且會保持原來的視窗，里面的服務也不會掛斷

2. 主視窗隱藏和恢復

2.1. 主視窗

2.1.1. 為什么需要 主視窗?

一個應用存在著許多的視窗，需要一個視窗作為 主視窗，如果該視窗關閉，則意味著整個應用被關閉，
場景：在應用只有一個頁面的時，用戶點擊關閉按鈕，不想讓整個應用關閉，而是隱藏；
例如：其他的APP，像微信，QQ等桌面端，

利用上文中提到的關閉視窗的 API ,我們實作一個主視窗的隱藏和恢復，

改造一下 close 事件

let mainWindowId: number // 用于標記主視窗id

const browserWindow = new BrowserWindow()

// 記錄下主視窗id
if (!mainWindowId) {
  mainWindowId = browserWindow.id
}

browserWindow.on('close', event => {
  // 如果關閉的是主視窗，阻止
  if (browserWindow.id === mainWindowId) {
    event.preventDefault()
    browserWindow.hide()
  }
})

2.1.2. 恢復主視窗顯示

能隱藏，就能恢復，

const mainWindow = BrowserWindowsMap.get(mainWindowId)
if (mainWindow) {
  mainWindow.restore()
  mainWindow.show()
}

**mainWindow.show()** 方法：功能如其名，就是“show出視窗”，
_為什么要是有 __mainWindow.restore()_ ？
_windows_ _下如果 __hide_ _之后不呼叫 __show_ _方法而是只呼叫 __restore_ 方法就會導致頁面掛住不能用

2.1.3. 強制關閉主視窗

有些場景下，可能需要的強制退出，附上代碼：

const mainWindow = BrowserWindowsMap.get(mainWindowId)
if (mainWindow) {
  mainWindowId = -1
  mainWindow.close()
}

存在的問題

我們改變了 Electron 視窗的既定行為，就會有許多場景下會有問題

問題一：因為阻止了 close 事件，導致 關機 時無法關閉 主視窗，可以使用如下代碼

app.on('before-quit', () => {
    closeMainWindow()
})

在 macOS Linux Windows 下都可以，

問題二：為避免啟動 多個應用

app.on('second-instance', () => {
  const mainWindow = BrowserWindowsMap.get(mainWindowId)
  if (mainWindow) {
    mainWindow.restore()
    mainWindow.show()
  }
})

在 macOS Linux Windows 下都可以

問題三：首次啟動應用程式、嘗試在應用程式已運行時或單擊 應用程式 的 塢站 或 任務欄圖示 時重新激活它

app.on('activate', () => {
  if (mainWindow) {
    mainWindow.restore()
    mainWindow.show()
  }
})

只應用于macOS 下

問題四： 雙擊托盤圖示 打開APP

tray.on('double-click', () => {
  if (mainWindow) {
    mainWindow.restore()
    mainWindow.show()
  }
})

這樣每個環節的代碼都有，即可實作，具體代碼可參見鏈接

3. 視窗的聚焦和失焦

3.1. 聚焦

3.1.1. 創建視窗時配置

const { BrowserWindow } = require('electron');
const win = new BrowserWindow();
win.loadURL('https://github.com')

focusable:true  視窗便可聚焦，便可以使用聚焦的 API 
focusable:false 在 Windows 中設定 focusable: false 也意味著設定了skipTaskbar: true. 在 Linux 中設定 focusable: false 時視窗停止與 wm 互動, 并且視窗將始終置頂；

以下討論的情況僅為focusable:true情況下

const { BrowserWindow } = require('electron');
const win = new BrowserWindow() // focusable:true 為默認配置

羅列了一下 API

3.1.2. 關于聚焦的API

3.1.3. 其他API副作用和聚焦有關的：

3.2. 失焦

3.2.1. 關于失焦的api

3.2.2. 其他api副作用和失焦有關的：

4. 視窗型別

4.1. 無邊框視窗

4.1.1. 描述

無邊框視窗是不帶外殼（包括視窗邊框、工具列等），只含有網頁內容的視窗

4.1.2. 實作

Windows macOS Linux

const { BrowserWindow } = require('electron')
let win = new BrowserWindow({ width: 800, height: 600, frame: false })
win.show()

在macOS下，還有不同的實作方式，官方檔案

4.1.3. macOS 下獨有的無邊框

• 配置titleBarStyle: 'hidden'

回傳一個隱藏標題欄的全尺寸內容視窗，在左上角仍然有標準的視窗控制按鈕（俗稱“紅綠燈”）

// 創建一個無邊框的視窗
const { BrowserWindow } = require('electron')
let win = new BrowserWindow({ titleBarStyle: 'hidden' })
win.show()

效果如下：

• 配置titleBarStyle: 'hiddenInset'

回傳一個另一種隱藏了標題欄的視窗，其中控制按鈕到視窗邊框的距離更大，

// 創建一個無邊框的視窗
const { BrowserWindow } = require('electron')
let win = new BrowserWindow({ titleBarStyle: 'hiddenInset' })
win.show()

效果如下：

配置titleBarStyle: 'customButtonsOnHover'

效果如下：

4.1.4. 視窗頂部無法拖拽的問題

雖然無邊框視窗，很美觀，可以自定義title；但是改變了Electron視窗頂部的默認行為，就需要使用代碼來兼容它，實作其原來承擔的功能，

出現上述情況，是因為在默認情況下, 無邊框視窗是不可拖拽的， 應用程式需要在 CSS 中指定 -webkit-app-region: drag 來告訴 Electron 哪些區域是可拖拽的（如作業系統的標準標題欄），在可拖拽區域內部使用 -webkit-app-region: no-drag 則可以將其中部磁區域排除， 請注意, 當前只支持矩形形狀，完整檔案

使用-webkit-app-region: drag 來實作拖拽，但是會導致內部的click事件失效，這個時候可以將需要click元素設定為-webkit-app-region: no-drag，具體的細節 Electron 的issues

為了不影響視窗內的業務代碼，這里拖拽的代碼，應該在preload觸發，

preload 代碼運行，在視窗代碼運行之前

核心代碼：

// 在頂部插入一個可以移動的dom
function initTopDrag() {
  const topDiv = document.createElement('div') // 創建節點
  topDiv.style.position = 'fixed' // 一直在頂部
  topDiv.style.top = '0'
  topDiv.style.left = '0'
  topDiv.style.height = '20px' // 頂部20px才可拖動
  topDiv.style.width = '100%' // 寬度100%
  topDiv.style.zIndex = '9999' // 懸浮于最外層
  topDiv.style.pointerEvents = 'none' // 用于點擊穿透
  // @ts-ignore
  topDiv.style['-webkit-user-select'] = 'none' // 禁止選擇文字
  // @ts-ignore
  topDiv.style['-webkit-app-region'] = 'drag' // 拖動
  document.body.appendChild(topDiv) // 添加節點
}

window.addEventListener('DOMContentLoaded', function onDOMContentLoaded() {
    initTopDrag()
})

在創建視窗時參考 preload 即可

const path = require('path')
const { BrowserWindow } = require('electron')

const BaseWebPreferences = {
  nodeIntegration: true,
  preload: path.resolve(__dirname, './windowType.js'), // 這里參考preload.js 路徑
}

// 主視窗代碼
const win = new BrowserWindow({ webPreferences: BaseWebPreferences, frame: false, titleBarStyle: 'hiddenInset' })
win.loadURL('https://github.com')

便可實作視窗頂部拖拽

_tips: 如果視窗打開了 __devtools_ ，視窗也是可以拖拽的，只不過這個拖拽體驗不好

4.2. 父子視窗

所謂的父子視窗，就是子視窗永遠在父視窗之上，只要子視窗存在，哪怕位置不在父視窗上方，都是無法操作父視窗

const { BrowserWindow } = require('electron')

let top = new BrowserWindow()
let child = new BrowserWindow({ parent: top })
child.show()
top.show()

在 視窗之間通信 章節中介紹到父子視窗之間的通信；通過 getParentWindow 拿到父視窗的 類BrowserWindowProxy，通過 win.postMessage(message,targetOrigin) 實作通信

4.3. 模態視窗

模態視窗也是一種父子視窗，只不過展示會有不同

const { BrowserWindow } = require('electron')

let top = new BrowserWindow()
let child = new BrowserWindow({ parent: top, modal: true, show: false })
child.loadURL('https://github.com')
child.once('ready-to-show', () => {
  child.show()
})

5. 視窗之間的通信

實作視窗通信必須不影響視窗內的業務代碼， jdk 等的注入

5.1. 主行程干預方式

主行程是可以干預渲染行程生成新的視窗的，只需要在創建視窗時，webContents 監聽 new-window

import path from 'path'
import { PRELOAD_FILE } from 'app/config'
import { browserWindow } from 'electron';

const BaseWebPreferences: Electron.BrowserWindowConstructorOptions['webPreferences'] = {
  nodeIntegration: true,
  webSecurity: false,
  preload: path.resolve(__dirname, PRELOAD_FILE),
}


// 創建視窗監聽
browserWindow.webContents.on('new-window', (event, url, frameName, disposition) => {
    event.preventDefault()
    // 在通過BrowserWindow創建視窗
    const win = new BrowserWindow({ 
      show:false, 
      webPreferences: {
        ...BaseWebPreferences,
        additionalArguments:[`--parentWindow=${browserWindow.id}`] // 把父視窗的id傳過去
      } 
    });
    win.loadURl(url);
    win.once('ready-to-show',()=>{
        win.show()
    })
})

在 preload.js  檔案window.process.argv，便能拿到父視窗的id，window.process.argv是一個字串陣列，可以使用yargs來決議

preload.js  代碼

import { argv } from 'yargs'
console.log(argv);

拿到了父視窗的 id ，封裝一下通信代碼，掛載到 window 上

/**
 * 這個是用于視窗通信例子的preload，
 * preload執行順序在視窗js執行順序之前
 */
import { ipcRenderer, remote } from 'electron'
const { argv } = require('yargs')

const { BrowserWindow } = remote

// 父視窗監聽子視窗事件
ipcRenderer.on('communication-to-parent', (event, msg) => {
  alert(msg)
})

const { parentWindowId } = argv
if (parentWindowId !== 'undefined') {
  const parentWindow = BrowserWindow.fromId(parentWindowId as number)
  // 掛載到window
  // @ts-ignore
  window.send = (params: any) => {
    parentWindow.webContents.send('communication-to-parent', params)
  }
}

應用一下試試看：

這種方法可以實作通信，但是太麻煩了，

5.2. 父子視窗通信

和主行程干預，通過ipc通信方式差不多，只是利用父子視窗這點，不用通過additionalArguments傳遞父視窗id，在子視窗通過window.parent，就可以拿到父視窗

browserWindow.webContents.on('new-window', (event, url, frameName, disposition) => {
    event.preventDefault()
      
    // 在通過BrowserWindow創建視窗
    const win = new BrowserWindow({ 
        show:false, 
        webPreferences:BaseWebPreferences,
        parent:browserWindow // 添加父視窗
      });
    win.loadURl(url);
    win.once('ready-to-show',()=>{
        win.show()
    })
    
})

弊端：子視窗永遠在父視窗之上，

const path = require('path')
const { BrowserWindow } = require('electron')

const BaseWebPreferences = {
  // // 集成node
  nodeIntegration: true,
  // // 禁用同源策略
  // webSecurity: false,
  // 預加載腳本 通過絕對地址注入
  preload: path.resolve(__dirname, './communication2.js'),
}

// 主視窗代碼
const parent = new BrowserWindow({ webPreferences: BaseWebPreferences, left: 100, top: 0 })
parent.loadURL(
  'file:///' + path.resolve(__dirname, '../playground/index.html#/demo/communication-part2/main'),
)
parent.webContents.on('new-window', (event, url, frameName, disposition) => {
  // 阻止默認事件
  event.preventDefault()
  // 在通過BrowserWindow創建視窗
  // 子視窗代碼
  const son = new BrowserWindow({
    webPreferences: BaseWebPreferences,
    parent,
    width: 400,
    height: 400,
    alwaysOnTop: false,
  })
  // son.webContents.openDevTools();
  son.loadURL(
    'file:///' +
      path.resolve(__dirname, '../playground/index.html#/demo/communication-part2/client'),
  )
})

preload.js

import { remote, ipcRenderer } from 'electron'

// 父視窗監聽子視窗事件
ipcRenderer.on('communication-to-parent', (event, msg) => {
  alert(msg)
})

const parentWindow = remote.getCurrentWindow().getParentWindow()
// @ts-ignore
window.sendToParent = (params: any) =>
  parentWindow.webContents.send('communication-to-parent', params)

但是必須得是父子視窗，有弊端，

5.3. 使用window.open

終極方法

在 web 端，使用 window.open  會回傳一個 windowObjectReference ，通過這個方法可以實作 postMessage ；但是在 Electron 端，把 window.open 方法重新定義了；使用 window.open 創建一個新視窗時會回傳一個 BrowserWindowProxy物件，并提供一個有限功能的子視窗.
MDN檔案 Electron檔案

const  BrowserWindowProxy = window.open('https://github.com', '_blank', 'nodeIntegration=no')
BrowserWindowProxy.postMessage(message, targetOrigin)

代碼精簡，且需要的功能，即符合 BrowserWindow(options) 中 options 配置的，都可以使用 window.open 配置，

6. 全屏、最大化、最小化、恢復

6.1. 全屏

6.1.1. 創建時進入全屏

配置new BrowserWindow({ fullscreen:true })

const { BrowserWindow } = require('electron')
const win = new BrowserWindow({ fullscreen:true,fullscreenable:true })
win.loadURL('https://github.com')

6.1.2. 使用API進入全屏

確保當前視窗的fullscreenable:true，以下API才能使用

1. win.setFullScreen(flag)，設定全屏狀態；
2. win.setSimpleFullScreen(flag)，macOS下獨有，設定簡單全屏，

6.1.3. 全屏狀態的獲取

1. win.fullScreen，來判斷當前視窗是否全屏；
2. win.isFullScreen()，macOS獨有；
3. win.isSimpleFullScreen()，macOS獨有，

6.1.4. 全屏事件的監聽

1. rezise 調整視窗大小后觸發;
2. enter-full-screen 視窗進入全屏狀態時觸發;
3. leave-full-screen 視窗離開全屏狀態時觸發;
4. enter-html-full-screen 視窗進入由HTML API 觸發的全屏狀態時觸發;
5. leave-html-full-screen 視窗離開由HTML API觸發的全屏狀態時觸發，

6.1.5. HTML API無法和視窗聯動問題

const path = require('path')
const { BrowserWindow } = require('electron')
const BaseWebPreferences = { 
    nodeIntegration: true,
    preload: path.resolve(__dirname, './fullScreen.js'), 
};
const win = new BrowserWindow({ webPreferences: BaseWebPreferences })
win.loadURL('file:///' + path.resolve(__dirname, '../playground/index.html#/demo/full-screen'))

使用按鈕全屏和退出全屏是可以的，但是先點擊左上角??全屏，再使用按鈕退出全屏，是不行的，因為無法知道當前的狀態是全屏，還是不是全屏，

解決辦法：，將win.setFullScreen(flag)方法掛載到視窗的window上
加載這樣一段preload.js代碼即可

import { remote } from 'electron'

const setFullScreen = remote.getCurrentWindow().setFullScreen
const isFullScreen = remote.getCurrentWindow().isFullScreen

window.setFullScreen = setFullScreen
window.isFullScreen = isFullScreen

_ setFullScreen檔案 https://www.electronjs.org/docs/api/browser-window#winsetfullscreenflag isFullScreen 檔案_https://www.electronjs.org/docs/api/browser-window#winisfullscreen

6.2. 最大化、最小化

6.2.1. 創建視窗配置

完整API檔案

const { BrowserWindow } = require('electron')
const win = new BrowserWindow({ minWidth:300,minHeight:300,maxWidth:500,maxHeight:500,width:600,height:600 })
win.loadURL('https://github.com')

當使用 minWidth/maxWidth/minHeight/maxHeight 設定最小或最大視窗大小時, 它只限制用戶， 它不會阻止您將不符合大小限制的值傳遞給 setBounds/setSize 或 BrowserWindow 的建構式，

6.2.2. 相關事件

6.2.3. 相關狀態API

1. win.minimizable 視窗是否可以最小化
2. win.maximizable 視窗是否可以最大化
3. win.isMaximized() 是否最大化
4. win.isMinimized() 是否最小化

6.2.4. 控制API

1. win.maximize() 使視窗最大化
2. win.unmaximize() 退出最大化
3. win.minimize() 使視窗最小化
4. win.unminimize() 退出最小化

6.3. 視窗恢復

win.restore() 將視窗從最小化狀態恢復到以前的狀態，在前面的例子 主視窗隱藏和恢復也有用到這個api

7. 視窗各事件觸發順序

7.1. 視窗加載時

BrowserWindow實體：即 new BrowserWindow() 回傳的實體物件
webContents： 即 BrowserWindow 實體中的 webContents 物件
webPreferences: 即 new BrowserWindow(options) 中 options 的 webPreferences 配置物件

從上到下，依次執行

7.2. 視窗加載完畢，用戶觸發事件（不包括resize和move）

7.3. 用戶移動視窗

1. 移動視窗之前 will-move；
2. 移動視窗中 move；
3. 移動之后 moved；

7.4. 用戶改變視窗大小

1. 改變之前 will-resize；
2. 改變之后 resize

7.5. 視窗的內容例外事件（webContent事件）

7.6. 視窗關閉（包括意外關閉）

• 關閉之前：觸發主行程中注冊的 close  事件
• 視窗內的 JavaScript  執行 window.onbeforeunload
• 視窗內的 JavaScript  執行 window.onunload
• 關閉之后：觸發主行程中注冊的 closed  事件

對 Electron 感興趣？請關注我們的開源專案 Electron Playground，帶你極速上手 Electron，

我們每周五會精選一些有意思的文章和訊息和大家分享，來掘金關注我們的 曉前端周刊，

我們是好未來 · 曉黑板前端技術團隊，
我們會經常與大家分享最新最酷的行業技術知識，
歡迎來 知乎、掘金、Segmentfault、CSDN、簡書、開源中國、博客園 關注我們，

標籤：其他

上一篇：Taro 3.1 beta 發布: 開放式架構新增 4 端支持

下一篇：最近的總結：markdown、hr、em、后代選擇器