13. protocol

原文：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类型
  • 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的拦截器，并且恢复它为原始的处理方式。

最后编辑于 ：
©著作权归作者所有,转载或内容合作请联系作者
  • 人面猴
    序言：七十年代末，一起剥皮案震惊了整个滨河市，随后出现的几起案子，更是在滨河造成了极大的恐慌，老刑警刘岩，带你破解...
    沈念sama阅读 201,312评论 5赞 473
  • 死咒
    序言：滨河连续发生了三起死亡事件，死亡现场离奇诡异，居然都是意外死亡，警方通过查阅死者的电脑和手机，发现死者居然都...
    沈念sama阅读 84,578评论 2赞 377
  • 救了他两次的神仙让他今天三更去死
    文/潘晓璐 我一进店门，熙熙楼的掌柜王于贵愁眉苦脸地迎上来，“玉大人，你说我怎么就摊上这事。” “怎么了？”我有些...
    开封第一讲书人阅读 148,337评论 0赞 333
  • 道士缉凶录：失踪的卖姜人
    文/不坏的土叔 我叫张陵，是天一观的道长。 经常有香客问我，道长，这世上最难降的妖魔是什么？ 我笑而不...
    开封第一讲书人阅读 54,134评论 1赞 272
  • 港岛之恋（遗憾婚礼）
    正文 为了忘掉前任，我火速办了婚礼，结果婚礼上，老公的妹妹穿的比我还像新娘。我一直安慰自己，他们只是感情好，可当我...
    茶点故事阅读 63,161评论 5赞 363
  • 恶毒庶女顶嫁案：这布局不是一般人想出来的
    文/花漫 我一把揭开白布。 她就那样静静地躺着，像睡着了一般。 火红的嫁衣衬着肌肤如雪。 梳的纹丝不乱的头发上，一...
    开封第一讲书人阅读 48,303评论 1赞 280
  • 城市分裂传说
    那天，我揣着相机与录音，去河边找鬼。 笑死，一个胖子当着我的面吹牛，可吹牛的内容都是我干的。 我是一名探鬼主播，决...
    沈念sama阅读 37,761评论 3赞 393
  • 双鸳鸯连环套：你想象不到人心有多黑
    文/苍兰香墨 我猛地睁开眼，长吁一口气：“原来是场噩梦啊……” “哼！你这毒妇竟也来了？” 一声冷哼从身侧响起，我...
    开封第一讲书人阅读 36,421评论 0赞 256
  • 万荣杀人案实录
    序言：老挝万荣一对情侣失踪，失踪者是张志新（化名）和其女友刘颖，没想到半个月后，有当地人在树林里发现了一具尸体，经...
    沈念sama阅读 40,609评论 1赞 295
  • 护林员之死
    正文 独居荒郊野岭守林人离奇死亡，尸身上长有42处带血的脓包…… 初始之章·张勋 以下内容为张勋视角 年9月15日...
    茶点故事阅读 35,450评论 2赞 317
  • 白月光启示录
    正文 我和宋清朗相恋三年，在试婚纱的时候发现自己被绿了。 大学时的朋友给我发了我未婚夫和他白月光在一起吃饭的照片。...
    茶点故事阅读 37,504评论 1赞 329
  • 活死人
    序言：一个原本活蹦乱跳的男人离奇死亡，死状恐怖，灵堂内的尸体忽然破棺而出，到底是诈尸还是另有隐情，我是刑警宁泽，带...
    沈念sama阅读 33,194评论 3赞 318
  • 日本核电站爆炸内幕
    正文 年R本政府宣布，位于F岛的核电站，受9级特大地震影响，放射性物质发生泄漏。R本人自食恶果不足惜，却给世界环境...
    茶点故事阅读 38,760评论 3赞 303
  • 男人毒药：我在死后第九天来索命
    文/蒙蒙 一、第九天 我趴在偏房一处隐蔽的房顶上张望。 院中可真热闹，春花似锦、人声如沸。这庄子的主人今日做“春日...
    开封第一讲书人阅读 29,836评论 0赞 19
  • 一桩弑父案，背后竟有这般阴谋
    文/苍兰香墨 我抬头看了看天上的太阳。三九已至，却和暖如春，着一层夹袄步出监牢的瞬间，已是汗流浃背。 一阵脚步声响...
    开封第一讲书人阅读 31,066评论 1赞 257
  • 情欲美人皮
    我被黑心中介骗来泰国打工， 没想到刚下飞机就差点儿被人妖公主榨干…… 1. 我叫王不留，地道东北人。 一个月前我还...
    沈念sama阅读 42,612评论 2赞 348
  • 代替公主和亲
    正文 我出身青楼，却偏偏与公主长得像，于是被迫代替她去往敌国和亲。 传闻我的和亲对象是个残疾皇子，可洞房花烛夜当晚...
    茶点故事阅读 42,178评论 2赞 341

推荐阅读更多精彩内容