протокол

Зарегистрируйте пользовательский протокол и перехватите существующие запросы протокола.

Пример реализации протокола, который имеет тот же эффект, что и file:// протокол:

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

app.whenReady().then(() => {
  protocol.registerFileProtocol('atom', (request, callback) => {
    const url = request.url.substr(7)
    callback({ path: path.normalize(`${__dirname}/${url}`) })
  })
})

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

Использование `protocol` с пользовательским `partition` или `session`

Протокол регистрируется в определенном объекте Electron session. Если вы не укажете сессию, то ваш protocol будет применён к по умолчанию используемой Electron сессии. Однако, если вы определите partition или session в browserWindow окна, то это окно будет использовать другую сессию и ваш пользовательский протокол не будет работать, если вы просто используете electron.protocol.XXX.

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

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

app.whenReady().then(() => {
  const partition = 'persist:example'
  const ses = session.fromPartition(partition)

  ses.protocol.registerFileProtocol('atom', (request, callback) => {
    const url = request.url.substr(7)
    callback({ path: path.normalize(`${__dirname}/${url}`) })
  })

  mainWindow = new BrowserWindow({ webPreferences: { partition } })
})

Методы

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

`protocol.registerSchemesAsPrivileged(customSchemes)`

customSchemes CustomScheme[]

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

Регистрирует scheme как стандартный, защищённый, обходит политику безопасности содержимого для ресурсов, позволяет регистрировать ServiceWorker, поддерживает API fetch и потоковую передачу видео/аудио. Укажите привилегию со значением true для включения этой возможности.

Пример регистрации привилегированного схемы, обходящего политику безопасности содержимого:

const { protocol } = require('electron')
protocol.registerSchemesAsPrivileged([
  { scheme: 'foo', privileges: { bypassCSP: true } }
])

Стандартная схема соответствует тому, что RFC 3986 называет общим синтаксисом URI. Например, http и https являются стандартными схемами, в то время как file — нет.

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

Например, при загрузке следующей страницы с пользовательским протоколом без регистрации его как стандартной схемы, изображение не загрузится, так как нестандартные схемы не могут распознать относительные URL:

<body>
  <img src='test.png'>
</body>

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

По умолчанию веб-хранилища (localStorage, sessionStorage, webSQL, indexedDB, cookies) отключены для нестандартных схем. Поэтому, если вы хотите зарегистрировать пользовательский протокол для замены протокола http, необходимо зарегистрировать его как стандартную схему.

Протоколы, использующие потоки (http и stream протоколы), должны установить stream: true. Элементы HTML <video> и <audio> по умолчанию ожидают, что протоколы буферизуют свои ответы. Флаг stream настраивает эти элементы, чтобы они правильно ожидали потоковые ответы.

`protocol.registerFileProtocol(scheme, handler)`

scheme строка
handler Функция
- request ЗапросПротокола
- callback Функция
  - response (строка | ОтветПротокола)

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

Регистрирует протокол scheme, который будет отправлять файл в качестве ответа. Функция handler будет вызвана с request и callback, где request — входящий запрос для scheme.

Для обработки request, функция callback должна быть вызвана с путём к файлу или объектом, имеющим свойство path, например, callback(filePath) или callback({ path: filePath }). Свойство filePath должно быть абсолютным путём.

По умолчанию scheme обрабатывается как http:, что парсится по-другому, чем протоколы, которые следуют общему синтаксису URI, как file:.

`protocol.registerBufferProtocol(scheme, handler)`

scheme строка
handler Функция
- request ЗапросПротокола
- callback Функция
  - response (Буфер | ОтветПротокола)

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

Регистрирует протокол scheme, который будет отправлять Buffer в качестве ответа.

Использование аналогично registerFileProtocol, за исключением того, что callback должно быть вызвано с объектом Buffer или объектом, имеющим свойство data.

Пример:

protocol.registerBufferProtocol('atom', (request, callback) => {
  callback({ mimeType: 'text/html', data: Buffer.from('<h5>Response</h5>') })
})

`protocol.registerStringProtocol(scheme, handler)`

scheme строка
handler Функция
- request ЗапросПротокола
- callback Функция
  - response (строка | ОтветПротокола)

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

Регистрирует протокол scheme, который будет отправлять string в качестве ответа.

Использование аналогично registerFileProtocol, за исключением того, что callback должно быть вызвано с строкой string или объектом, имеющим свойство data.

`protocol.registerHttpProtocol(scheme, handler)`

scheme строка
handler Функция
- request ЗапросПротокола
- callback Функция
  - response ОтветПротокола

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

Регистрирует протокол scheme, который будет отправлять HTTP запрос в качестве ответа.

Использование аналогично registerFileProtocol, за исключением того, что callback должно быть вызвано с объектом, имеющим свойство url.

`protocol.registerStreamProtocol(scheme, handler)`

scheme строка
handler Функция
- request ЗапросПротокола
- callback Функция
  - response (ПотокЧтения | ОтветПротокола)

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

Регистрирует протокол scheme, который будет отправлять поток в качестве ответа.

Использование аналогично registerFileProtocol, за исключением того, что callback должно быть вызвано с объектом ReadableStream или объектом, имеющим свойство data.

Пример:

const { protocol } = require('electron')
const { PassThrough } = require('stream')

function createStream (text) {
  const rv = new PassThrough() // PassThrough is also a Readable stream
  rv.push(text)
  rv.push(null)
  return rv
}

protocol.registerStreamProtocol('atom', (request, callback) => {
  callback({
    statusCode: 200,
    headers: {
      'content-type': 'text/html'
    },
    data: createStream('<h5>Response</h5>')
  })
})

Можно передать любой объект, реализующий API потока чтения (вызывает события data/end/error). Например, вот как можно вернуть файл:

protocol.registerStreamProtocol('atom', (request, callback) => {
  callback(fs.createReadStream('index.html'))
})

`protocol.unregisterProtocol(scheme)`

scheme строка

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

Удаляет пользовательский протокол scheme.

`protocol.isProtocolRegistered(scheme)`

scheme строка

Возвращает boolean - Зарегистрирован ли уже scheme.