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 rectagular 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 rectagular 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(ignore) 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

忽略鼠标消息会使 Web 内容忽略鼠标移动，这意味着不会发出鼠标移动事件。在 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.