# session `session` 模塊可以用來創建一個新的 `Session` 對象. 你也可以通過使用 [`webContents`](web-contents.md) 的屬性 `session` 來使用一個已有頁面的 `session` ，`webContents` 是[`BrowserWindow`](browser-window.md) 的屬性. ```javascript 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` 模塊中創建一個 `Session` 對象 : ```javascript const session = require('electron').session; var ses = session.fromPartition('persist:name'); ``` ### 實例事件 實例 `Session` 有以下事件: #### Event: 'will-download' * `event` Event * `item` [DownloadItem](download-item.md) * `webContents` [WebContents](web-contents.md) 當 Electron 將要從 `webContents` 下載 `item` 時觸發. 調用 `event.preventDefault()` 可以取消下載，并且在進程的下個 tick中，這個 `item` 也不可用. ```javascript 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. 例如: ```javascript // 查詢所有 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 發送一個請求，希望獲得所有匹配 `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 變為 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 - 代理使用規則. * `callback` Function - 操作完成時調用. 設置 proxy settings. 當 `pacScript` 和 `proxyRules` 一同提供時，將忽略 `proxyRules`，并且使用 `pacScript` 配置 . `proxyRules` 需要遵循下面的規則: ``` 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` 來模擬網絡. ```javascript // 模擬 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)` ，則將會回復到默認證書驗證過程. ```javascript 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](web-contents.md) 請求許可. * `permission` String - 枚舉了 'media', 'geolocation', 'notifications', 'midiSysex', 'pointerLock', 'fullscreen'. * `callback` Function - 允許或禁止許可. 為對應 `session` 許可請求設置響應句柄.調用 `callback(true)` 接收許可，調用 `callback(false)` 禁止許可. ```javascript 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 事件發生的時候使用 `listener(details)` 調用 `listener`，`details` 是一個用來描述請求的對象.為 `listener` 使用 `null` 則會退定事件. `filter` 是一個擁有 `urls` 屬性的對象，這是一個 url 模式數組，這用來過濾掉不匹配指定 url 模式的請求.如果忽略 `filter` ，那么所有請求都將可以成功匹配. 所有事件的 `listener` 都有一個回調事件，當 `listener` 完成它的工作的時候，它將使用一個 `response` 對象來調用. ```javascript // 將所有請求的代理都修改為下列 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 - 被發送的內容. * `file` String - 上載文件路徑. `callback` 必須使用一個 `response` 對象來調用: * `response` Object * `cancel` Boolean (可選) * `redirectURL` String (可選) - 原始請求阻止發送或完成，而不是重定向. #### `ses.webRequest.onBeforeSendHeaders([filter, ]listener)` * `filter` Object * `listener` Function 一旦請求報文頭可用了,在發送 HTTP 請求的之前，使用 `listener(details, callback)` 調用 `listener`.這也許會在服務器發起一個tcp 連接，但是在發送任何 http 數據之前發生. * `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 來創建請求. #### `ses.webRequest.onSendHeaders([filter, ]listener)` * `filter` Object * `listener` Function 在一個請求正在發送到服務器的時候，使用 `listener(details)` 來調用 `listener` ，之前 `onBeforeSendHeaders` 修改部分響應可用，同時取消監聽. * `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的首字節到達的時候，使用 `listener(details)` 調用 `listener`.對 http 請求來說，這意味著狀態線和響應頭可用了. * `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 當一個錯誤發生的時候，使用 `listener(details)` 調用 `listener`. * `details` Object * `id` Integer * `url` String * `method` String * `resourceType` String * `timestamp` Double * `fromCache` Boolean * `error` String - 錯誤描述.