Сессия

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

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

Модуль session может использоваться для создания новых объектов Session.

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

const { BrowserWindow } = require('electron')

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

const ses = win.webContents.session
console.log(ses.getUserAgent())

Методы​

Модуль session имеет следующие методы:

session.fromPartition(partition[, options])​

• partition строка
• options Объект (необязательно)
  • cache логическое значение - Включить кэш.

Возвращает Session - Экземпляр сессии из partition строки. Если существует существующая сессия с тем же partition, то она будет возвращена; в противном случае будет создан новый экземпляр Session с options.

Если partition начинается с префикса persist:, страница будет использовать постоянную сессию, доступную всем страницам приложения с тем же partition. Если префикс persist: отсутствует, страница будет использовать сессию в оперативной памяти. Если partition пусто, будет возвращена стандартная сессия приложения.

Для создания Session с options, необходимо убедиться, что Session с partition никогда ранее не использовался. Изменить options существующего объекта Session невозможно.

Свойства​

Модуль session имеет следующие свойства:

session.defaultSession​

Объект Session, стандартный объект сессии приложения.

Класс: Сессия​

Получение и установка свойств сессии.

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

Вы можете создать объект Session в модуле session:

const { session } = require('electron')
const ses = session.fromPartition('persist:name')
console.log(ses.getUserAgent())

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

Следующие события доступны для экземпляров Session:

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

Возвращает:

• event Событие
• item ЭлементЗагрузки
• webContents WebContents

Выполняется, когда Electron собирается загрузить item в webContents.

Вызов event.preventDefault() отменит загрузку, и item не будет доступен в следующем цикле обработки.

const { session } = require('electron')
session.defaultSession.on('will-download', (event, item, webContents) => {
  event.preventDefault()
  require('got')(item.getURL()).then((response) => {
    require('fs').writeFileSync('/somewhere', response.body)
  })
})

Событие: 'extension-loaded'​

Возвращает:

• event Событие
• extension Расширение

Выполняется после загрузки расширения. Это происходит всякий раз, когда расширение добавляется в набор "активных" расширений. Это включает:

• Загрузку расширений из Session.loadExtension.
• Перезагрузку расширений:
  • после сбоя.
  • если расширение запросило это (chrome.runtime.reload()).

Событие: 'extension-unloaded'​

Возвращает:

• event Событие
• extension Расширение

Выполняется после разгрузки расширения. Это происходит, когда вызывается Session.removeExtension.

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

Возвращает:

• event Событие
• extension Расширение

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

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

Возвращает:

• event Событие
• preconnectUrl строка - URL, запрашиваемый для предварительного соединения рендером.
• allowCredentials логическое значение - Истинно, если рендер запрашивает включение учетных данных (подробнее см. спецификацию).

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

Событие: 'spellcheck-dictionary-initialized'​

Возвращает:

• event Событие
• languageCode строка - Код языка файла словаря

Выполняется, когда файл словаря hunspell был успешно инициализирован. Это происходит после загрузки файла.

Событие: 'spellcheck-dictionary-download-begin'​

Возвращает:

• event Событие
• languageCode строка - Код языка файла словаря

Выполняется при начале загрузки файла словаря hunspell

Событие: 'spellcheck-dictionary-download-success'​

Возвращает:

• event Событие
• languageCode строка - Код языка файла словаря

Выполняется после успешной загрузки файла словаря hunspell

Событие: 'spellcheck-dictionary-download-failure'​

Возвращает:

• event Событие
• languageCode строка - Код языка файла словаря

Выполняется при сбое загрузки файла словаря hunspell. Для получения подробностей о сбое необходимо собрать netlog и проверить запрос на загрузку.

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

Возвращает:

• event Событие
• details Объект
  • deviceList HIDDevice[]
  • frame WebFrameMain
• callback Функция
  • deviceId строка | null (необязательно)

Выполняется, когда необходимо выбрать устройство HID при вызове navigator.hid.requestDevice. callback должен быть вызван с deviceId для выбора; отсутствие аргументов у callback отменяет запрос. Дополнительно, управление разрешениями на navigator.hid можно настроить с помощью ses.setPermissionCheckHandler(handler) и ses.setDevicePermissionHandler(handler).

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

let win = null

app.whenReady().then(() => {
  win = new BrowserWindow()

  win.webContents.session.setPermissionCheckHandler((webContents, permission, requestingOrigin, details) => {
    if (permission === 'hid') {
      // Add logic here to determine if permission should be given to allow HID selection
      return true
    }
    return false
  })

  // Optionally, retrieve previously persisted devices from a persistent store
  const grantedDevices = fetchGrantedDevices()

  win.webContents.session.setDevicePermissionHandler((details) => {
    if (new URL(details.origin).hostname === 'some-host' && details.deviceType === 'hid') {
      if (details.device.vendorId === 123 && details.device.productId === 345) {
        // Always allow this type of device (this allows skipping the call to `navigator.hid.requestDevice` first)
        return true
      }

      // Search through the list of devices that have previously been granted permission
      return grantedDevices.some((grantedDevice) => {
        return grantedDevice.vendorId === details.device.vendorId &&
              grantedDevice.productId === details.device.productId &&
              grantedDevice.serialNumber && grantedDevice.serialNumber === details.device.serialNumber
      })
    }
    return false
  })

  win.webContents.session.on('select-hid-device', (event, details, callback) => {
    event.preventDefault()
    const selectedDevice = details.deviceList.find((device) => {
      return device.vendorId === '9025' && device.productId === '67'
    })
    callback(selectedPort?.deviceId)
  })
})

Событие: 'hid-device-added'​

Возвращает:

• event Событие
• details Объект
  • device HIDDevice[]
  • frame WebFrameMain

Выполняется после вызова navigator.hid.requestDevice и выполнения select-hid-device если новое устройство становится доступным до вызова обратного вызова select-hid-device. Это событие предназначено для использования при использовании пользовательского интерфейса для запроса выбора устройства, чтобы интерфейс мог быть обновлён с новым добавленным устройством.

Событие: 'hid-device-removed'​

Возвращает:

• event Событие
• details Объект
  • device HIDDevice[]
  • frame WebFrameMain

Издаётся после того, как был вызван navigator.hid.requestDevice, и select-hid-device был запущен, если устройство было удалено до вызова обратного вызова от select-hid-device. Это событие предназначено для использования при использовании пользовательского интерфейса для запроса выбора устройства, чтобы пользовательский интерфейс мог быть обновлён для удаления указанного устройства.

Событие: 'hid-device-revoked'​

Возвращает:

• event Событие
• details Объект
  • device HIDDevice[]
  • origin строка (необязательно) - Происхождение, из которого было отозвано устройство.

Издаётся после того, как был вызван HIDDevice.forget(). Это событие может использоваться для поддержки сохранения разрешений в постоянном хранилище, когда используется setDevicePermissionHandler.

Событие: 'select-serial-port'​

Возвращает:

• event Событие
• portList SerialPort[]
• webContents WebContents
• callback Функция
  • portId строка

Издаётся, когда требуется выбрать последовательный порт при вызове navigator.serial.requestPort. callback должен быть вызван с portId, который нужно выбрать, передача пустой строки в callback отменит запрос. Кроме того, разрешения на navigator.serial могут быть управляемы с помощью ses.setPermissionCheckHandler(handler) с разрешением serial.

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

let win = null

app.whenReady().then(() => {
  win = new BrowserWindow({
    width: 800,
    height: 600
  })

  win.webContents.session.setPermissionCheckHandler((webContents, permission, requestingOrigin, details) => {
    if (permission === 'serial') {
      // Add logic here to determine if permission should be given to allow serial selection
      return true
    }
    return false
  })

  // Optionally, retrieve previously persisted devices from a persistent store
  const grantedDevices = fetchGrantedDevices()

  win.webContents.session.setDevicePermissionHandler((details) => {
    if (new URL(details.origin).hostname === 'some-host' && details.deviceType === 'serial') {
      if (details.device.vendorId === 123 && details.device.productId === 345) {
        // Always allow this type of device (this allows skipping the call to `navigator.serial.requestPort` first)
        return true
      }

      // Search through the list of devices that have previously been granted permission
      return grantedDevices.some((grantedDevice) => {
        return grantedDevice.vendorId === details.device.vendorId &&
              grantedDevice.productId === details.device.productId &&
              grantedDevice.serialNumber && grantedDevice.serialNumber === details.device.serialNumber
      })
    }
    return false
  })

  win.webContents.session.on('select-serial-port', (event, portList, webContents, callback) => {
    event.preventDefault()
    const selectedPort = portList.find((device) => {
      return device.vendorId === '9025' && device.productId === '67'
    })
    if (!selectedPort) {
      callback('')
    } else {
      callback(selectedPort.portId)
    }
  })
})

Событие: 'serial-port-added'​

Возвращает:

• event Событие
• port SerialPort
• webContents WebContents

Издаётся после того, как был вызван navigator.serial.requestPort, и select-serial-port был запущен, если новый последовательный порт стал доступен до вызова обратного вызова от select-serial-port. Это событие предназначено для использования при использовании пользовательского интерфейса для запроса выбора порта, чтобы пользовательский интерфейс мог быть обновлён с новым добавленным портом.

Событие: 'serial-port-removed'​

Возвращает:

• event Событие
• port SerialPort
• webContents WebContents

Издаётся после того, как был вызван navigator.serial.requestPort, и select-serial-port был запущен, если последовательный порт был удалён до вызова обратного вызова от select-serial-port. Это событие предназначено для использования при использовании пользовательского интерфейса для запроса выбора порта, чтобы пользовательский интерфейс мог быть обновлён для удаления указанного порта.

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

Следующие методы доступны для экземпляров Session:

ses.getCacheSize()​

Возвращает Promise<Integer> - текущий размер кэша сеанса в байтах.

ses.clearCache()​

Возвращает Promise<void> - разрешается, когда операция очистки кэша завершена.

Очищает HTTP-кэш сеанса.

ses.clearStorageData([options])​

• options Объект (необязательно)
  • origin строка (необязательно) - Должен следовать представлению window.location.origin scheme://host:port.
  • storages массив строк (необязательно) - Типы хранилищ для очистки, могут содержать: appcache, cookies, filesystem, indexdb, localstorage, shadercache, websql, serviceworkers, cachestorage Если не указано, очищаются все типы хранилищ.
  • quotas массив строк (необязательно) - Типы квот для очистки, могут содержать: temporary, persistent, syncable Если не указано, очищаются все квоты.

Возвращает Promise<void> - разрешается, когда данные хранилища были очищены.

ses.flushStorageData()​

Записывает любые не записанные данные DOMStorage на диск.

ses.setProxy(config)​

• config Объект
  • mode строка (необязательно) - Режим прокси. Должен быть одним из direct, auto_detect, pac_script, fixed_servers или system. Если не указано, будет определено автоматически на основе других указанных параметров.
    • direct В прямом режиме все соединения создаются напрямую, без участия прокси.
    • auto_detect В режиме автоопределения конфигурация прокси определяется скриптом PAC, который можно загрузить по адресу http://wpad/wpad.dat.
    • pac_script В режиме скрипта PAC конфигурация прокси определяется скриптом PAC, который извлекается из URL, указанного в pacScript. Это режим по умолчанию, если указан pacScript.
    • fixed_servers В режиме фиксированных серверов конфигурация прокси задается в proxyRules. Это режим по умолчанию, если указан proxyRules.
    • system В системном режиме конфигурация прокси берется из операционной системы. Обратите внимание, что системный режим отличается от установки отсутствия конфигурации прокси. В последнем случае Electron обращается к системным настройкам только если никакие параметры командной строки не влияют на конфигурацию прокси.
  • pacScript строка (необязательно) - URL, связанный с файлом PAC.
  • proxyRules строка (необязательно) - Правила, указывающие, какие прокси использовать.
  • proxyBypassRules строка (необязательно) - Правила, указывающие, какие URL должны обойти настройки прокси.

Возвращает Promise<void> - Разрешается, когда процесс настройки прокси завершён.

Настраивает настройки прокси.

Если mode не указано, pacScript и proxyRules предоставлены вместе, опция proxyRules игнорируется, и применяется конфигурация pacScript.

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

proxyRules должно соответствовать правилам ниже:

proxyRules = schemeProxies[";"<schemeProxies>]
schemeProxies = [<urlScheme>"="]<proxyURIList>
urlScheme = "http" | "https" | "ftp" | "socks"
proxyURIList = <proxyURL>[","<proxyURIList>]
proxyURL = [<proxyScheme>"://"]<proxyHost>[":"<proxyPort>]

Например:

• http=foopy:80;ftp=foopy2 - Используйте HTTP-прокси foopy:80 для URL http://, и HTTP-прокси foopy2:80 для URL ftp://.
• foopy:80 - Используйте HTTP-прокси foopy:80 для всех URL.
• foopy:80,bar,direct:// - Используйте HTTP-прокси foopy:80 для всех URL, переходя к bar если foopy:80 недоступен, и после этого не используйте прокси.
• socks4://foopy - Используйте SOCKS v4-прокси foopy:1080 для всех URL.
• http=foopy,socks5://bar.com - Используйте HTTP-прокси foopy для http-URL, и перейдите к SOCKS5-прокси bar.com если foopy недоступен.
• http=foopy,direct:// - Используйте HTTP-прокси foopy для http-URL, и не используйте прокси, если foopy недоступен.
• http=foopy;socks=foopy2 - Используйте HTTP-прокси foopy для http-URL, и используйте socks4://foopy2 для всех остальных URL.

proxyBypassRules — это список правил, разделённых запятыми, описанный ниже:

• [ URL_SCHEME "://" ] HOSTNAME_PATTERN [ ":" <port> ]

  Соответствует всем именам хостов, которые соответствуют шаблону HOSTNAME_PATTERN.

  Примеры: "foobar.com", "foobar.com", ".foobar.com", "foobar.com:99", "https://x..y.com:99"

• "." HOSTNAME_SUFFIX_PATTERN [ ":" PORT ]

  Сопоставляет определённое доменное окончание.

  Примеры: ".google.com", ".com", "http://.google.com"

• [ SCHEME "://" ] IP_LITERAL [ ":" PORT ]

  Сопоставляет URL, которые являются литералами IP-адресов.

  Примеры: "127.0.1", "[0:0::1]", "[::1]", "http://[::1]:99"

• IP_LITERAL "/" PREFIX_LENGTH_IN_BITS

  Сопоставляет любой URL, который указывает на IP-литерал, который попадает в указанный диапазон. Диапазон IP задаётся с использованием нотации CIDR.

  Примеры: "192.168.1.1/16", "fefe:13::abc/33".

• <local>

  Сопоставляет локальные адреса. Значение <local> — это соответствие хоста одному из: "127.0.0.1", "::1", "localhost".

ses.resolveProxy(url)​

• url URL

Возвращает Promise<string> - Разрешается с информацией о прокси для url.

ses.forceReloadProxyConfig()​

Возвращает Promise<void> — выполняется, когда все внутренние состояния службы прокси сброшены, и, если доступна, применяется последняя конфигурация прокси. Сценарий pac будет повторно получен из pacScript снова, если режим прокси pac_script.

ses.setDownloadPath(path)​

• path строка - Местоположение для загрузки.

Устанавливает каталог сохранения загрузок. По умолчанию, каталог загрузок будет Downloads в соответствующей папке приложения.

ses.enableNetworkEmulation(options)​

• options Объект
  • offline логическое значение (необязательно) - Имитировать отключение сети. По умолчанию false.
  • latency Вещественное число (необязательно) - RTT в мс. По умолчанию 0, что отключит задержку.
  • downloadThroughput Вещественное число (необязательно) - Скорость загрузки в Бит/с. По умолчанию 0, что отключит ограничение скорости загрузки.
  • uploadThroughput Вещественное число (необязательно) - Скорость загрузки в Бит/с. По умолчанию 0, что отключит ограничение скорости загрузки.

Имитирует сеть с заданной конфигурацией для session.

// To emulate a GPRS connection with 50kbps throughput and 500 ms latency.
window.webContents.session.enableNetworkEmulation({
  latency: 500,
  downloadThroughput: 6400,
  uploadThroughput: 6400
})

// To emulate a network outage.
window.webContents.session.enableNetworkEmulation({ offline: true })

ses.preconnect(options)​

• options Объект
  • url строка - URL для предварительной установки соединения. Только источник актуален для открытия сокета.
  • numSockets число (необязательно) - количество сокетов для предварительной установки соединения. Должно быть между 1 и 6. По умолчанию 1.

Предварительно устанавливает соединение с указанным количеством сокетов к источнику.

ses.closeAllConnections()​

Возвращает Promise<void> — выполняется, когда все подключения закрыты.

Примечание: Это приведет к завершению/ошибке всех запросов, которые в данный момент выполняются.

ses.disableNetworkEmulation()​

Отключает любую активную имитацию сети для session. Возвращает исходную конфигурацию сети.

ses.setCertificateVerifyProc(proc)​

• proc Функция | null
  • request Объект
    • hostname строка
    • certificate Сертификат
    • validatedCertificate Сертификат
    • isIssuedByKnownRoot логическое значение - true, если Chromium распознает корневой центр сертификации как стандартный корень. Если нет, то, вероятно, этот сертификат был сгенерирован прокси MITM, корень которого был установлен локально (например, корпоративным прокси). Необходимо доверять этому только если verificationResult OK.
    • verificationResult строка - OK, если сертификат доверен, в противном случае ошибка, например CERT_REVOKED.
    • errorCode Целое число - Код ошибки.
  • callback Функция
    • verificationResult Целое число - Значение может быть одним из кодов ошибок сертификата из здесь. Помимо кодов ошибок сертификата, можно использовать следующие специальные коды.
      • 0 - Указывает на успех и отключает проверку Certificate Transparency.
      • -2 - Указывает на ошибку.
      • -3 - Использует результат проверки из Chromium.

Устанавливает процедуру проверки сертификата для session, proc будет вызываться с proc(request, callback) при каждом запросе проверки сертификата сервера. Вызов callback(0) принимает сертификат, вызов callback(-2) отклоняет его.

Вызов setCertificateVerifyProc(null) вернёт проверку сертификатов к значению по умолчанию.

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

win.webContents.session.setCertificateVerifyProc((request, callback) => {
  const { hostname } = request
  if (hostname === 'github.com') {
    callback(0)
  } else {
    callback(-2)
  }
})

ПРИМЕЧАНИЕ: Результат этой процедуры кэшируется службой сети.

ses.setPermissionRequestHandler(handler)​

• handler Функция | null
  • webContents WebContents - WebContents, запрашивающий разрешение. Обратите внимание, что если запрос поступает от подрамки, вы должны использовать requestingUrl для проверки источника запроса.
  • permission строка - Тип запрошенного разрешения.
    • clipboard-read - Запрос доступа для чтения из буфера обмена.
    • media - Запрос доступа к устройствам мультимедиа, таким как камера, микрофон и динамики.
    • display-capture - Запрос доступа для захвата экрана.
    • mediaKeySystem - Запрос доступа к контенту, защищенному DRM.
    • geolocation - Запрос доступа к текущему местоположению пользователя.
    • notifications - Запрос создания уведомлений и возможности отображать их в системном трее пользователя.
    • midi - Запрос доступа к MIDI в API webmidi.
    • midiSysex - Запрос доступа к сообщениям системного эксклюзива в API webmidi.
    • pointerLock - Запрос прямого интерпретирования движений мыши как метода ввода. Чтобы узнать больше, перейдите сюда.
    • fullscreen - Запрос ввода приложения в полноэкранный режим.
    • openExternal - Запрос открытия ссылок в сторонних приложениях.
    • unknown - Неизвестный запрос на разрешение
  • callback Функция
    • permissionGranted логическое значение - Разрешить или запретить разрешение.
  • details Объект - Некоторые свойства доступны только для определенных типов разрешений.
    • externalURL строка (необязательно) - URL запроса openExternal.
    • securityOrigin строка (необязательно) - Безопасный источник запроса media.
    • mediaTypes строка[] (необязательно) - Типы доступа к медиа, запрашиваемые элементы, могут быть video или audio
    • requestingUrl строка - Последний URL, загруженный запрашиваемой рамкой.
    • isMainFrame логическое значение - Является ли рамка, делающая запрос, главной рамой

Устанавливает обработчик, который можно использовать для ответа на запросы разрешения для session. Вызов callback(true) разрешит разрешение, а вызов callback(false) отклонит его. Для удаления обработчика вызовите setPermissionRequestHandler(null). Обратите внимание, что вы также должны реализовать setPermissionCheckHandler для получения полного управления разрешениями. Большинство веб-API проверяют разрешение и затем делают запрос разрешения, если проверка отклонена.

const { session } = require('electron')
session.fromPartition('some-partition').setPermissionRequestHandler((webContents, permission, callback) => {
  if (webContents.getURL() === 'some-host' && permission === 'notifications') {
    return callback(false) // denied.
  }

  callback(true)
})

ses.setPermissionCheckHandler(handler)​

• handler Функция\<логическое значение> | null
  • webContents (WebContents | null) - WebContents, проверяющий разрешение. Обратите внимание, что если запрос поступает от подрамки, вы должны использовать requestingUrl для проверки источника запроса. Все подрамки с разными источниками, производящие проверки разрешений, передадут обработчику null webContents, в то время как некоторые другие проверки разрешений, такие как проверки notifications, всегда передадут null. Вы должны использовать embeddingOrigin и requestingOrigin для определения того, в каком источнике находятся владеющая и запрашивающая рамки соответственно.
  • permission строка - Тип проверки разрешения. Допустимые значения midiSysex, notifications, geolocation, media,mediaKeySystem,midi, pointerLock, fullscreen, openExternal, hid, или serial.
  • requestingOrigin строка - URL источника проверки разрешения
  • details Объект - Некоторые свойства доступны только для определенных типов разрешений.
    • embeddingOrigin строка (необязательно) - Источник рамки, содержащей рамку, которая сделала проверку разрешения. Устанавливается только для подрамок с разными источниками, производящих проверки разрешений.
    • securityOrigin строка (необязательно) - Безопасный источник проверки media.
    • mediaType строка (необязательно) - Тип доступа к медиа, который запрашивается, может быть video, audio или unknown
    • requestingUrl строка (необязательно) - Последний URL, загруженный запрашиваемой рамкой. Не предоставляется для подрамок с разными источниками, производящих проверки разрешений.
    • isMainFrame логическое значение - Является ли рамка, делающая запрос, главной рамой

Устанавливает обработчик, который может использоваться для ответа на проверки разрешений для session. Возвращение true позволит разрешить разрешение, а false — отклонит его. Обратите внимание, что для получения полного управления разрешениями также необходимо реализовать setPermissionRequestHandler. Большинство веб-API выполняют проверку разрешений, а затем запрашивают разрешение, если проверка отклонена. Для удаления обработчика вызовите setPermissionCheckHandler(null).

const { session } = require('electron')
const url = require('url')
session.fromPartition('some-partition').setPermissionCheckHandler((webContents, permission, requestingOrigin) => {
  if (new URL(requestingOrigin).hostname === 'some-host' && permission === 'notifications') {
    return true // granted
  }

  return false // denied
})

ses.setDevicePermissionHandler(handler)​

• handler Function<boolean> | null
  • details Object
    • deviceType string - Тип устройства, для которого запрашивается разрешение, может быть hid или serial.
    • origin string - URL источника проверки разрешения на устройство.
    • device HIDDevice | SerialPort- устройство, для которого запрашивается разрешение.

Устанавливает обработчик, который может использоваться для ответа на проверки разрешений на устройство для session. Возвращение true позволит разрешить доступ к устройству, а false — отклонит его. Для удаления обработчика вызовите setDevicePermissionHandler(null). Этот обработчик можно использовать для предоставления стандартных разрешений на устройства без предварительного запроса разрешения на устройства (например, с помощью navigator.hid.requestDevice). Если этот обработчик не определен, будут использоваться стандартные разрешения на устройства, предоставленные через выбор устройства (например, с помощью navigator.hid.requestDevice). Кроме того, по умолчанию Electron сохраняет предоставленные разрешения на устройства в памяти. Если требуется хранение на более длительный срок, разработчик может сохранить предоставленные разрешения на устройства (например, при обработке события select-hid-device) и затем считывать их из этого хранилища с помощью setDevicePermissionHandler.

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

let win = null

app.whenReady().then(() => {
  win = new BrowserWindow()

  win.webContents.session.setPermissionCheckHandler((webContents, permission, requestingOrigin, details) => {
    if (permission === 'hid') {
      // Add logic here to determine if permission should be given to allow HID selection
      return true
    } else if (permission === 'serial') {
      // Add logic here to determine if permission should be given to allow serial port selection
    }
    return false
  })

  // Optionally, retrieve previously persisted devices from a persistent store
  const grantedDevices = fetchGrantedDevices()

  win.webContents.session.setDevicePermissionHandler((details) => {
    if (new URL(details.origin).hostname === 'some-host' && details.deviceType === 'hid') {
      if (details.device.vendorId === 123 && details.device.productId === 345) {
        // Always allow this type of device (this allows skipping the call to `navigator.hid.requestDevice` first)
        return true
      }

      // Search through the list of devices that have previously been granted permission
      return grantedDevices.some((grantedDevice) => {
        return grantedDevice.vendorId === details.device.vendorId &&
              grantedDevice.productId === details.device.productId &&
              grantedDevice.serialNumber && grantedDevice.serialNumber === details.device.serialNumber
      })
    } else if (details.deviceType === 'serial') {
      if (details.device.vendorId === 123 && details.device.productId === 345) {
        // Always allow this type of device (this allows skipping the call to `navigator.hid.requestDevice` first)
        return true
      }
    }
    return false
  })

  win.webContents.session.on('select-hid-device', (event, details, callback) => {
    event.preventDefault()
    const selectedDevice = details.deviceList.find((device) => {
      return device.vendorId === '9025' && device.productId === '67'
    })
    callback(selectedPort?.deviceId)
  })
})

ses.clearHostResolverCache()​

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

Очищает кэш хост-разрешителя.

ses.allowNTLMCredentialsForDomains(domains)​

• domains string - Список серверов, для которых включена интегрированная аутентификация, разделённый запятыми.

Динамически устанавливает, следует ли всегда отправлять учетные данные для аутентификации HTTP NTLM или Negotiate.

const { session } = require('electron')
// consider any url ending with `example.com`, `foobar.com`, `baz`
// for integrated authentication.
session.defaultSession.allowNTLMCredentialsForDomains('*example.com, *foobar.com, *baz')

// consider all urls for integrated authentication.
session.defaultSession.allowNTLMCredentialsForDomains('*')

ses.setUserAgent(userAgent[, acceptLanguages])​

• userAgent string
• acceptLanguages string (необязательно)

Переопределяет userAgent и acceptLanguages для этой сессии.

acceptLanguages должен быть упорядоченным списком кодов языков, разделённых запятыми, например, "en-US,fr,de,ko,zh-CN,ja".

Это не влияет на существующие WebContents, и каждый WebContents может использовать webContents.setUserAgent для переопределения пользовательского агента на уровне сессии.

ses.isPersistent()​

Возвращает boolean — является ли эта сессия постоянной. По умолчанию webContents сессия BrowserWindow является постоянной. При создании сессии из раздела сессия с префиксом persist: будет постоянной, а другие — временными.

ses.getUserAgent()​

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

ses.setSSLConfig(config)​

• config Object
  • minVersion string (необязательно) - Может быть tls1, tls1.1, tls1.2 или tls1.3. Минимальная версия SSL для подключения к удалённым серверам. По умолчанию tls1.
  • maxVersion string (необязательно) - Может быть tls1.2 или tls1.3. Максимальная версия SSL для подключения к удалённым серверам. По умолчанию tls1.3.
  • disabledCipherSuites Integer[] (необязательно) - Список наборов шифров, которые явно запрещены помимо тех, которые отключены встроенной политикой net. Поддерживаются литеральные формы: 0xAABB, где AA — cipher_suite[0], а BB — cipher_suite[1], как определено в RFC 2246, раздел 7.4.1.2. Нераспознанные, но анализируемые наборы шифров в этой форме не вернут ошибку. Пример: для отключения TLS_RSA_WITH_RC4_128_MD5 укажите 0x0004, а для отключения TLS_ECDH_ECDSA_WITH_RC4_128_SHA укажите 0xC002. Обратите внимание, что шифры TLSv1.3 отключить с помощью этого механизма нельзя.

Устанавливает конфигурацию SSL для сессии. Все последующие сетевые запросы будут использовать новую конфигурацию. Существующие сетевые подключения (например, подключения WebSocket) не будут прерваны, но старые сокеты в пуле не будут повторно использованы для новых подключений.

ses.getBlobData(identifier)​

• identifier string - Действительный UUID.

Возвращает Promise<Buffer> — разрешает с данными blob.

ses.downloadURL(url)​

• url string

Инициализирует загрузку ресурса по адресу url. API сгенерирует DownloadItem, к которому можно получить доступ с помощью события will-download.

Примечание: Это не выполняет никаких проверок безопасности, связанных с происхождением страницы, в отличие от webContents.downloadURL.

ses.createInterruptedDownload(options)​

• options Object
  • path string - Абсолютный путь к файлу загрузки.
  • urlChain string[] - Полный URL-цепь для загрузки.
  • mimeType string (необязательно)
  • offset Integer - Начальный диапазон для загрузки.
  • length Integer - Общая длина загрузки.
  • lastModified string (необязательно) - Значение заголовка Last-Modified.
  • eTag string (необязательно) - Значение заголовка ETag.
  • startTime Double (необязательно) - Время начала загрузки в секундах с начала эпохи UNIX.

Позволяет возобновить cancelled или interrupted загрузки из предыдущих Session. API сгенерирует DownloadItem, к которому можно получить доступ с помощью события will-download. В DownloadItem не будет связанных WebContents и начальное состояние будет interrupted. Загрузка начнется только при вызове API resume на DownloadItem.

ses.clearAuthCache()​

Возвращает Promise<void> — выполняется, когда кэш HTTP-аутентификации сессии был очищен.

ses.setPreloads(preloads)​

• preloads string[] - Массив абсолютных путей к предварительно загружаемым скриптам

Добавляет скрипты, которые будут выполняться НА ВСЕХ содержимых веб-страниц, связанных с этой сессией, сразу перед выполнением обычных скриптов preload.

ses.getPreloads()​

Возвращает string[] — массив путей к предварительно загружаемым скриптам, которые были зарегистрированы.

ses.setCodeCachePath(path)​

• path String - Абсолютный путь для хранения кэша JS-кода, сгенерированного v8, из рендерера.

Устанавливает каталог для хранения кэша сгенерированного JS-кода code cache для этой сессии. Каталог не обязательно должен быть создан пользователем перед этим вызовом, среда выполнения создаст его, если он не существует, иначе будет использоваться существующий каталог. Если каталог не может быть создан, тогда кэш кода не будет использоваться, и все операции, связанные с кэшем кода, будут выполняться без ошибок в среде выполнения. По умолчанию каталог будет Code Cache в соответствующей папке данных пользователя.

ses.clearCodeCaches(options)​

• options Object
  • urls String[] (необязательно) - Массив URL, соответствующих ресурсам, для которых требуется удалить кэш сгенерированного кода. Если список пуст, все записи в каталоге кэша будут удалены.

Возвращает Promise<void> — разрешается, когда завершена операция очистки кэша кода.

ses.setSpellCheckerEnabled(enable)​

• enable boolean

Устанавливает, следует ли включить встроенную проверку орфографии.

ses.isSpellCheckerEnabled()​

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

ses.setSpellCheckerLanguages(languages)​

• languages string[] — массив кодов языков для включения проверки орфографии.

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

Примечание: В macOS используется проверка орфографии ОС и автоматически определяет ваш язык. Этот API является бесполезным в macOS.

ses.getSpellCheckerLanguages()​

Возвращает string[] — массив кодов языков, для которых включена проверка орфографии. Если этот список пустой, проверка орфографии будет использовать en-US. По умолчанию при запуске, если этот параметр пустой, Electron попытается заполнить его текущим локалем ОС. Этот параметр сохраняется при перезапуске.

Примечание: В macOS используется проверка орфографии ОС и имеет свой собственный список языков. Этот API бесполезен в macOS.

ses.setSpellCheckerDictionaryDownloadURL(url)​

• url string — базовый URL для скачивания словарей hunspell Electron.

По умолчанию Electron скачивает словари hunspell с CDN Chromium. Если вы хотите изменить это поведение, вы можете использовать этот API, чтобы указать загрузчику словарей свой собственный хостинг словарей hunspell. В каждом релизе мы публикуем файл hunspell_dictionaries.zip, содержащий необходимые файлы для размещения.

Сервер файлов должен быть регистронезависимым. Если вы не можете этого сделать, вы должны загрузить каждый файл дважды: один раз с регистром, который у него есть в ZIP-архиве, и один раз со строчными буквами.

Если файлы, представленные в hunspell_dictionaries.zip, доступны по адресу https://example.com/dictionaries/language-code.bdic, то вы должны вызвать этот API с ses.setSpellCheckerDictionaryDownloadURL('https://example.com/dictionaries/'). Обратите внимание на заключительную косую черту. URL словарей формируется как ${url}${filename}.

Примечание: В macOS используется проверка орфографии ОС, поэтому мы не загружаем никакие файлы словарей. Этот API является бесполезным в macOS.

ses.listWordsInSpellCheckerDictionary()​

Возвращает Promise<string[]> — массив всех слов в пользовательском словаре приложения. Разрешается после загрузки всего словаря с диска.

ses.addWordToSpellCheckerDictionary(word)​

• word string — слово, которое вы хотите добавить в словарь

Возвращает boolean — успешно ли слово было записано в пользовательский словарь. Этот API не будет работать в неперсистентных (в оперативной памяти) сессиях.

Примечание: В macOS и Windows 10 это слово также будет записано в пользовательский словарь ОС.

ses.removeWordFromSpellCheckerDictionary(word)​

• word string — слово, которое вы хотите удалить из словаря

Возвращает boolean — успешно ли слово было удалено из пользовательского словаря. Этот API не будет работать в неперсистентных (в оперативной памяти) сессиях.

Примечание: В macOS и Windows 10 это слово также будет удалено из пользовательского словаря ОС.

ses.loadExtension(path[, options])​

• path string — Путь к каталогу с распакованным расширением Chrome
• options Объект (необязательно)
  • allowFileAccess boolean — разрешить расширению читать локальные файлы по протоколу file:// и вставлять скрипты содержимого в страницы file://. Это требуется, например, для загрузки расширений devtools на URL file://. По умолчанию false.

Возвращает Promise<Extension> — разрешается после загрузки расширения.

Этот метод выбросит исключение, если расширение не удалось загрузить. Если при установке расширения возникают предупреждения (например, если расширение запрашивает API, которого Electron не поддерживает), они будут записаны в консоль.

Обратите внимание, что Electron не поддерживает весь набор API расширений Chrome. Подробнее о поддерживаемых API расширений см. в разделе Поддерживаемые API расширений.

Обратите внимание, что в предыдущих версиях Electron расширения, которые загружались, запоминались для будущих запусков приложения. Сейчас это не так: loadExtension необходимо вызывать при каждом запуске приложения, если вы хотите загрузить расширение.

const { app, session } = require('electron')
const path = require('path')

app.on('ready', async () => {
  await session.defaultSession.loadExtension(
    path.join(__dirname, 'react-devtools'),
    // allowFileAccess is required to load the devtools extension on file:// URLs.
    { allowFileAccess: true }
  )
  // Note that in order to use the React DevTools extension, you'll need to
  // download and unzip a copy of the extension.
})

Этот API не поддерживает загрузку упакованных (.crx) расширений.

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

Примечание: Загрузка расширений в сессии оперативной памяти (неперсистентной) не поддерживается и вызовет ошибку.

ses.removeExtension(extensionId)​

• extensionId string — ID расширения для удаления

Выгружает расширение.

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

ses.getExtension(extensionId)​

• extensionId string — ID расширения для запроса

Возвращает Extension | null — загруженное расширение с заданным ID.

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

ses.getAllExtensions()​

Возвращает Extension[] — список всех загруженных расширений.

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

ses.getStoragePath()​

Возвращает string | null — абсолютный путь к файловой системе, где данные для этой сессии сохраняются на диске. Для сессий в оперативной памяти возвращает null.

Instance Properties​

Следующие свойства доступны для экземпляров Session:

ses.availableSpellCheckerLanguages Только для чтения​

Массив string[] с содержанием всех известных поддерживаемых языков проверки орфографии. Передача кода языка в API setSpellCheckerLanguages, которого нет в этом массиве, приведет к ошибке.

ses.spellCheckerEnabled​

Значение boolean обозначающее, включена ли встроенная проверка орфографии.

ses.storagePath Только для чтения​

Значение string | null обозначающее абсолютный путь в файловой системе, где данные этой сессии сохраняются на диске. Для сессий в оперативной памяти возвращает null.

ses.cookies Только для чтения​

Объект Cookies для этой сессии.

ses.serviceWorkers Только для чтения​

Объект ServiceWorkers для этой сессии.

ses.webRequest Только для чтения​

Объект WebRequest для этой сессии.

ses.protocol Только для чтения​

Объект Protocol для этой сессии.

const { app, session } = require('electron')
const path = require('path')

app.whenReady().then(() => {
  const protocol = session.fromPartition('some-partition').protocol
  if (!protocol.registerFileProtocol('atom', (request, callback) => {
    const url = request.url.substr(7)
    callback({ path: path.normalize(`${__dirname}/${url}`) })
  })) {
    console.error('Failed to register protocol')
  }
})

ses.netLog Только для чтения​

Объект NetLog для этой сессии.

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

app.whenReady().then(async () => {
  const netLog = session.fromPartition('some-partition').netLog
  netLog.startLogging('/path/to/net-log')
  // After some network events
  const path = await netLog.stopLogging()
  console.log('Net-logs written to', path)
})