原文:https://github.com/electron/electron/blob/master/docs/api/protocol.md
译者:Lin
注册一个自定义协议,并且拦截现有协议的请求
进程:主进程
执行一个协议的例子,对file://
协议同样有效:
const {app, protocol} = require('electron')
const path = require('path')
app.on('ready', () => {
protocol.registerFileProtocol('atom', (request, callback) => {
const url = request.url.substr(7)
callback({path: path.normalize(`${__dirname}/${url}`)})
}, (error) => {
if (error) console.error('Failed to register protocol')
})
})
注意:除特殊说明的方法之外,所有方法都必须在app
模块分发ready
事件之后使用。
方法
protocol
模块有以下方法:
protocol.registerStandardSchemes(schemes[, options])
-
schemes
String[]类型 - 以标准scheme注册自定义scheme。 -
options
Object类型(可选参数)-
secure
Boolean类型(可选参数)-true
表示安全的注册scheme。否则则是false
。
-
一个标准的scheme遵循RFC 3986的generic URI syntax。例如http
和https
是标准scheme,而file
则不是。
注册一个scheme作为标准,当开启服务时将允许相关的和完全一致的资源被正确的解析。否则scheme将会像file
协议一样,没有资格解析相应的URL。
例如当你使用没有注册为标准scheme的自定义协议加载下面的页面时,图片将不会被加载,因为不标准schemes将无法识别相应的URL:
<body>
![](test.png)
</body>
注册一个scheme作为标准将允许通过FileSystem API使用文件。否则渲染器将抛出一个安全的scheme的错误。
默认情况下,网页存储接口(localStorage, sessionStorage, webSQL, indexedDB, cookies)在不标准的scheme中是不允许使用的。所以通常情况下,如果你想注册一个自定义协议来代替http
协议,你需要注册它为一个标准的scheme:
const {app, protocol} = require('electron')
protocol.registerStandardSchemes(['atom'])
app.on('ready', () => {
protocol.registerHttpProtocol('atom', '...')
})
注意:这个方法只可以在app
模块分发ready
事件之前使用。
protocol.registerServiceWorkerSchemes(schemes)
-
schemes
String[]类型 - 注册自定义scheme来处理service workers。
protocol.registerFileProtocol(scheme, handler[, completion])
-
scheme
String类型 -
handler
Function类型-
request
Object类型-
url
String类型 -
referrer
String类型 -
method
String类型 -
uploadData
UploadData[]类型
-
-
callback
Function类型-
filePath
String类型(可选参数)
-
-
-
completion
Function类型(可选参数)-
error
Error类型
-
注册scheme
中的协议,该协议将会发送文件作为响应。当一个request
被使用scheme
创建,handler
将会被使用handler(request, callback)
调用。当scheme
被成功注册将会被使用completion(null)
调用,当scheme
注册失败将会被使用completion(error)
调用。
为了处理request
,callback
需要被使用文件的路径或者一个拥有path
属性的对象来调用,例如callback(filePath)
或callback({path: filePath})
。
当callback
没有被使用任何值或使用一个数值或一个拥有error
属性的对象而调用的时候,将认为你指定的error
数值是request
失败的原因。对于你可以使用的错误数值,你可以查看net error list。
默认情况下,scheme
是被处理为类似http:
,像file:
一样遵循"generic URI syntax"来分析不同的协议,所以你可能想调用protocol.registerStandardSchemes
来使你的scheme被处理为一个标准scheme。
protocol.registerBufferProtocol(scheme, handler[, completion])
-
scheme
String类型 -
handler
Function类型-
request
Object类型-
url
String类型 -
referrer
String类型 -
method
String类型 -
uploadData
UploadData[]类型
-
-
callback
Function类型-
buffer
(Buffer | MimeTypedBuffer)类型(可选参数)
-
-
-
completion
Function类型(可选参数)-
error
Error类型
-
注册scheme
中的协议,该协议将会发送一个Buffer
作为响应。
使用上类似于registerFileProtocol
,除了callback
需要被使用Buffer
对象或者一个拥有data
、mimeType
和charset
属性的对象来调用。
例如:
const {protocol} = require('electron')
protocol.registerBufferProtocol('atom', (request, callback) => {
callback({mimeType: 'text/html', data: new Buffer('<h5>Response</h5>')})
}, (error) => {
if (error) console.error('Failed to register protocol')
})
protocol.registerStringProtocol(scheme, handler[, completion])
-
scheme
String类型 -
handler
Function类型-
request
Object类型-
url
String类型 -
referrer
String类型 -
method
String类型 -
uploadData
UploadData[]类型
-
-
callback
Function类型-
data
String类型(可选参数)
-
-
-
completion
Function类型(可选参数)-
error
Error类型
-
注册scheme
中的协议,该协议将会发送一个String
作为响应。
使用上类似于registerFileProtocol
,除了callback
需要被使用String
对象或者一个拥有data
、mimeType
和charset
属性的对象来调用。
protocol.registerHttpProtocol(scheme, handler[, completion])
-
scheme
String类型 -
handler
Function类型-
request
Object类型-
url
String类型 -
referrer
String类型 -
method
String类型 -
uploadData
UploadData[]类型
-
-
callback
Function类型-
redirectRequest
Object类型-
url
String类型 -
method
String类型 -
session
Object类型(可选参数) -
uploadData
Object类型(可选参数)-
contentType
String类型 - 内容的MIME类型。 -
data
String类型 - 要发送的内容。
-
-
-
-
-
completion
Function类型(可选参数)-
error
Error类型
-
注册scheme
中的协议,该协议将会发送一个HTTP请求作为响应。
使用上类似于registerFileProtocol
,除了callback
需要被使用redirectRequest
对象或者一个拥有url
、method
、referrer
、uploadData
和session
属性的对象来调用。
默认情况下,HTTP请求将重用当前会话。如果你想要请求一个不同的胡话,你需要设置session
为null
。
对于POST请求,必须提供uploadData
对象。
protocol.unregisterProtocol(scheme[, completion])
-
scheme
String类型 -
completion
Function类型(可选参数)-
error
Error类型
-
取消注册scheme
的自定义协议。
protocol.isProtocolHandled(scheme, callback)
-
scheme
String类型 -
callback
Function类型-
error
Error类型
-
callback
将会被使用一个布尔值调用,来表明这事是否有一个对scheme
的处理。
protocol.interceptFileProtocol(scheme, handler[, completion])
-
scheme
String类型 -
handler
Function类型-
request
Object类型-
url
String类型 -
referrer
String类型 -
method
String类型 -
uploadData
UploadData[]类型
-
-
callback
Function类型-
filePath
String类型
-
-
-
completion
Function类型(可选参数)-
error
Error类型
-
拦截scheme
协议,并使用handler
作为这个协议的心得处理器,将发送一个文件作为返回值。
protocol.interceptStringProtocol(scheme, handler[, completion])
-
scheme
String类型 -
handler
Function类型-
request
Object类型-
url
String类型 -
referrer
String类型 -
method
String类型 -
uploadData
UploadData[]类型
-
-
callback
Function类型-
data
String类型(可选参数)
-
-
-
completion
Function类型(可选参数)-
error
Error类型
-
拦截scheme
协议,并使用handler
作为这个协议的心得处理器,将发送一个String
作为返回值。
protocol.interceptBufferProtocol(scheme, handler[, completion])
-
scheme
String类型 -
handler
Function类型-
request
Object类型-
url
String类型 -
referrer
String类型 -
method
String类型 -
uploadData
UploadData[]类型
-
-
callback
Function类型-
buffer
Buffer类型(可选参数)
-
-
-
completion
Function类型(可选参数)-
error
Error类型
-
拦截scheme
协议,并使用handler
作为这个协议的心得处理器,将发送一个Buffer
作为返回值。
protocol.interceptHttpProtocol(scheme, handler[, completion])
-
scheme
String类型 -
handler
Function类型-
request
Object类型-
url
String类型 -
referrer
String类型 -
method
String类型 -
uploadData
UploadData[]类型
-
-
callback
Function类型-
redirectRequest
Object类型-
url
String类型 -
method
String类型 -
session
Object类型(可选参数) -
uploadData
Object类型(可选参数)-
contentType
String类型 - 内容的MIME类型。 -
data
String类型 - 要发送的内容。
-
-
-
-
-
completion
Function类型(可选参数)-
error
Error类型
-
拦截scheme
协议,并使用handler
作为这个协议的心得处理器,将发送一个新的HTTP请求作为返回值。
protocol.uninterceptProtocol(scheme[, completion])
-
scheme
String类型 -
completion
Function类型(可选参数)-
error
Error类型
-
移除一个已经安装的scheme
的拦截器,并且恢复它为原始的处理方式。