BrowserWindow

Создавайте и управляйте окнами браузера.

Процесс: Основной

Этот модуль нельзя использовать, пока не будет отправлено событие ready модуля app.

// In the main process.
const { BrowserWindow } = require('electron')

const win = new BrowserWindow({ width: 800, height: 600 })

// Load a remote URL
win.loadURL('https://github.com')

// Or load a local HTML file
win.loadFile('index.html')

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

Класс BrowserWindow предоставляет различные способы изменения внешнего вида и поведения окон вашего приложения. Более подробную информацию см. в руководстве Настройка окон.

Грамотное отображение окна​

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

Использование события ready-to-show​

При загрузке страницы событие ready-to-show будет отправлено, когда процесс рендеринга страницы впервые отобразит страницу, если окно еще не показано. Отображение окна после этого события не вызовет визуальной вспышки:

const { BrowserWindow } = require('electron')
const win = new BrowserWindow({ show: false })
win.once('ready-to-show', () => {
  win.show()
})

Это событие обычно отправляется после события did-finish-load, но для страниц с множеством удаленных ресурсов оно может быть отправлено до события did-finish-load.

Обратите внимание, что использование этого события предполагает, что рендерер будет считаться «видимым» и будет отрисовываться, даже если show равно false. Это событие никогда не будет отправлено, если вы используете paintWhenInitiallyHidden: false

Установка свойства backgroundColor​

Для сложного приложения событие ready-to-show может быть отправлено слишком поздно, из-за чего приложение будет казаться медленным. В этом случае рекомендуется отобразить окно сразу и использовать значение backgroundColor близкое к фоновому цвету вашего приложения:

const { BrowserWindow } = require('electron')

const win = new BrowserWindow({ backgroundColor: '#2e2c29' })
win.loadURL('https://github.com')

Обратите внимание, что даже для приложений, использующих событие ready-to-show, все равно рекомендуется установить backgroundColor, чтобы приложение чувствовалось более нативным.

Некоторые примеры допустимых значений backgroundColor включают:

const win = new BrowserWindow()
win.setBackgroundColor('hsl(230, 100%, 50%)')
win.setBackgroundColor('rgb(255, 145, 145)')
win.setBackgroundColor('#ff00a3')
win.setBackgroundColor('blueviolet')

Дополнительную информацию об этих типах цветов см. в допустимых параметрах в win.setBackgroundColor.

Родительские и дочерние окна​

Используя опцию parent, можно создать дочерние окна:

const { BrowserWindow } = require('electron')

const top = new BrowserWindow()
const child = new BrowserWindow({ parent: top })
child.show()
top.show()

Окно child всегда будет отображаться поверх окна top.

Модальные окна​

Модальное окно — это дочернее окно, которое отключает родительское окно. Чтобы создать модальное окно, необходимо установить опции parent и modal:

const { BrowserWindow } = require('electron')

const child = new BrowserWindow({ parent: top, modal: true, show: false })
child.loadURL('https://github.com')
child.once('ready-to-show', () => {
  child.show()
})

Видимость страницы​

API видимости страницы Page Visibility API работает следующим образом:

• На всех платформах состояние видимости отслеживает, скрыто/минимизировано ли окно или нет.
• Кроме того, на macOS состояние видимости также отслеживает состояние перекрытия окна. Если окно перекрыто (т.е. полностью закрыто) другим окном, состояние видимости будет hidden. На других платформах состояние видимости будет hidden только при минимизации или явном скрытии окна с win.hide().
• Если окно BrowserWindow создано с show: false, начальное состояние видимости будет visible, несмотря на то, что окно фактически скрыто.
• Если backgroundThrottling отключено, состояние видимости останется visible даже при минимизации, перекрытии или скрытии окна.

Рекомендуется приостанавливать дорогостоящие операции, когда состояние видимости hidden для минимизации энергопотребления.

Примечания к платформам​

• На macOS модальные окна будут отображаться как листы, прикрепленные к родительскому окну.
• На macOS дочерние окна сохраняют относительное положение по отношению к родительскому окну при перемещении родительского окна, в то время как на Windows и Linux дочерние окна не перемещаются.
• В Linux тип модальных окон будет изменен на dialog.
• В Linux многие среды рабочего стола не поддерживают скрытие модального окна.

Класс: BrowserWindow​

Создавайте и управляйте окнами браузера.

Процесс: Основной

BrowserWindow является EventEmitter.

Он создает новое окно BrowserWindow с нативными свойствами, как установлено в options.

new BrowserWindow([options])​

• options Объект (необязательно)
  • width Целое число (необязательно) - Ширина окна в пикселях. По умолчанию 800.
  • height Целое число (необязательно) - Высота окна в пикселях. По умолчанию 600.
  • x Целое число (необязательно) - (обязательно, если используется y) Отступ окна слева от экрана. По умолчанию окно центрируется.
  • y Целое число (необязательно) - (обязательно, если используется x) Отступ окна сверху от экрана. По умолчанию окно центрируется.
  • useContentSize булево (необязательно) - width и height будут использоваться как размеры веб-страницы, что означает, что фактические размеры окна будут включать размер рамки окна и будут немного больше. По умолчанию false.
  • center булево (необязательно) - Показать окно по центру экрана. По умолчанию false.
  • minWidth Целое число (необязательно) - Минимальная ширина окна. По умолчанию 0.
  • minHeight Целое число (необязательно) - Минимальная высота окна. По умолчанию 0.
  • maxWidth Целое число (необязательно) - Максимальная ширина окна. По умолчанию без ограничения.
  • maxHeight Целое число (необязательно) - Максимальная высота окна. По умолчанию без ограничения.
  • resizable булево (необязательно) - Возможность изменения размеров окна. По умолчанию true.
  • movable булево (необязательно) macOS Windows - Возможность перемещения окна. Не реализовано в Linux. По умолчанию true.
  • minimizable булево (необязательно) macOS Windows - Возможность сворачивания окна. Не реализовано в Linux. По умолчанию true.
  • maximizable булево (необязательно) macOS Windows - Возможность разворачивания окна на весь экран. Не реализовано в Linux. По умолчанию true.
  • closable булево (необязательно) macOS Windows - Возможность закрытия окна. Не реализовано в Linux. По умолчанию true.
  • focusable булево (необязательно) - Возможность фокусировки окна. По умолчанию true. В Windows установка focusable: false также подразумевает установку skipTaskbar: true. В Linux установка focusable: false заставляет окно прекратить взаимодействие с wm, так что окно всегда будет оставаться поверх всех рабочих пространств.
  • alwaysOnTop булево (необязательно) - Окно всегда должно оставаться поверх других окон. По умолчанию false.
  • fullscreen булево (необязательно) - Окно должно отображаться в полноэкранном режиме. При явном установке false кнопка полноэкранного режима будет скрыта или отключена в macOS. По умолчанию false.
  • fullscreenable булево (необязательно) - Возможность перевода окна в полноэкранный режим. В macOS также определяется, должна ли кнопка максимизации/увеличения масштаба переключать полноэкранный режим или максимизировать окно. По умолчанию true.
  • simpleFullscreen булево (необязательно) macOS - Использовать полноэкранный режим до Lion в macOS. По умолчанию false.
  • skipTaskbar булево (необязательно) macOS Windows - Отображать окно в панели задач. По умолчанию false.
  • kiosk булево (необязательно) - Окно в режиме киоска. По умолчанию false.
  • title строка (необязательно) - Заголовок окна по умолчанию. По умолчанию "Electron". Если тег HTML <title> определён в файле HTML, загруженном loadURL(), это свойство будет проигнорировано.
  • icon (NativeImage | строка) (необязательно) - Иконка окна. В Windows рекомендуется использовать ICO иконки для достижения наилучшего визуального эффекта, вы также можете оставить его неопределенным, чтобы использовалась иконка исполняемого файла.
  • show булево (необязательно) - Отображать окно при создании. По умолчанию true.
  • paintWhenInitiallyHidden булево (необязательно) - Рендерер должен быть активен, когда show является false и он только что был создан. Для корректной работы document.visibilityState при первой загрузке с show: false следует установить это значение в false. Установка этого значения в false приведет к тому, что событие ready-to-show не будет срабатывать. По умолчанию true.
  • frame булево (необязательно) - Укажите false для создания окна без рамки. По умолчанию true.
  • parent BrowserWindow (необязательно) - Укажите родительское окно. По умолчанию null.
  • modal булево (необязательно) - Является ли это модальным окном. Это работает только тогда, когда окно является дочерним окном. По умолчанию false.
  • acceptFirstMouse булево (необязательно) macOS - Нажатие на неактивное окно также должно нажимать на содержимое веб-страницы. По умолчанию false в macOS. Этот параметр не настраивается на других платформах.
  • disableAutoHideCursor булево (необязательно) - Скрыть курсор при вводе. По умолчанию false.
  • autoHideMenuBar булево (необязательно) - Автоматически скрывать строку меню, если нажата клавиша Alt. По умолчанию false.
  • enableLargerThanScreen булево (необязательно) macOS - Разрешить увеличение размеров окна за пределы экрана. Актуально только для macOS, так как в других ОС окна, превышающие размер экрана, разрешены по умолчанию. По умолчанию false.
  • backgroundColor строка (необязательно) - Цвет фона окна в формате Hex, RGB, RGBA, HSL, HSLA или именованном формате CSS-цвета. Поддерживается альфа в формате #AARRGGBB, если transparent установлено в true. По умолчанию #FFF (белый). Дополнительная информация см. в win.setBackgroundColor.
  • hasShadow булево (необязательно) - Окно должно иметь тень. По умолчанию true.
  • opacity число (необязательно) macOS Windows - Установить начальную непрозрачность окна в диапазоне от 0,0 (полностью прозрачное) до 1,0 (полностью непрозрачное). Реализовано только в Windows и macOS.
  • darkTheme булево (необязательно) - Принудительно использовать тёмную тему для окна, работает только в некоторых настольных средах GTK+3. По умолчанию false.
  • transparent булево (необязательно) - Делает окно прозрачным. По умолчанию false. В Windows не работает, если окно не безрамковое.
  • type строка (необязательно) - Тип окна, по умолчанию - обычное окно. Подробнее см. ниже.
  • visualEffectState строка (необязательно) macOS - Укажите, как внешний вид материала должен отражать состояние активности окна в macOS. Должен использоваться с свойством vibrancy . Возможные значения:
    • followWindow - Подложка автоматически отображается активной, когда окно активное, и неактивной, когда нет. Это значение по умолчанию.
    • active - Подложка всегда отображается активной.
    • inactive - Подложка всегда отображается неактивной.
  • titleBarStyle строка (необязательно) macOS Windows - Стиль панели заголовка окна. По умолчанию default. Возможные значения:
    • default - Результат - стандартная панель заголовка для macOS или Windows соответственно.
    • hidden - Результат - скрытая панель заголовка и окно содержимого полного размера. В macOS у окна всё ещё есть стандартные элементы управления окном («сигнальные огни») в верхнем левом углу. В Windows, в сочетании с titleBarOverlay: true , это активирует наложение элементов управления окном (см. titleBarOverlay для получения дополнительной информации), в противном случае элементы управления окном не будут отображаться.
    • hiddenInset macOS - Только в macOS, результат - скрытая панель заголовка с альтернативным видом, где кнопки сигнальных огней немного отодвинуты от края окна.
    • customButtonsOnHover macOS - Только в macOS, результат - скрытая панель заголовка и окно содержимого полного размера, кнопки сигнальных огней будут отображаться при наведении курсора в верхнем левом углу окна. Примечание: Этот параметр в настоящее время является экспериментальным.
  • trafficLightPosition Точка (необязательно) macOS - Установите пользовательское положение кнопок сигнальных огней в окнах без рамки.
  • roundedCorners булево (необязательно) macOS - Окно без рамки должно иметь закругленные углы в macOS. По умолчанию true. Установка этого свойства в false предотвратит возможность перевода окна в полноэкранный режим.
  • fullscreenWindowTitle булево (необязательно) Устарело macOS - Отображает заголовок в строке заголовка в полноэкранном режиме в macOS для стиля заголовка hiddenInset . По умолчанию false.
  • thickFrame булево (необязательно) - Использовать стиль WS_THICKFRAME для окон без рамки в Windows, который добавляет стандартную рамку окна. Установка в false удалит тень окна и анимации окна. По умолчанию true.

• • vibrancy строка (необязательно) macOS - Добавляет эффект вибрации в окно, только на macOS. Может быть appearance-based, light, dark, titlebar, selection, menu, popover, sidebar, medium-light, ultra-dark, header, sheet, window, hud, fullscreen-ui, tooltip, content, under-window, или under-page. Обратите внимание, что appearance-based, light, dark, medium-light, и ultra-dark устарели и были удалены в macOS Catalina (10.15).
  • zoomToPageWidth булево (необязательно) macOS - Управляет поведением на macOS при нажатии на зеленую кнопку остановки на панели инструментов с нажатой клавишей Option или кликом по пункту меню «Окно» > «Масштабировать». Если true, окно будет увеличиваться до предпочтительной ширины веб-страницы при масштабировании, false приведет к масштабированию до ширины экрана. Это также повлияет на поведение при прямом вызове maximize(). По умолчанию false.
  • tabbingIdentifier строка (необязательно) macOS - Имя группы вкладок, позволяет открыть окно как родную вкладку на macOS 10.12+. Окна с одинаковым идентификатором вкладок будут сгруппированы вместе. Это также добавляет родную кнопку новой вкладки в панель вкладок вашего окна и позволяет вашему app и окну получать событие new-window-for-tab.
  • webPreferences Объект (необязательно) - Настройки функций веб-страницы.

• • • devTools boolean (optional) - Включить DevTools. Если значение false, нельзя использовать BrowserWindow.webContents.openDevTools() для открытия DevTools. По умолчанию true.
    • nodeIntegration boolean (optional) - Включить интеграцию Node.js. По умолчанию false.
    • nodeIntegrationInWorker boolean (optional) - Включить интеграцию Node.js в веб-воркерах. По умолчанию false. Дополнительная информация в Многопоточности.
    • nodeIntegrationInSubFrames boolean (optional) - Экспериментальный параметр для включения поддержки Node.js в подрамках, таких как iframes и дочерние окна. Все ваши загрузчики будут загружаться для каждого iframe. Можно использовать process.isMainFrame для определения, находитесь ли вы в основном фрейме.
    • preload string (optional) - Указывает скрипт, который будет загружен перед выполнением других скриптов на странице. Этот скрипт всегда будет иметь доступ к API Node.js, независимо от того, включена или выключена интеграция Node.js. Значение должно быть полным путем к файлу скрипта. При выключенной интеграции Node.js скрипт загрузки может повторно ввести глобальные символы Node в глобальную область видимости. Пример см. здесь.
    • sandbox boolean (optional) - Если установлено, это изолирует рендерер, связанный с окном, делая его совместимым с ящиком Chromium на уровне операционной системы и отключая движок Node.js. Это не то же самое, что параметр nodeIntegration, и API, доступные скрипту загрузки, ограничены. Подробнее об этом параметре см. здесь.
    • session Сессия (optional) - Устанавливает сессию, используемую страницей. Вместо непосредственного передачи объекта Сессии, можно использовать опцию partition, которая принимает строку раздела. Если установлены как session, так и partition, session будет иметь приоритет. По умолчанию используется стандартная сессия.
    • partition string (optional) - Устанавливает сессию, используемую страницей, на основе строки раздела сессии. Если partition начинается с префикса persist:, страница будет использовать постоянную сессию, доступную всем страницам в приложении с одинаковым partition. Если префикс persist: отсутствует, страница будет использовать сессию в оперативной памяти. Присваивая одинаковые partition, несколько страниц могут использовать одну и ту же сессию. По умолчанию используется стандартная сессия.
    • zoomFactor number (optional) - Коэффициент масштабирования страницы по умолчанию, 3.0 соответствует 300%. По умолчанию 1.0.
    • javascript boolean (optional) - Включает поддержку JavaScript. По умолчанию true.
    • webSecurity boolean (optional) - При false, отключает политику одного происхождения (обычно используется при тестировании веб-сайтов), и устанавливает allowRunningInsecureContent в true, если этот параметр не был установлен пользователем. По умолчанию true.
    • allowRunningInsecureContent boolean (optional) - Разрешить https-странице запускать JavaScript, CSS или плагины из http-ссылок. По умолчанию false.
    • images boolean (optional) - Включает поддержку изображений. По умолчанию true.
    • imageAnimationPolicy string (optional) - Указывает, как запускать анимации изображений (например, GIF). Может быть animate, animateOnce или noAnimation. По умолчанию animate.
    • textAreasAreResizable boolean (optional) - Разрешить изменение размера элементов TextArea. По умолчанию true.
    • webgl boolean (optional) - Включает поддержку WebGL. По умолчанию true.
    • plugins boolean (optional) - Включить плагины. По умолчанию false.
    • experimentalFeatures boolean (optional) - Включает экспериментальные функции Chromium. По умолчанию false.
    • scrollBounce boolean (optional) macOS - Включает эффект отскока прокрутки (резиновое растяжение) на macOS. По умолчанию false.
    • enableBlinkFeatures string (optional) - Список строк свойств, разделенных через ,, например, CSSVariables,KeyboardEventKey для включения. Полный список поддерживаемых строк свойств можно найти в файле RuntimeEnabledFeatures.json5.
    • disableBlinkFeatures string (optional) - Список строк свойств, разделенных через ,, например, CSSVariables,KeyboardEventKey для отключения. Полный список поддерживаемых строк свойств можно найти в файле RuntimeEnabledFeatures.json5.
    • defaultFontFamily Object (optional) - Устанавливает шрифт по умолчанию для семейства шрифтов.
      • standard string (optional) - По умолчанию Times New Roman.
      • serif string (optional) - По умолчанию Times New Roman.
      • sansSerif string (optional) - По умолчанию Arial.
      • monospace string (optional) - По умолчанию Courier New.
      • cursive string (optional) - По умолчанию Script.
      • fantasy string (optional) - По умолчанию Impact.
    • defaultFontSize Integer (optional) - По умолчанию 16.
    • defaultMonospaceFontSize Integer (optional) - По умолчанию 13.
    • minimumFontSize Integer (optional) - По умолчанию 0.
    • defaultEncoding string (optional) - По умолчанию ISO-8859-1.
    • backgroundThrottling boolean (optional) - Замедлять анимации и таймеры, когда страница становится фоновой. Также влияет на API видимости страницы. По умолчанию true.
    • offscreen boolean (optional) - Включить рендеринг вне области видимости для окна браузера. По умолчанию false. Подробности см. в руководстве по рендерингу вне области видимости.
    • contextIsolation boolean (optional) - Выполнять API Electron и указанный скрипт preload в отдельном контексте JavaScript. По умолчанию true. Контекст, в котором выполняется скрипт preload, будет иметь доступ только к своим глобальным переменным document и window, а также к своему набору встроенных функций JavaScript (Array, Object, JSON, и т.д.), которые недоступны загружаемому контенту. API Electron будет доступен только в скрипте preload, а не на загружаемой странице. Этот параметр следует использовать при загрузке потенциально небезопасного удаленного контента, чтобы убедиться, что загруженный контент не может повлиять на скрипт preload и используемые API Electron. Этот параметр использует ту же технику, что и скрипты содержимого Chrome. В DevTools к этому контексту можно получить доступ, выбрав запись «Изолированный контекст Electron» в раскрывающемся списке в верхней части вкладки «Консоль».
    • webviewTag boolean (optional) - Включить <webview> тег. По умолчанию false. Примечание: скрипт preload для <webview> будет иметь включенную интеграцию Node.js при его выполнении, поэтому необходимо убедиться, что удаленный/недоверенный контент не может создать тег <webview> с потенциально вредоносным скриптом preload. Можно использовать событие will-attach-webview на webContents для удаления скрипта preload и проверки или изменения начальных настроек <webview>.
    • additionalArguments string[] (optional) - Список строк, которые будут добавлены к process.argv в процессе рендеринга этого приложения. Полезно для передачи небольших данных в скрипты загрузки рендер-процесса.
    • safeDialogs boolean (optional) - Включить защиту от последовательных диалоговых окон. По умолчанию false.
    • safeDialogsMessage string (optional) - Сообщение для отображения при срабатывании защиты от последовательных диалоговых окон. Если не определено, используется стандартное сообщение. Обратите внимание, что в настоящее время стандартное сообщение на английском языке и не локализовано.
    • disableDialogs boolean (optional) - Полностью отключить диалоговые окна. Переопределяет safeDialogs. По умолчанию false.
    • navigateOnDragDrop boolean (optional) - Переход по ссылке при перетаскивании файла или ссылки на страницу. По умолчанию false.
    • autoplayPolicy string (optional) - Политика автовоспроизведения для контента в окне, может быть no-user-gesture-required, user-gesture-required, document-user-activation-required. По умолчанию no-user-gesture-required.
    • disableHtmlFullscreenWindowResize boolean (optional) - Предотвратить изменение размера окна при переходе в полноэкранный режим HTML. По умолчанию false.
    • accessibleTitle string (optional) - Альтернативная строка заголовка, предоставленная только для инструментов доступности, таких как средства чтения с экрана. Эта строка не отображается пользователю напрямую.
    • spellcheck boolean (optional) - Включить встроенную проверку орфографии. По умолчанию true.
    • enableWebSQL boolean (optional) - Включить API WebSQL. По умолчанию true.
    • v8CacheOptions string (optional) - Определяет политику кэширования кода v8, используемую blink. Принимаемые значения:
      • none - Отключение кэширования кода
      • code - Кэширование кода на основе эвристики
      • bypassHeatCheck - Обход эвристик кэширования кода, но с отложенной компиляцией
      • bypassHeatCheckAndEagerCompile - Как выше, но компиляция немедленная. По умолчанию code.
    • enablePreferredSizeMode boolean (optional) - Включить режим предпочтительного размера. Предпочтительный размер — минимальный размер, необходимый для отображения макета документа без необходимости прокрутки. При включении этого параметра будет генерироваться событие preferred-size-changed для WebContents при изменении предпочтительного размера. По умолчанию false.

• • titleBarOverlay Объект | Булево (необязательно) - При использовании безрамочного окна в сочетании с win.setWindowButtonVisibility(true) на macOS или использовании titleBarStyle, чтобы стандартные элементы управления окном ("светофоры" на macOS) были видимы, эта свойство включает JavaScript-API для наложения элементов управления окном JavaScript APIs и CSS Environment Variables. Указание true приведет к наложению с цветами по умолчанию системы. Значение по умолчанию false.
    • color Строка (необязательно) Windows - Цвет CSS наложения элементов управления окном при включении. Значение по умолчанию - цвет системы.
    • symbolColor Строка (необязательно) Windows - Цвет CSS символов на наложении элементов управления окном при включении. Значение по умолчанию - цвет системы.
    • height Целое число (необязательно) macOS Windows - Высота строки заголовка и наложения элементов управления окном в пикселях. Значение по умолчанию - высота системы.

При установке минимального или максимального размера окна с использованием minWidth/maxWidth/ minHeight/maxHeight, это ограничение только для пользователя. Это не предотвратит передачу размера, который не соответствует ограничениям, в setBounds/setSize или конструктор BrowserWindow.

Возможные значения и поведение параметра type зависят от платформы. Возможные значения:

• В Linux возможные типы desktop, dock, toolbar, splash, notification.
• В macOS возможные типы desktop, textured, panel.
  • Тип textured добавляет металлический градиентный вид (NSWindowStyleMaskTexturedBackground).
  • Тип desktop помещает окно на уровень окна фонового рабочего стола (kCGDesktopWindowLevel - 1). Обратите внимание, что окно рабочего стола не получит фокус, события клавиатуры или мыши, но вы можете использовать globalShortcut для получения ввода.
  • Тип panel позволяет окну плавать поверх полноэкранных приложений, добавляя маску стиля NSWindowStyleMaskNonactivatingPanel, обычно используемую для NSPanel, во время выполнения. Также окно будет отображаться на всех пространствах (рабочих столах).
• В Windows возможен тип toolbar.

События экземпляра​

Объекты, созданные с помощью new BrowserWindow, излучают следующие события:

Примечание: Некоторые события доступны только на определенных операционных системах и помечены как таковые.

Событие: 'page-title-updated'​

Возвращает:

• event Событие
• title строка
• explicitSet логическое значение

Выпускается, когда документ изменил свой заголовок, вызов event.preventDefault() предотвратит изменение заголовка родного окна. explicitSet равно false, когда заголовок синтезируется из URL файла.

Событие: 'close'​

Возвращает:

• event Событие

Выпускается, когда окно собирается закрыться. Оно выпускается до событий beforeunload и unload DOM. Вызов event.preventDefault() отменяет закрытие.

Обычно вы хотите использовать обработчик beforeunload, чтобы решить, должно ли окно закрываться, что также будет вызвано при перезагрузке окна. В Electron возвращение любого значения, отличного от undefined, отменит закрытие. Например:

window.onbeforeunload = (e) => {
  console.log('I do not want to be closed')

  // Unlike usual browsers that a message box will be prompted to users, returning
  // a non-void value will silently cancel the close.
  // It is recommended to use the dialog API to let the user confirm closing the
  // application.
  e.returnValue = false
}

Примечание: Существует тонкая разница в поведении window.onbeforeunload = handler и window.addEventListener('beforeunload', handler). Рекомендуется всегда явно устанавливать event.returnValue, а не только возвращать значение, так как первый работает более последовательно в Electron.

Событие: 'closed'​

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

Событие: 'session-end' Windows​

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

Событие: 'unresponsive'​

Выпускается, когда веб-страница становится неотзывчивой.

Событие: 'responsive'​

Выпускается, когда неотзывчивая веб-страница снова становится отзывчивой.

Событие: 'blur'​

Выпускается, когда окно теряет фокус.

Событие: 'focus'​

Выпускается, когда окно получает фокус.

Событие: 'show'​

Выпускается при отображении окна.

Событие: 'hide'​

Выпускается, когда окно скрыто.

Событие: 'ready-to-show'​

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

Обратите внимание, что использование этого события подразумевает, что рендерер будет считаться "видимым" и будет рисовать, даже если show равно false. Это событие никогда не будет выпущено, если вы используете paintWhenInitiallyHidden: false

Событие: 'maximize'​

Выпускается, когда окно максимализировано.

Событие: 'unmaximize'​

Выпускается, когда окно покидает состояние максимализации.

Событие: 'minimize'​

Выпускается, когда окно минимизировано.

Событие: 'restore'​

Выпускается, когда окно восстановлено из минимизированного состояния.

Событие: 'will-resize' macOS Windows​

Возвращает:

• event Событие
• newBounds Прямоугольник - Размер, к которому окно изменяется.
• details Объект
  • edge (строка) - Край окна, перетаскиваемый для изменения размера. Может быть bottom, left, right, top-left, top-right, bottom-left или bottom-right.

Выпускается перед изменением размера окна. Вызов event.preventDefault() предотвратит изменение размера окна.

Обратите внимание, что это событие выпускается только при ручном изменении размера окна. Изменение размера окна с использованием setBounds/setSize не вызовет это событие.

Возможные значения и поведение параметра edge зависят от платформы. Возможные значения:

• В Windows возможные значения bottom, top, left, right, top-left, top-right, bottom-left, bottom-right.
• В macOS возможные значения bottom и right.
  • Значение bottom используется для обозначения вертикального изменения размера.
  • Значение right используется для обозначения горизонтального изменения размера.

Событие: 'resize'​

Выпускается после изменения размера окна.

Событие: 'resized' macOS Windows​

Выпускается один раз, когда окно закончит изменение размера.

Это обычно происходит, когда окно было изменено размера вручную. В macOS изменение размера окна с setBounds/setSize и установкой параметра animate в true также вызовет это событие после завершения изменения размера.

Событие: 'will-move' macOS Windows​

Возвращает:

• event Событие
• newBounds Прямоугольник - Положение, в которое перемещается окно.

Выполняется перед перемещением окна. В Windows, вызов event.preventDefault() предотвратит перемещение окна.

Обратите внимание, что этот событие генерируется только при ручном перемещении окна. Перемещение окна с помощью setPosition/setBounds/center не сгенерирует это событие.

Событие: 'move'​

Срабатывает при перемещении окна в новое положение.

Событие: 'moved' macOS Windows​

Срабатывает один раз при перемещении окна в новое положение.

Примечание: В macOS это событие является алиасом move.

Событие: 'enter-full-screen'​

Срабатывает, когда окно переходит в полноэкранный режим.

Событие: 'leave-full-screen'​

Срабатывает, когда окно покидает полноэкранный режим.

Событие: 'enter-html-full-screen'​

Срабатывает, когда окно переходит в полноэкранный режим, вызванный API HTML.

Событие: 'leave-html-full-screen'​

Срабатывает, когда окно покидает полноэкранный режим, вызванный API HTML.

Событие: 'always-on-top-changed'​

Возвращает:

• event Событие
• isAlwaysOnTop boolean

Срабатывает, когда окну задано или снято свойство "всегда поверх" других окон.

Событие: 'app-command' Windows Linux​

Возвращает:

• event Событие
• command строка

Срабатывает при вызове команды приложения. Обычно связаны с медиа-клавишами клавиатуры или командами браузера, а также с кнопкой "Назад", встроенной в некоторые мыши в Windows.

Команды приводятся к нижнему регистру, подчеркивания заменяются дефисами, и префикс APPCOMMAND_ удаляется. Например, APPCOMMAND_BROWSER_BACKWARD генерирует browser-backward.

const { BrowserWindow } = require('electron')
const win = new BrowserWindow()
win.on('app-command', (e, cmd) => {
  // Navigate the window back when the user hits their mouse back button
  if (cmd === 'browser-backward' && win.webContents.canGoBack()) {
    win.webContents.goBack()
  }
})

Следующие команды приложения явно поддерживаются в Linux:

• browser-backward
• browser-forward

Событие: 'scroll-touch-begin' macOS​

Срабатывает при начале фазы события прокрутки колесом.

Событие: 'scroll-touch-end' macOS​

Срабатывает по окончании фазы события прокрутки колесом.

Событие: 'scroll-touch-edge' macOS​

Срабатывает, когда фаза события прокрутки достигла края элемента.

Событие: 'swipe' macOS​

Возвращает:

• event Событие
• direction строка

Срабатывает при свайпе тремя пальцами. Возможные направления: up, right, down, left.

Метод, лежащий в основе этого события, разработан для обработки свайпов трекпада в стиле старых macOS, где содержимое экрана не перемещается вместе со свайпом. Большинство трекпадов macOS больше не настроены на разрешение такого рода свайпов, поэтому для правильной генерации события необходимо установить в System Preferences > Trackpad > More Gestures параметр "Прокрутка между страницами" в значение "Прокрутка двумя или тремя пальцами".

Событие: 'rotate-gesture' macOS​

Возвращает:

• event Событие
• rotation Число с плавающей запятой

Срабатывает при жесте вращения трекпада. Непрерывно генерируется до завершения жеста вращения. Значение rotation в каждом событии — угол в градусах, на который повернуто с предыдущего события. Последнее событие при жесте вращения всегда имеет значение 0 . Противочасовой поворот — положительные значения, а по часовой стрелке — отрицательные.

Событие: 'sheet-begin' macOS​

Срабатывает при открытии листа (sheet).

Событие: 'sheet-end' macOS​

Срабатывает при закрытии листа (sheet).

Событие: 'new-window-for-tab' macOS​

Срабатывает при нажатии на кнопку создания новой вкладки.

Событие: 'system-context-menu' Windows​

Возвращает:

• event Событие
• point Точка - Координаты контекстного меню на экране

Срабатывает при вызове контекстного меню системы на окне. Обычно срабатывает при нажатии правой кнопкой мыши на неклиентскую область окна. Это область заголовка окна или любая область, объявленная как -webkit-app-region: drag в оконном фрейме без рамки.

Вызов event.preventDefault() предотвратит отображение меню.

Статические методы​

Класс BrowserWindow содержит следующие статические методы:

BrowserWindow.getAllWindows()​

Возвращает BrowserWindow[] - Массив всех открытых окон браузера.

BrowserWindow.getFocusedWindow()​

Возвращает BrowserWindow | null - Окно, на котором сфокусирован курсор в приложении. В противном случае возвращает null.

BrowserWindow.fromWebContents(webContents)​

• webContents WebContents

Возвращает BrowserWindow | null - Окно, владеющее данным webContents, или null, если содержимое не принадлежит окну.

BrowserWindow.fromBrowserView(browserView)​

• browserView BrowserView

Возвращает BrowserWindow | null - Окно, владеющее данным browserView. Если данное представление не прикреплено к окну, возвращает null.

BrowserWindow.fromId(id)​

• id Целое число

Возвращает BrowserWindow | null - Окно с заданным id.

Свойства экземпляров​

У объектов, созданных с помощью new BrowserWindow, есть следующие свойства:

const { BrowserWindow } = require('electron')
// In this example `win` is our instance
const win = new BrowserWindow({ width: 800, height: 600 })
win.loadURL('https://github.com')

win.webContents Только для чтения​

Объект WebContents, принадлежащий этому окну. Все события и операции, связанные с веб-страницей, выполняются через него.

См. webContents документацию для его методов и событий.

win.id Только для чтения​

Свойство Integer, представляющее уникальный идентификатор окна. Каждый идентификатор уникален среди всех BrowserWindow экземпляров всего приложения Electron.

win.autoHideMenuBar​

Свойство boolean, определяющее, следует ли автоматически скрывать строку меню окна. После установки, строка меню будет отображаться только при нажатии на единственную клавишу Alt.

Если строка меню уже отображается, установка этого свойства в true не скроет её мгновенно.

win.simpleFullScreen​

Свойство boolean, определяющее, находится ли окно в режиме простого полноэкранного режима (до Lion).

win.fullScreen​

Свойство boolean, определяющее, находится ли окно в полноэкранном режиме.

win.focusable Windows macOS​

Свойство boolean, определяющее, может ли окно получить фокус.

win.visibleOnAllWorkspaces macOS Linux​

Свойство boolean, определяющее, отображается ли окно на всех рабочих столах.

Примечание: Всегда возвращает false в Windows.

win.shadow​

Свойство boolean, определяющее, имеет ли окно тень.

win.menuBarVisible Windows Linux​

Свойство boolean, определяющее, должна ли быть видимой строка меню.

Примечание: Если строка меню скрывается автоматически, пользователи всё ещё могут отобразить её, нажав на единственную клавишу Alt.

win.kiosk​

Свойство boolean, определяющее, находится ли окно в режиме киоска.

win.documentEdited macOS​

Свойство boolean, определяющее, был ли изменён документ окна.

Значок в строке заголовка станет серым, если установлено значение true.

win.representedFilename macOS​

Свойство string, определяющее путь к файлу, который представляет окно, и значок файла будет отображаться в строке заголовка окна.

win.title​

Свойство string, определяющее заголовок нативного окна.

Примечание: Заголовок веб-страницы может отличаться от заголовка нативного окна.

win.minimizable macOS Windows​

Свойство boolean, определяющее, может ли пользователь вручную минимизировать окно.

В Linux установщик является бесполезной операцией, хотя получатель возвращает true.

win.maximizable macOS Windows​

Свойство boolean, определяющее, может ли пользователь вручную максимизировать окно.

В Linux установщик является бесполезной операцией, хотя получатель возвращает true.

win.fullScreenable​

Свойство boolean, определяющее, переключает ли кнопка максимизации/увеличения масштаба окно в полноэкранный режим или максимизирует окно.

win.resizable​

Свойство boolean, определяющее, может ли пользователь вручную изменять размер окна.

win.closable macOS Windows​

Свойство boolean, определяющее, может ли пользователь вручную закрыть окно.

В Linux установщик является бесполезной операцией, хотя получатель возвращает true.

win.movable macOS Windows​

Свойство boolean, определяющее, может ли пользователь перемещать окно.

В Linux установщик является бесполезной операцией, хотя получатель возвращает true.

win.excludedFromShownWindowsMenu macOS​

Свойство boolean, определяющее, исключено ли окно из меню приложений «Окна». false по умолчанию.

const win = new BrowserWindow({ height: 600, width: 600 })

const template = [
  {
    role: 'windowmenu'
  }
]

win.excludedFromShownWindowsMenu = true

const menu = Menu.buildFromTemplate(template)
Menu.setApplicationMenu(menu)

win.accessibleTitle​

Свойство string, определяющее альтернативный заголовок, предоставленный только для инструментов доступности, таких как программы чтения с экрана. Эта строка не отображается пользователям напрямую.

Методы экземпляров​

Объекты, созданные с помощью new BrowserWindow, имеют следующие методы экземпляров:

Примечание: Некоторые методы доступны только на определённых операционных системах и помечены как таковые.

win.destroy()​

Вынужденное закрытие окна. События unload и beforeunload не будут отправлены для веб-страницы, и событие close также не будет отправлено для этого окна, но гарантирует, что событие closed будет отправлено.

win.close()​

Попытка закрыть окно. Это имеет тот же эффект, что и при ручном нажатии пользователем кнопки закрытия окна. Однако веб-страница может отменить закрытие. См. событие close.

win.focus()​

Фокусировка на окне.

win.blur()​

Удаление фокуса с окна.

win.isFocused()​

Возвращает boolean — находится ли окно в фокусе.

win.isDestroyed()​

Возвращает boolean — уничтожено ли окно.

win.show()​

Отображение и фокусировка на окне.

win.showInactive()​

Отображение окна, но без фокусировки.

win.hide()​

Скрытие окна.

win.isVisible()​

Возвращает boolean — отображается ли окно для пользователя.

win.isModal()​

Возвращает boolean — является ли текущее окно модальным.

win.maximize()​

Максимизирует окно. Также отобразит (но не сфокусирует) окно, если оно уже не отображается.

win.unmaximize()​

Возвращает окно к исходному размеру.

win.isMaximized()​

Возвращает boolean — максимизировано ли окно.

win.minimize()​

Минимизирует окно. На некоторых платформах минимизированное окно будет отображено в доке.

win.restore()​

Восстанавливает окно из минимизированного состояния в его предыдущее состояние.

win.isMinimized()​

Возвращает boolean — минимизировано ли окно.

win.setFullScreen(flag)​

• flag boolean

Устанавливает, должно ли окно быть в полноэкранном режиме.

win.isFullScreen()​

Возвращает boolean — находится ли окно в полноэкранном режиме.

win.setSimpleFullScreen(flag) macOS​

• flag boolean

Переходит в или выходит из простого полноэкранного режима.

Простой полноэкранный режим эмулирует родное полноэкранное поведение, найденное в версиях macOS до Lion (10.7).

win.isSimpleFullScreen() macOS​

Возвращает boolean — находится ли окно в простом (до Lion) полноэкранном режиме.

win.isNormal()​

Возвращает boolean — находится ли окно в нормальном состоянии (не максимизировано, не минимизировано, не в полноэкранном режиме).

win.setAspectRatio(aspectRatio[, extraSize])​

• aspectRatio Float — коэффициент пропорций, который необходимо поддерживать для некоторой части области содержимого.
• extraSize Размер (необязательно) macOS — дополнительный размер, который не нужно включать при поддержании коэффициента пропорций.

Это позволит окну поддерживать коэффициент пропорций. Дополнительный размер позволяет разработчику иметь пространство, заданное в пикселях, которое не включается в расчёты коэффициента пропорций. Этот API уже учитывает разницу между размером окна и размером его содержимого.

Рассмотрим обычное окно с видеопроигрывателем HD и соответствующими элементами управления. Возможно, есть 15 пикселей элементов управления слева, 25 пикселей элементов управления справа и 50 пикселей элементов управления под проигрывателем. Для поддержания коэффициента пропорций 16:9 (стандартный коэффициент пропорций для HD @1920x1080) внутри самого проигрывателя мы будем вызывать эту функцию с аргументами 16/9 и { width: 40, height: 50 }. Второй аргумент не заботится о том, где находятся дополнительные ширина и высота внутри области содержимого — только о том, что они существуют. Суммируйте любые дополнительные области ширины и высоты, которые у вас есть в области содержимого в целом.

Коэффициент пропорций не соблюдается при изменении размера окна программно с помощью API, таких как win.setSize.

win.setBackgroundColor(backgroundColor)​

• backgroundColor строка — цвет в формате Hex, RGB, RGBA, HSL, HSLA или именованном формате цвета CSS. Альфа-канал является необязательным для типа hex.

Примеры допустимых значений backgroundColor:

• Hex
  • #fff (сокращённый RGB)
  • #ffff (сокращённый ARGB)
  • #ffffff (RGB)
  • #ffffffff (ARGB)
• RGB
  • rgb(([\d]+),\s([\d]+),\s([\d]+))
    • например rgb(255, 255, 255)
• RGBA
  • rgba(([\d]+),\s([\d]+),\s([\d]+),\s*([\d.]+))
    • например rgba(255, 255, 255, 1.0)
• HSL
  • hsl((-?[\d.]+),\s([\d.]+)%,\s([\d.]+)%)
    • например hsl(200, 20%, 50%)
• HSLA
  • hsla((-?[\d.]+),\s([\d.]+)%,\s([\d.]+)%,\s*([\d.]+))
    • например hsla(200, 20%, 50%, 0.5)
• Имя цвета
  • Варианты перечислены в SkParseColor.cpp
  • Аналогично ключевым словам CSS Color Module Level 3, но регистрозависимы.
    • например blueviolet или red

Устанавливает цвет фона окна. См. Установку backgroundColor.

win.previewFile(path[, displayName]) macOS​

• path строка — абсолютный путь к файлу для предварительного просмотра с помощью QuickLook. Это важно, так как Quick Look использует имя файла и расширение файла в пути, чтобы определить тип содержимого открываемого файла.
• displayName строка (необязательно) — имя файла для отображения в модальном представлении Quick Look. Это чисто визуально и не влияет на тип содержимого файла. По умолчанию path.

Использует Quick Look для предварительного просмотра файла по заданному пути.

win.closeFilePreview() macOS​

Закрывает текущую открытую панель Quick Look.

win.setBounds(bounds[, animate])​

• bounds Partial<Прямоугольник>
• animate boolean (необязательно) macOS

Изменяет размер и перемещает окно в предоставленные границы. Любые не указанные свойства будут по умолчанию иметь свои текущие значения.

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

// set all bounds properties
win.setBounds({ x: 440, y: 225, width: 800, height: 600 })

// set a single bounds property
win.setBounds({ width: 100 })

// { x: 440, y: 225, width: 100, height: 600 }
console.log(win.getBounds())

win.getBounds()​

Возвращает Прямоугольник — bounds окна в виде Object.

win.getBackgroundColor()​

Возвращает string — получает цвет фона окна в формате Hex (#RRGGBB) .

См. Установку backgroundColor.

Примечание: значение альфа-канала не возвращается вместе с красным, зелёным и синим значениями.

win.setContentBounds(bounds[, animate])​

• bounds Прямоугольник
• animate boolean (необязательно) macOS

Изменяет размер и перемещает область клиента окна (например, веб-страницу) в предоставленные границы.

win.getContentBounds()​

Возвращает Прямоугольник — bounds области клиента окна в виде Object.

win.getNormalBounds()​

Возвращает Прямоугольник — содержит границы окна в нормальном состоянии.

Примечание: независимо от текущего состояния окна (максимизированное, минимизированное или в полноэкранном режиме) эта функция всегда возвращает положение и размер окна в нормальном состоянии. В нормальном состоянии функции getBounds и getNormalBounds возвращают один и тот же Прямоугольник.

win.setEnabled(enable)​

• enable boolean

Отключить или включить окно.

win.isEnabled()​

Возвращает boolean — включено ли окно.

win.setSize(width, height[, animate])​

• width Целое число
• height Целое число
• animate boolean (необязательно) macOS

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

win.getSize()​

Возвращает Integer[] — содержит ширину и высоту окна.

win.setContentSize(width, height[, animate])​

• width Целое число
• height Целое число
• animate логическое значение (необязательно) macOS

Изменяет размер клиентской области окна (например, веб-страницы) до width и height.

win.getContentSize()​

Возвращает Integer[] - Содержит ширину и высоту клиентской области окна.

win.setMinimumSize(width, height)​

• width Целое число
• height Целое число

Устанавливает минимальный размер окна до width и height.

win.getMinimumSize()​

Возвращает Integer[] - Содержит минимальную ширину и высоту окна.

win.setMaximumSize(width, height)​

• width Целое число
• height Целое число

Устанавливает максимальный размер окна до width и height.

win.getMaximumSize()​

Возвращает Integer[] - Содержит максимальную ширину и высоту окна.

win.setResizable(resizable)​

• resizable логическое значение

Устанавливает, можно ли пользователю вручную изменять размер окна.

win.isResizable()​

Возвращает boolean - Можно ли пользователю вручную изменять размер окна.

win.setMovable(movable) macOS Windows​

• movable логическое значение

Устанавливает, можно ли пользователю перемещать окно. В Linux ничего не делает.

win.isMovable() macOS Windows​

Возвращает boolean - Можно ли пользователю перемещать окно.

В Linux всегда возвращает true.

win.setMinimizable(minimizable) macOS Windows​

• minimizable логическое значение

Устанавливает, можно ли пользователю вручную сворачивать окно. В Linux ничего не делает.

win.isMinimizable() macOS Windows​

Возвращает boolean - Можно ли пользователю вручную сворачивать окно.

В Linux всегда возвращает true.

win.setMaximizable(maximizable) macOS Windows​

• maximizable логическое значение

Устанавливает, можно ли пользователю вручную разворачивать окно. В Linux ничего не делает.

win.isMaximizable() macOS Windows​

Возвращает boolean - Можно ли пользователю вручную разворачивать окно.

В Linux всегда возвращает true.

win.setFullScreenable(fullscreenable)​

• fullscreenable логическое значение

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

win.isFullScreenable()​

Возвращает boolean - Будет ли кнопка максимизации/увеличения отображения переключать полноэкранный режим или максимизировать окно.

win.setClosable(closable) macOS Windows​

• closable логическое значение

Устанавливает, можно ли пользователю вручную закрыть окно. В Linux ничего не делает.

win.isClosable() macOS Windows​

Возвращает boolean - Можно ли пользователю вручную закрыть окно.

В Linux всегда возвращает true.

win.setAlwaysOnTop(flag[, level][, relativeLevel])​

• flag логическое значение
• level строка (необязательно) macOS Windows - Значения включают normal, floating, torn-off-menu, modal-panel, main-menu, status, pop-up-menu, screen-saver, и dock (Устарело). По умолчанию floating при flag является истинным. level сбрасывается до normal при ложном значении флага. Обратите внимание, что с floating по status включительно, окно размещается под панелью Dock на macOS и под строкой задач на Windows. С pop-up-menu и выше оно отображается над панелью Dock на macOS и над строкой задач на Windows. Для получения дополнительной информации см. документацию macOS.
• relativeLevel Целое число (необязательно) macOS - Число уровней выше для установки этого окна относительно заданного level. По умолчанию 0 Обратите внимание, что Apple не рекомендует устанавливать уровни выше 1 над screen-saver.

Устанавливает, что окно должно отображаться всегда поверх других окон. После установки этого флага окно по-прежнему является обычным окном, а не окном панели инструментов, которое нельзя сфокусировать.

win.isAlwaysOnTop()​

Возвращает boolean - Отображается ли окно всегда поверх других окон.

win.moveAbove(mediaSourceId)​

• mediaSourceId строка - Идентификатор окна в формате идентификатора источника DesktopCapturer. Например, "window:1869:0".

Перемещает окно над окном-источником в порядке z-индекса. Если mediaSourceId не является окном или если окно не существует, этот метод возвращает ошибку.

win.moveTop()​

Перемещает окно на самый верх (z-порядок) независимо от фокуса

win.center()​

Перемещает окно в центр экрана.

win.setPosition(x, y[, animate])​

• x Целое число
• y Целое число
• animate логическое значение (необязательно) macOS

Перемещает окно в x и y.

win.getPosition()​

Возвращает Integer[] - Содержит текущее положение окна.

win.setTitle(title)​

• title строка

Изменяет заголовок нативного окна на title.

win.getTitle()​

Возвращает string - Заголовок нативного окна.

Примечание: Заголовок веб-страницы может отличаться от заголовка нативного окна.

win.setSheetOffset(offsetY[, offsetX]) macOS​

• offsetY Вещественное число
• offsetX Вещественное число (необязательно)

Изменяет точку прикрепления листов на macOS. По умолчанию листы прикрепляются непосредственно под рамкой окна, но вы можете отобразить их под HTML-рендеренной панелью инструментов. Например:

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

const toolbarRect = document.getElementById('toolbar').getBoundingClientRect()
win.setSheetOffset(toolbarRect.height)

win.flashFrame(flag)​

• flag boolean

Запускает или останавливает мигание окна для привлечения внимания пользователя.

win.setSkipTaskbar(skip) macOS Windows​

• skip boolean

Заставляет окно не отображаться в панели задач.

win.setKiosk(flag)​

• flag boolean

Переключает режим киоска.

win.isKiosk()​

Возвращает boolean — находится ли окно в режиме киоска.

win.isTabletMode() Windows​

Возвращает boolean — находится ли окно в режиме планшета Windows 10.

Так как пользователи Windows 10 могут использовать свой ПК как планшет, приложения в этом режиме могут оптимизировать свой интерфейс для планшетов, например, увеличивая панель заголовка и скрывая кнопки панели заголовка.

Этот API возвращает, находится ли окно в режиме планшета, и событие resize может использоваться для прослушивания изменений в режиме планшета.

win.getMediaSourceId()​

Возвращает string — идентификатор окна в формате идентификатора DesktopCapturerSource. Например, "window:1324:0".

Более точно формат window:id:other_id, где id — HWND в Windows, CGWindowID (uint64_t) в macOS и Window (unsigned long) в Linux. other_id используется для идентификации содержимого веб-страниц (вкладок) в пределах одного окна верхнего уровня.

win.getNativeWindowHandle()​

Возвращает Buffer — платформозависимую дескриптор окна.

Тип дескриптора — HWND в Windows, NSView* в macOS и Window (unsigned long) в Linux.

win.hookWindowMessage(message, callback) Windows​

• message Целое число
• callback Функция
  • wParam любой — wParam, переданный в WndProc
  • lParam любой — lParam, переданный в WndProc

Подключает обработчик сообщения окна. Функция callback вызывается при получении сообщения в WndProc.

win.isWindowMessageHooked(message) Windows​

• message Целое число

Возвращает boolean — true или false в зависимости от того, подключен ли обработчик сообщения.

win.unhookWindowMessage(message) Windows​

• message Целое число

Отключает обработчик сообщения окна.

win.unhookAllWindowMessages() Windows​

Отключает все обработчики сообщений окна.

win.setRepresentedFilename(filename) macOS​

• filename строка

Устанавливает путь к файлу, который представляет окно, и значок файла будет отображаться в строке заголовка окна.

win.getRepresentedFilename() macOS​

Возвращает string — путь к файлу, который представляет окно.

win.setDocumentEdited(edited) macOS​

• edited boolean

Указывает, был ли изменён документ окна, и значок в строке заголовка станет серым, если значение будет true.

win.isDocumentEdited() macOS​

Возвращает boolean — был ли изменён документ окна.

win.focusOnWebView()​

win.blurWebView()​

win.capturePage([rect])​

• rect Прямоугольник (необязательно) — границы для захвата

Возвращает Promise<NativeImage> — разрешает NativeImage

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

win.loadURL(url[, options])​

• url строка
• options Объект (необязательно)
  • httpReferrer (строка | Referrer) (необязательно) — URL HTTP Referrer.
  • userAgent строка (необязательно) — пользовательский агент, инициализировавший запрос.
  • extraHeaders строка (необязательно) — дополнительные заголовки, разделенные "\n"
  • postData (UploadRawData | UploadFile)[] (необязательно)
  • baseURLForDataURL строка (необязательно) — базовый URL (с завершающим разделителем пути) для файлов, которые должны быть загружены по ссылке data URL. Это необходимо только если указанный url — ссылка data URL и необходимо загрузить другие файлы.

Возвращает Promise<void> — промис разрешится, когда страница закончит загрузку (см. did-finish-load), и отклонится, если страница не загрузится (см. did-fail-load).

Аналогично webContents.loadURL(url[, options]).

url может быть удалённым адресом (например, http://) или путём к локальному HTML-файлу, использующему протокол file://.

Для обеспечения правильного форматирования URL-адресов файлов рекомендуется использовать метод Node url.format:

const url = require('url').format({
  protocol: 'file',
  slashes: true,
  pathname: require('path').join(__dirname, 'index.html')
})

win.loadURL(url)

Вы можете загрузить URL-адрес с помощью запроса POST с данными в формате URL-кодирования, выполнив следующие действия:

win.loadURL('http://localhost:8000/post', {
  postData: [{
    type: 'rawData',
    bytes: Buffer.from('hello=world')
  }],
  extraHeaders: 'Content-Type: application/x-www-form-urlencoded'
})

win.loadFile(filePath[, options])​

• filePath строка
• options Объект (необязательно)
  • query Record<string, string> (необязательно) — передаётся в url.format().
  • search строка (необязательно) — передаётся в url.format().
  • hash строка (необязательно) — передаётся в url.format().

Возвращает Promise<void> — промис разрешится, когда страница закончит загрузку (см. did-finish-load), и отклонится, если страница не загрузится (см. did-fail-load).

Аналогично webContents.loadFile, filePath должен быть путём к HTML-файлу относительно корня приложения. См. документацию по webContents для получения дополнительной информации.

win.reload()​

Аналогично webContents.reload.

win.setMenu(menu) Linux Windows​

• menu Меню | null

Устанавливает menu в качестве строковой панели меню окна.

win.removeMenu() Linux Windows​

Удаляет строковую панель меню окна.

win.setProgressBar(progress[, options])​

• progress Double
• options Объект (необязательно)
  • mode строка Windows - Режим полосы прогресса. Может быть none, normal, indeterminate, error или paused.

Устанавливает значение прогресса в полосе прогресса. Допустимый диапазон [0, 1.0].

Удалить полосу прогресса, когда прогресс < 0; Переключиться на режим неопределенного прогресса, когда прогресс > 1.

В Linux поддерживается только среда рабочего стола Unity, вам необходимо указать имя файла *.desktop в поле desktopName в package.json. По умолчанию используется {app.name}.desktop.

В Windows можно передать режим. Допустимые значения none, normal, indeterminate, error, и paused. Если вы вызываете setProgressBar без установленного режима (но со значением в допустимом диапазоне), предполагается normal.

win.setOverlayIcon(overlay, description) Windows​

• overlay NativeImage | null - значок для отображения в правом нижнем углу значка значка панели задач. Если этот параметр null, наложение очищается
• description строка - описание, которое будет предоставлено экранным чтецом системы доступности

Устанавливает наложение 16 x 16 пикселей на текущий значок панели задач, обычно используемое для передачи какого-либо статуса приложения или для пассивного уведомления пользователя.

win.setHasShadow(hasShadow)​

• hasShadow логическое значение

Устанавливает, должен ли у окна быть отступ.

win.hasShadow()​

Возвращает boolean - Имеет ли окно отступ.

win.setOpacity(opacity) Windows macOS​

• opacity число - от 0,0 (полностью прозрачное) до 1,0 (полностью непрозрачное)

Устанавливает непрозрачность окна. В Linux ничего не делает. Значения чисел вне границ ограничиваются диапазоном [0, 1].

win.getOpacity()​

Возвращает number - от 0,0 (полностью прозрачное) до 1,0 (полностью непрозрачное). В Linux всегда возвращает 1.

win.setShape(rects) Windows Linux Экспериментальная​

• rects Прямоугольник[] - Устанавливает форму окна. Передача пустого списка возвращает окну прямоугольную форму.

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

win.setThumbarButtons(buttons) Windows​

• buttons ThumbarButton[]

Возвращает boolean - Были ли успешно добавлены кнопки

Добавляет панель инструментов миниатюр с указанным набором кнопок к миниатюре изображения окна в макете кнопки панели задач. Возвращает объект boolean, указывающий, была ли миниатюра добавлена успешно.

Количество кнопок на панели инструментов миниатюр не должно превышать 7 из-за ограниченного пространства. После настройки панели инструментов миниатюр панель инструментов удалить нельзя из-за ограничений платформы. Но вы можете вызвать API с пустым массивом, чтобы очистить кнопки.

buttons — массив объектов Button:

• Button Объект
  • icon NativeImage - значок, отображаемый на панели инструментов миниатюр.
  • click Функция
  • tooltip строка (необязательно) - текст подсказки кнопки.
  • flags массив строк (необязательно) - Управление определенными состояниями и поведением кнопки. По умолчанию ['enabled'].

flags — массив, который может содержать следующие string:

• enabled - Кнопка активна и доступна пользователю.
• disabled - Кнопка отключена. Она присутствует, но имеет визуальное состояние, указывающее, что она не отреагирует на действия пользователя.
• dismissonclick - При нажатии кнопки окно миниатюры закрывается немедленно.
• nobackground - Не рисовать границу кнопки, использовать только изображение.
• hidden - Кнопка не отображается пользователю.
• noninteractive - Кнопка включена, но не интерактивна; состояние нажатия кнопки не отображается. Это значение предназначено для случаев, когда кнопка используется в уведомлении.

win.setThumbnailClip(region) Windows​

• region Прямоугольник - область окна

Устанавливает область окна, которая будет отображаться как изображение миниатюры при наведении указателя мыши на окно в панели задач. Вы можете сбросить миниатюру до всего окна, указав пустую область: { x: 0, y: 0, width: 0, height: 0 }.

win.setThumbnailToolTip(toolTip) Windows​

• toolTip строка

Устанавливает подсказку, отображаемую при наведении указателя мыши на миниатюру окна в панели задач.

win.setAppDetails(options) Windows​

• options Объект
  • appId строка (необязательно) - идентификатор пользователя приложения окна App User Model ID. Он должен быть установлен, иначе другие параметры не будут иметь эффекта.
  • appIconPath строка (необязательно) - значок повторного запуска окна.
  • appIconIndex Целое число (необязательно) - индекс значка в appIconPath. Игнорируется, когда appIconPath не установлен. По умолчанию 0.
  • relaunchCommand строка (необязательно) - Команда повторного запуска окна.
  • relaunchDisplayName строка (необязательно) - Имя отображения повторного запуска окна.

Устанавливает свойства для кнопки окна на панели задач.

Примечание: relaunchCommand и relaunchDisplayName должны быть установлены вместе. Если один из этих параметров не установлен, то ни один из них не будет использован.

win.showDefinitionForSelection() macOS​

То же, что и webContents.showDefinitionForSelection().

win.setIcon(icon) Windows Linux​

• icon NativeImage | строка

Изменяет значок окна.

win.setWindowButtonVisibility(visible) macOS​

• visible логическое значение

Устанавливает, должны ли быть видны кнопки индикатора состояния окна.

win.setAutoHideMenuBar(hide) Windows Linux​

• hide boolean

Устанавливает, должен ли автоматически скрываться оконная строка меню. После установки оконная строка меню будет отображаться только при нажатии на единственную клавишу Alt.

Если оконная строка меню уже отображается, вызов setAutoHideMenuBar(true) немедленно её не скроет.

win.isMenuBarAutoHide() Windows Linux​

Возвращает boolean — автоматически ли скрывается строка меню.

win.setMenuBarVisibility(visible) Windows Linux​

• visible boolean

Устанавливает, должна ли быть видимой оконная строка меню. Если оконная строка меню имеет режим автоскрытия, пользователи могут всё равно вызвать её, нажав на единственную клавишу Alt.

win.isMenuBarVisible() Windows Linux​

Возвращает boolean — видима ли оконная строка меню.

win.setVisibleOnAllWorkspaces(visible[, options]) macOS Linux​

• visible boolean
• options Object (optional)
  • visibleOnFullScreen boolean (optional) macOS - Устанавливает, должен ли быть видимым окно поверх окон в полноэкранном режиме.
  • skipTransformProcessType boolean (optional) macOS - Вызов setVisibleOnAllWorkspaces по умолчанию преобразует тип процесса между UIElementApplication и ForegroundApplication, чтобы обеспечить правильное поведение. Однако это скроет окно и док на короткое время каждый раз при вызове. Если ваше окно уже имеет тип UIElementApplication, вы можете обойти это преобразование, передав true в skipTransformProcessType.

Устанавливает, должно ли быть окно видимым на всех рабочих столах.

Примечание: Этот API ничего не делает в Windows.

win.isVisibleOnAllWorkspaces() macOS Linux​

Возвращает boolean — видимо ли окно на всех рабочих столах.

Примечание: Этот API всегда возвращает false в Windows.

win.setIgnoreMouseEvents(ignore[, options])​

• ignore boolean
• options Object (optional)
  • forward boolean (optional) macOS Windows - Если true, передает сообщения о перемещении мыши в Chromium, что позволяет использовать события, связанные с мышью, такие как mouseleave. Используется только когда ignore равно true. Если ignore равно false, пересылка всегда отключена независимо от этого значения.

Заставляет окно игнорировать все события мыши.

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

win.setContentProtection(enable) macOS Windows​

• enable boolean

Предотвращает захват содержимого окна другими приложениями.

В macOS устанавливает sharingType окна NSWindow в NSWindowSharingNone. В Windows вызывает SetWindowDisplayAffinity с WDA_EXCLUDEFROMCAPTURE. Для Windows 10 версии 2004 и выше окно будет полностью удалено из захвата; более старые версии Windows ведут себя так, как будто применяется WDA_MONITOR — захватывается чёрное окно.

win.setFocusable(focusable) macOS Windows​

• focusable boolean

Изменяет возможность получения фокуса окном.

В macOS фокус от окна не снимается.

win.isFocusable() macOS Windows​

Возвращает возможность получения фокуса окном.

win.setParentWindow(parent)​

• parent BrowserWindow | null

Устанавливает parent в качестве родительского окна текущего окна. Передача null превратит текущее окно в окно верхнего уровня.

win.getParentWindow()​

Возвращает BrowserWindow | null — родительское окно или null в случае отсутствия родительского окна.

win.getChildWindows()​

Возвращает BrowserWindow[] — все дочерние окна.

win.setAutoHideCursor(autoHide) macOS​

• autoHide boolean

Управляет скрытием курсора при вводе.

win.selectPreviousTab() macOS​

Выбирает предыдущую вкладку, когда включены собственные вкладки и в окне есть другие вкладки.

win.selectNextTab() macOS​

Выбирает следующую вкладку, когда включены собственные вкладки и в окне есть другие вкладки.

win.mergeAllWindows() macOS​

Объединяет все окна в одно окно с несколькими вкладками, когда включены собственные вкладки и открыто более одного окна.

win.moveTabToNewWindow() macOS​

Перемещает текущую вкладку в новое окно, если включены собственные вкладки и в текущем окне более одной вкладки.

win.toggleTabBar() macOS​

Переключает видимость панели вкладок, если включены собственные вкладки и в текущем окне только одна вкладка.

win.addTabbedWindow(browserWindow) macOS​

• browserWindow BrowserWindow

Добавляет окно в качестве вкладки в это окно после вкладки для экземпляра окна.

win.setVibrancy(type) macOS​

• type string | null - Может быть appearance-based, light, dark, titlebar, selection, menu, popover, sidebar, medium-light, ultra-dark, header, sheet, window, hud, fullscreen-ui, tooltip, content, under-window, или under-page. См. документацию macOS для получения дополнительной информации.

Добавляет эффект мерцания к окну браузера. Передача null или пустой строки удалит эффект мерцания из окна.

Обратите внимание, что appearance-based, light, dark, medium-light, и ultra-dark устарели и будут удалены в будущей версии macOS.

win.setTrafficLightPosition(position) macOS​

• position Точка

Устанавливает пользовательское положение кнопок светофора в окне без рамки.

win.getTrafficLightPosition() macOS​

Возвращает Point — пользовательское положение кнопок светофора в окне без рамки.

win.setTouchBar(touchBar) macOS​

• touchBar TouchBar | null

Устанавливает макет TouchBar для текущего окна. Указание null или undefined очищает строку Touch Bar. Этот метод работает только если у устройства есть Touch Bar и оно работает под macOS 10.12.1+.

Примечание: API TouchBar в настоящее время находится в стадии разработки и может быть изменён или удалён в будущих выпусках Electron.

win.setBrowserView(browserView) Экспериментально​

• browserView BrowserView | null - Прикрепляет browserView к win. Если другие BrowserView прикреплены, они будут удалены из этого окна.

win.getBrowserView() Экспериментально​

Возвращает BrowserView | null - BrowserView прикреплённое к win. Возвращает null если оно не прикреплено. Выбрасывает ошибку, если несколько BrowserView прикреплены.

win.addBrowserView(browserView) Экспериментально​

• browserView BrowserView

Заменяющий API для setBrowserView, поддерживающий работу с несколькими BrowserView.

win.removeBrowserView(browserView) Экспериментально​

• browserView BrowserView

win.setTopBrowserView(browserView) Экспериментально​

• browserView BrowserView

Выводит browserView над другими BrowserView прикреплёнными к win. Выбрасывает ошибку, если browserView не прикреплено к win.

win.getBrowserViews() Экспериментально​

Возвращает BrowserView[] - массив всех BrowserView, которые были прикреплены с помощью addBrowserView или setBrowserView.

Примечание: API BrowserView в настоящее время находится в стадии разработки и может быть изменён или удалён в будущих выпусках Electron.

win.setTitleBarOverlay(options) Windows​

• options Объект
  • color Строка (необязательно) Windows - Цвет CSS наложения элементов управления окном, когда оно включено.
  • symbolColor Строка (необязательно) Windows - Цвет CSS символов на наложении элементов управления окном, когда оно включено.
  • height Целое число (необязательно) Windows - Высота строки заголовка и наложения элементов управления окном в пикселях.

В окне, где наложение элементов управления окном уже включено, этот метод обновляет стиль наложения строки заголовка.