protocol

Регистрация пользовательского протокола и перехват существующих запросов протокола.

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

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

app.whenReady().then(() => {
  protocol.registerFileProtocol('atom', (request, callback) => {
    const filePath = url.fileURLToPath('file://' + request.url.slice('atom://'.length))
    callback(filePath)
  })
})

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

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

Протокол регистрируется для определенного Electron объекта session. Если вы не укажете сеанс, то ваш protocol будет применен сеансу по умолчанию, который использует Electron. Однако, если вы определите partition или session в браузереWindow в webPreferences, то это окно будет использовать другой сеанс, и ваш пользовательский протокол не будет работать, если вы просто используете 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 и может быть вызван только один раз.

Registers the scheme as standard, secure, bypasses content security policy for resources, allows registering ServiceWorker, supports fetch API, and streaming video/audio. Specify a privilege with the value of true to enable the capability.

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

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>

Registering a scheme as standard will allow access to files through the FileSystem API. В противном случае программа для схемы выдаст ошибку безопасности.

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

Protocols that use streams (http and stream protocols) should set stream: true. The <video> and <audio> HTML elements expect protocols to buffer their responses by default. The stream flag configures those elements to correctly expect streaming responses.

`protocol.registerFileProtocol(scheme, handler)`

scheme string
handler Function
- request ProtocolRequest
- callback Function
  - response (string | ProtocolResponse)

Returns boolean - Whether the protocol was successfully registered

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

To handle the request, the callback should be called with either the file's path or an object that has a path property, e.g. callback(filePath) or callback({ path: filePath }). filePath должен быть абсолютным путем.

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

`protocol.registerBufferProtocol(scheme, handler)`

scheme string
handler Function
- request ProtocolRequest
- callback Function
  - response (Buffer | ProtocolResponse)

Returns boolean - Whether the protocol was successfully registered

Регистрирует протокол 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 string
handler Function
- request ProtocolRequest
- callback Function
  - response (string | ProtocolResponse)

Returns boolean - Whether the protocol was successfully registered

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

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

`protocol.registerHttpProtocol(scheme, handler)`

scheme string
handler Function
- request ProtocolRequest
- callback Function
  - response ProtocolResponse

Returns boolean - Whether the protocol was successfully registered

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

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

`protocol.registerStreamProtocol(scheme, handler)`

scheme string
handler Function
- request ProtocolRequest
- callback Function
  - response (ReadableStream | ProtocolResponse)

Returns boolean - Whether the protocol was successfully registered

Регистрирует протокол 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 string

Returns boolean - Whether the protocol was successfully unregistered

Отменяет регистрацию пользовательского протокола scheme.

`protocol.isProtocolRegistered(scheme)`

scheme string

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