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
stringhandler
Functionrequest
ProtocolRequestcallback
Functionresponse
(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
stringhandler
Functionrequest
ProtocolRequestcallback
Functionresponse
(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
stringhandler
Functionrequest
ProtocolRequestcallback
Functionresponse
(string | ProtocolResponse)
Returns boolean
- Whether the protocol was successfully registered
Регистрирует протокол scheme
, который отправит string
в качестве ответа.
Использование аналогично registerFileProtocol
, за исключением того, что callback
должен вызываться либо с string
, либо с объектом, имеющим свойство data
.
protocol.registerHttpProtocol(scheme, handler)
scheme
stringhandler
Functionrequest
ProtocolRequestcallback
Functionresponse
ProtocolResponse
Returns boolean
- Whether the protocol was successfully registered
Регистрирует протокол scheme
, который отправит HTTP-запрос в качестве ответа.
Использование аналогично registerFileProtocol
, за исключением того, что callback
должен быть вызван с объектом, имеющим свойство url
.
protocol.registerStreamProtocol(scheme, handler)
scheme
stringhandler
Functionrequest
ProtocolRequestcallback
Functionresponse
(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
уже зарегистрированной.
protocol.interceptFileProtocol(scheme, handler)
scheme
stringhandler
Functionrequest
ProtocolRequestcallback
Functionresponse
(string | ProtocolResponse)
Returns boolean
- Whether the protocol was successfully intercepted
Перехватывает протокол scheme
и использует handler
в качестве нового обработчика протокола, который отправляет файл в качестве ответа.
protocol.interceptStringProtocol(scheme, handler)
scheme
stringhandler
Functionrequest
ProtocolRequestcallback
Functionresponse
(string | ProtocolResponse)
Returns boolean
- Whether the protocol was successfully intercepted
Перехватывает протокол scheme
и использует handler
в качестве нового обработчика протокола, который отправляет string
в качестве ответа.
protocol.interceptBufferProtocol(scheme, handler)
scheme
stringhandler
Functionrequest
ProtocolRequestcallback
Functionresponse
(Buffer | ProtocolResponse)
Returns boolean
- Whether the protocol was successfully intercepted
Перехватывает протокол scheme
и использует handler
в качестве нового обработчика протокола, который отправляет Buffer
в качестве ответа.
protocol.interceptHttpProtocol(scheme, handler)
scheme
stringhandler
Functionrequest
ProtocolRequestcallback
Functionresponse
ProtocolResponse
Returns boolean
- Whether the protocol was successfully intercepted
Перехватывает протокол scheme
и использует handler
в качестве нового обработчика протокола, который отправляет новый HTTP-запрос в качестве ответа.
protocol.interceptStreamProtocol(scheme, handler)
scheme
stringhandler
Functionrequest
ProtocolRequestcallback
Functionresponse
(ReadableStream | ProtocolResponse)
Returns boolean
- Whether the protocol was successfully intercepted
То же самое, что и protocol.registerStreamProtocol
, за исключением того, что он заменяет существующий обработчик протокола.
protocol.uninterceptProtocol(scheme)
scheme
string
Returns boolean
- Whether the protocol was successfully unintercepted
Remove the interceptor installed for scheme
and restore its original handler.
protocol.isProtocolIntercepted(scheme)
scheme
string
Возвращает boolean
- является ли scheme
уже перехваченной.