Electron session 模塊

2019-08-14 19:21 更新

session 模塊可以用來創(chuàng)建一個新的 Session 對象.

你也可以通過使用 webContents 的屬性 session 來使用一個已有頁面的 session ，webContents是BrowserWindow 的屬性.

const BrowserWindow = require('electron').BrowserWindow;

var win = new BrowserWindow({ width: 800, height: 600 });
win.loadURL("http://github.com");

var ses = win.webContents.session;

方法

session 模塊有如下方法:

session.fromPartition(partition)

  • partition String

從字符串 partition 返回一個新的 Session 實例.

如果 partition 以 persist: 開頭，那么這個page將使用一個持久的 session，這個 session 將對應用的所有 page 可用.如果沒前綴，這個 page 將使用一個歷史 session.如果 partition 為空，那么將返回應用的默認 session .

屬性

session 模塊有如下屬性:

session.defaultSession

返回應用的默認 session 對象.

Class: Session

可以在 session 模塊中創(chuàng)建一個 Session 對象 :

const session = require('electron').session;

var ses = session.fromPartition('persist:name');

實例事件

實例 Session 有以下事件:

Event: 'will-download'

當 Electron 將要從 webContents 下載 item 時觸發(fā).

調用 event.preventDefault() 可以取消下載，并且在進程的下個 tick中，這個 item 也不可用.

session.defaultSession.on('will-download', function(event, item, webContents) {
  event.preventDefault();
  require('request')(item.getURL(), function(data) {
    require('fs').writeFileSync('/somewhere', data);
  });
});

實例方法

實例 Session 有以下方法:

ses.cookies

cookies 賦予你全力來查詢和修改 cookies. 例如:

// 查詢所有 cookies.
session.defaultSession.cookies.get({}, function(error, cookies) {
  console.log(cookies);
});

// 查詢與指定 url 相關的所有 cookies.
session.defaultSession.cookies.get({ url : "http://www.github.com" }, function(error, cookies) {
  console.log(cookies);
});

// 設置 cookie;
// may overwrite equivalent cookies if they exist.
var cookie = { url : "http://www.github.com", name : "dummy_name", value : "dummy" };
session.defaultSession.cookies.set(cookie, function(error) {
  if (error)
    console.error(error);
});

ses.cookies.get(filter, callback)

  • filter Object
    • url String (可選) - 與獲取 cookies 相關的 url.不設置的話就是從所有 url 獲取 cookies .
    • name String (可選) - 通過 name 過濾 cookies.
    • domain String (可選) - 獲取對應域名或子域名的 cookies .
    • path String (可選) - 獲取對應路徑的 cookies .
    • secure Boolean (可選) - 通過安全性過濾 cookies.
    • session Boolean (可選) - 過濾掉 session 或 持久的 cookies.
  • callback Function

發(fā)送一個請求，希望獲得所有匹配 details 的 cookies, 在完成的時候，將通過 callback(error, cookies) 調用 callback.

cookies是一個 cookie 對象.

  • cookie Object
    • name String - cookie 名.
    • value String - cookie值.
    • domain String - cookie域名.
    • hostOnly String - 是否 cookie 是一個 host-only cookie.
    • path String - cookie路徑.
    • secure Boolean - 是否是安全 cookie.
    • httpOnly Boolean - 是否只是 HTTP cookie.
    • session Boolean - cookie 是否是一個 session cookie 或一個帶截至日期的持久 cookie .
    • expirationDate Double (可選) - cookie的截至日期，數值為UNIX紀元以來的秒數. 對session cookies 不提供.

ses.cookies.set(details, callback)

  • details Object
    • url String - 與獲取 cookies 相關的 url.
    • name String - cookie 名. 忽略默認為空.
    • value String - cookie 值. 忽略默認為空.
    • domain String - cookie的域名. 忽略默認為空.
    • path String - cookie 的路徑. 忽略默認為空.
    • secure Boolean - 是否已經進行了安全性標識. 默認為 false.
    • session Boolean - 是否已經 HttpOnly 標識. 默認為 false.
    • expirationDate Double - cookie的截至日期，數值為UNIX紀元以來的秒數. 如果忽略, cookie 變?yōu)?session cookie.
  • callback Function

使用 details 設置 cookie, 完成時使用 callback(error) 掉喲個 callback .

ses.cookies.remove(url, name, callback)

  • url String - 與 cookies 相關的 url.
  • name String - 需要刪除的 cookie 名.
  • callback Function

刪除匹配 url 和 name 的 cookie, 完成時使用 callback()調用callback.

ses.getCacheSize(callback)

  • callback Function
    • size Integer - 單位 bytes 的緩存 size.

返回 session 的當前緩存 size .

ses.clearCache(callback)

  • callback Function - 操作完成時調用

清空 session 的 HTTP 緩存.

ses.clearStorageData([options, ]callback)

  • options Object (可選)
    • origin String - 應當遵循 window.location.origin 的格式 scheme://host:port.
    • storages Array - 需要清理的 storages 類型, 可以包含 : appcache, cookies, filesystem, indexdb, local storage, shadercache, websql, serviceworkers
    • quotas Array - 需要清理的類型指標, 可以包含: temporary, persistent, syncable.
  • callback Function - 操作完成時調用.

清除 web storages 的數據.

ses.flushStorageData()

將沒有寫入的 DOMStorage 寫入磁盤.

ses.setProxy(config, callback)

  • config Object
    • pacScript String - 與 PAC 文件相關的 URL.
    • proxyRules String - 代理使用規(guī)則.
  • callback Function - 操作完成時調用.

設置 proxy settings.

當 pacScript 和 proxyRules 一同提供時，將忽略 proxyRules，并且使用 pacScript 配置 .

proxyRules 需要遵循下面的規(guī)則:

proxyRules = schemeProxies[";"<schemeProxies>]
schemeProxies = [<urlScheme>"="]<proxyURIList>
urlScheme = "http" | "https" | "ftp" | "socks"
proxyURIList = <proxyURL>[","<proxyURIList>]
proxyURL = [<proxyScheme>"://"]<proxyHost>[":"<proxyPort>]

例子:

  • http=foopy:80;ftp=foopy2 - 為 http:// URL 使用 HTTP 代理 foopy:80 , 和為 ftp:// URL HTTP 代理 foopy2:80 .
  • foopy:80 - 為所有 URL 使用 HTTP 代理 foopy:80 .
  • foopy:80,bar,direct:// - 為所有 URL 使用 HTTP 代理 foopy:80 , 如果 foopy:80 不可用，則切換使用 bar, 再往后就不使用代理了.
  • socks4://foopy - 為所有 URL 使用 SOCKS v4 代理 foopy:1080.
  • http=foopy,socks5://bar.com - 為所有 URL 使用 HTTP 代理 foopy, 如果 foopy不可用，則切換到 SOCKS5 代理 bar.com.
  • http=foopy,direct:// - 為所有http url 使用 HTTP 代理，如果 foopy不可用，則不使用代理.
  • http=foopy;socks=foopy2 - 為所有http url 使用 foopy 代理，為所有其他 url 使用 socks4://foopy2代理.

ses.resolveProxy(url, callback)

  • url URL
  • callback Function

解析 url 的代理信息.當請求完成的時候使用 callback(proxy) 調用 callback.

ses.setDownloadPath(path)

  • path String - 下載地址

設置下載保存地址，默認保存地址為各自 app 應用的 Downloads目錄.

ses.enableNetworkEmulation(options)

  • options Object
    • offline Boolean - 是否模擬網絡故障.
    • latency Double - 每毫秒的 RTT
    • downloadThroughput Double - 每 Bps 的下載速率.
    • uploadThroughput Double - 每 Bps 的上載速率.

通過給定配置的 session 來模擬網絡.

// 模擬 GPRS 連接，使用的 50kbps 流量，500 毫秒的 rtt.
window.webContents.session.enableNetworkEmulation({
    latency: 500,
    downloadThroughput: 6400,
    uploadThroughput: 6400
});

// 模擬網絡故障.
window.webContents.session.enableNetworkEmulation({offline: true});

ses.disableNetworkEmulation()

停止所有已經使用 session 的活躍模擬網絡. 重置為原始網絡類型.

ses.setCertificateVerifyProc(proc)

  • proc Function

為 session 設置證書驗證過程，當請求一個服務器的證書驗證時，使用 proc(hostname, certificate, callback) 調用 proc.調用 callback(true) 來接收證書，調用 callback(false) 來拒絕驗證證書.

調用了 setCertificateVerifyProc(null) ，則將會回復到默認證書驗證過程.

myWindow.webContents.session.setCertificateVerifyProc(function(hostname, cert, callback) {
  if (hostname == 'github.com')
    callback(true);
  else
    callback(false);
});

ses.setPermissionRequestHandler(handler)

  • handler Function
    • webContents Object - WebContents 請求許可.
    • permission String - 枚舉了 'media', 'geolocation', 'notifications', 'midiSysex', 'pointerLock', 'fullscreen'.
    • callback Function - 允許或禁止許可.

為對應 session 許可請求設置響應句柄.調用 callback(true) 接收許可，調用 callback(false) 禁止許可.

session.fromPartition(partition).setPermissionRequestHandler(function(webContents, permission, callback) {
  if (webContents.getURL() === host) {
    if (permission == "notifications") {
      callback(false); // denied.
      return;
    }
  }

  callback(true);
});

ses.clearHostResolverCache([callback])

  • callback Function (可選) - 操作結束調用.

清除主機解析緩存.

ses.webRequest

在其生命周期的不同階段，webRequest API 設置允許攔截并修改請求內容.

每個 API 接收一可選的 filter 和 listener，當 API 事件發(fā)生的時候使用 listener(details) 調用 listener，details 是一個用來描述請求的對象.為 listener 使用 null 則會退定事件.

filter 是一個擁有 urls 屬性的對象，這是一個 url 模式數組，這用來過濾掉不匹配指定 url 模式的請求.如果忽略 filter ，那么所有請求都將可以成功匹配.

所有事件的 listener 都有一個回調事件，當 listener 完成它的工作的時候，它將使用一個 response對象來調用.

// 將所有請求的代理都修改為下列 url.
var filter = {
  urls: ["https://*.github.com/*", "*://electron.github.io"]
};

session.defaultSession.webRequest.onBeforeSendHeaders(filter, function(details, callback) {
  details.requestHeaders['User-Agent'] = "MyAgent";
  callback({cancel: false, requestHeaders: details.requestHeaders});
});

ses.webRequest.onBeforeRequest([filter, ]listener)

  • filter Object
  • listener Function

當一個請求即將開始的時候，使用 listener(details, callback) 調用 listener.

  • details Object
    • id Integer
    • url String
    • method String
    • resourceType String
    • timestamp Double
    • uploadData Array (可選)
  • callback Function

uploadData 是一個 data 數組對象:

  • data Object
    • bytes Buffer - 被發(fā)送的內容.
    • file String - 上載文件路徑.

callback 必須使用一個 response 對象來調用:

  • response Object
    • cancel Boolean (可選)
    • redirectURL String (可選) - 原始請求阻止發(fā)送或完成，而不是重定向.

ses.webRequest.onBeforeSendHeaders([filter, ]listener)

  • filter Object
  • listener Function

一旦請求報文頭可用了,在發(fā)送 HTTP 請求的之前，使用 listener(details, callback) 調用 listener.這也許會在服務器發(fā)起一個tcp 連接，但是在發(fā)送任何 http 數據之前發(fā)生.

  • details Object
    • id Integer
    • url String
    • method String
    • resourceType String
    • timestamp Double
    • requestHeaders Object
  • callback Function

必須使用一個 response 對象來調用 callback :

  • response Object
    • cancel Boolean (可選)
    • requestHeaders Object (可選) - 如果提供了,將使用這些 headers 來創(chuàng)建請求.

ses.webRequest.onSendHeaders([filter, ]listener)

  • filter Object
  • listener Function

在一個請求正在發(fā)送到服務器的時候，使用 listener(details) 來調用 listener ，之前 onBeforeSendHeaders 修改部分響應可用，同時取消監(jiān)聽.

  • details Object
    • id Integer
    • url String
    • method String
    • resourceType String
    • timestamp Double
    • requestHeaders Object

ses.webRequest.onHeadersReceived([filter,] listener)

  • filter Object
  • listener Function

當 HTTP 請求報文頭已經到達的時候，使用 listener(details, callback) 調用 listener .

  • details Object
    • id String
    • url String
    • method String
    • resourceType String
    • timestamp Double
    • statusLine String
    • statusCode Integer
    • responseHeaders Object
  • callback Function

必須使用一個 response 對象來調用 callback :

  • response Object
    • cancel Boolean
    • responseHeaders Object (可選) - 如果提供, 服務器將假定使用這些頭來響應.

ses.webRequest.onResponseStarted([filter, ]listener)

  • filter Object
  • listener Function

當響應body的首字節(jié)到達的時候，使用 listener(details) 調用 listener.對 http 請求來說，這意味著狀態(tài)線和響應頭可用了.

  • details Object
    • id Integer
    • url String
    • method String
    • resourceType String
    • timestamp Double
    • responseHeaders Object
    • fromCache Boolean - 標識響應是否來自磁盤 cache.
    • statusCode Integer
    • statusLine String

ses.webRequest.onBeforeRedirect([filter, ]listener)

  • filter Object
  • listener Function

當服務器的重定向初始化正要啟動時，使用 listener(details) 調用 listener.

  • details Object
    • id String
    • url String
    • method String
    • resourceType String
    • timestamp Double
    • redirectURL String
    • statusCode Integer
    • ip String (可選) - 請求的真實服務器ip 地址
    • fromCache Boolean
    • responseHeaders Object

ses.webRequest.onCompleted([filter, ]listener)

  • filter Object
  • listener Function

當請求完成的時候，使用 listener(details) 調用 listener.

  • details Object
    • id Integer
    • url String
    • method String
    • resourceType String
    • timestamp Double
    • responseHeaders Object
    • fromCache Boolean
    • statusCode Integer
    • statusLine String

ses.webRequest.onErrorOccurred([filter, ]listener)

  • filter Object
  • listener Function

當一個錯誤發(fā)生的時候，使用 listener(details) 調用 listener.

  • details Object
    • id Integer
    • url String
    • method String
    • resourceType String
    • timestamp Double
    • fromCache Boolean
    • error String - 錯誤描述.
以上內容是否對您有幫助：
在線筆記
App下載
App下載

掃描二維碼

下載編程獅App

公眾號
微信公眾號

編程獅公眾號