Spec-Zone.ru › Electron

webContents

Отображение и управление веб-страницами.

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

webContents — это EventEmitter. Он отвечает за отображение и управление веб-страницей и является свойством объекта BrowserWindow. Пример доступа к объекту webContents. 

const { BrowserWindow } = require('electron')

const win = new BrowserWindow({ width: 800, height: 1500 })
win.loadURL('http://github.com')

const contents = win.webContents
console.log(contents)

Методы​

Эти методы доступны из модуля webContents:

const { webContents } = require('electron')
console.log(webContents)

webContents.getAllWebContents()​

Возвращает WebContents[] — массив всех WebContents экземпляров. Он будет содержать содержимое веб-страниц для всех окон, веб-вью, открытых инструментов разработчика и страниц расширения инструментов разработчика.

webContents.getFocusedWebContents()​

Возвращает WebContents | null — содержимое веб-страницы, на которой сфокусирован этот процесс, в противном случае возвращает null.

webContents.fromId(id)​

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

Возвращает WebContents | undefined — экземпляр WebContents с заданным идентификатором или undefined , если нет WebContents, связанного с этим идентификатором.

webContents.fromDevToolsTargetId(targetId)​

  • targetId строка - TargetID протокола Chrome DevTools TargetID, связанный с экземпляром WebContents.

Возвращает WebContents | undefined — экземпляр WebContents с заданным TargetID или undefined , если нет WebContents, связанного с этим TargetID.

При взаимодействии с протоколом Chrome DevTools может быть полезно найти экземпляр WebContents по его присвоенному TargetID.

async function lookupTargetId (browserWindow) {
  const wc = browserWindow.webContents
  await wc.debugger.attach('1.3')
  const { targetInfo } = await wc.debugger.sendCommand('Target.getTargetInfo')
  const { targetId } = targetInfo
  const targetWebContents = await webContents.fromDevToolsTargetId(targetId)
}

Класс: WebContents​

Отображение и управление содержимым экземпляра BrowserWindow.

Процесс: Основной
Этот класс не экспортируется из модуля 'electron'. Он доступен только в качестве возвращаемого значения других методов API Electron.

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

Событие: 'did-finish-load'​

Вызывается, когда навигация завершена, т.е. индикатор загрузки вкладки перестал вращаться, и событие onload было отправлено.

Событие: 'did-fail-load'​

Возвращает:

  • event Событие
  • errorCode Целое число
  • errorDescription строка
  • validatedURL строка
  • isMainFrame логическое значение
  • frameProcessId Целое число
  • frameRoutingId Целое число

Это событие подобно did-finish-load, но вызывается, когда загрузка завершилась неудачей. Полный список кодов ошибок и их значений доступен здесь.

Событие: 'did-fail-provisional-load'​

Возвращает:

  • event Событие
  • errorCode Целое число
  • errorDescription строка
  • validatedURL строка
  • isMainFrame логическое значение
  • frameProcessId Целое число
  • frameRoutingId Целое число

Это событие подобно did-fail-load, но вызывается, когда загрузка была отменена (например, был вызван window.stop()).

Событие: 'did-frame-finish-load'​

Возвращает:

  • event Событие
  • isMainFrame логическое значение
  • frameProcessId Целое число
  • frameRoutingId Целое число

Вызывается, когда фрейм завершает навигацию.

Событие: 'did-start-loading'​

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

Событие: 'did-stop-loading'​

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

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

Возвращает:

  • event Событие

Вызывается, когда документ в фрейме верхнего уровня загружен.

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

Возвращает:

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

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

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

Возвращает:

  • event Событие
  • favicons строковый массив — массив URL-адресов.

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

Событие: 'new-window' Устаревший​

Возвращает:

  • event NewWindowWebContentsEvent
  • url строка
  • frameName строка
  • disposition строка — Может быть default, foreground-tab, background-tab, new-window, save-to-disk и other.
  • options BrowserWindowConstructorOptions — параметры, которые будут использоваться для создания нового BrowserWindow.
  • additionalFeatures строковый массив — нестандартные функции (функции, не обрабатываемые Chromium или Electron), переданные window.open(). Устаревший, и теперь всегда будет пустым массивом [].
  • referrer Referrer — referrer, который будет передан новому окну. Может или не может привести к отправке заголовка Referer, в зависимости от политики referrer.
  • postBody PostBody (необязательно) — данные POST, которые будут отправлены в новое окно вместе с соответствующими заголовками. Если данные POST не нужно отправлять, значение будет null. Определяется только при создании окна формой, которая установила target=_blank.

Устарело в пользу webContents.setWindowOpenHandler.

Вызывается, когда страница запрашивает открытие нового окна для url. Может быть запрошено window.open или внешней ссылкой, например <a target='_blank'>.

По умолчанию для url создается новое BrowserWindow.

Вызов event.preventDefault() предотвратит автоматическое создание нового BrowserWindow Electron. Если вы вызовете event.preventDefault() и вручную создадите новое BrowserWindow, то должны установить event.newGuest для ссылки на новый экземпляр BrowserWindow. Отсутствие этого может привести к неожиданному поведению. Например:

myBrowserWindow.webContents.on('new-window', (event, url, frameName, disposition, options, additionalFeatures, referrer, postBody) => {
  event.preventDefault()
  const win = new BrowserWindow({
    webContents: options.webContents, // use existing webContents if provided
    show: false
  })
  win.once('ready-to-show', () => win.show())
  if (!options.webContents) {
    const loadOptions = {
      httpReferrer: referrer
    }
    if (postBody != null) {
      const { data, contentType, boundary } = postBody
      loadOptions.postData = postBody.data
      loadOptions.extraHeaders = `content-type: ${contentType}; boundary=${boundary}`
    }

    win.loadURL(url, loadOptions) // existing webContents will be navigated automatically
  }
  event.newGuest = win
})

Событие: 'did-create-window'​

Возвращает:

  • window BrowserWindow
  • details Объект
    • url string — URL созданного окна.
    • frameName string — Имя, присвоенное созданному окну в вызове window.open().
    • options BrowserWindowConstructorOptions — Параметры, используемые для создания BrowserWindow. Они объединяются в порядке убывания приоритета: распаршенные параметры из строки features из window.open(), параметры webPreferences, относящиеся к безопасности, унаследованные от родительского элемента, и параметры, предоставленные в webContents.setWindowOpenHandler. Нераспознанные параметры не отфильтровываются.
    • referrer Referrer — Ссылка, которая будет передана новому окну. Может или не может привести к отправке заголовка Referer, в зависимости от политики ссылки.
    • postBody PostBody (необязательно) — Данные POST, которые будут отправлены в новое окно вместе с соответствующими заголовками. Если данные POST не нужно отправлять, значение будет null. Определяется только при создании окна с помощью формы, которая установила target=_blank.
    • disposition string — Может быть default, foreground-tab, background-tab, new-window, save-to-disk и other.

Имеет место после успешного создания окна через window.open в рендере. Не излучается, если создание окна отменено из webContents.setWindowOpenHandler.

Дополнительные сведения и способы использования в сочетании с webContents.setWindowOpenHandler см. в window.open().

Событие: 'will-navigate'​

Возвращает:

  • event Событие
  • url string

Издается, когда пользователь или страница хотят начать навигацию. Это может произойти при изменении объекта window.location или щелчке пользователем ссылки на странице.

Это событие не будет излучаться при программной инициации навигации с помощью API, таких как webContents.loadURL и webContents.back.

Также оно не издается для навигации внутри страницы, например, при нажатии на ссылки-якоря или обновлении window.location.hash. Для этой цели используйте событие did-navigate-in-page.

Вызов event.preventDefault() предотвратит навигацию.

Событие: 'did-start-navigation'​

Возвращает:

  • event Событие
  • url string
  • isInPlace boolean
  • isMainFrame boolean
  • frameProcessId Целое число
  • frameRoutingId Целое число

Издается, когда любое окно (включая основное) начинает навигацию. isInPlace будет true для навигации внутри страницы.

Событие: 'will-redirect'​

Возвращает:

  • event Событие
  • url string
  • isInPlace boolean
  • isMainFrame boolean
  • frameProcessId Целое число
  • frameRoutingId Целое число

Издается при перенаправлении со стороны сервера во время навигации. Например, перенаправление 302.

Это событие будет издано после did-start-navigation и всегда перед событием did-redirect-navigation для той же навигации.

Вызов event.preventDefault() предотвратит навигацию (а не только перенаправление).

Событие: 'did-redirect-navigation'​

Возвращает:

  • event Событие
  • url string
  • isInPlace boolean
  • isMainFrame boolean
  • frameProcessId Целое число
  • frameRoutingId Целое число

Издается после перенаправления со стороны сервера во время навигации. Например, перенаправление 302.

Это событие нельзя предотвратить. Если вы хотите предотвратить перенаправления, обратитесь к событию will-redirect выше.

Событие: 'did-navigate'​

Возвращает:

  • event Событие
  • url string
  • httpResponseCode Целое число — -1 для навигаций, не относящихся к HTTP
  • httpStatusText string — пустая строка для навигаций, не относящихся к HTTP

Издается при завершении навигации основного фрейма.

Это событие не издается при навигации внутри страницы, например, при нажатии на ссылки-якоря или обновлении window.location.hash. Для этой цели используйте событие did-navigate-in-page.

Событие: 'did-frame-navigate'​

Возвращает:

  • event Событие
  • url string
  • httpResponseCode Целое число — -1 для навигаций, не относящихся к HTTP
  • httpStatusText string — пустая строка для навигаций, не относящихся к HTTP,
  • isMainFrame boolean
  • frameProcessId Целое число
  • frameRoutingId Целое число

Издается при завершении навигации любого фрейма.

Это событие не издается при навигации внутри страницы, например, при нажатии на ссылки-якоря или обновлении window.location.hash. Для этой цели используйте событие did-navigate-in-page.

Событие: 'did-navigate-in-page'​

Возвращает:

  • event Событие
  • url string
  • isMainFrame boolean
  • frameProcessId Целое число
  • frameRoutingId Целое число

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

При навигации внутри страницы URL страницы изменяется, но не происходит навигации за пределы страницы. Примеры таких ситуаций — нажатие на ссылки-якоря или срабатывание события hashchange DOM.

Событие: 'will-prevent-unload'​

Возвращает:

  • event Событие

Издается, когда обработчик события beforeunload пытается отменить загрузку страницы.

Вызов event.preventDefault() проигнорирует обработчик события beforeunload и позволит загрузить страницу.

const { BrowserWindow, dialog } = require('electron')
const win = new BrowserWindow({ width: 800, height: 600 })
win.webContents.on('will-prevent-unload', (event) => {
  const choice = dialog.showMessageBoxSync(win, {
    type: 'question',
    buttons: ['Leave', 'Stay'],
    title: 'Do you want to leave this site?',
    message: 'Changes you made may not be saved.',
    defaultId: 0,
    cancelId: 1
  })
  const leave = (choice === 0)
  if (leave) {
    event.preventDefault()
  }
})

Примечание: Это событие будет издано для BrowserViews , но не будет учтено — это потому, что мы не связываем жизненный цикл BrowserView с его собственным BrowserWindow, если он есть, в соответствии со спецификацией.

Событие: 'crashed' Устаревшее​

Возвращает:

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

Издается при сбое или завершении процесса рендеринга.

Устаревшее: Это событие заменено событием render-process-gone , которое содержит более подробную информацию о причинах исчезновения процесса рендеринга. Это не всегда связано с ошибкой. Логическое значение killed можно заменить проверкой reason === 'killed' при переключении на это событие.

Событие: 'render-process-gone'​

Возвращает:

  • event Событие
  • details Объект
    • reason string — Причина исчезновения процесса рендеринга. Возможные значения:
      • clean-exit — Процесс завершился с кодом выхода 0
      • abnormal-exit — Процесс завершился с ненулевым кодом выхода
      • killed — Процесс был завершён внешним сигналом SIGTERM или иным образом
      • crashed — Процесс завершился с ошибкой
      • oom — Процесс завершился из-за нехватки памяти
      • launch-failed — Процесс не был успешно запущен
      • integrity-failure — Проверка целостности кода Windows завершилась ошибкой
    • exitCode Целое число — Код выхода процесса, если reason имеет значение launch-failed, в таком случае exitCode будет платформенно-специфическим кодом ошибки запуска.

Издается, когда процесс рендеринга неожиданно завершается. Обычно это происходит из-за сбоя или завершения процесса.

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

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

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

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

Событие: 'plugin-crashed'​

Возвращает:

  • event Событие
  • name string
  • version string

Издается, когда процесс плагина завершился с ошибкой.

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

Издается, когда webContents уничтожен.

Событие: 'before-input-event'​

Возвращает:

  • event Событие
  • input Объект - свойства ввода.
    • type строка - Либо keyUp, либо keyDown.
    • key строка - Эквивалент KeyboardEvent.key.
    • code строка - Эквивалент KeyboardEvent.code.
    • isAutoRepeat логическое значение - Эквивалент KeyboardEvent.repeat.
    • isComposing логическое значение - Эквивалент KeyboardEvent.isComposing.
    • shift логическое значение - Эквивалент KeyboardEvent.shiftKey.
    • control логическое значение - Эквивалент KeyboardEvent.controlKey.
    • alt логическое значение - Эквивалент KeyboardEvent.altKey.
    • meta логическое значение - Эквивалент KeyboardEvent.metaKey.
    • location число - Эквивалент KeyboardEvent.location.
    • modifiers массив строк - См. InputEvent.modifiers.

Выдаётся перед отправкой событий keydown и keyup на странице. Вызов event.preventDefault предотвратит события страницы keydown/keyup и сокращения меню.

Для предотвращения только сокращений меню используйте setIgnoreMenuShortcuts:

const { BrowserWindow } = require('electron')

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

win.webContents.on('before-input-event', (event, input) => {
  // For example, only enable application menu keyboard shortcuts when
  // Ctrl/Cmd are down.
  win.webContents.setIgnoreMenuShortcuts(!input.control && !input.meta)
})

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

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

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

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

Событие: 'zoom-changed'​

Возвращает:

  • event Событие
  • zoomDirection строка - Может быть in или out.

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

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

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

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

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

Обратите внимание, что на macOS фокус означает, что WebContents является первым ответчиком окна, поэтому переключение фокуса между окнами не будет вызывать события focus и blur для WebContents, так как первый ответчик каждого окна не изменяется.

События focus и blur для WebContents следует использовать только для определения изменения фокуса между различными WebContents и BrowserView в одном окне.

Событие: 'devtools-opened'​

Выдаётся при открытии DevTools.

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

Выдаётся при закрытии DevTools.

Событие: 'devtools-focused'​

Выдаётся, когда DevTools получает фокус / открывается.

Событие: 'certificate-error'​

Возвращает:

  • event Событие
  • url строка
  • error строка - Код ошибки.
  • certificate Сертификат
  • callback Функция
    • isTrusted логическое значение - Указывает, можно ли считать сертификат надёжным.
  • isMainFrame логическое значение

Выдаётся при неудачной проверке certificate для url.

Использование аналогично событию certificate-error для app.

Событие: 'select-client-certificate'​

Возвращает:

  • event Событие
  • url URL
  • certificateList Сертификат[]
  • callback Функция
    • certificate Сертификат - Должен быть сертификатом из указанного списка.

Выдаётся при запросе клиентского сертификата.

Использование аналогично событию select-client-certificate для app.

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

Возвращает:

  • event Событие
  • authenticationResponseDetails Объект
    • url URL
  • authInfo Объект
    • isProxy логическое значение
    • scheme строка
    • host строка
    • port Целое число
    • realm строка
  • callback Функция
    • username строка (необязательно)
    • password строка (необязательно)

Выдаётся, когда webContents хочет выполнить аутентификацию basic.

Использование аналогично событию login для app.

Событие: 'found-in-page'​

Возвращает:

  • event Событие
  • result Объект
    • requestId Целое число
    • activeMatchOrdinal Целое число - Позиция активного совпадения.
    • matches Целое число - Количество совпадений.
    • selectionArea Прямоугольник - Координаты первой области совпадения.
    • finalUpdate логическое значение

Выдаётся, когда доступен результат запроса [webContents.findInPage].

Событие: 'media-started-playing'​

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

Событие: 'media-paused'​

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

Событие: 'did-change-theme-color'​

Возвращает:

  • event Событие
  • color (строка | null) - Цвет темы в формате '#rrggbb'. Он равен null при отсутствии цвета темы.

Выдаётся, когда цвет темы страницы меняется. Обычно это происходит при встрече тега meta:

<meta name='theme-color' content='#ff0000'>

Событие: 'update-target-url'​

Возвращает:

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

Выдаётся, когда курсор мыши перемещается над ссылкой или фокус клавиатуры перемещается на ссылку.

Событие: 'cursor-changed'​

Возвращает:

  • event Событие
  • type строка
  • image NativeImage (необязательно)
  • scale Вещественное число (необязательно) - коэффициент масштабирования для пользовательского курсора.
  • size Размер (необязательно) - размер image.
  • hotspot Точка (необязательно) - координаты точки привязки пользовательского курсора.

Издаётся, когда тип курсора изменяется. Параметр type может быть default, crosshair, pointer, text, wait, help, e-resize, n-resize, ne-resize, nw-resize, s-resize, se-resize, sw-resize, w-resize, ns-resize, ew-resize, nesw-resize, nwse-resize, col-resize, row-resize, m-panning, e-panning, n-panning, ne-panning, nw-panning, s-panning, se-panning, sw-panning, w-panning, move, vertical-text, cell, context-menu, alias, progress, nodrop, copy, none, not-allowed, zoom-in, zoom-out, grab, grabbing или custom.

Если параметр type равен custom, параметр image будет содержать пользовательское изображение курсора в NativeImage, а scale, size и hotspot будут содержать дополнительную информацию о пользовательском курсоре.

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

Возвращает:

  • event Событие
  • params Объект
    • x Целое число - координата x.
    • y Целое число - координата y.
    • frame WebFrameMain - Фрейм, из которого был вызван контекстное меню.
    • linkURL строка - URL ссылки, которая содержит узел, на котором было вызвано контекстное меню.
    • linkText строка - Текст, связанный со ссылкой. Может быть пустой строкой, если содержимое ссылки - изображение.
    • pageURL строка - URL главной страницы, на которой было вызвано контекстное меню.
    • frameURL строка - URL подфрейма, на котором было вызвано контекстное меню.
    • srcURL строка - Исходный URL элемента, на котором было вызвано контекстное меню. Элементы с исходными URL - это изображения, аудио и видео.
    • mediaType строка - Тип узла, на котором было вызвано контекстное меню. Может быть none, image, audio, video, canvas, file или plugin.
    • hasImageContents логическое значение - Указывает, было ли контекстное меню вызвано на изображении, содержащем непустые данные.
    • isEditable логическое значение - Указывает, является ли контекст редактируемым.
    • selectionText строка - Текст выделения, на котором было вызвано контекстное меню.
    • titleText строка - Текст заголовка выделения, на котором было вызвано контекстное меню.
    • altText строка - Текст Alt выделения, на котором было вызвано контекстное меню.
    • suggestedFilename строка - Предлагаемое имя файла для использования при сохранении файла через опцию «Сохранить ссылку как» контекстного меню.
    • selectionRect Прямоугольник - Прямоугольник, представляющий координаты выделения в пространстве документа.
    • selectionStartOffset число - Начальная позиция текста выделения.
    • referrerPolicy Политика пересылки - Политика пересылки фрейма, на котором вызвано меню.
    • misspelledWord строка - Неправильно написанное слово под курсором, если оно есть.
    • dictionarySuggestions массив строк - Массив предложенных слов для замены misspelledWord. Доступен только в случае неправильно написанного слова и включённого орфографического контроля.
    • frameCharset строка - Кодировка символов фрейма, на котором было вызвано меню.
    • inputFieldType строка - Если контекстное меню было вызвано на поле ввода, тип этого поля. Возможные значения - none, plainText, password, other.
    • spellcheckEnabled логическое значение - Если контекст редактируемый, включён ли орфографический контроль.
    • menuSourceType строка - Источник ввода, который вызвал контекстное меню. Может быть none, mouse, keyboard, touch, touchMenu, longPress, longTap, touchHandle, stylus, adjustSelection или adjustSelectionReset.
    • mediaFlags Объект - Флаги для элемента мультимедиа, на котором было вызвано контекстное меню.
      • inError логическое значение - Сообщает, завис ли элемент мультимедиа.
      • isPaused логическое значение - Сообщает, приостановлен ли элемент мультимедиа.
      • isMuted логическое значение - Сообщает, выключен ли звук элемента мультимедиа.
      • hasAudio логическое значение - Содержит ли элемент мультимедиа аудио.
      • isLooping логическое значение - Сообщает, циклически ли повторяется элемент мультимедиа.
      • isControlsVisible логическое значение - Сообщает, отображаются ли элементы управления для элемента мультимедиа.
      • canToggleControls логическое значение - Сообщает, можно ли переключать элементы управления элемента мультимедиа.
      • canPrint логическое значение - Можно ли распечатать элемент мультимедиа.
      • canSave логическое значение - Можно ли загрузить элемент мультимедиа.
      • canShowPictureInPicture логическое значение - Может ли элемент мультимедиа отображать режим «картинка в картинке».
      • isShowingPictureInPicture логическое значение - Отображается ли элемент мультимедиа в режиме «картинка в картинке».
      • canRotate логическое значение - Можно ли повернуть элемент мультимедиа.
      • canLoop логическое значение - Можно ли циклически повторять элемент мультимедиа.
    • editFlags Объект - Эти флаги указывают, считает ли рендерер, что может выполнить соответствующее действие.
      • canUndo логическое значение - Считает ли рендерер, что может отменить действие.
      • canRedo логическое значение - Считает ли рендерер, что может повторить действие.
      • canCut логическое значение - Считает ли рендерер, что может вырезать.
      • canCopy логическое значение - Считает ли рендерер, что может скопировать.
      • canPaste логическое значение - Считает ли рендерер, что может вставить.
      • canDelete логическое значение - Считает ли рендерер, что может удалить.
      • canSelectAll логическое значение - Считает ли рендерер, что может выбрать всё.
      • canEditRichly логическое значение - Считает ли рендерер, что может редактировать текст в формате HTML.

Издаётся, когда появляется новое контекстное меню, которое необходимо обработать.

Событие: 'select-bluetooth-device'​

Возвращает:

  • event Событие
  • devices BluetoothDevice[]
  • callback Функция
    • deviceId строка

Издаётся, когда необходимо выбрать устройство Bluetooth при вызове navigator.bluetooth.requestDevice. Для использования API webBluetooth должен быть включён navigator.bluetooth. Если event.preventDefault не вызывается, будет выбран первый доступный девайс. callback должен быть вызван с deviceId для выбора, передача пустой строки в callback отменит запрос.

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

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

let win = null
app.commandLine.appendSwitch('enable-experimental-web-platform-features')

app.whenReady().then(() => {
  win = new BrowserWindow({ width: 800, height: 600 })
  win.webContents.on('select-bluetooth-device', (event, deviceList, callback) => {
    event.preventDefault()
    const result = deviceList.find((device) => {
      return device.deviceName === 'test'
    })
    if (!result) {
      callback('')
    } else {
      callback(result.deviceId)
    }
  })
})

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

Возвращает:

  • event Событие
  • dirtyRect Прямоугольник
  • image NativeImage - Данные изображения всего фрейма.

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

const { BrowserWindow } = require('electron')

const win = new BrowserWindow({ webPreferences: { offscreen: true } })
win.webContents.on('paint', (event, dirty, image) => {
  // updateBitmap(dirty, image.getBitmap())
})
win.loadURL('http://github.com')

Событие: 'devtools-reload-page'​

Издаётся, когда окно разработчика инструктирует webContents перезагрузить страницу

Событие: 'will-attach-webview'​

Возвращает:

  • event Событие
  • webPreferences WebPreferences - Параметры веб-страницы, которые будут использоваться гостевой страницей. Этот объект можно изменить для настройки параметров гостевой страницы.
  • params Record<string, string> - Другие <webview> параметры, такие как src URL. Этот объект можно изменить для настройки параметров гостевой страницы.

Издаётся, когда содержимое веб-страницы <webview> подключается к этому содержимому веб-страницы. Вызов event.preventDefault() уничтожит гостевую страницу.

Это событие можно использовать для настройки webPreferences для webContents <webview> перед её загрузкой и предоставляет возможность задать настройки, которые нельзя задать через атрибуты <webview>.

Событие: 'did-attach-webview'​

Возвращает:

  • event Событие
  • webContents WebContents - Содержимое гостевой веб-страницы, используемое <webview>.

Издаётся, когда <webview> подключена к данному содержимому веб-страницы.

Событие: 'console-message'​

Возвращает:

  • event Событие
  • level Целое число - Уровень ведения журнала, от 0 до 3. В порядке соответствует verbose, info, warning и error.
  • message строка - Само сообщение консоли
  • line Целое число - Номер строки источника, вызвавшего это сообщение консоли
  • sourceId строка

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

Событие: 'preload-error'​

Возвращает:

  • event Событие
  • preloadPath строка
  • error Ошибка

Выпускается, когда скрипт загрузки preloadPath выбрасывает необработанное исключение error.

Событие: 'ipc-message'​

Возвращает:

  • event Событие
  • channel строка
  • ...args any[]

Выпускается, когда процесс рендеринга отправляет асинхронное сообщение через ipcRenderer.send().

Событие: 'ipc-message-sync'​

Возвращает:

  • event Событие
  • channel строка
  • ...args any[]

Выпускается, когда процесс рендеринга отправляет синхронное сообщение через ipcRenderer.sendSync().

Событие: 'preferred-size-changed'​

Возвращает:

  • event Событие
  • preferredSize Размер - Минимальный размер, необходимый для размещения макета документа — без необходимости прокрутки.

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

Это событие будет выпущено только тогда, когда enablePreferredSizeMode установлено в true в webPreferences.

Событие: 'frame-created'​

Возвращает:

  • event Событие
  • details Объект
    • frame WebFrameMain

Выпускается, когда mainFrame, <iframe>, или вложенный <iframe> загружается на странице.

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

contents.loadURL(url[, options])​

  • url строка
  • options Объект (необязательно)
    • httpReferrer (строка | Ссылка) (необязательно) - URL HTTP-ссылки.
    • postData (UploadRawData | UploadFile)[] (необязательно)
    • baseURLForDataURL строка (необязательно) - Базовый URL (с заключительным разделителем пути) для файлов, которые должны загружаться по URL данных. Это необходимо только в том случае, если указанный url является URL данных и ему нужно загрузить другие файлы.

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

Загружает url в окне. url должен содержать префикс протокола, например, http:// или file://.

const { webContents } = require('electron')
const options = { extraHeaders: 'pragma: no-cache\n' }
webContents.loadURL('https://github.com', options)

contents.loadFile(filePath[, options])​

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

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

Загружает указанный файл в окно, filePath должен быть путем к HTML-файлу, относительно корня вашего приложения. Например, структура приложения подобна этой:

| root
| - package.json
| - src
|   - main.js
|   - index.html

Для этого потребуются код подобный этому

win.loadFile('src/index.html')

contents.downloadURL(url)​

  • url строка

Инициализирует загрузку ресурса по адресу url без перехода. Событие will-download объекта session будет активировано.

contents.getURL()​

Возвращает string — URL текущей веб-страницы.

const { BrowserWindow } = require('electron')
const win = new BrowserWindow({ width: 800, height: 600 })
win.loadURL('http://github.com').then(() => {
  const currentURL = win.webContents.getURL()
  console.log(currentURL)
})

contents.getTitle()​

Возвращает string — заголовок текущей веб-страницы.

contents.isDestroyed()​

Возвращает boolean — является ли веб-страница уничтоженной.

contents.focus()​

Фокусирует веб-страницу.

contents.isFocused()​

Возвращает boolean — имеет ли веб-страница фокус.

contents.isLoading()​

Возвращает boolean — загружаются ли ресурсы веб-страницы.

contents.isLoadingMainFrame()​

Возвращает boolean — загружается ли основной фрейм (а не только фреймы или фреймы внутри него).

contents.isWaitingForResponse()​

Возвращает boolean — ожидает ли веб-страница первого ответа от основного ресурса страницы.

contents.stop()​

Останавливает любые ожидающие переходы.

contents.reload()​

Перезагружает текущую веб-страницу.

contents.reloadIgnoringCache()​

Перезагружает текущую страницу, игнорируя кэш.

contents.canGoBack()​

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

contents.canGoForward()​

Возвращает boolean — может ли браузер перейти к следующей веб-странице.

contents.canGoToOffset(offset)​

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

Возвращает boolean — может ли веб-страница перейти к offset.

contents.clearHistory()​

Очищает историю навигации.

contents.goBack()​

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

END_OF_DOCUMENT_MARKER

contents.goForward()​

Переводит браузер вперёд на веб-страницу.

contents.goToIndex(index)​

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

Перенаправляет браузер на указанный абсолютный индекс веб-страницы.

contents.goToOffset(offset)​

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

Переходит к указанному смещению от «текущей записи».

contents.isCrashed()​

Возвращает boolean — Состояние зависания процесса рендеринга.

contents.forcefullyCrashRenderer()​

Принудительно завершает процесс рендеринга, который в настоящее время отображает эту webContents. Это вызовет событие render-process-gone с reason=killed || reason=crashed. Обратите внимание, что некоторые webContents используют общие процессы рендеринга, поэтому вызов этого метода может также привести к зависанию хост-процесса для других webContents.

Вызов reload() сразу после вызова этого метода заставит перезагрузку произойти в новом процессе. Это следует использовать, когда этот процесс нестабилен или неприменим, например, для восстановления после события unresponsive.

contents.on('unresponsive', async () => {
  const { response } = await dialog.showMessageBox({
    message: 'App X has become unresponsive',
    title: 'Do you want to try forcefully reloading the app?',
    buttons: ['OK', 'Cancel'],
    cancelId: 1
  })
  if (response === 0) {
    contents.forcefullyCrashRenderer()
    contents.reload()
  }
})

contents.setUserAgent(userAgent)​

  • userAgent строка

Переопределяет пользовательский агент для этой веб-страницы.

contents.getUserAgent()​

Возвращает string — пользовательский агент для этой веб-страницы.

contents.insertCSS(css[, options])​

  • css строка
  • options Объект (необязательно)
    • cssOrigin строка (необязательно) — Может быть либо 'user', либо 'author'. Устанавливает источник каскада вставленного стилевого листа. По умолчанию — 'author'.

Возвращает Promise<string> — обещание, которое разрешается с ключом для вставленного CSS, который позже можно использовать для удаления CSS с помощью contents.removeInsertedCSS(key).

Вставляет CSS на текущую веб-страницу и возвращает уникальный ключ для вставленного стилевого листа.

contents.on('did-finish-load', () => {
  contents.insertCSS('html, body { background-color: #f00; }')
})

contents.removeInsertedCSS(key)​

  • key строка

Возвращает Promise<void> — разрешается, если удаление прошло успешно.

Удаляет вставленный CSS с текущей веб-страницы. Стилевой лист идентифицируется по его ключу, который возвращается из contents.insertCSS(css).

contents.on('did-finish-load', async () => {
  const key = await contents.insertCSS('html, body { background-color: #f00; }')
  contents.removeInsertedCSS(key)
})

contents.executeJavaScript(code[, userGesture])​

  • code строка
  • userGesture логическое значение (необязательно) — По умолчанию false.

Возвращает Promise<any> — обещание, которое разрешается с результатом выполненного кода или отклоняется, если результат кода — отклоненное обещание.

Вычисляет code на странице.

В окне браузера некоторые HTML-API, такие как requestFullScreen, могут вызываться только с помощью жеста пользователя. Установка userGesture в true устранит это ограничение.

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

contents.executeJavaScript('fetch("https://jsonplaceholder.typicode.com/users/1").then(resp => resp.json())', true)
  .then((result) => {
    console.log(result) // Will be the JSON object from the fetch call
  })

contents.executeJavaScriptInIsolatedWorld(worldId, scripts[, userGesture])​

  • worldId Целое число — ID мира для выполнения javascript, 0 — это мир по умолчанию, 999 — мир, используемый функцией Electron's contextIsolation. Вы можете указать здесь любое целое число.
  • scripts WebSource[]
  • userGesture логическое значение (необязательно) — По умолчанию false.

Возвращает Promise<any> — обещание, которое разрешается с результатом выполненного кода или отклоняется, если результат кода — отклоненное обещание.

Функционирует как executeJavaScript , но вычисляет scripts в изолированном контексте.

contents.setIgnoreMenuShortcuts(ignore)​

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

Игнорировать сочетания клавиш меню приложения, пока этот веб-контент фокусируется.

contents.setWindowOpenHandler(handler)​

  • handler Функция<{действие: 'отклонить'} | {действие: 'разрешить', параметрыОкнаБраузера?: BrowserWindowConstructorOptions}>

    • details Объект
      • url строка — результирующая версия URL, переданного window.open(). Например, открытие окна с window.open('foo') даст что-то вроде https://the-origin/the/current/path/foo.
      • frameName строка — Имя окна, предоставленное в window.open()
      • features строка — Список параметров окна, разделенных запятыми, предоставленных window.open().
      • disposition строка — Может быть default, foreground-tab, background-tab, new-window, save-to-disk или other.
      • referrer Referrer — Указатель, который будет передан в новое окно. Может или не может привести к отправке заголовка Referer, в зависимости от политики указателя.
      • postBody PostBody (необязательно) — Данные отправки, которые будут отправлены в новое окно вместе с соответствующими заголовками, которые будут установлены. Если данные отправки не должны отправляться, значение будет null. Определяется только тогда, когда окно создается формой, которая установила target=_blank.

    Возвращает {action: 'deny'} | {action: 'allow', overrideBrowserWindowOptions?: BrowserWindowConstructorOptions} — deny отменяет создание нового окна. allow позволит создать новое окно. Указание overrideBrowserWindowOptions позволяет настроить созданное окно. Возврат нераспознанного значения, такого как null, undefined или объект без распознанного значения 'action', приведет к ошибке в консоли и будет иметь тот же эффект, что и возврат {action: 'deny'}.

Вызывается перед созданием окна, когда запрашивается новое окно рендером, например, с помощью window.open(), ссылки с target="_blank", нажатия на ссылку с нажатой клавишей Shift или отправки формы с <form target="_blank">. Подробнее см. window.open() и способ использования вместе с did-create-window.

contents.setAudioMuted(muted)​

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

Выключить звук на текущей веб-странице.

contents.isAudioMuted()​

Возвращает boolean — Состояние приглушения страницы.

contents.isCurrentlyAudible()​

Возвращает boolean — Состояние воспроизведения аудио.

contents.setZoomFactor(factor)​

  • factor Двойное значение — Коэффициент масштабирования; значение по умолчанию 1,0.

Изменяет коэффициент масштабирования на указанное значение. Коэффициент масштабирования — это процент масштабирования, делённый на 100, таким образом, 300% = 3,0.

Значение коэффициента должно быть больше 0,0.

contents.getZoomFactor()​

Возвращает number — текущий коэффициент масштабирования.

contents.setZoomLevel(level)​

  • level число — Уровень масштабирования.

Изменяет уровень масштабирования на указанный уровень. Исходный размер равен 0, и каждое приращение выше или ниже соответствует увеличению или уменьшению масштаба на 20% по отношению к исходному размеру в пределах от 300% до 50% соответственно. Формула для этого: scale := 1.2 ^ level.

END_OF_DOCUMENT_MARKER

ПРИМЕЧАНИЕ: Политика масштабирования на уровне Chromium — same-origin, что означает, что уровень масштабирования для определённого домена распространяется на все экземпляры окон с тем же домена. Различие URL-адресов окон позволит масштабированию работать по окнам.

contents.getZoomLevel()​

Возвращает number — текущий уровень масштабирования.

contents.setVisualZoomLevelLimits(minimumLevel, maximumLevel)​

  • minimumLevel число
  • maximumLevel число

Возвращает Promise<void>

Устанавливает максимальный и минимальный уровни масштабирования с помощью пинцета.

ПРИМЕЧАНИЕ: Визуальное масштабирование по умолчанию отключено в Electron. Чтобы его включить, вызовите:

contents.setVisualZoomLevelLimits(1, 3)

contents.undo()​

Выполняет команду редактирования undo в веб-странице.

contents.redo()​

Выполняет команду редактирования redo в веб-странице.

contents.cut()​

Выполняет команду редактирования cut в веб-странице.

contents.copy()​

Выполняет команду редактирования copy в веб-странице.

contents.copyImageAt(x, y)​

  • x Целое число
  • y Целое число

Копирует изображение в заданной позиции в буфер обмена.

contents.paste()​

Выполняет команду редактирования paste в веб-странице.

contents.pasteAndMatchStyle()​

Выполняет команду редактирования pasteAndMatchStyle в веб-странице.

contents.delete()​

Выполняет команду редактирования delete в веб-странице.

contents.selectAll()​

Выполняет команду редактирования selectAll в веб-странице.

contents.unselect()​

Выполняет команду редактирования unselect в веб-странице.

contents.replace(text)​

  • text строка

Выполняет команду редактирования replace в веб-странице.

contents.replaceMisspelling(text)​

  • text строка

Выполняет команду редактирования replaceMisspelling в веб-странице.

contents.insertText(text)​

  • text строка

Возвращает Promise<void>

Вставляет text в фокусированный элемент.

contents.findInPage(text[, options])​

  • text строка - Текст для поиска, не должен быть пустым.
  • options Объект (необязательно)
    • forward логическое значение (необязательно) - Направление поиска (вперёд или назад), по умолчанию true.
    • findNext логическое значение (необязательно) - Начать новую сессию поиска. Должно быть true для начальных запросов и false для последующих запросов. По умолчанию false.
    • matchCase логическое значение (необязательно) - Поиск с учётом регистра, по умолчанию false.

Возвращает Integer — идентификатор запроса.

Инициирует поиск всех совпадений text на веб-странице. Результаты запроса можно получить, подписавшись на событие found-in-page.

contents.stopFindInPage(action)​

  • action строка - Указывает действие при завершении запроса [webContents.findInPage].
    • clearSelection - Очистить выделение.
    • keepSelection - Перевести выделение в обычное выделение.
    • activateSelection - Сфокусировать и нажать на узел выделения.

Останавливает любой запрос findInPage для webContents с указанным action.

const { webContents } = require('electron')
webContents.on('found-in-page', (event, result) => {
  if (result.finalUpdate) webContents.stopFindInPage('clearSelection')
})

const requestId = webContents.findInPage('api')
console.log(requestId)

contents.capturePage([rect])​

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

Возвращает Promise<NativeImage> — результат в виде NativeImage

Захватывает снимок страницы в пределах rect. Пропуск rect позволит захватить всю видимую страницу.

contents.isBeingCaptured()​

Возвращает boolean — Захват страницы в данный момент. Возвращает true, если счётчик захвата больше 0.

contents.incrementCapturerCount([size, stayHidden, stayAwake])​

  • size Размер (необязательно) - Предпочтительный размер для захвата.
  • stayHidden логическое значение (необязательно) - Скрыть страницу вместо её отображения.
  • stayAwake логическое значение (необязательно) - Поддерживать систему активной вместо её перехода в спящий режим.

Увеличивает счётчик захвата на 1. Страница считается видимой, когда окно браузера скрыто, а счётчик захвата не равен нулю. Если вы хотите, чтобы страница оставалась скрытой, вы должны установить stayHidden в значение true.

Это также влияет на API видимости страницы.

contents.decrementCapturerCount([stayHidden, stayAwake])​

  • stayHidden логическое значение (необязательно) - Сохранить страницу в скрытом состоянии, вместо видимого.
  • stayAwake логическое значение (необязательно) - Поддерживать систему активной вместо её перехода в спящий режим.

Уменьшает счётчик захвата на 1. Страница перейдёт в скрытое или затенённое состояние, когда её окно браузера скрыто или затенёно, и счётчик захвата достигнет нуля. Если вы хотите уменьшить счётчик скрытых захватчиков, вы должны установить stayHidden в значение true.

contents.getPrinters() Устаревшая​

Получить список системных принтеров.

Возвращает PrinterInfo[]

Устаревшая функция: Следует использовать новый API contents.getPrintersAsync.

contents.getPrintersAsync()​

Получить список системных принтеров.

Возвращает Promise<PrinterInfo[]> — результат в виде PrinterInfo[]

contents.print([options], [callback])​

  • options Объект (необязательно)
    • silent булево (необязательно) - Не спрашивать пользователя о настройках печати. По умолчанию false.
    • printBackground булево (необязательно) - Печатать цвет фона и изображение веб-страницы. По умолчанию false.
    • deviceName строка (необязательно) - Установите имя устройства принтера для использования. Должно быть системным именем, а не «дружественным» именем, например «Brother_QL_820NWB», а не «Brother QL-820NWB».
    • color булево (необязательно) - Установите, будет ли напечатанная веб-страница в цвете или в оттенках серого. По умолчанию true.
    • margins Объект (необязательно)
      • marginType строка (необязательно) - Может быть default, none, printableArea, или custom. Если выбран custom, вам также необходимо указать top, bottom, left, и right.
      • top число (необязательно) - Верхний отступ напечатанной веб-страницы в пикселях.
      • bottom число (необязательно) - Нижний отступ напечатанной веб-страницы в пикселях.
      • left число (необязательно) - Левый отступ напечатанной веб-страницы в пикселях.
      • right число (необязательно) - Правый отступ напечатанной веб-страницы в пикселях.
    • landscape булево (необязательно) - Нужно ли печатать веб-страницу в альбомной ориентации. По умолчанию false.
    • scaleFactor число (необязательно) - Коэффициент масштабирования веб-страницы.
    • pagesPerSheet число (необязательно) - Количество страниц на листе.
    • collate булево (необязательно) - Нужно ли сшивать страницы.
    • copies число (необязательно) - Количество копий веб-страницы для печати.
    • pageRanges Массив объектов (необязательно) - Диапазон страниц для печати. В macOS учитывается только один диапазон.
      • from число - Индекс первой страницы для печати (нумерация с 0).
      • to число - Индекс последней страницы для печати (включительно) (нумерация с 0).
    • duplexMode строка (необязательно) - Установите режим дуплексной печати напечатанной веб-страницы. Может быть simplex, shortEdge, или longEdge.
    • dpi Пара<строка, число> (необязательно)
      • horizontal число (необязательно) - Горизонтальная разрешающая способность (dpi).
      • vertical число (необязательно) - Вертикальная разрешающая способность (dpi).
    • header строка (необязательно) - Строка для печати в качестве заголовка страницы.
    • footer строка (необязательно) - Строка для печати в качестве подвала страницы.
    • pageSize строка | Размер (необязательно) - Укажите размер страницы печатаемого документа. Может быть A3, A4, A5, Legal, Letter, Tabloid или объект, содержащий height.
  • callback Функция (необязательно)
    • success булево - Указывает на успех вызова печати.
    • failureReason строка - Описание ошибки, возвращаемое при ошибке печати.

При передаче пользовательской pageSize, Chromium пытается проверить минимальные значения, специфичные для платформы, для width_microns и height_microns. Ширина и высота должны быть не менее 353 микронов, но могут быть выше на некоторых операционных системах.

Печатает веб-страницу окна. Когда silent установлено в true, Electron выберет стандартный принтер системы, если deviceName пусто, и стандартные настройки печати.

Используйте page-break-before: always; CSS-стиль для принудительной печати на новой странице.

Пример использования:

const options = {
  silent: true,
  deviceName: 'My-Printer',
  pageRanges: [{
    from: 0,
    to: 1
  }]
}
win.webContents.print(options, (success, errorType) => {
  if (!success) console.log(errorType)
})

contents.printToPDF(options)​

  • options Объект
    • headerFooter Пара<строка, строка> (необязательно) - заголовок и подвал для PDF.
      • title строка - Заголовок для PDF.
      • url строка - URL для подвала PDF.
    • landscape булево (необязательно) - true для альбомной, false для книжной ориентации.
    • marginsType Целое число (необязательно) - Указывает тип отступов. Использует 0 для стандартных отступов, 1 для отсутствия отступов и 2 для минимальных отступов.
    • scaleFactor число (необязательно) - Коэффициент масштабирования веб-страницы. Может принимать значения от 0 до 100.
    • pageRanges Пара<строка, число> (необязательно) - Диапазон страниц для печати.
      • from число - Индекс первой страницы для печати (нумерация с 0).
      • to число - Индекс последней страницы для печати (включительно) (нумерация с 0).
    • pageSize строка | Размер (необязательно) - Укажите размер страницы генерируемого PDF. Может быть A3, A4, A5, Legal, Letter, Tabloid или объект, содержащий height и width в микронах.
    • printBackground булево (необязательно) - Печатать ли фоны CSS.
    • printSelectionOnly булево (необязательно) - Печатать только выделенный текст.

Возвращает Promise<Buffer> - Разрешается сгенерированными данными PDF.

Печатает веб-страницу окна как PDF с настраиваемыми параметрами печати Chromium.

landscape будет проигнорировано, если используется CSS at-правило @page в веб-странице.

По умолчанию пустой options будет рассматриваться как:

{
  marginsType: 0,
  printBackground: false,
  printSelectionOnly: false,
  landscape: false,
  pageSize: 'A4',
  scaleFactor: 100
}

Используйте page-break-before: always; CSS-стиль для принудительной печати на новой странице.

Пример webContents.printToPDF:

const { BrowserWindow } = require('electron')
const fs = require('fs')
const path = require('path')
const os = require('os')

const win = new BrowserWindow({ width: 800, height: 600 })
win.loadURL('http://github.com')

win.webContents.on('did-finish-load', () => {
  // Use default printing options
  const pdfPath = path.join(os.homedir(), 'Desktop', 'temp.pdf')
  win.webContents.printToPDF({}).then(data => {
    fs.writeFile(pdfPath, data, (error) => {
      if (error) throw error
      console.log(`Wrote PDF successfully to ${pdfPath}`)
    })
  }).catch(error => {
    console.log(`Failed to write PDF to ${pdfPath}: `, error)
  })
})

contents.addWorkSpace(path)​

  • path строка

Добавляет указанный путь в рабочее пространство DevTools. Должен использоваться после создания DevTools:

const { BrowserWindow } = require('electron')
const win = new BrowserWindow()
win.webContents.on('devtools-opened', () => {
  win.webContents.addWorkSpace(__dirname)
})

contents.removeWorkSpace(path)​

  • path строка

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

contents.setDevToolsWebContents(devToolsWebContents)​

  • devToolsWebContents WebContents

Использует devToolsWebContents как целевой WebContents для отображения DevTools.

devToolsWebContents не должен производить навигацию и не должен использоваться для других целей после вызова.

По умолчанию Electron управляет DevTools, создавая внутреннее WebContents с нативным представлением, над которым у разработчиков очень ограниченный контроль. С помощью метода setDevToolsWebContents разработчики могут использовать любое WebContents для отображения DevTools в нём, включая BrowserWindow, BrowserView и <webview> теги.

Обратите внимание, что закрытие DevTools не уничтожает devToolsWebContents, ответственность за уничтожение devToolsWebContents лежит на вызывающей стороне.

Пример отображения DevTools в теге <webview>:

<html>
<head>
  <style type="text/css">
    * { margin: 0; }
    #browser { height: 70%; }
    #devtools { height: 30%; }
  </style>
</head>
<body>
  <webview id="browser" src="https://github.com"></webview>
  <webview id="devtools" src="about:blank"></webview>
  <script>
    const { ipcRenderer } = require('electron')
    const emittedOnce = (element, eventName) => new Promise(resolve => {
      element.addEventListener(eventName, event => resolve(event), { once: true })
    })
    const browserView = document.getElementById('browser')
    const devtoolsView = document.getElementById('devtools')
    const browserReady = emittedOnce(browserView, 'dom-ready')
    const devtoolsReady = emittedOnce(devtoolsView, 'dom-ready')
    Promise.all([browserReady, devtoolsReady]).then(() => {
      const targetId = browserView.getWebContentsId()
      const devtoolsId = devtoolsView.getWebContentsId()
      ipcRenderer.send('open-devtools', targetId, devtoolsId)
    })
  </script>
</body>
</html>
// Main process
const { ipcMain, webContents } = require('electron')
ipcMain.on('open-devtools', (event, targetContentsId, devtoolsContentsId) => {
  const target = webContents.fromId(targetContentsId)
  const devtools = webContents.fromId(devtoolsContentsId)
  target.setDevToolsWebContents(devtools)
  target.openDevTools()
})

Пример отображения DevTools в BrowserWindow:

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

let win = null
let devtools = null

app.whenReady().then(() => {
  win = new BrowserWindow()
  devtools = new BrowserWindow()
  win.loadURL('https://github.com')
  win.webContents.setDevToolsWebContents(devtools.webContents)
  win.webContents.openDevTools({ mode: 'detach' })
})

contents.openDevTools([options])​

  • options Объект (необязательно)
    • mode строка - Открывает DevTools с указанным состоянием панели задач, может быть left, right, bottom, undocked, detach. По умолчанию используется последнее состояние панели задач. В режиме undocked возможно возвращение к привязанному состоянию. В режиме detach это невозможно.
    • activate булево (необязательно) - Нужно ли переводить открытое окно DevTools на передний план. По умолчанию true.

Открывает DevTools.

Когда contents является тегом <webview> , mode будет detach по умолчанию. Явное указание пустого mode может принудительно использовать последнее состояние панели задач.

В Windows, если включен Windows Control Overlay, DevTools будут открыты с mode: 'detach'.

contents.closeDevTools()​

Закрывает DevTools.

contents.isDevToolsOpened()​

Возвращает boolean - открыты ли DevTools.

contents.isDevToolsFocused()​

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

contents.toggleDevTools()​

Переключает инструменты разработчика.

contents.inspectElement(x, y)​

  • x Целое число
  • y Целое число

Начинает инспектирование элемента в позиции (x, y).

contents.inspectSharedWorker()​

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

contents.inspectSharedWorkerById(workerId)​

  • workerId строка

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

contents.getAllSharedWorkers()​

Возвращает SharedWorkerInfo[] - информацию обо всех рабочих процессах общего использования.

contents.inspectServiceWorker()​

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

contents.send(channel, ...args)​

  • channel строка
  • ...args любой массив

Отправляет асинхронное сообщение в процесс рендеринга через channel, вместе с аргументами. Аргументы будут сериализованы с помощью алгоритма структурированного клонирования, так же как и postMessage, поэтому цепочки прототипов не будут включены. Отправка функций, промисов, символов, WeakMaps или WeakSets приведет к исключению.

ПРИМЕЧАНИЕ: Отправка нестандартных типов JavaScript, таких как объекты DOM или специальные объекты Electron, приведет к исключению.

Процесс рендеринга может обработать сообщение, прослушав channel с модулем ipcRenderer.

Пример отправки сообщений из основного процесса в процесс рендеринга:

// In the main process.
const { app, BrowserWindow } = require('electron')
let win = null

app.whenReady().then(() => {
  win = new BrowserWindow({ width: 800, height: 600 })
  win.loadURL(`file://${__dirname}/index.html`)
  win.webContents.on('did-finish-load', () => {
    win.webContents.send('ping', 'whoooooooh!')
  })
})
<!-- index.html -->
<html>
<body>
  <script>
    require('electron').ipcRenderer.on('ping', (event, message) => {
      console.log(message) // Prints 'whoooooooh!'
    })
  </script>
</body>
</html>

contents.sendToFrame(frameId, channel, ...args)​

  • frameId Целое число | [число, число] - ID кадра для отправки или пара [processId, frameId], если кадр находится в другом процессе по отношению к главному.
  • channel строка
  • ...args любой массив

Отправляет асинхронное сообщение в определённый кадр в процессе рендеринга через channel, вместе с аргументами. Аргументы будут сериализованы с помощью алгоритма структурированного клонирования, так же как и postMessage, поэтому цепочки прототипов не будут включены. Отправка функций, промисов, символов, WeakMaps или WeakSets приведет к исключению.

ПРИМЕЧАНИЕ: Отправка нестандартных типов JavaScript, таких как объекты DOM или специальные объекты Electron, приведет к исключению.

Процесс рендеринга может обработать сообщение, прослушав channel с модулем ipcRenderer.

Если вы хотите получить frameId заданного контекста рендеринга, используйте значение webFrame.routingId. Например:

// In a renderer process
console.log('My frameId is:', require('electron').webFrame.routingId)

Вы также можете получить доступ к frameId из всех входящих IPC-сообщений в основном процессе.

// In the main process
ipcMain.on('ping', (event) => {
  console.info('Message came from frameId:', event.frameId)
})

contents.postMessage(channel, message, [transfer])​

  • channel строка
  • message любое значение
  • transfer MessagePortMain[] (необязательно)

Отправляет сообщение в процесс рендеринга, необязательно передавая владение нулю или более объектам [MessagePortMain].

Переданные MessagePortMain объекты будут доступны в процессе рендеринга через свойство ports испущенного события. По прибытии в рендере они будут объектами нативного DOM MessagePort.

Например:

// Main process
const { port1, port2 } = new MessageChannelMain()
webContents.postMessage('port', { message: 'hello' }, [port1])

// Renderer process
ipcRenderer.on('port', (e, msg) => {
  const [port] = e.ports
  // ...
})

contents.enableDeviceEmulation(parameters)​

  • parameters Объект
    • screenPosition строка - Укажите тип экрана для эмуляции (по умолчанию: desktop):
      • desktop - Тип экрана для настольного компьютера.
      • mobile - Тип экрана для мобильного устройства.
    • screenSize Размер - Установите эмулируемый размер экрана (screenPosition == мобильный).
    • viewPosition Точка - Позиционируйте просмотр на экране (screenPosition == мобильный) (по умолчанию: { x: 0, y: 0 }).
    • deviceScaleFactor Целое число - Установите коэффициент масштаба устройства (если ноль, используется исходный коэффициент масштаба устройства) (по умолчанию: 0).
    • viewSize Размер - Установите эмулируемый размер просмотра (пустое значение означает, что переопределения нет).
    • scale Вещественное число - Масштаб эмулируемого просмотра внутри доступного пространства (не в режиме подгонки к просмотру) (по умолчанию: 1).

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

contents.disableDeviceEmulation()​

Отключить эмуляцию устройства, включенную с помощью webContents.enableDeviceEmulation.

contents.sendInputEvent(inputEvent)​

  • inputEvent MouseInputEvent | MouseWheelInputEvent | KeyboardInputEvent

Отправляет событие ввода event на страницу. Примечание: для того, чтобы sendInputEvent() работало, необходимо, чтобы содержащий содержимое BrowserWindow был сфокусирован.

contents.beginFrameSubscription([onlyDirty ,]callback)​

  • onlyDirty логическое значение (необязательно) - по умолчанию false.
  • callback Функция
    • image NativeImage
    • dirtyRect Прямоугольник

Начинает подписку на события презентации и захват кадров, функция callback будет вызвана с callback(image, dirtyRect) при событии презентации.

image - экземпляр NativeImage, хранящий захваченный кадр.

dirtyRect - объект со свойствами x, y, width, height, описывающими, какая часть страницы была перерисована. Если onlyDirty установлено в значение true, image будет содержать только перерисованную область. onlyDirty по умолчанию равно false.

contents.endFrameSubscription()​

Прекратить подписку на события презентации кадра.

contents.startDrag(item)​

  • item Объект
    • file строка - Путь к файлу, который перетаскивается.
    • files массив строк (необязательно) - Пути к файлам, которые перетаскиваются. (files переопределит поле file)
    • icon NativeImage | строка - На macOS изображение должно быть непустым.

Устанавливает item в качестве перетаскиваемого элемента для текущей операции перетаскивания и отпускания, file - абсолютный путь к файлу, который перетаскивается, а icon - изображение, отображаемое под курсором при перетаскивании.

END_OF_DOCUMENT_MARKER

contents.savePage(fullPath, saveType)​

  • fullPath string - Абсолютный путь к файлу.
  • saveType string - Укажите тип сохранения.
    • HTMLOnly - Сохранить только HTML страницы.
    • HTMLComplete - Сохранить полную страницу в формате HTML.
    • MHTML - Сохранить полную страницу в формате MHTML.

Возвращает Promise<void> - разрешает, если страница сохранена.

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

win.loadURL('https://github.com')

win.webContents.on('did-finish-load', async () => {
  win.webContents.savePage('/tmp/test.html', 'HTMLComplete').then(() => {
    console.log('Page was saved successfully.')
  }).catch(err => {
    console.log(err)
  })
})

contents.showDefinitionForSelection() macOS​

Отображает всплывающее окно словаря, которое ищет выбранное слово на странице.

contents.isOffscreen()​

Возвращает boolean - Указывает, включено ли отображение вне экрана.

contents.startPainting()​

Если отображение вне экрана включено и не происходит рисование, начать рисование.

contents.stopPainting()​

Если отображение вне экрана включено и происходит рисование, остановить рисование.

contents.isPainting()​

Возвращает boolean - Если отображение вне экрана включено, возвращает, происходит ли в данный момент рисование.

contents.setFrameRate(fps)​

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

Если отображение вне экрана включено, устанавливает частоту кадров на указанное число. Принимаются только значения от 1 до 240.

contents.getFrameRate()​

Возвращает Integer - Если отображение вне экрана включено, возвращает текущую частоту кадров.

contents.invalidate()​

Планирует полную перерисовку окна, в котором находится этот веб-контент.

Если отображение вне экрана включено, делает кадр недействительным и генерирует новый с помощью события 'paint'.

contents.getWebRTCIPHandlingPolicy()​

Возвращает string - Возвращает политику обработки IP-адресов WebRTC.

contents.setWebRTCIPHandlingPolicy(policy)​

  • policy string - Укажите политику обработки IP-адресов WebRTC.
    • default - Раскрывает публичные и локальные IP-адреса пользователя. Это стандартное поведение. При использовании этой политики WebRTC имеет право перечислить все интерфейсы и привязать их, чтобы обнаружить публичные интерфейсы.
    • default_public_interface_only - Раскрывает публичный IP-адрес пользователя, но не раскрывает локальный IP-адрес пользователя. При использовании этой политики WebRTC должен использовать только маршрут по умолчанию, используемый http. Это не раскрывает никакие локальные адреса.
    • default_public_and_private_interfaces - Раскрывает публичные и локальные IP-адреса пользователя. При использовании этой политики WebRTC должен использовать только маршрут по умолчанию, используемый http. Это также раскрывает связанный адрес по умолчанию. Маршрут по умолчанию — это маршрут, выбранный ОС на конечной точке с несколькими подключениями.
    • disable_non_proxied_udp - Не раскрывает публичные или локальные IP-адреса. При использовании этой политики WebRTC должен использовать только TCP для связи со сверстниками или серверами, если сервер прокси не поддерживает UDP.

Установка политики обработки IP-адресов WebRTC позволяет контролировать, какие IP-адреса раскрываются через WebRTC. Подробнее см. BrowserLeaks.

contents.getMediaSourceId(requestWebContents)​

  • requestWebContents WebContents - Веб-контент, которому будет зарегистрирован идентификатор.

Возвращает string - Идентификатор потока WebContents. Этот идентификатор можно использовать с navigator.mediaDevices.getUserMedia с помощью chromeMediaSource типа tab. Идентификатор ограничен веб-контентом, к которому он зарегистрирован, и действителен только 10 секунд.

contents.getOSProcessId()​

Возвращает Integer - Идентификатор процесса операционной системы связанного процесса рендеринга.

contents.getProcessId()​

Возвращает Integer - Внутренний идентификатор процесса Chromium связанного процесса рендеринга. Может быть сравнен с frameProcessId, переданным событиями навигации, специфичными для фрейма (например, did-frame-navigate).

contents.takeHeapSnapshot(filePath)​

  • filePath string - Путь к выходному файлу.

Возвращает Promise<void> - Указывает, успешно ли был создан снимок.

Создаёт снимок кучи V8 и сохраняет его в filePath.

contents.getBackgroundThrottling()​

Возвращает boolean - Будет ли этот WebContents ограничивать анимацию и таймеры, когда страница переходит в фоновый режим. Это также влияет на API Page Visibility.

contents.setBackgroundThrottling(allowed)​

  • allowed boolean

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

contents.getType()​

Возвращает string - тип веб-контента. Может быть backgroundPage, window, browserView, remote, webview или offscreen.

contents.setImageAnimationPolicy(policy)​

  • policy string - Может быть animate, animateOnce или noAnimation.

Устанавливает политику анимации изображений для этого веб-контента. Политика влияет только на новые изображения, существующие изображения, которые в настоящее время анимируются, не затрагиваются. Это известное ограничение в Chromium, вы можете принудительно пересчитать анимацию изображений с помощью img.src = img.src, что приведет к отсутствию сетевого трафика, но обновит политику анимации.

Это соответствует функции доступности animationPolicy в Chromium.

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

contents.audioMuted​

Свойство boolean, которое определяет, заглушен ли этот документ.

contents.userAgent​

Свойство string, которое определяет пользовательский агент для этой веб-страницы.

contents.zoomLevel​

Свойство number, которое определяет уровень масштабирования для этого веб-контента.

Исходный размер — 0, каждое увеличение или уменьшение соответствует масштабированию на 20% больше или меньше по умолчанию, соответственно, до пределов 300% и 50% от исходного размера. Формула для этого scale := 1.2 ^ level.

contents.zoomFactor​

Свойство number, которое определяет коэффициент масштабирования для этого веб-контента.

Коэффициент масштабирования — это процент масштабирования, деленный на 100, поэтому 300% = 3,0.

contents.frameRate​

Свойство Integer, которое устанавливает частоту кадров веб-контента на указанное число. Принимаются только значения от 1 до 240.

Применимо только если отображение вне экрана включено.

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

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

contents.session Только для чтения​

Сессия, используемая этим webContents.

contents.hostWebContents Только для чтения​

Экземпляр web-contents, который может владеть этим объектом.

contents.devToolsWebContents Только для чтения​

Свойство, представляющее DevTools web-contents ассоциированные с заданным.

Примечание: Пользователи не должны хранить этот объект, так как он может стать недоступным после закрытия DevTools.

contents.debugger Только для чтения​

Экземпляр отладчика для этого webContents.

contents.backgroundThrottling​

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

contents.mainFrame Только для чтения​

Свойство, представляющее главную (верхнюю) фрейм-структуру страницы.

© GitHub Inc.
Licensed under the MIT license.
https://www.electronjs.org/docs/latest/api/web-contents

Spec-Zone.ru

Настройки Оффлайн Что нового Помощь О нас
Spec-Zone .ru
спецификации, руководства, описания, API