Skip to main content

自定义窗口交互

🌐 Custom Window Interactions

自定义可拖动区域​

🌐 Custom draggable regions

默认情况下，窗口是通过操作系统提供的标题栏拖动的。移除默认标题栏的应用需要使用 app-region CSS 属性来定义可以用于拖动窗口的特定区域。设置 app-region: drag 会将一个矩形区域标记为可拖动。

🌐 By default, windows are dragged using the title bar provided by the OS chrome. Apps that remove the default title bar need to use the app-region CSS property to define specific areas that can be used to drag the window. Setting app-region: drag marks a rectangular area as draggable.

需要注意的是，可拖动区域会忽略所有指针事件。例如，重叠在可拖动区域上的按钮元素在该重叠区域内不会触发鼠标点击或鼠标进入/退出事件。通过设置 app-region: no-drag 可以通过将一个矩形区域排除在可拖动区域之外来重新启用指针事件。

🌐 It is important to note that draggable areas ignore all pointer events. For example, a button element that overlaps a draggable region will not emit mouse clicks or mouse enter/exit events within that overlapping area. Setting app-region: no-drag reenables pointer events by excluding a rectangular area from a draggable region.

要让整个窗口可以拖动，你可以将 app-region: drag 添加到 body 的样式中：

🌐 To make the whole window draggable, you can add app-region: drag as body's style:

styles.css
body {
  app-region: drag;
}

请注意，如果你已经将整个窗口设置为可拖动，你还必须将按钮标记为不可拖动，否则用户将无法点击它们：

🌐 And note that if you have made the whole window draggable, you must also mark buttons as non-draggable, otherwise it would be impossible for users to click on them:

styles.css
button {
  app-region: no-drag;
}

如果你只是将自定义标题栏设置为可拖动，你还需要把标题栏中的所有按钮设置为不可拖动。

🌐 If you're only setting a custom title bar as draggable, you also need to make all buttons in title bar non-draggable.

提示：禁用文本选择​

🌐 Tip: disable text selection

在创建可拖动区域时，拖动行为可能会与文本选择冲突。例如，当你拖动标题栏时，可能会意外选中其文本内容。为防止这种情况，你需要在可拖动区域内禁用文本选择，方法如下：

🌐 When creating a draggable region, the dragging behavior may conflict with text selection. For example, when you drag the title bar, you may accidentally select its text contents. To prevent this, you need to disable text selection within a draggable area like this:

.titlebar {
  user-select: none;
  app-region: drag;
}

提示：禁用右键菜单​

🌐 Tip: disable context menus

在某些平台上，可拖动区域将被视为非客户区框架，因此当你右键点击它时，系统菜单会弹出。为了让上下文菜单在所有平台上都能正常工作，你不应在可拖动区域使用自定义上下文菜单。

🌐 On some platforms, the draggable area will be treated as a non-client frame, so when you right click on it, a system menu will pop up. To make the context menu behave correctly on all platforms, you should never use a custom context menu on draggable areas.

点击窗口​

🌐 Click-through windows

要创建一个可点击穿透的窗口，即让窗口忽略所有鼠标事件，你可以调用 win.setIgnoreMouseEvents(忽略) API：

🌐 To create a click-through window, i.e. making the window ignore all mouse events, you can call the win.setIgnoreMouseEvents(ignore) API:

main.js
const { BrowserWindow } = require('electron')

const win = new BrowserWindow()
win.setIgnoreMouseEvents(true)

转发鼠标事件 macOS Windows​

🌐 Forward mouse events macOS Windows

忽略鼠标消息会使网页内容对鼠标移动无感，这意味着鼠标移动事件将不会被触发。在 Windows 和 macOS 上，可以使用一个可选参数将鼠标移动消息转发到网页，从而允许触发诸如 mouseleave 的事件：

🌐 Ignoring mouse messages makes the web contents oblivious to mouse movement, meaning that mouse movement events will not be emitted. On Windows and macOS, an optional parameter can be used to forward mouse move messages to the web page, allowing events such as mouseleave to be emitted:

main.js
const { BrowserWindow, ipcMain } = require('electron')

const path = require('node:path')

const win = new BrowserWindow({
  webPreferences: {
    preload: path.join(__dirname, 'preload.js')
  }
})

ipcMain.on('set-ignore-mouse-events', (event, ignore, options) => {
  const win = BrowserWindow.fromWebContents(event.sender)
  win.setIgnoreMouseEvents(ignore, options)
})
preload.js
window.addEventListener('DOMContentLoaded', () => {
  const el = document.getElementById('clickThroughElement')
  el.addEventListener('mouseenter', () => {
    ipcRenderer.send('set-ignore-mouse-events', true, { forward: true })
  })
  el.addEventListener('mouseleave', () => {
    ipcRenderer.send('set-ignore-mouse-events', false)
  })
})

当鼠标悬停在 #clickThroughElement 元素上时，这会使网页可点击，而在元素外则恢复正常。

🌐 This makes the web page click-through when over the #clickThroughElement element, and returns to normal outside it.