protocol
注册自定义协议并拦截现有协议请求。
进程:主进程
实现一个与 file://
协议具有相同效果的协议的示例
const { app, protocol, net } = require('electron')
const path = require('node:path')
const url = require('node:url')
app.whenReady().then(() => {
protocol.handle('atom', (request) => {
const filePath = request.url.slice('atom://'.length)
return net.fetch(url.pathToFileURL(path.join(__dirname, filePath)).toString())
})
})
除非另有说明,否则所有方法都只能在 app
模块的 ready
事件发出后才能使用。
使用 protocol
结合自定义 partition
或 session
协议是注册到特定的 Electron session
对象上的。如果你不指定 session,那么你的 protocol
将应用于 Electron 使用的默认 session。但是,如果你在 browserWindow
的 webPreferences
中定义了 partition
或 session
,那么该窗口将使用不同的 session,而如果你只使用 electron.protocol.XXX
,你的自定义协议将无法正常工作。
要使你的自定义协议与自定义 session 结合使用,你需要显式地将其注册到该 session。
const { app, BrowserWindow, net, protocol, session } = require('electron')
const path = require('node:path')
const url = require('url')
app.whenReady().then(() => {
const partition = 'persist:example'
const ses = session.fromPartition(partition)
ses.protocol.handle('atom', (request) => {
const filePath = request.url.slice('atom://'.length)
return net.fetch(url.pathToFileURL(path.resolve(__dirname, filePath)).toString())
})
const mainWindow = new BrowserWindow({ webPreferences: { partition } })
})
方法
protocol
模块具有以下方法
protocol.registerSchemesAsPrivileged(customSchemes)
customSchemes
CustomScheme[]
此方法只能在 app
模块的 ready
事件发出之前使用,并且只能调用一次。
将 scheme
注册为标准、安全、绕过资源的内容安全策略、允许注册 ServiceWorker、支持 fetch API、流式视频/音频和 V8 代码缓存。将特权指定为 true
以启用该功能。
注册一个特权 scheme 的示例,该 scheme 会绕过内容安全策略
const { protocol } = require('electron')
protocol.registerSchemesAsPrivileged([
{ scheme: 'foo', privileges: { bypassCSP: true } }
])
标准 scheme 符合 RFC 3986 中所说的 通用 URI 语法。例如,http
和 https
是标准 scheme,而 file
则不是。
将 scheme 注册为标准 scheme 允许相对和绝对资源在提供时被正确解析。否则,该 scheme 将表现得像 file
协议,但无法解析相对 URL。
例如,当使用自定义协议加载以下页面而未将其注册为标准 scheme 时,图片将不会加载,因为非标准 scheme 无法识别相对 URL。
<body>
<img src='test.png'>
</body>
将 scheme 注册为标准 scheme 将允许通过 FileSystem API 访问文件。否则,渲染器将为此 scheme 抛出安全错误。
默认情况下,web 存储 API(localStorage、sessionStorage、webSQL、indexedDB、cookies)对非标准 scheme 是禁用的。因此,通常情况下,如果你想注册一个自定义协议来替换 http
协议,你必须将其注册为标准 scheme。
使用流(http 和 stream 协议)的协议应设置 stream: true
。<video>
和 <audio>
HTML 元素默认期望协议缓冲其响应。stream
标志可配置这些元素以正确期望流式响应。
protocol.handle(scheme, handler)
scheme
string - 要处理的 scheme,例如https
或my-app
。这是 URL 中:
前面的部分。handler
Function<GlobalResponse | Promise<GlobalResponse>>request
GlobalRequest
为 scheme
注册一个协议处理程序。对具有此 scheme 的 URL 的请求将委托给此处理程序来确定应发送什么响应。
可以返回 Response
或 Promise<Response>
。
示例
const { app, net, protocol } = require('electron')
const path = require('node:path')
const { pathToFileURL } = require('url')
protocol.registerSchemesAsPrivileged([
{
scheme: 'app',
privileges: {
standard: true,
secure: true,
supportFetchAPI: true
}
}
])
app.whenReady().then(() => {
protocol.handle('app', (req) => {
const { host, pathname } = new URL(req.url)
if (host === 'bundle') {
if (pathname === '/') {
return new Response('<h1>hello, world</h1>', {
headers: { 'content-type': 'text/html' }
})
}
// NB, this checks for paths that escape the bundle, e.g.
// app://bundle/../../secret_file.txt
const pathToServe = path.resolve(__dirname, pathname)
const relativePath = path.relative(__dirname, pathToServe)
const isSafe = relativePath && !relativePath.startsWith('..') && !path.isAbsolute(relativePath)
if (!isSafe) {
return new Response('bad', {
status: 400,
headers: { 'content-type': 'text/html' }
})
}
return net.fetch(pathToFileURL(pathToServe).toString())
} else if (host === 'api') {
return net.fetch('https://api.my-server.com/' + pathname, {
method: req.method,
headers: req.headers,
body: req.body
})
}
})
})
有关更多详细信息,请参阅 MDN 文档中的 Request
和 Response
。
protocol.unhandle(scheme)
scheme
string - 要从中移除处理程序的 scheme。
移除使用 protocol.handle
注册的协议处理程序。
protocol.isProtocolHandled(scheme)
scheme
string
返回 boolean
- scheme
是否已处理。
protocol.registerFileProtocol(scheme, handler)
已弃用
scheme
stringhandler
Functionrequest
ProtocolRequestcallback
Functionresponse
(string | ProtocolResponse)
返回 boolean
- 协议是否已成功注册
注册一个 scheme
协议,该协议将发送一个文件作为响应。handler
将使用 request
和 callback
调用,其中 request
是对 scheme
的传入请求。
要处理 request
,应使用文件的路径或具有 path
属性的对象调用 callback
,例如 callback(filePath)
或 callback({ path: filePath })
。filePath
必须是绝对路径。
默认情况下,scheme
被视为 http:
,它与遵循“通用 URI 语法”的协议(如 file:
)的解析方式不同。
protocol.registerBufferProtocol(scheme, handler)
已弃用
scheme
stringhandler
Functionrequest
ProtocolRequestcallback
Functionresponse
(Buffer | ProtocolResponse)
返回 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
stringhandler
Functionrequest
ProtocolRequestcallback
Functionresponse
(string | ProtocolResponse)
返回 boolean
- 协议是否已成功注册
注册一个 scheme
协议,该协议将发送一个 string
作为响应。
用法与 registerFileProtocol
相同,只是 callback
应使用 string
或具有 data
属性的对象来调用。
protocol.registerHttpProtocol(scheme, handler)
已弃用
scheme
stringhandler
Functionrequest
ProtocolRequestcallback
Functionresponse
ProtocolResponse
返回 boolean
- 协议是否已成功注册
注册一个 scheme
协议,该协议将发送一个 HTTP 请求作为响应。
用法与 registerFileProtocol
相同,只是 callback
应使用具有 url
属性的对象来调用。
protocol.registerStreamProtocol(scheme, handler)
已弃用
scheme
stringhandler
Functionrequest
ProtocolRequestcallback
Functionresponse
(ReadableStream | ProtocolResponse)
返回 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
string
返回 boolean
- 协议是否已成功注销
注销 scheme
的自定义协议。
protocol.isProtocolRegistered(scheme)
已弃用
scheme
string
返回 boolean
- scheme
是否已注册。
protocol.interceptFileProtocol(scheme, handler)
已弃用
scheme
stringhandler
Functionrequest
ProtocolRequestcallback
Functionresponse
(string | ProtocolResponse)
返回 boolean
- 协议是否已成功拦截
拦截 scheme
协议,并将 handler
作为协议的新处理程序,该处理程序发送一个文件作为响应。
protocol.interceptStringProtocol(scheme, handler)
已弃用
scheme
stringhandler
Functionrequest
ProtocolRequestcallback
Functionresponse
(string | ProtocolResponse)
返回 boolean
- 协议是否已成功拦截
拦截 scheme
协议,并将 handler
作为协议的新处理程序,该处理程序发送一个 string
作为响应。
protocol.interceptBufferProtocol(scheme, handler)
已弃用
scheme
stringhandler
Functionrequest
ProtocolRequestcallback
Functionresponse
(Buffer | ProtocolResponse)
返回 boolean
- 协议是否已成功拦截
拦截 scheme
协议,并将 handler
作为协议的新处理程序,该处理程序发送一个 Buffer
作为响应。
protocol.interceptHttpProtocol(scheme, handler)
已弃用
scheme
stringhandler
Functionrequest
ProtocolRequestcallback
Functionresponse
ProtocolResponse
返回 boolean
- 协议是否已成功拦截
拦截 scheme
协议,并将 handler
作为协议的新处理程序,该处理程序发送一个新的 HTTP 请求作为响应。
protocol.interceptStreamProtocol(scheme, handler)
已弃用
scheme
stringhandler
Functionrequest
ProtocolRequestcallback
Functionresponse
(ReadableStream | ProtocolResponse)
返回 boolean
- 协议是否已成功拦截
与 protocol.registerStreamProtocol
相同,但它会替换现有的协议处理程序。
protocol.uninterceptProtocol(scheme)
已弃用
scheme
string
返回 boolean
- 协议是否已成功解除拦截
移除为 scheme
安装的拦截器并恢复其原始处理程序。
protocol.isProtocolIntercepted(scheme)
已弃用
scheme
string
返回 boolean
- scheme
是否已拦截。