protocol

注册自定义协议并拦截基于现有协议的请求。

进程：主进程

实现与 file:// 协议具有相同效果的协议的示例:

  1. const { app, protocol } = require('electron')
  2. const path = require('path')
  4. app.on('ready', () => {
  5.   protocol.registerFileProtocol('atom', (request, callback) => {
  6.     const url = request.url.substr(7)
  7.     callback({ path: path.normalize(`${__dirname}/${url}`) })
  8.   }, (error) => {
  9.     if (error) console.error('Failed to register protocol')
  10.   })
  11. })

注意: 除了指定的方法, 其他方法只能在 app 模块的 ready 事件被触发后使用。

Using protocol with a custom partition or session

A protocol is registered to a specific Electron session object. If you don’t specify a session, then your protocol will be applied to the default session that Electron uses. However, if you define a partition or session on your browserWindow‘s webPreferences, then that window will use a different session and your custom protocol will not work if you just use electron.protocol.XXX.

To have your custom protocol work in combination with a custom session, you need to register it to that session explicitly.

  1. const { session, app, protocol } = require('electron')
  2. const path = require('path')
  4. app.on('ready', () => {
  5.   const partition = 'persist:example'
  6.   const ses = session.fromPartition(partition)
  8.   ses.protocol.registerFileProtocol('atom', (request, callback) => {
  9.     const url = request.url.substr(7)
  10.     callback({ path: path.normalize(`${__dirname}/${url}`) })
  11.   }, (error) => {
  12.     if (error) console.error('Failed to register protocol')
  13.   })
  15.   mainWindow = new BrowserWindow({
  16.     width: 800,
  17.     height: 600,
  18.     webPreferences: {
  19.       partition: partition
  20.     }
  21.   })
  22. })

方法

protocol 模块具有以下方法：

protocol.registerSchemesAsPrivileged(customSchemes)

注意. 此方法只能在 app 的 ready 事件触发前调用，且只能调用一次

Registers the scheme as standard, secure, bypasses content security policy for resources, allows registering ServiceWorker and supports fetch API.

Specify a privilege with the value of true to enable the capability. An example of registering a privileged scheme, with bypassing Content Security Policy:

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

标准scheme遵循 RFC 3986 所设定的 URI泛型语法 。 例如, http 和 https 是标准协议, 而 file 不是。

将一个scheme注册为标准scheme, 将保证相对和绝对资源在使用时能够得到正确的解析。 否则, 该协议将表现为 file 协议, 而且，这种文件协议将不能解析相对路径。

例如, 当您使用自定义协议加载以下内容时，如果你不将其注册为标准scheme, 图片将不会被加载, 因为非标准scheme无法识别相对 路径:

  1. <body>
  2.   <img src='test.png'>
  3. </body>

注册一个scheme作为标准scheme将允许其通过FileSystem 接口访问文件。 否则, 渲染器将会因为该scheme，而抛出一个安全性错误。

默认情况下web storage apis (localStorage, sessionStorage, webSQL, indexedDB, cookies) 被禁止访问非标准schemes。 So in general if you want to register a custom protocol to replace the http protocol, you have to register it as a standard scheme.

protocol.registerSchemesAsPrivileged can be used to replicate the functionality of the previous protocol.registerStandardSchemes, webFrame.registerURLSchemeAs* and protocol.registerServiceWorkerSchemes functions that existed prior to Electron 5.0.0, for example:

before (<= v4.x)

  1. // Main
  2. protocol.registerStandardSchemes(['scheme1', 'scheme2'], { secure: true })
  3. // Renderer
  4. webFrame.registerURLSchemeAsPrivileged('scheme1', { secure: true })
  5. webFrame.registerURLSchemeAsPrivileged('scheme2', { secure: true })

after (>= v5.x)

  1. protocol.registerSchemesAsPrivileged([
  2.   { scheme: 'scheme1', privileges: { standard: true, secure: true } },
  3.   { scheme: 'scheme2', privileges: { standard: true, secure: true } }
  4. ])

protocol.registerFileProtocol(scheme, handler[, completion])

  • scheme String
  • handler Function
    • request Object
      • url String
      • headers Record
      • referrer String
      • method String
      • uploadData UploadData[]
    • callback Function
  • completion Function (optional)
    • error Error

注册一个 scheme 协议, 将该文件作为响应发送 当要使用 scheme 创建 request 时, 将使用 handler(request, callback) 来调用 handler 。 completion 将在 scheme 注册成功时通过completion(null) 调用，失败时通过completion(error) 调用。

要处理 request, 应当使用文件的路径或具有 path 属性的对象来调用 callback。例如:callback(filePath)或 callback({ path: filePath }). The object may also have a headers property which gives a map of headers to values for the response headers, e.g. callback({ path: filePath, headers: {"Content-Security-Policy": "default-src 'none'"]}).

当 callback 被调用后，并且没有带着数字或 error 属性的对象时, request将会失败, 并且带有你指定的 error错误号。 更多的错误号信息，您可以查阅网络错误列表.

By default the scheme is treated like http:, which is parsed differently than protocols that follow the “generic URI syntax” like file:.

protocol.registerBufferProtocol(scheme, handler[, completion])

  • scheme String
  • handler Function
    • request Object
      • url String
      • headers Record
      • referrer String
      • method String
      • uploadData UploadData[]
    • callback Function
  • completion Function (optional)
    • error Error

注册一个 scheme 协议, 将 Buffer作为响应发送

该用法与 registerFileProtocol 相同, 只是callback 会被Buffer对象或者带有data，mimeType和 charset属性的对象调用。

示例：

  1. const { protocol } = require('electron')
  3. protocol.registerBufferProtocol('atom', (request, callback) => {
  4.   callback({ mimeType: 'text/html', data: Buffer.from('<h5>Response</h5>') })
  5. }, (error) => {
  6.   if (error) console.error('Failed to register protocol')
  7. })

protocol.registerStringProtocol(scheme, handler[, completion])

  • scheme String
  • handler Function
  • completion Function (optional)
    • error Error

注册一个 scheme 协议, 将 String 作为响应发送

该用法与 registerFileProtocol 相同, 只是callback 会被String对象或者带有data，mimeType和 charset属性的对象调用。

protocol.registerHttpProtocol(scheme, handler[, completion])

  • scheme String
  • handler Function
    • request Object
      • url String
      • headers Record
      • referrer String
      • method String
      • uploadData UploadData[]
    • callback Function
      • redirectRequest Object
  • completion Function (optional)
    • error Error

注册一个 scheme 协议, 将 HTTP 请求作为响应发送

该用法与 registerFileProtocol 相同, 只是callback 会被redirectRequest对象或者带有url, method, referrer, uploadData 和 session 属性的对象调用。

By default the HTTP request will reuse the current session. If you want the request to have a different session you should set session to null.

对于 POST 请求, 必须提供 uploadData 对象。

protocol.registerStreamProtocol(scheme, handler[, completion])

  • scheme String
  • handler Function
  • completion Function (optional)
    • error Error

注册一个 scheme 协议, 将 Readable作为响应发送

该用法类似于 register{Any}Protocol ，只是callback 会被Readable对象或者带有data, statusCode 和 headers 属性的对象调用。

示例：

  1. const { protocol } = require('electron')
  2. const { PassThrough } = require('stream')
  4. function createStream (text) {
  5.   const rv = new PassThrough() // PassThrough is also a Readable stream
  6.   rv.push(text)
  7.   rv.push(null)
  8.   return rv
  9. }
  11. protocol.registerStreamProtocol('atom', (request, callback) => {
  12.   callback({
  13.     statusCode: 200,
  14.     headers: {
  15.       'content-type': 'text/html'
  16.     },
  17.     data: createStream('<h5>Response</h5>')
  18.   })
  19. }, (error) => {
  20.   if (error) console.error('Failed to register protocol')
  21. })

It is possible to pass any object that implements the readable stream API (emits data/end/error events). For example, here’s how a file could be returned:

  1. const { protocol } = require('electron')
  2. const fs = require('fs')
  4. protocol.registerStreamProtocol('atom', (request, callback) => {
  5.   callback(fs.createReadStream('index.html'))
  6. }, (error) => {
  7.   if (error) console.error('Failed to register protocol')
  8. })

protocol.unregisterProtocol(scheme[, completion])

  • scheme String
  • completion Function (optional)
    • error Error

取消对自定义scheme的注册

protocol.isProtocolHandled(scheme)

  • scheme String

Returns Promise<Boolean> - fulfilled with a boolean that indicates whether there is already a handler for scheme.

protocol.interceptFileProtocol(scheme, handler[, completion])

  • scheme String
  • handler Function
    • request Object
      • url String
      • headers Record
      • referrer String
      • method String
      • uploadData UploadData[]
    • callback Function
      • filePath String
  • completion Function (optional)
    • error Error

终止 scheme 协议, 并将 handler 作为该protocol新的处理方式，即返回一个file。

protocol.interceptStringProtocol(scheme, handler[, completion])

  • scheme String
  • handler Function
  • completion Function (optional)
    • error Error

终止 scheme 协议, 并将 handler 作为该protocol新的处理方式，即返回一个String。

protocol.interceptBufferProtocol(scheme, handler[, completion])

  • scheme String
  • handler Function
    • request Object
      • url String
      • headers Record
      • referrer String
      • method String
      • uploadData UploadData[]
    • callback Function
      • buffer Buffer (可选)
  • completion Function (optional)
    • error Error

终止 scheme 协议, 并将 handler 作为该protocol新的处理方式，即返回一个Buffer。

protocol.interceptHttpProtocol(scheme, handler[, completion])

  • scheme String
  • handler Function
    • request Object
      • url String
      • headers Record
      • referrer String
      • method String
      • uploadData UploadData[]
    • callback Function
      • redirectRequest Object
  • completion Function (optional)
    • error Error

终止 scheme 协议, 并将 handler 作为该protocol新的处理方式，即返回一个新 HTTP 请求。

protocol.interceptStreamProtocol(scheme, handler[, completion])

  • scheme String
  • handler Function
  • completion Function (optional)
    • error Error

它与 registerStreamProtocol方法相同, 不过它是用来替换现有的protocol处理方式。

protocol.uninterceptProtocol(scheme[, completion])

  • scheme String
  • completion Function (optional)
    • error Error

移除为 scheme 安装的拦截器，并还原其原始处理方式。