窗口状态保持

🌐 Window State Persistence

概述

🌐 Overview

窗口状态持久化可以让你的 Electron 应用自动保存和恢复窗口的位置、大小以及显示模式（比如最大化或全屏状态），即使应用重启也一样。

🌐 Window State Persistence allows your Electron application to automatically save and restore a window's position, size, and display modes (such as maximized or fullscreen states) across application restarts.

这个功能对那些用户经常调整大小、移动或最大化窗口，并希望在重新打开应用时窗口保持相同状态的应用特别有用。

🌐 This feature is particularly useful for applications where users frequently resize, move, or maximize windows and expect them to remain in the same state when reopening the app.

用法

🌐 Usage

基本用法

🌐 Basic usage

要启用窗口状态持久化，请在你的窗口构造函数选项中设置 windowStatePersistence: true，并为窗口提供一个唯一的 name。

🌐 To enable Window State Persistence, set windowStatePersistence: true in your window constructor options and provide a unique name for the window.

const { app, BrowserWindow } = require('electron')

function createWindow () {
  const win = new BrowserWindow({
    name: 'main-window',
    width: 800,
    height: 600,
    windowStatePersistence: true
  })

  win.loadFile('index.html')
}

app.whenReady().then(createWindow)

通过这种配置，Electron 会自动：

🌐 With this configuration, Electron will automatically:

在创建窗口时恢复其位置、大小和显示模式（如果存在之前的状态）
每当窗口状态改变时（位置、大小或显示模式），就保存它。
在成功恢复状态后触发一个 persisted-state-restored 事件。
让恢复的窗口状态适应多显示器设置，并自动显示变化。

note

窗口状态持久化要求窗口在构造函数选项中设置一个唯一的 name 属性。这个名称用作存储和检索窗口已保存状态的标识符。

选择性坚持

🌐 Selective persistence

你可以通过传入一个带有特定选项的对象来控制窗口状态的哪些方面会被保存：

🌐 You can control which aspects of the window state are persisted by passing an object with specific options:

const { app, BrowserWindow } = require('electron')

function createWindow () {
  const win = new BrowserWindow({
    name: 'main-window',
    width: 800,
    height: 600,
    windowStatePersistence: {
      bounds: true, // Save position and size (default: true)
      displayMode: false // Don't save maximized/fullscreen/kiosk state (default: true)
    }
  })

  win.loadFile('index.html')
}

app.whenReady().then(createWindow)

在这个例子中，窗口会记住它的位置和大小，但每次启动时都会以普通模式打开，即使上次关闭时是最大化或全屏状态。

🌐 In this example, the window will remember its position and size but will always start in normal mode, even if it was maximized or fullscreened when last closed.

清除持久状态

🌐 Clearing persisted state

你可以使用静态的 clearPersistedState 方法以编程方式清除特定窗口的已保存状态：

🌐 You can programmatically clear the saved state for a specific window using the static clearPersistedState method:

const { BrowserWindow } = require('electron')

// Clear saved state for a specific window
BrowserWindow.clearPersistedState('main-window')

// Now when you create a window with this name,
// it will use the default constructor options
const win = new BrowserWindow({
  name: 'main-window',
  width: 800,
  height: 600,
  windowStatePersistence: true
})

API参考

🌐 API reference

窗口状态持久化 API 在 BaseWindow 和 BrowserWindow 上都可用（因为 BrowserWindow 扩展了 BaseWindow），且使用方式完全一样。

🌐 The Window State Persistence APIs are available on both BaseWindow and BrowserWindow (since BrowserWindow extends BaseWindow) and work identically.

完整的 API 文档，请参见：

🌐 For complete API documentation, see:

概述​

用法​

基本用法​

选择性坚持​

清除持久状态​

API参考​

概述

用法

基本用法

选择性坚持

清除持久状态

API参考