13. protocol

作者: Shmily落墨 | 来源:发表于2017-03-17 10:40 被阅读321次

原文：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类型

使用上类似于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类型

使用上类似于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类型

使用上类似于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的拦截器，并且恢复它为原始的处理方式。

13. protocol

方法

`protocol.registerStandardSchemes(schemes[, options])`

`protocol.registerServiceWorkerSchemes(schemes)`

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

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

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

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

`protocol.unregisterProtocol(scheme[, completion])`

`protocol.isProtocolHandled(scheme, callback)`

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

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

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

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

`protocol.uninterceptProtocol(scheme[, completion])`

相关文章

网友评论

延伸阅读

深度阅读

栏目导航

热点阅读

Electron官方文档(v1.6.1)中文翻译