Настройка окон

Модуль BrowserWindow является основой вашего приложения Electron, и он предоставляет множество API, которые могут изменить внешний вид и поведение окон браузера. В этом руководстве мы рассмотрим различные варианты настройки окон на macOS, Windows и Linux.

Создание бескромочных окон​

Бескромочное окно — это окно без рамки. Не путать с браузером Google Chrome, рамка окна относится к частям окна (например, панелям инструментов, элементам управления), которые не являются частью веб-страницы.

Для создания бескромочного окна необходимо установить frame в значение false в конструкторе BrowserWindow.

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

Применение пользовательских стилей панели заголовка macOS Windows​

Стили панели заголовка позволяют скрыть большую часть рамки окна BrowserWindow, сохраняя при этом встроенные системные элементы управления, и могут быть настроены с помощью параметра titleBarStyle в конструкторе BrowserWindow.

Применение стиля панели заголовка hidden приводит к скрытию панели заголовка и увеличению размера содержимого окна.

const { BrowserWindow } = require('electron')
const win = new BrowserWindow({ titleBarStyle: 'hidden' })

Управление элементами управления macOS​

На macOS применение стиля панели заголовка hidden все равно отобразит стандартные элементы управления окном («указатели») в верхнем левом углу.

Настройка внешнего вида элементов управления macOS​

Стиль панели заголовка customButtonsOnHover скроет элементы управления до тех пор, пока вы не наведете на них указатель мыши. Это полезно, если вы хотите создать пользовательские элементы управления в вашем HTML, но все же использовать родной интерфейс для управления окном.

const { BrowserWindow } = require('electron')
const win = new BrowserWindow({ titleBarStyle: 'customButtonsOnHover' })

Настройка расположения элементов управления macOS​

Для изменения расположения элементов управления окном есть два параметра настройки.

Применение стиля панели заголовка hiddenInset сдвинет вертикальный отступ элементов управления на фиксированное значение.

const { BrowserWindow } = require('electron')
const win = new BrowserWindow({ titleBarStyle: 'hiddenInset' })

Если вам нужен более точный контроль над позиционированием элементов управления, вы можете передать набор координат в параметр trafficLightPosition в конструкторе BrowserWindow.

const { BrowserWindow } = require('electron')
const win = new BrowserWindow({
  titleBarStyle: 'hidden',
  trafficLightPosition: { x: 10, y: 10 }
})

Показать и скрыть элементы управления программно macOS​

Вы также можете программно показывать и скрывать элементы управления из главного процесса. Параметр win.setWindowButtonVisibility заставляет элементы управления отображаться или скрываться в зависимости от значения его булевого параметра.

const { BrowserWindow } = require('electron')
const win = new BrowserWindow()
// hides the traffic lights
win.setWindowButtonVisibility(false)

Примечание: учитывая количество доступных API, существует множество способов достижения этой цели. Например, сочетание frame: false с win.setWindowButtonVisibility(true) даст тот же результат, что и установка titleBarStyle: 'hidden'.

Наложение элементов управления окном macOS Windows​

API Window Controls Overlay — это веб-стандарт, который позволяет веб-приложениям настраивать область панели заголовка при установке на рабочем столе. Electron предоставляет доступ к этому API через параметр конструктора BrowserWindow titleBarOverlay.

Этот параметр работает только при применении пользовательского стиля titlebarStyle на macOS или Windows. При включенном titleBarOverlay, элементы управления окном отображаются в своем стандартном расположении, и DOM-элементы не могут использовать область под этой областью.

Параметр titleBarOverlay принимает два различных формата значений.

Указание true на любой платформе приведет к области наложения с стандартными системными цветами:

// on macOS or Windows
const { BrowserWindow } = require('electron')
const win = new BrowserWindow({
  titleBarStyle: 'hidden',
  titleBarOverlay: true
})

В Windows вы также можете указать дополнительные параметры. Цвет наложения и символов можно задать, установив titleBarOverlay в объект и используя свойства color и symbolColor соответственно. Высота наложения также может быть указана с помощью свойства height.

Если опция цвета не указана, цвет по умолчанию будет системным цветом кнопок управления окном. Аналогично, если высота не указана, она будет по умолчанию.

// on Windows
const { BrowserWindow } = require('electron')
const win = new BrowserWindow({
  titleBarStyle: 'hidden',
  titleBarOverlay: {
    color: '#2f3241',
    symbolColor: '#74b1be',
    height: 60
  }
})

Примечание: после включения наложения панели заголовка в главном процессе вы можете получить значения цвета и размера наложения в рендерере, используя набор только для чтения JavaScript API и CSS переменные среды.

Ограничения​

• Прозрачные цвета в настоящее время не поддерживаются. Обновления по этому вопросу можно найти в PR #33567.

Создание прозрачных окон​

Установив параметр transparent в значение true, вы можете создать полностью прозрачное окно.

const { BrowserWindow } = require('electron')
const win = new BrowserWindow({ transparent: true })

Ограничения​

• Вы не можете нажимать через прозрачную область. Подробности см. в #1335.
• Прозрачные окна не изменяют размер. Установка resizable в значение true может привести к тому, что прозрачное окно перестанет работать на некоторых платформах.
• Фильтр CSS blur() применяется только к содержимому окна, поэтому нет способа применить эффект размытия к содержимому под окном (т.е. другим открытым на компьютере приложениям).
• Окно не будет прозрачным при открытии DevTools.
• В Windows:
  • Прозрачные окна не будут работать при отключенном DWM.
  • Прозрачные окна нельзя максимизировать с помощью системного меню Windows или двойным щелчком по панели заголовка. Объяснение этого можно найти в PR #28207.
• В macOS:
  • Теневой эффект родного окна не будет отображаться в прозрачном окне.

Создание кликабельных окон​

Для создания кликабельного окна, т.е. окна, которое игнорирует все события мыши, можно вызвать API win.setIgnoreMouseEvents(ignore):

const { BrowserWindow } = require('electron')
const win = new BrowserWindow()
win.setIgnoreMouseEvents(true)

Передача событий мыши macOS Windows​

Игнорирование сообщений мыши делает содержимое веб-страницы невосприимчивым к движению мыши, что означает, что события перемещения мыши не будут генерироваться. В Windows и macOS можно использовать необязательный параметр для перенаправления сообщений о перемещении мыши на веб-страницу, что позволяет генерировать такие события, как mouseleave:

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

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

ipcMain.on('set-ignore-mouse-events', (event, ...args) => {
  const win = BrowserWindow.fromWebContents(event.sender)
  win.setIgnoreMouseEvents(...args)
})

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, и возвращает её к обычному режиму за пределами этого элемента.

Настройка пользовательской области перетаскивания​

По умолчанию безрамочное окно не перетаскивается. Приложения должны указать -webkit-app-region: drag в CSS, чтобы указать Electron, какие области можно перетаскивать (например, стандартную строку заголовка ОС), и приложения также могут использовать -webkit-app-region: no-drag для исключения неперетаскиваемой области из перетаскиваемой области. Обратите внимание, что в настоящее время поддерживаются только прямоугольные формы.

Чтобы сделать всё окно перетаскиваемым, можно добавить -webkit-app-region: drag в качестве стиля body:

body {
  -webkit-app-region: drag;
}

И обратите внимание, что если вы сделали всё окно перетаскиваемым, вы также должны пометить кнопки как неперетаскиваемые, в противном случае пользователи не смогут на них нажать:

button {
  -webkit-app-region: no-drag;
}

Если вы настраиваете только строку заголовка для перетаскивания, вам также необходимо сделать все кнопки в строке заголовка неперетаскиваемыми.

Совет: отключение выделения текста​

При создании области перетаскивания поведение перетаскивания может конфликтовать с выделением текста. Например, при перетаскивании строки заголовка вы можете случайно выделить её содержимое. Чтобы предотвратить это, необходимо отключить выделение текста в области перетаскивания следующим образом:

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

Совет: отключение контекстных меню​

На некоторых платформах область перетаскивания будет обрабатываться как фрейм вне клиентской области, поэтому при нажатии правой кнопкой мыши на ней будет появляться системное меню. Чтобы обеспечить корректное поведение контекстного меню на всех платформах, вы никогда не должны использовать пользовательское контекстное меню в областях перетаскивания.