快捷導(dǎo)航

Electron無邊框窗口拖拽以及最大化和還原窗口示例詳解

更新時(shí)間：2026年03月30日 09:13:59 作者：靜待雨落

在Electron應(yīng)用開發(fā)中,窗口拖拽是自定義無邊框窗口的核心功能,這篇文章主要介紹了Electron無邊框窗口拖拽以及最大化和還原窗口的相關(guān)資料,文中通過代碼介紹的非常詳細(xì),需要的朋友可以參考下

什么是無邊框窗口

設(shè)置了frame: false,新建的窗口就沒有邊框了！

mainWindow = new BrowserWindow({
    width: 800,
    height: 600,
    frame: false, // 無邊框核心配置
    webPreferences: {
      nodeIntegration: true, // 啟用 Node 集成，允許渲染進(jìn)程調(diào)用 Electron API
      contextIsolation: false // 關(guān)閉上下文隔離，簡化調(diào)用
    }
  });

無邊框窗口如何拖拽

Electron無邊框窗口默認(rèn)無法拖拽，需在 HTML 中給可拖拽區(qū)域添加 CSS 樣式 -webkit-app-region: drag;（注意：按鈕等可點(diǎn)擊元素需設(shè)置 webkit-app-region: no-drag; 避免無法點(diǎn)擊）。

// 可拖拽部分
.header {
    -webkit-app-region: drag;
}
// 不需要拖拽部分
.main {
    -webkit-app-region: no-drag;
}

如何最大化窗口和還原

Electron提供了窗口的最大化和還原窗口的api

    // 最大化窗口
    mainWindow.maximize()
    // 還原窗口
    mainWindow.unmaximize();

但是！在無邊框窗口中使用mainWindow.maximize()最大化窗口并不能被還原，此時(shí)就需要其他方法來實(shí)現(xiàn)此功能。

首先判斷是否處于全屏狀態(tài)

// 兼容所有瀏覽器的全屏狀態(tài)判斷
function isDocumentFullScreen() {
  return !!document.fullscreenElement || 
         !!document.webkitFullscreenElement || // 對應(yīng) webkitIsFullScreen 的元素版
         !!document.mozFullScreenElement ||    // 對應(yīng) mozFullScreen 的元素版
         !!document.msFullscreenElement;
}

你在使用 TypeScript 時(shí)，調(diào)用 document.webkitFullscreenElement、document.mozFullScreenElement 等廠商前綴全屏 API 出現(xiàn)類型錯(cuò)誤，這是因?yàn)?TypeScript 的內(nèi)置 DOM 類型定義中僅包含標(biāo)準(zhǔn) API（如 document.fullscreenElement），未包含這些非標(biāo)準(zhǔn)的廠商前綴屬性，以下是幾種完整的解決方案，按推薦優(yōu)先級(jí)排序：

一、方案 1：類型斷言（Type Assertion）—— 快速解決單個(gè)屬性報(bào)錯(cuò)

這是最簡潔的臨時(shí)解決方案，通過類型斷言告訴 TypeScript 「該屬性存在于 document 上」，忽略類型檢查報(bào)錯(cuò)。

實(shí)現(xiàn)代碼

// 兼容所有瀏覽器的全屏狀態(tài)判斷（TS 兼容寫法）
function isDocumentFullScreen(): boolean {
  // 對 document 進(jìn)行類型斷言，指定為包含廠商前綴屬性的任意類型
  const doc = document as any;
  return !!doc.fullscreenElement || 
         !!doc.webkitFullscreenElement || 
         !!doc.mozFullScreenElement || 
         !!doc.msFullscreenElement;
}
// 或直接對單個(gè)屬性進(jìn)行斷言（更精準(zhǔn)）
function isDocumentFullScreen精準(zhǔn)版(): boolean {
  return !!document.fullscreenElement || 
         !!(document as { webkitFullscreenElement?: Element | null }).webkitFullscreenElement || 
         !!(document as { mozFullScreenElement?: Element | null }).mozFullScreenElement || 
         !!(document as { msFullscreenElement?: Element | null }).msFullscreenElement;
}

特點(diǎn)

優(yōu)點(diǎn)：快速便捷，無需額外配置，適合簡單場景或臨時(shí)調(diào)試。
缺點(diǎn)：缺乏類型提示，若屬性名拼寫錯(cuò)誤（如把 webkitFullscreenElement 寫成 webkitFullScreenElement），運(yùn)行時(shí)才會(huì)暴露問題。

二、方案 2：擴(kuò)展全局 DOM 類型（推薦）—— 長期優(yōu)雅解決

通過 TypeScript 的「全局類型擴(kuò)展」功能，為 Document 接口補(bǔ)充廠商前綴屬性的類型定義，既解決報(bào)錯(cuò)，又能獲得類型提示，是長期項(xiàng)目的最優(yōu)解。

步驟 1：創(chuàng)建類型聲明文件（如 global.d.ts）

在項(xiàng)目根目錄或 src 目錄下創(chuàng)建 .d.ts 后綴的類型聲明文件（TS 會(huì)自動(dòng)識(shí)別該類型文件，無需手動(dòng)引入）：

// global.d.ts
declare global {
  interface Document {
    // 補(bǔ)充 WebKit/Blink 內(nèi)核廠商前綴屬性
    webkitFullscreenElement?: Element | null;
    // 補(bǔ)充 Gecko 內(nèi)核廠商前綴屬性（注意：S 大寫，與標(biāo)準(zhǔn) API 有差異）
    mozFullScreenElement?: Element | null;
    // 補(bǔ)充 Trident 內(nèi)核廠商前綴屬性
    msFullscreenElement?: Element | null;
    // 可選：若需使用舊版布爾值屬性，也可補(bǔ)充對應(yīng)類型
    webkitIsFullScreen?: boolean;
    mozFullScreen?: boolean;
  }
}
// 必須導(dǎo)出空對象，標(biāo)識(shí)這是一個(gè)模塊
export {};

步驟 2：配置 tsconfig.json（確保類型文件被識(shí)別）

確保 tsconfig.json 中包含該類型文件的路徑（默認(rèn)情況下，"include" 會(huì)覆蓋 src 下所有 .ts/.d.ts 文件，若已配置可跳過）：

{
  "compilerOptions": {
    "target": "ES6",
    "module": "CommonJS",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "typeRoots": ["./node_modules/@types", "./src/types"] // 若類型文件放在 src/types 下，需配置此路徑
  },
  "include": ["src/**/*", "global.d.ts"] // 包含全局類型聲明文件
}

步驟 3：正常使用代碼（無報(bào)錯(cuò)且有類型提示）

// 此時(shí) TS 不會(huì)報(bào)錯(cuò)，且能自動(dòng)提示對應(yīng)屬性
function isDocumentFullScreen(): boolean {
  return !!document.fullscreenElement || 
         !!document.webkitFullscreenElement || 
         !!document.mozFullScreenElement || 
         !!document.msFullscreenElement;
}

特點(diǎn)

優(yōu)點(diǎn)：類型安全、有代碼提示，一勞永逸，適合長期維護(hù)的項(xiàng)目。
缺點(diǎn)：需要額外創(chuàng)建類型文件，初次配置略繁瑣。

補(bǔ)充說明

廠商前綴 API 已逐步被廢棄，若項(xiàng)目無需兼容老舊瀏覽器，推薦直接使用標(biāo)準(zhǔn) API document.fullscreenElement，無需額外處理類型問題。
若使用方案 2 后仍報(bào)錯(cuò)，可重啟 TS 語言服務(wù)（VS Code 中可按 Ctrl+Shift+P，輸入「TypeScript: Restart TS Server」）。
類型聲明文件中，屬性添加 ? 表示可選屬性（因?yàn)椴⒎撬袨g覽器都存在這些屬性），符合實(shí)際兼容場景。

進(jìn)入全屏

if (!isFull) { // 進(jìn)入全屏
    let element = document.documentElement;
    if (element.requestFullscreen) {
        element.requestFullscreen();
    } else if (element.msRequestFullscreen) {
        element.msRequestFullscreen();
    } else if (element.mozRequestFullScreen) {
        element.mozRequestFullScreen();
    } else if (element.webkitRequestFullscreen) {
        element.webkitRequestFullscreen();
    }
}

邏輯：先獲取頁面根元素 document.documentElement（即 <html> 標(biāo)簽，通常讓整個(gè)頁面進(jìn)入全屏），再優(yōu)先調(diào)用標(biāo)準(zhǔn) API，降級(jí)調(diào)用廠商前綴方法：
- element.requestFullscreen()：標(biāo)準(zhǔn)進(jìn)入全屏方法（需指定 “要全屏的元素”）。
- element.msRequestFullscreen()：IE / 舊版 Edge 的進(jìn)入全屏方法。
- element.mozRequestFullScreen()：Firefox 的進(jìn)入全屏方法（注意命名是 RequestFullScreen）。
- element.webkitRequestFullscreen()：Chrome/Safari 的進(jìn)入全屏方法。

退出全屏

if (isFull) {// 退出全屏
    if (document.exitFullscreen) {
        document.exitFullscreen();
    } else if (document.msExitFullscreen) {
        document.msExitFullscreen();
    } else if (document.mozCancelFullScreen) {
        document.mozCancelFullScreen();
    } else if (document.webkitExitFullscreen) {
        document.webkitExitFullscreen();
    }
}

邏輯：優(yōu)先調(diào)用標(biāo)準(zhǔn) API，若瀏覽器不支持，則降級(jí)調(diào)用對應(yīng)廠商前綴的 “退出全屏” 方法：
- document.exitFullscreen()：標(biāo)準(zhǔn)退出全屏方法。
- document.msExitFullscreen()：IE / 舊版 Edge 的退出全屏方法。
- document.mozCancelFullScreen()：Firefox 的退出全屏方法（注意命名是 CancelFullScreen）。
- document.webkitExitFullscreen()：Chrome/Safari 的退出全屏方法。