session

ブラウザーセッション、クッキー、キャッシュ、プロキシの設定などを管理します。

プロセス: Main

session モジュールは、新しい session オブジェクトを作成するのに使用できます。

WebContents の session プロパティ、または session モジュールから、既存のページの session にアクセスすることもできます 。

const { BrowserWindow } = require('electron')

const win = new BrowserWindow({ width: 800, height: 600 })
win.loadURL('https://github.com')

const ses = win.webContents.session
console.log(ses.getUserAgent())

メソッド

session モジュールには以下のメソッドがあります。

session.fromPartition(partition[, options])

• partition string
• options Object (任意)
  • cache boolean - キャッシュを有効にするかどうか。

戻り値 Session - partition 文字列からの Session のインスタンス。 同じ partition を持つ既存の session が存在する場合は、それが返されます。 それ以外の場合は、options で新しい session インスタンスが作成されます。

partition が persist: 始まりの場合、ページはアプリの全ページで利用可能な永続的なセッションを同じ partition で使用します。 persist: プレフィックスがない場合、ページは、インメモリセッションを使用します。 partition が空の場合は、アプリのデフォルトのセッションが返されます。

options で Session を作成するには、以前に partition との Session が使用されていないことを確認する必要があります。 既存の Session オブジェクトの options を変更する方法はありません。

session.fromPath(path[, options])

• path string
• options Object (任意)
  • cache boolean - キャッシュを有効にするかどうか。

戻り値 Session - path 文字列で指定された絶対パスからの Session のインスタンス。 同じ絶対パスを持つ既存の Session がある場合はそれを返します。そうでなければ、新しい Session インスタンスを options で作成します。 パスが絶対パスでない場合、この呼び出しはエラーを送出します。 さらに、空文字列が指定された場合もエラーを送出します。

Session を options で作成する場合、path を持つ Session が一度も使われていないことを確認すべきです。 既存の Session オブジェクトの options を変更する方法はありません。

プロパティ

session モジュールには以下のプロパティがあります。

session.defaultSession

アプリのデフォルトの Session オブジェクト。

クラス: Session

セッションのプロパティを取得し、設定します。

プロセス: メイン
このクラスは 'electron' モジュールからはエクスポートされません。 Electron API では、他のメソッドの戻り値としてのみ利用できます。

session モジュールでは、Session オブジェクトを作成できます。

const { session } = require('electron')
const ses = session.fromPartition('persist:name')
console.log(ses.getUserAgent())

インスタンスイベント

Session のインスタンスでは、以下のイベントが利用できます。

イベント: 'will-download'

戻り値：

• event Event
• item DownloadItem
• webContents WebContents

Electron が webContents 内で item をダウンロードするときに発生します。

event.preventDefault() を呼び出すと、ダウンロードをキャンセルし、item はプロセスの次のティックから使用できなくなります。

const { session } = require('electron')
session.defaultSession.on('will-download', (event, item, webContents) => {
  event.preventDefault()
  require('got')(item.getURL()).then((response) => {
    require('node:fs').writeFileSync('/somewhere', response.body)
  })
})

イベント: 'extension-loaded'

戻り値：

• event Event
• extension Extension

拡張機能が読み込まれた後に発生します。 これは、拡張機能が "有効な" 拡張機能のセットに追加されるたびに発生します。 これは以下のものが含まれます。

• Session.loadExtension から拡張機能が読み込まれるとき。
• 拡張機能が再読み込みされるとき。
  • クラッシュによって。
  • 拡張機能が要求したことで (chrome.runtime.reload())。

イベント: 'extension-unloaded'

戻り値：

• event Event
• extension Extension

拡張機能が取り除かれた後に発生します。 これは Session.removeExtension が呼ばれたときに発生します。

イベント: 'extension-ready'

戻り値：

• event Event
• extension Extension

拡張機能が読み込まれ、必要なブラウザの状態がすべて初期化され、拡張機能のバックグラウンドページの開始をサポートするようになった後に発生します。

イベント: 'preconnect'

戻り値：

• event Event
• preconnectUrl string - レンダラーによって事前接続に要求されている URL。
• allowCredentials boolean - レンダラーが接続に資格情報を含めることを要求している場合は true です (詳細については、仕様 を参照してください)。

一般的に リソースヒント が原因で、レンダリングプロセスが URL への事前接続を要求したときに生成されます。

イベント: 'spellcheck-dictionary-initialized'

戻り値：

• event Event
• languageCode string - 辞書ファイルの言語コード

hunspell 辞書ファイルの初期化に成功したときに発生します。 これはファイルをダウンロードした後に発生します。

イベント: 'spellcheck-dictionary-download-begin'

戻り値：

• event Event
• languageCode string - 辞書ファイルの言語コード

hunspell 辞書ファイルのダウンロードが始まったときに発生します

イベント: 'spellcheck-dictionary-download-success'

戻り値：

• event Event
• languageCode string - 辞書ファイルの言語コード

hunspell 辞書ファイルのダウンロードに成功したときに発生します

イベント: 'spellcheck-dictionary-download-failure'

戻り値：

• event Event
• languageCode string - 辞書ファイルの言語コード

hunspell 辞書ファイルのダウンロードが失敗したときに発生します。 失敗の詳細は、netlog を収集してダウンロードリクエストを調べる必要があります。

イベント: 'select-hid-device'

戻り値：

• event Event
• details Object
  • deviceList HIDDevice[]
  • frame WebFrameMain
• callback Function
  • deviceId string | null (任意)

navigator.hid.requestDevice の呼び出し時に HID デバイスを選択する必要がある場合に発生します。 callback は選択する deviceId で呼び出してください。callback に引数を渡さなければ、リクエストをキャンセルします。 また、ses.setPermissionCheckHandler(handler) や ses.setDevicePermissionHandler(handler) を使うことで navigator.hid での権限をさらに管理できます。

const { app, BrowserWindow } = require('electron')

let win = null

app.whenReady().then(() => {
  win = new BrowserWindow()

  win.webContents.session.setPermissionCheckHandler((webContents, permission, requestingOrigin, details) => {
    if (permission === 'hid') {
      // ここにロジックを追加して、その HID の選択を許可するかどうかを決定します。
      return true
    }
    return false
  })

  // 任意で、永続ストアから以前に永続化されたデバイスを取得します。
  const grantedDevices = fetchGrantedDevices()

  win.webContents.session.setDevicePermissionHandler((details) => {
    if (new URL(details.origin).hostname === 'some-host' && details.deviceType === 'hid') {
      if (details.device.vendorId === 123 && details.device.productId === 345) {
        // 常にこのタイプのデバイスを許可します (これにより最初の `navigator.hid.requestDevice` の呼び出しをスキップできます)
        return true
      }

      // 過去に許可されたデバイスのリストを検索します。
      return grantedDevices.some((grantedDevice) => {
        return grantedDevice.vendorId === details.device.vendorId &&
              grantedDevice.productId === details.device.productId &&
              grantedDevice.serialNumber && grantedDevice.serialNumber === details.device.serialNumber
      })
    }
    return false
  })

  win.webContents.session.on('select-hid-device', (event, details, callback) => {
    event.preventDefault()
    const selectedDevice = details.deviceList.find((device) => {
      return device.vendorId === 9025 && device.productId === 67
    })
    callback(selectedDevice?.deviceId)
  })
})

イベント: 'hid-device-added'

戻り値：

• event Event
• details Object
  • device HIDDevice
  • frame WebFrameMain

navigator.hid.requestDevice が呼ばれた後や、select-hid-device から呼ばれるコールバックが利用可能なる前に新しいデバイスが利用可能になると、select-hid-device が発生します。 このイベントは、UI でユーザーにデバイスの選択を求め、新しく追加されたデバイスで UI を更新するために使用することを意図しています。

イベント: 'hid-device-removed'

戻り値：

• event Event
• details Object
  • device HIDDevice
  • frame WebFrameMain

navigator.hid.requestDevice が呼ばれたときや、select-hid-device のコールバックが呼ばれる前にデバイスが取り除かれた場合に、select-hid-device が発生した後に発生します。 このイベントは、UI でユーザーにデバイスの選択を求め、指定されたデバイスを取り除いて UI を更新するために使用することを意図しています。

イベント: 'hid-device-revoked'

戻り値：

• event Event
• details Object
  • device HIDDevice
  • origin string (任意) - デバイスが失効したオリジンです。

HIDDevice.forget() が呼ばれた後に発生します。 このイベントは、setDevicePermissionHandler が使用されたときに権限の永続ストレージの維持に利用できます。

イベント: 'select-serial-port'

戻り値：

• event Event
• portList SerialPort[]
• webContents WebContents
• callback Function
  • portId string

navigator.serial.requestPort の呼び出し時にシリアルポートを選択する必要がある場合に発生します。 callback は選んだ portId で呼び出されなければなりません。空の文字列を callback に渡すとリクエストがキャンセルされます。 さらに、ses.setPermissionCheckHandler(handler) を serial パーミッションで使用することで navigator.serial のパーミッションを管理できます。

const { app, BrowserWindow } = require('electron')

let win = null

app.whenReady().then(() => {
  win = new BrowserWindow({
    width: 800,
    height: 600
  })

  win.webContents.session.setPermissionCheckHandler((webContents, permission, requestingOrigin, details) => {
    if (permission === 'serial') {
      // ここにロジックを追加して、シリアルの選択を許可すべきかどうか判断します
      return true
    }
    return false
  })

  // 任意で、永続ストアから以前に永続化されたデバイスを取得します
  const grantedDevices = fetchGrantedDevices()

  win.webContents.session.setDevicePermissionHandler((details) => {
    if (new URL(details.origin).hostname === 'some-host' && details.deviceType === 'serial') {
      if (details.device.vendorId === 123 && details.device.productId === 345) {
        // このタイプのデバイスを常に許可します (これにより最初の `navigator.serial.requestPort` の呼び出しを省略できます)
        return true
      }

      // 過去に許可されたデバイスのリストを検索する
      return grantedDevices.some((grantedDevice) => {
        return grantedDevice.vendorId === details.device.vendorId &&
              grantedDevice.productId === details.device.productId &&
              grantedDevice.serialNumber && grantedDevice.serialNumber === details.device.serialNumber
      })
    }
    return false
  })

  win.webContents.session.on('select-serial-port', (event, portList, webContents, callback) => {
    event.preventDefault()
    const selectedPort = portList.find((device) => {
      return device.vendorId === '9025' && device.productId === '67'
    })
    if (!selectedPort) {
      callback('')
    } else {
      callback(selectedPort.portId)
    }
  })
})

イベント: 'serial-port-added'

戻り値：

• event Event
• port SerialPort
• webContents WebContents

navigator.serial.requestPort が呼ばれた後や、select-serial-port から呼ばれるコールバックが利用可能なる前に新しいシリアルポートが利用可能になると、select-serial-port が発生します。 このイベントは、UI でユーザーにポートの選択を求め、新しく追加されたポートで UI を更新するために使用することを意図しています。

イベント: 'serial-port-removed'

戻り値：

• event Event
• port SerialPort
• webContents WebContents

navigator.serial.requestPort が呼ばれたときや、select-serial-port のコールバックが呼ばれる前にシリアルポートが取り除かれた場合に、select-serial-port が発生した後に発生します。 このイベントは、UI でユーザーにポートの選択を求め、指定されたポートを取り除いて UI を更新するために使用することを意図しています。

イベント: 'serial-port-revoked'

戻り値：

• event Event
• details Object
  • port SerialPort
  • frame WebFrameMain
  • origin string - デバイスが失効したオリジンです。

SerialPort.forget() が呼ばれた後に発生します。 このイベントは、setDevicePermissionHandler が使用されたときに権限の永続ストレージの維持に利用できます。

// ブラウザープロセス
const { app, BrowserWindow } = require('electron')

app.whenReady().then(() => {
  const win = new BrowserWindow({
    width: 800,
    height: 600
  })

  win.webContents.session.on('serial-port-revoked', (event, details) => {
    console.log(`Access revoked for serial device from origin ${details.origin}`)
  })
})

// レンダラープロセス

const portConnect = async () => {
  // ポートを要求します。
  const port = await navigator.serial.requestPort()

  // シリアルポートが開くまで待機します。
  await port.open({ baudRate: 9600 })

  // ...その後、シリアルポートへのアクセスを失効します。
  await port.forget()
}

イベント: 'select-usb-device'

戻り値：

• event Event
• details Object
  • deviceList USBDevice[]
  • frame WebFrameMain
• callback Function
  • deviceId string (任意)

navigator.usb.requestDevice の呼び出し時に USB デバイスを選択する必要がある場合に発生します。 callback は選択する deviceId で呼び出してください。callback に引数を渡さなければ、リクエストをキャンセルします。 また、ses.setPermissionCheckHandler(handler) や ses.setDevicePermissionHandler(handler) を使うことで navigator.usb での権限をさらに管理できます。

const { app, BrowserWindow } = require('electron')

let win = null

app.whenReady().then(() => {
  win = new BrowserWindow()

  win.webContents.session.setPermissionCheckHandler((webContents, permission, requestingOrigin, details) => {
    if (permission === 'usb') {
      // ここにロジックを追加して、その USB の選択を許可するかどうかを決定します。
      return true
    }
    return false
  })

  // 任意で、永続ストアから以前に永続化されたデバイスを取得します (永続化された許可の取得には、開発者が fetchGrantedDevices を実装する必要があります)。
  const grantedDevices = fetchGrantedDevices()

  win.webContents.session.setDevicePermissionHandler((details) => {
    if (new URL(details.origin).hostname === 'some-host' && details.deviceType === 'usb') {
      if (details.device.vendorId === 123 && details.device.productId === 345) {
        // 常にこのタイプのデバイスを許可します (これにより最初の `navigator.usb.requestDevice` の呼び出しをスキップできます)。
        return true
      }

      // 過去に許可されたデバイスのリストを検索します。
      return grantedDevices.some((grantedDevice) => {
        return grantedDevice.vendorId === details.device.vendorId &&
              grantedDevice.productId === details.device.productId &&
              grantedDevice.serialNumber && grantedDevice.serialNumber === details.device.serialNumber
      })
    }
    return false
  })

  win.webContents.session.on('select-usb-device', (event, details, callback) => {
    event.preventDefault()
    const selectedDevice = details.deviceList.find((device) => {
      return device.vendorId === 9025 && device.productId === 67
    })
    if (selectedDevice) {
      // 任意で、永続化されたデバイスにこれを追加します (パーミッションの永続化には、開発者が updateGrantedDevices を実装する必要があります)。
      grantedDevices.push(selectedDevice)
      updateGrantedDevices(grantedDevices)
    }
    callback(selectedDevice?.deviceId)
  })
})

イベント: 'usb-device-added'

戻り値：

• event Event
• device USBDevice
• webContents WebContents

navigator.usb.requestDevice が呼ばれた後や、select-usb-device から呼ばれるコールバックが利用可能なる前に新しいデバイスが利用可能になると、select-usb-device が発生します。 このイベントは、UI でユーザーにデバイスの選択を求め、新しく追加されたデバイスで UI を更新するために使用することを意図しています。

イベント: 'usb-device-removed'

戻り値：

• event Event
• device USBDevice
• webContents WebContents

navigator.usb.requestDevice が呼ばれたときや、select-usb-device のコールバックが呼ばれる前にデバイスが取り除かれた場合に、select-usb-device が発生した後に発生します。 このイベントは、UI でユーザーにデバイスの選択を求め、指定されたデバイスを取り除いて UI を更新するために使用することを意図しています。

イベント: 'usb-device-revoked'

戻り値：

• event Event
• details Object
  • device USBDevice
  • origin string (任意) - デバイスが失効したオリジンです。

USBDevice.forget() が呼ばれた後に発生します。 このイベントは、setDevicePermissionHandler が使用されたときに権限の永続ストレージの維持に利用できます。

インスタンスメソッド

Session のインスタンスでは、以下のメソッドが利用できます。

ses.getCacheSize()

戻り値 Promise<Integer> - バイト単位の、session の現在のキャッシュサイズ。

ses.clearCache()

戻り値 Promise<void> - キャッシュクリア操作が完了すると実行されます。

セッションの HTTP キャッシュをクリアします。

ses.clearStorageData([options])

• options Object (任意)
  • origin string (任意) - window.location.origin の表記の scheme://host:port に従わなければいけません。
  • storages string[] (任意) - 消去するストレージの種別です。cookies、filesystem、indexdb、localstorage、shadercache、websql、serviceworkers、cachestorage のいずれかにできます。 指定しない場合は、全種類のストレージをクリアします。
  • quotas string[] (任意) - 消去するクォータの種類。temporary, syncable のいずれかにできます。 指定しない場合は、全てのクオータをクリアします。

戻り値 Promise<void> - ストレージデータがクリアされると実行されます。

ses.flushStorageData()

未書き込みの DOM ストレージのデータをディスクに書き込みます。

ses.setProxy(config)

• config Object
  • mode string (任意) - そのプロキシのモード。 direct、auto_detect、pac_script、fixed_servers、system のうちの一つであるべきです。 指定しない場合は、他の指定オプションに基づいて自動決定されます。
    • direct direct モードでは、すべての接続はプロキシを介さずに直接作成されます。
    • auto_detect auto_detect モードでは、プロキシの設定は http://wpad/wpad.dat でダウンロードできる PAC スクリプトによって決定されます。
    • pac_script pac_script モードでは、プロキシの設定は pacScript で指定された URL から取得される PAC スクリプトによって決定されます。 これは pacScript が指定されている場合のデフォルトモードです。
    • fixed_servers fixed_servers モードでは、プロキシの設定を proxyRules で指定します。 これは proxyRules が指定されている場合のデフォルトモードです。
    • system system モードでは、プロキシ構成をオペレーティングシステムから取得します。 system モードはプロキシ構成を設定しない場合とは異なりますのでご注意ください。 後者の場合、プロキシ設定に影響を与えるコマンドラインオプションがない場合にのみ、 Electron はシステム設定にフォールバックします。
  • pacScript string (任意) - PAC ファイルに関連付けられた URL。
  • proxyRules string (任意) - 使用するプロキシを示すルール。
  • proxyBypassRules string (任意) - プロキシ設定をバイパスする URL を示すルール。

戻り値 Promise<void> - プロキシ設定処理が完了すると実行されます。

プロキシ設定を設定します。

mode を指定せずに pacScript とproxyRules をどちらも一緒に指定した場合、proxyRules は オプションは無視され pacScript の設定が適用されます。

以前のプロキシでプールされたソケットが将来のリクエストで再利用されるのを防ぐには、現在フライト中の接続を閉じるために ses.closeAllConnections が必要でしょう。

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 に foopy:80 HTTP プロキシを使用する。
• foopy:80,bar,direct:// - すべての URL に foopy:80 HTTP プロキシを使用する。 foopy:80 が使用できない場合は bar にフェイルオーバーし、その後はプロキシを使用しません。
• socks4://foopy - すべての URL に SOCKS 4 プロキシ foopy:1080 を使用する。
• http=foopy,socks5://bar.com - HTTP の URL には HTTP プロキシ foopy を使用し、foopy が使用できない場合は SOCKS 5 プロキシ bar.com にフェイルオーバーします。
• http=foopy,socks5://bar.com - HTTP の URL には HTTP プロキシ foopy を使用し、foopy が使用できない場合はプロキシを使用しません。
• http=foopy;socks=foopy2 - HTTP の URL には HTTP プロキシ foopy を、ほかの URLには socks4://foopy2 を使用します。

proxyBypassRules は以下に説明されているコンマ区切りのルールのリストです。

• [ URL_SCHEME "://" ] HOSTNAME_PATTERN [ ":" <port> ]

  HOSTNAME_PATTERN パターンに一致するすべてのホスト名のマッチ。

  例: "foobar.com", "*foobar.com", "*.foobar.com", "*foobar.com:99", "https://x.\*.y.com:99"

• "." HOSTNAME_SUFFIX_PATTERN [ ":" PORT ]

  特定のドメインサフィックスのマッチ。

  例: ".google.com", ".com", "http://.google.com"

• [ SCHEME "://" ] IP_LITERAL [ ":" PORT ]

  IP アドレスリテラルである URL のマッチ。

  例: "127.0.1", "[0:0::1]", "[::1]", "http://[::1]:99"

• IP_LITERAL "/" PREFIX_LENGTH_IN_BITS

  指定された範囲内の IP リテラルに一致する URL のマッチ。 IP の範囲は CIDR 表記で指定します。

  例: "192.168.1.1/16", "fefe:13::abc/33".

• <local>

  ローカルアドレスのマッチ。 <local> の意味は、ホストが "127.0.0.1"、"::1"、"localhost" のいずれかに一致するかどうかです。

ses.resolveHost(host, [options])

• host string - 解決するホスト名。
• options Object (任意)
  • queryType string (任意) - 要求される DNS クエリタイプ。 未指定の場合、リゾルバは IPv4/IPv6 の設定に基づいて A または AAAAA (あるいはその両方) を選択します。
    • A - A レコードのみを取得します。
    • AAAA - AAAA レコードのみを取得します。
  • source string (任意) - アドレス解決に使用するソースです。 省略すると、リゾルバが適切なソースを選択できるようにします。 大規模な外部ソースを使用するときのみ影響します (解決または DNS の利用のためにシステムを呼び出すなど)。 ソースが指定された場合でも、「localhost」や IP リテラルの解決のようなものの結果はキャッシュから来ることがあります。 以下の値のいずれかです。
    • any (既定) - リゾルバが適切なソースを選択します。 DNS、MulticastDNS、HOSTS ファイルなどから結果が得られることもあります。
    • system - getaddrinfo() システムコール経由などで、システムや OS のみで結果を取得します。
    • dns - DNS クエリのみで結果を取得します。
    • mdns - マルチチャスト DNS クエリのみで結果を取得します。
    • localOnly - 外部ソースを使用しません。 結果は、ソース設定に関係なく利用可能な高速ローカルソースからのみ取得します。例えば、キャッシュ、hosts ファイル、IP リテラル解決などです。
  • cacheUsage string (任意) - 応答の提供に利用できる DNS キャッシュのエントリがある場合に、そのエントリの取り扱いを示します。 以下の値のいずれかです。
    • allowed (既定) - ホストのキャッシュが古くなければ、そこから結果を取得します。
    • staleAllowed - ホストのキャッシュが (有効期限切れやネットワークの変更で) 古い場合でも、そこから結果を取得します。
    • disallowed - ホストのキャッシュからは結果を取得しません。
  • secureDnsPolicy string (任意) - このリクエストに対するリゾルバのセキュア DNS の動作を制御します。 以下の値のいずれかです。
    • allow (既定)
    • disable

戻り値 Promise<ResolvedHost> - host について解決された IP アドレスによって解決されます。

ses.resolveProxy(url)

• url URL

戻り値 Promise<string> - url のプロキシ情報で実行されます。

ses.forceReloadProxyConfig()

戻り値 Promise<void> - プロキシサービスのすべての内部状態がリセットされたときに解決します。すでに利用可能な場合は最新のプロキシ設定が再適用されます。 プロキシモードが pac_script の場合、再び pacScript から PAC スクリプトが取得されます。

ses.setDownloadPath(path)

• path string - ダウンロード場所。

ダウンロードの保存ディレクトリを設定します。 デフォルトでは、ダウンロードディレクトリは各アプリフォルダの下の ダウンロード (Downloads) になります。

ses.enableNetworkEmulation(options)

• options Object
  • offline boolean (任意) - ネットワークの停止をエミュレートするかどうか。 省略値は false です。
  • latency Double (任意) - RTT ミリ秒。 省略値は 0 で、このときレイテンシのスロットルは無効化されます。
  • downloadThroughput Double (任意) - 下りレート Bps。 省略値は 0 で、このときダウンロードのスロットルは無効化されます。
  • uploadThroughput Double (任意) - 上りレート Bps。 省略値は 0 で、このときアップロードのスロットルは無効化されます。

session の指定された構成でネットワークをエミュレートします。

const win = new BrowserWindow()

// 50kbps のスループットと 500ms の待ち時間で GPRS 接続をエミュレートします。
win.webContents.session.enableNetworkEmulation({
  latency: 500,
  downloadThroughput: 6400,
  uploadThroughput: 6400
})

// ネットワークの切断をエミュレートします。
win.webContents.session.enableNetworkEmulation({ offline: true })

ses.preconnect(options)

• options Object
  • url string - 事前接続する URL。 ソケットの開通に関係しているのはオリジンのみです。
  • numSockets number (任意) - 事前接続するソケット数。 1 から 6 にしてください。 省略値は 1 です。

指定された数のソケットをオリジンに事前接続します。

ses.closeAllConnections()

戻り値 Promise<void> - すべての接続が閉じられた時に解決されます。

注: 現在フライト中のすべてのリクエストが終了/失敗します。

ses.fetch(input[, init])

• input string | GlobalRequest
• init RequestInit & { bypassCustomProtocolHandlers?: boolean } (任意)

戻り地 Promise<GlobalResponse> - Response をご参照ください。

Chrome のネットワークスタックを使って、レンダラーでの fetch() の動作と同様にリクエストを送信します。 これは Node.js の HTTP スタックを使用する Node の fetch() とは異なります。

サンプル:

async function example () {
  const response = await net.fetch('https://my.app')
  if (response.ok) {
    const body = await response.json()
    // ... 結果を使いましょう。
  }
}

net.fetch() という、デフォルトセッション からのリクエストを発行する便利なメソッドもご参照ください。

fetch() についての詳細は MDN のドキュメントをご参照ください。

制限事項:

• net.fetch() は data: や blob: スキームをサポートしていません。
• integrity オプションの値は無視されます。
• 返された Response オブジェクトの .type と .url の値は不正確です。

デフォルトでは、net.fetch によるリクエストは カスタムプロトコル だけでなく file: に対しても行うことができ、webRequest ハンドラが存在すればそれをトリガします。 RequestInit で非標準の bypassCustomProtocolHandlers オプションを設定している場合、このリクエストでカスタムプロトコルハンドラは呼ばれません。 これにより、干渉されるリクエストを組み込みハンドラへ転送できます。 webRequest ハンドラはカスタムプロトコルをバイパスしても引き続きトリガされます。

protocol.handle('https', (req) => {
  if (req.url === 'https://my-app.com') {
    return new Response('<body>my app</body>')
  } else {
    return net.fetch(req, { bypassCustomProtocolHandlers: true })
  }
})

ses.disableNetworkEmulation()

session に対して既にアクティブなネットワークエミュレーションを無効にします。 元のネットワーク構成にリセットします。

ses.setCertificateVerifyProc(proc)

• proc Function | null
  • request Object
    • hostname string
    • certificate Certificate
    • validatedCertificate Certificate
    • isIssuedByKnownRoot boolean - Chromium がルート CA を標準ルートとして認識している場合は true です。 そうでない場合は、ローカルにインストールされた MITM プロキシ (企業のプロキシなど) のルートによってこの証明書が生成されている可能性があります。 verificationResult が OK でない場合、信頼しないでください。
    • verificationResult string - 証明書が信頼されている場合は OK に、さもなくば CERT_REVOKED のようなエラーになります。
    • errorCode Integer - エラーコード。
  • callback Function
    • verificationResult Integer - こちら の証明書エラーコードのうち一つの値を取ります。 証明書エラーコードの他に、以下の特殊コードを取ることがあります。
      • 0 - 成功を示し、証明書の透明性の検証を無効にします。
      • -2 - 失敗を示します。
      • -3 - Chromium からの認証結果を使用します。

session の証明書検証プロセスを設定し、サーバー証明書の検証が要求されるたびにproc を proc(request, callback) で呼びます。 callback(0) を呼ぶと証明書を承認し、callback(-2) を呼ぶとそれを拒否します。

setCertificateVerifyProc(null) を呼び出すと、デフォルトの証明書検証プロシージャに戻ります。

const { BrowserWindow } = require('electron')
const win = new BrowserWindow()

win.webContents.session.setCertificateVerifyProc((request, callback) => {
  const { hostname } = request
  if (hostname === 'github.com') {
    callback(0)
  } else {
    callback(-2)
  }
})

注意: このプロシージャの結果は、ネットワークサービスによってキャッシュされます。

ses.setPermissionRequestHandler(handler)

• handler Function | null
  • webContents WebContents - 権限を要求している WebContents。 リクエストがサブフレームからのものである場合、リクエストのオリジンを確認するためには requestingUrl を使用する必要があることに注意してください。
  • permission string - 要求されたパーミッションのタイプ。
    • clipboard-read - クリップボードからの読み取りアクセスを要求する。
    • clipboard-sanitized-write - クリップボードへの書き込みアクセスを要求します。
    • display-capture - 画面キャプチャ API 経由で画面キャプチャへのアクセスを要求します。
    • fullscreen - 全画面 API を介して、アプリの全画面状態の制御を要求します。
    • geolocation - 位置情報 API 経由で位置情報へのアクセスを要求します。
    • idle-detection - IdleDetector API 経由でユーザーの待機状態へのアクセスを要求します。
    • media - カメラ、マイク、スピーカーなどのメディアデバイスへのアクセスを要求する。
    • mediaKeySystem - DRM で保護されたコンテンツへのアクセスを要求します。
    • midi - Web MIDI API での MIDI アクセスを要求します。
    • midiSysex - Web MIDI API でのシステム排他メッセージの使用を要求します。
    • notifications - 通知 API を使用して通知を作成しユーザーにシステムトレイを表示する機能を要求します。
    • pointerLock - ポインターロック API を介して入力メソッドとしてマウスの動きに直接干渉できるように要求します。 これらのリクエストは、常にメインフレームから送信されているように見えます。
    • keyboardLock - キーボードロック API を介して、物理キーボードの任意またはすべてのキーのキー押下のキャプチャをリクエストします。 これらのリクエストは、常にメインフレームから送信されているように見えます。
    • openExternal - 外部アプリケーションでリンクを開くように要求する。
    • window-management - getScreenDetails API を使用して画面をエミュレートするアクセスをリクエストします。
    • unknown - 認識されない認可リクエスト.
  • callback Function
    • permissionGranted boolean - 権限の許可か拒否.
  • details Object - このプロパティの一部は、特定の権限タイプでのみ使用できます。
    • externalURL string (任意) - openExternal リクエストの URL。
    • securityOrigin string (任意) - media のリクエストでのセキュリティオリジン。
    • mediaTypes string[] (任意) - 要求されている、複数のメディアアクセスのタイプ。要素は video か audio にできます
    • requestingUrl string - リクエストしているフレームが読み込んだ最後の URL
    • isMainFrame boolean - リクエストしたフレームがメインフレームかどうか

session の、権限の要求に応答するために使用できるハンドラを設定します。 callback(true) を呼ぶと権限が許可され callback(false) を呼ぶと拒否されます。 ハンドラをクリアするには、setPermissionRequestHandler(null) を呼びます。 注意として、完全な認可処理にするには setPermissionCheckHandler も実装しなければなりません。 ほとんどのウェブ API は権限の確認を行い、確認が拒否されている場合は認可のリクエストを行います。

const { session } = require('electron')
session.fromPartition('some-partition').setPermissionRequestHandler((webContents, permission, callback) => {
  if (webContents.getURL() === 'some-host' && permission === 'notifications') {
    return callback(false) // 拒否。
  }

  callback(true)
})

ses.setPermissionCheckHandler(handler)

• handler Function<boolean> | null
  • webContents (WebContents | null) - 権限を確認している WebContents リクエストがサブフレームからのものである場合、リクエストのオリジンを確認するためには requestingUrl を使用する必要があることに注意してください。 すべてのクロスオリジンサブフレームによる権限の確認はハンドラの webContents に null が渡されますが、notifications の確認のような、ある特定の権限の確認では常に null が渡されます。 embeddingOrigin と requestingOrigin を使用して、所有しているフレームと要求しているフレームがそれぞれどのオリジンにあるかを判断する必要があります。
  • permission string - 権限確認の種別。
    • clipboard-read - クリップボードからの読み取りアクセスを要求する。
    • clipboard-sanitized-write - クリップボードへの書き込みアクセスを要求します。
    • geolocation - 位置情報 API 経由でのユーザーの位置情報へのアクセスです。
    • fullscreen - 全画面 API を介して、アプリの全画面状態を制御します。
    • hid - HID プロトコルにアクセスし、WebHID API を介して HID デバイスを操作します。
    • idle-detection - IdleDetector API 経由でユーザーの待機状態へアクセスします。
    • media - カメラ、マイク、スピーカーなどのメディアデバイスへアクセスします。
    • mediaKeySystem - DRM で保護されたコンテンツへアクセスします。
    • midi - Web MIDI API での MIDI アクセスを有効化します。
    • midiSysex - Web MIDI API でのシステム排他メッセージを使用します。
    • notifications - 通知 API を使用してデスクトップ通知を構成しユーザーへ表示します。
    • openExternal - 外部アプリケーションでリンクを開きます。
    • pointerLock - ポインターロック API を介して入力メソッドとしてマウスの動きに直接干渉します。 これらのリクエストは、常にメインフレームから送信されているように見えます。
    • serial - Web Serial API を使用して、シリアルデバイスとの読み取りと書き込みを行います。
    • usb - WebUSB API を使用して、非標準のユニバーサルシリアルバス (USB) 互換デバイスのサービスをウェブへ公開します。
  • requestingOrigin string - 権限チェックのオリジン URL
  • details Object - このプロパティの一部は、特定の権限タイプでのみ使用できます。
    • embeddingOrigin string (任意) - 権限の確認をしたフレームのオリジン。 権限の確認を行うクロスオリジンのサブフレームでのみ設定されます。
    • securityOrigin string (任意) - media の確認でのセキュリティオリジン。
    • mediaType string (任意) - 要求されたメディアアクセスの型で、video、audio か unknown になります。
    • requestingUrl string (任意) - リクエストしているフレームが読み込んだ最後の URL. 権限の確認を行うクロスオリジンのサブフレームでは提供されません。
    • isMainFrame boolean - リクエストしたフレームがメインフレームかどうか

session の、権限のチェックに応答するために使用できるハンドラを設定します。 trueを返すと権限を許可し、false を返すとそれを拒否します。 注意として、完全な認可処理にするには setPermissionRequestHandler も実装しなければなりません。 ほとんどのウェブ API は権限の確認を行い、確認が拒否されている場合は認可のリクエストを行います。 ハンドラをクリアするには、 setPermissionCheckHandler(null) を呼びます。

const { session } = require('electron')
const url = require('url')
session.fromPartition('some-partition').setPermissionCheckHandler((webContents, permission, requestingOrigin) => {
  if (new URL(requestingOrigin).hostname === 'some-host' && permission === 'notifications') {
    return true // 認可
  }

  return false // 拒否
})

ses.setDisplayMediaRequestHandler(handler)

• handler Function | null
  • request Object
    • frame WebFrameMain - メディアへのアクセスをリクエストしているフレームです。
    • securityOrigin String - リクエストしているページのオリジンです。
    • videoRequested Boolean - ウェブコンテンツが映像ストリームをリクエストしていると true です。
    • audioRequested Boolean - ウェブコンテンツが音声ストリームをリクエストしていると true です。
    • userGesture Boolean - リクエストがトリガされたときにユーザージェスチャが有効だったかどうかです。
  • callback Function
    • streamsオブジェクト
      • video Object | WebFrameMain (任意)
        • id String - 認可されたストリームの ID です。 これは大抵 DesktopCapturerSource オブジェクトに由来するものです。
        • name String - 認可されたストリームの名前です。 これは大抵 DesktopCapturerSource オブジェクトに由来するものです。
      • audio String | WebFrameMain (任意) - 文字列が指定される場合は、loopback か loopbackWithMute のどちらかです。 ループバックデバイスを指定すると、システムオーディオをキャプチャできます。これは現在 Windows でのみサポートされています。 WebFrameMain が指定されている場合はそのフレームからの音声をキャプチャします。
      • enableLocalEcho Boolean (任意) - audio が WebFrameMain 型で、このフラグが true に設定されている場合、オーディオのローカル再生は消音されません (つまり、MediaRecorder で WebFrameMain を録音する際にこのフラグを true に設定すると、録音中でもスピーカーへ音声が流れるようになります)。 省略値は false です。

このハンドラは、navigator.mediaDevices.getDisplayMedia API を通じてウェブコンテンツがディスプレイメディアへのアクセスを要求したときに呼び出されます。 desktopCapturer API を使用して、どのストリームへのアクセスを認可するのか選択してください。

const { session, desktopCapturer } = require('electron')

session.defaultSession.setDisplayMediaRequestHandler((request, callback) => {
  desktopCapturer.getSources({ types: ['screen'] }).then((sources) => {
    // 最初に見つけた画面へのアクセスを認可します。
    callback({ video: sources[0] })
  })
})

WebFrameMain オブジェクトを映像または音声ストリームとして渡すと、そのフレームからの映像または音声をキャプチャします。

const { session } = require('electron')

session.defaultSession.setDisplayMediaRequestHandler((request, callback) => {
  // タブに自身のキャプチャを許可します。
  callback({ video: request.frame })
})

関数の代わりに null を渡すとハンドラはデフォルトの状態にリセットされます。

ses.setDevicePermissionHandler(handler)

• handler Function<boolean> | null
  • details Object
    • deviceType string - 許可が求められているデバイスのタイプで、hid、serial または usb になります。
    • origin string - デバイス権限チェックのオリジン URL。
    • device HIDDevice | SerialPort | USBDevice - 許可を求められているデバイス。

デバイスの権限チェックの応答に使用できるハンドラを session に設定します。 true を返すとデバイスに権限を許可し、false を返すとそれを拒否します。 ハンドラを消去するには setDevicePermissionHandler(null) と呼び出します。 このハンドラは、最初にデバイスへの許可の呼び出しを (navigator.hid.requestDevice などを介して) せずに、デバイスへのデフォルト権限を提供するために利用できます。 このハンドラが定義されていない場合、(navigator.hid.requestDevice などを介した) デバイスの選択において付与された権限をデフォルトのデバイス権限として使用します。 Additionally, the default behavior of Electron is to store granted device permission in memory. より長期間の保存が必要な場合、開発者は付与されたデバイスのパーミッションを保存し (select-hid-device イベントを処理するときなど)、setDevicePermissionHandler でそのストレージから読み出しできます。

const { app, BrowserWindow } = require('electron')

let win = null

app.whenReady().then(() => {
  win = new BrowserWindow()

  win.webContents.session.setPermissionCheckHandler((webContents, permission, requestingOrigin, details) => {
    if (permission === 'hid') {
      // ここにロジックを追加して、その HID の選択を許可するかどうかを決定します。
      return true
    } else if (permission === 'serial') {
      // ここにロジックを追加して、そのシリアルポートの選択を許可するかどうかを決定します。
    } else if (permission === 'usb') {
      // ここにロジックを追加して、その USB デバイスの選択を許可するかどうかを決定します。
    }
    return false
  })

  // 任意で、永続ストアから以前に永続化されたデバイスを取得します。
  const grantedDevices = fetchGrantedDevices()

  win.webContents.session.setDevicePermissionHandler((details) => {
    if (new URL(details.origin).hostname === 'some-host' && details.deviceType === 'hid') {
      if (details.device.vendorId === 123 && details.device.productId === 345) {
        // 常にこのタイプのデバイスを許可します (これにより最初の `navigator.hid.requestDevice` の呼び出しをスキップできます)。
        return true
      }

      // 過去に許可されたデバイスのリストを検索します。
      return grantedDevices.some((grantedDevice) => {
        return grantedDevice.vendorId === details.device.vendorId &&
              grantedDevice.productId === details.device.productId &&
              grantedDevice.serialNumber && grantedDevice.serialNumber === details.device.serialNumber
      })
    } else if (details.deviceType === 'serial') {
      if (details.device.vendorId === 123 && details.device.productId === 345) {
        // 常にこのタイプのデバイスを許可します (これにより最初の `navigator.hid.requestDevice` の呼び出しをスキップできます)。
        return true
      }
    }
    return false
  })

  win.webContents.session.on('select-hid-device', (event, details, callback) => {
    event.preventDefault()
    const selectedDevice = details.deviceList.find((device) => {
      return device.vendorId === 9025 && device.productId === 67
    })
    callback(selectedDevice?.deviceId)
  })
})

ses.setUSBProtectedClassesHandler(handler)

• handler Function<string[]> | null
  • details Object
    • protectedClasses string[] - 保護された USB クラスの現在のリストです。 クラスの値は以下のいずれかを取ることがあります。
      • audio
      • audio-video
      • hid
      • mass-storage
      • smart-card
      • video
      • wireless

保護される USB クラス のオーバーライドに使用できるハンドラを設定します。 ハンドラの戻り値は、保護されている (例えばレンダラーでは利用できない) USB クラス文字列の配列です。 配列で有効な値は以下のとおりです。

• audio
• audio-video
• hid
• mass-storage
• smart-card
• video
• wireless

ハンドラから空の文字列配列を返すと、すべての USB クラスが許可されます。引数に渡された配列を返すと、保護された USB クラスのデフォルトのリストが維持されます (これはハンドラーが定義されていない場合のデフォルトの動作でもあります)。 ハンドラを消去するには setUSBProtectedClassesHandler(null) と呼び出します。

const { app, BrowserWindow } = require('electron')

let win = null

app.whenReady().then(() => {
  win = new BrowserWindow()

  win.webContents.session.setUSBProtectedClassesHandler((details) => {
    // 全てのクラスを許可するには:
    // return []
    // 保護クラスの現在のセットを維持するには:
    // return details.protectedClasses
    // 選択的にクラスを除去するには:
    return details.protectedClasses.filter((usbClass) => {
      // オーディオのクラスを除きます
      return usbClass.indexOf('audio') === -1
    })
  })
})

ses.setBluetoothPairingHandler(handler) Windows Linux

• handler Function | null
  • details Object
    • deviceId string
    • pairingKind string - リクエストしているペアリングの確認の種類です。 以下の値のいずれかです。
      • confirm このプロンプトはその Bluetooth デバイスをペアリングするかどうか確認するものです。
      • confirmPin このプロンプトは指定された PIN がデバイス上に表示された PIN と一致するかどうか確認するものです。
      • providePin このプロンプトはデバイスに PIN の提供を要求するものです。
    • frame WebFrameMain
    • pin string (任意) - pairingKind が confirmPin のとき、検証する PIN の値です。
  • callback Function
    • response Object
      • confirmed boolean - ダイアログがキャンセルされたならば、false が渡されます。 pairingKind が confirm や confirmPin であれば、この値はペアリングが承認されたことを示します。 pairingKind が providePin の場合は、提供されているならばこの値は true になります。
      • pin string | null (任意) - pairingKind が providePin のとき、この値は Bluetooth デバイスに必要な PIN になります。

Bluetooth のペアリング要求に応答するハンドラを設定します。 このハンドラにより、開発者はペアリングの前に追加の検証を必要とするデバイスを扱えます。 ハンドラが定義されていない場合、Linux や Windows 上での追加検証が必要なペアリングは自動キャンセルされます。 macOS は自動的にペアリングを行うため、macOS ではハンドラは不要です。 ハンドラを消去するには、setBluetoothPairingHandler(null) と呼び出してください。

const { app, BrowserWindow, session } = require('electron')
const path = require('node:path')

function createWindow () {
  let bluetoothPinCallback = null

  const mainWindow = new BrowserWindow({
    webPreferences: {
      preload: path.join(__dirname, 'preload.js')
    }
  })

  mainWindow.webContents.session.setBluetoothPairingHandler((details, callback) => {
    bluetoothPinCallback = callback
    // レンダラーに IPC メッセージを送信し、ユーザーにペアリングの確認を促します。
    // 注意として、このメッセージの処理してユーザーに表示するには、
    // レンダラーにもロジックが必要です。
    mainWindow.webContents.send('bluetooth-pairing-request', details)
  })

  // Bluetooth ペアリングのレスポンスを取得するために、レンダラーからの IPC メッセージをリッスンします。
  mainWindow.webContents.ipc.on('bluetooth-pairing-response', (event, response) => {
    bluetoothPinCallback(response)
  })
}

app.whenReady().then(() => {
  createWindow()
})

ses.clearHostResolverCache()

戻り値 Promise<void> - 操作が完了すると実行されます。

ホスト解決のキャッシュをクリアします。

ses.allowNTLMCredentialsForDomains(domains)

• domains string - 統合認証が有効であるサーバーのカンマ区切りのリスト。

HTTP NTLM またはネゴシエート認証の資格情報を常に送信するかどうかを動的に設定します。

const { session } = require('electron')
// 統合認証において、 `example.com`、`foobar.com`、`baz` で終わる
// URL を考えます。
session.defaultSession.allowNTLMCredentialsForDomains('*example.com, *foobar.com, *baz')

// 統合認証に、すべての URL を考えます。
session.defaultSession.allowNTLMCredentialsForDomains('*')

ses.setUserAgent(userAgent[, acceptLanguages])

• userAgent string
• acceptLanguages string (任意)

このセッションの userAgent と acceptLanguages をオーバーライドします。

acceptLanguages は、言語コードのカンマ区切りリスト (例: "en-US, fr, de, ko, zh-CN, ja") でなければなりません。

これは既存の WebContents には影響しません。それぞれの WebContents は webContents.setUserAgent を使用してセッション全体のユーザーエージェントをオーバーライドできます。

ses.isPersistent()

戻り値 boolean - このセッションが持続的なものであるかどうか。 BrowserWindow のデフォルトの webContents セッションは持続的です。 パーティションからセッションを作成する場合、persist: で始まるセッションは持続化され、他のセッションは一時的なものになります。

ses.getUserAgent()

戻り値 string - このセッションのユーザエージェント。

ses.setSSLConfig(config)

• config Object
  • minVersion string (任意) - tls1、tls1.1、tls1.2、tls1.3 のいずれかにできます。 これはリモートサーバーに接続する際に許可する最小の SSL バージョンです。 省略値は tls1 です。
  • maxVersion string (任意) - tls1.2 か tls1.3 にできます。 これはリモートサーバーに接続する際に許可する最大の SSL バージョンです。 省略値は tls1.3 です。
  • disabledCipherSuites Integer[] (任意) - ネット組み込みポリシーで無効化されたものに加えて、使用を禁止すべき暗号スートを明示したリスト。 0xAABB のようなリテラルの形式をサポートしています。ここで AA は cipher_suite[0] であり、BB は cipher_suite[1] です。これは RFC 2246 のセクション 7.4.1.2 で定義されています。 識別不可かつパース可能な暗号スートの形式であっても、エラーは返しません。 例: TLS_RSA_WITH_RC4_128_MD5 を無効にするには、0x0004 を指定し、TLS_ECDSA_WITH_RC4_128_SHA を無効にするには 0xC002 を指定します。 注意として、TLSv1.3 の暗号化方式はこの仕組みで無効にできません。

セッションの SSL 構成を設定します。 それ以降のネットワークリクエストではすべて新しい構成を使用します。 既存のネットワーク接続 (WebSocket 接続など) は終了しませんが、プール内の古いソケットは新しい接続に再利用されません。

ses.getBlobData(identifier)

• identifier string - 有効な UUID。

戻り値 Promise<Buffer> - blob データで実行されます。

ses.downloadURL(url[, options])

• url string
• options Object (任意)
  • headers Record<string, string> (任意) - HTTP リクエストのヘッダー。

url にあるリソースのダウンロードを初期化します。 この API は、will-download イベントでアクセスできる DownloadItem を生成します。

注意: これは webContents.downloadURL と異なり、ページのオリジンに関連するセキュリティチェックを実行しません。

ses.createInterruptedDownload(options)

• options Object
  • path string - ダウンロードの絶対パス。
  • urlChain string[] - ダウンロードの完全な URL チェーン。
  • mimeType string (任意)
  • offset Integer - ダウンロードの範囲の始端。
  • length Integer - ダウンロードの長さ。
  • lastModified string (任意) - ヘッダの最終更新日の値。
  • eTag string (任意) - ヘッダの ETag の値。
  • startTime Double (任意) - ダウンロードが開始されたときの UNIX エポックからの秒数。

以前の Session からの、cancelled または interrupted なダウンロードの再開を許可します。 この API は、will-download イベントでアクセスできる DownloadItem を生成します。 DownloadItem はそれに関連付けられた WebContents を持たず、初期状態は interrupted です。 DownloadItem の resume API を呼ぶことでのみ、ダウンロードが始まります。

ses.clearAuthCache()

戻り値 Promise<void> - session の HTTP 認証キャッシュがクリアされると実行されます。

ses.setPreloads(preloads)

• preloads string[] - プリロードスクリプトへの絶対パスの配列

通常の preload スクリプトが実行される直前に、このセッションに関連するすべてのウェブコンテンツで実行されるスクリプトを追加します。

ses.getPreloads()

戻り値 string[] - 登録されているプリロードスクリプトへのパスの配列。

ses.setCodeCachePath(path)

• path String - レンダラーが v8 で生成された JS のコードキャッシュを格納する絶対パス。

このセッションで生成された JS の コードキャッシュ を保存するディレクトリを設定します。 このディレクトリは、呼び出し以前にユーザーが作成しておく必要はありません。ランタイムは、存在しない場合には作成し、そうでない場合は既存のディレクトリを使用します。 ディレクトリを作成できない場合、コードキャッシュは使用されず、コードキャッシュに関連するすべての操作はランタイム内でエラーを出さずに失敗します。 デフォルトでは、それぞれのユーザーデータフォルダー配下の Code Cache というディレクトリです。

ses.clearCodeCaches(options)

• options Object
  • urls String[] (任意) - 生成されたコードキャッシュのうち削除する必要があるもののリソースに対応する URL の配列。 このリストが空の場合、キャッシュディレクトリのすべてのエントリが削除されます。

戻り値 Promise<void> - コードキャッシュの消去操作が完了すると解決されます。

ses.setSpellCheckerEnabled(enable)

• enable boolean

組み込みスペルチェッカーを有効にするかどうかを設定します。

ses.isSpellCheckerEnabled()

戻り値 boolean - 組み込みスペルチェッカーが有効化されているかどうか。

ses.setSpellCheckerLanguages(languages)

• languages string[] - スペルチェッカーを有効にする言語コードの配列。

組み込みスペルチェッカーは、ユーザーが入力している言語を自動的に検出しません。 スペルチェッカーが単語を正しくチェックするには、言語コードの配列でこの API を呼び出す必要があります。 ses.availableSpellCheckerLanguages プロパティで、サポートしている言語コードのリストを取得できます。

注: macOS では、OS のスペルチェッカーが使用されて言語が自動的に検出されます。 この API は、macOS では何もしません。

ses.getSpellCheckerLanguages()

戻り値 string[] - スペルチェッカーが有効になっている言語コードの配列。 このリストが空の場合、スペルチェッカーは en-US の使用へフォールバックします。 この設定が空のリストである場合、Electron は起動時に既定で現在の OS ロケールをこの設定に追加しようとします。 この設定は再起動後も持続します。

注意: macOS では、OS のスペルチェッカーが使用されて独自の言語リストを返します。 macOS の場合、この API は OS の設定言語を返します。

ses.setSpellCheckerDictionaryDownloadURL(url)

• url string - Electron が hunspell 辞書をダウンロードする基底 URL。

デフォルトでは、Electron は Chromium CDN から hunspell 辞書をダウンロードします。 この動作をオーバーライドする場合は、この API を使用して、独自ホスト版の hunspell 辞書を辞書ダウンローダーが指すようにすることができます。 ホストに必要なファイルが入っている、各リリースの hunspell_dictionaries.zip ファイルをこちらで公開しています。

ファイルサーバーは 大文字小文字を区別してはいけません。 できない場合、各ファイルを 2 回アップロードする必要があります。1 回目はその ZIP ファイルの大文字小文字のままで、2 回目はファイル名をすべて小文字にしてアップロードしてください。

hunspell_dictionaries.zip が https://example.com/dictionaries/language-code.bdic に存在して利用できる場合、ses.setSpellCheckerDictionaryDownloadURL('https://example.com/dictionaries/') を呼び出すことになります。 末尾のスラッシュに注意してください。 辞書への URL は、${url}${filename} の形式になります。

注: macOS では、OS のスペルチェッカーが使用されるため辞書ファイルをダウンロードしません。 この API は、macOS では何もしません。

ses.listWordsInSpellCheckerDictionary()

戻り値 Promise<string[]> - アプリのカスタム辞書の全単語の配列。 ディスクから完全な辞書が読み込まれたときに解決されます。

ses.addWordToSpellCheckerDictionary(word)

• word string - 辞書に追加したい単語

戻り値 boolean - 単語がカスタム辞書に正常に書き込まれたかどうか。 この API は、持続的でない (一時的な) セッションでは動作しません。

注意: macOS と Windows 10 では、この単語は OS カスタム辞書にも書き込まれます

ses.removeWordFromSpellCheckerDictionary(word)

• word string - 辞書から削除したい単語

戻り値 boolean - 単語がカスタム辞書から正常に削除されたかどうか。 この API は、持続的でない (一時的な) セッションでは動作しません。

注釈: macOS と Windows 10 では、この単語は OS カスタム辞書からも削除されます

ses.loadExtension(path[, options])

• path string - 解凍されていない Chrome 拡張機能を含んだディレクトリへのパス
• options Object (任意)
  • allowFileAccess boolean - 拡張機能が file:// プロトコルでローカルファイルを読み込んで file:// ページにコンテンツスクリプトを注入することを許可するかどうか。 これは、例えば file:// URL でデベロッパー ツール拡張機能を読み込むために必要です。 省略値は、false です。

戻り値 Promise<Extension> - 拡張機能が読み込まれたときに解決されます。

このメソッドは、拡張機能を読み込めなかった場合に例外を発生させます。 拡張機能のインストール時に警告が発生した場合 (Electron が未サポートの API を拡張機能が要求した場合など) は、コンソールにログが記録されます。

注意として、Electron は Chrome 拡張機能の API のすべてをサポートしていません。 サポート内容の詳細は サポートしている拡張機能 API をご参照ください。

注意として、以前のバージョンの Electron では、読み込まれた拡張機能は以降のアプリケーション実行のために記憶されます。 現在はそうなっていません。拡張機能を読み込みたい場合は、アプリを起動するたびに loadExtension を呼び出す必要があります。

const { app, session } = require('electron')
const path = require('node:path')

app.whenReady().then(async () => {
  await session.defaultSession.loadExtension(
    path.join(__dirname, 'react-devtools'),
    // allowFileAccess は、file:// の URL でデベロッパーツール拡張モジュールを読み込むために必要です。
    { allowFileAccess: true }
  )
  // 注意として、React デベロッパー ツール拡張機能を使用するにはそのコピーを
  // ダウンロードして解凍する必要があります。
})

この API は、パッケージした (.crx) 拡張機能の読み込みをサポートしていません。

注意: この API は app モジュールの ready イベントが発生する前には呼び出せません。

注: インメモリ (一時的な) セッションでの拡張機能読み込みはサポートされておらず、エラーが送出されます。

ses.removeExtension(extensionId)

• extensionId string - 削除する拡張機能の ID

拡張機能を取り除きます。

注意: この API は app モジュールの ready イベントが発生する前には呼び出せません。

ses.getExtension(extensionId)

• extensionId string - 取得する拡張機能の ID

Returns Extension | null - 指定した ID を持つロード済みの拡張機能。

注意: この API は app モジュールの ready イベントが発生する前には呼び出せません。

ses.getAllExtensions()

戻り値 Extension[] - 読み込まれた拡張機能のリスト。

注意: この API は app モジュールの ready イベントが発生する前には呼び出せません。

ses.getStoragePath()

戻り値 string | null - このセッションのデータが保存されている、ディスク上のファイルシステムの絶対パスです。 インメモリセッションの場合、これは null を返します。

インスタンスプロパティ

Session のインスタンスには以下のプロパティがあります。

ses.availableSpellCheckerLanguages 読み出し専用

この string[] 配列は利用可能な既知のすべてのスペルチェッカー言語で構成されます。 この配列にない言語コードを setSpellCheckerLanguages API に提供すると、エラーが発生します。

ses.spellCheckerEnabled

boolean 型で、組み込みスペルチェッカーが有効かどうかを示します。

ses.storagePath 読み出し専用

string | null 型で、このセッションのデータが保存されているディスクのファイルシステムの絶対パスを示します。 インメモリセッションの場合、これは null を返します。

ses.cookies 読み出し専用

このセッションの Cookie オブジェクト。

ses.serviceWorkers 読み出し専用

このセッションの ServiceWorkers オブジェクト。

ses.webRequest 読み出し専用

このセッションの WebRequest オブジェクト。

ses.protocol 読み出し専用

このセッションの Protocol オブジェクト。

const { app, session } = require('electron')
const path = require('node:path')

app.whenReady().then(() => {
  const protocol = session.fromPartition('some-partition').protocol
  if (!protocol.registerFileProtocol('atom', (request, callback) => {
    const url = request.url.substr(7)
    callback({ path: path.normalize(path.join(__dirname, url)) })
  })) {
    console.error('Failed to register protocol')
  }
})

ses.netLog 読み出し専用

このセッションの NetLog オブジェクト。

const { app, session } = require('electron')

app.whenReady().then(async () => {
  const netLog = session.fromPartition('some-partition').netLog
  netLog.startLogging('/path/to/net-log')
  // ネットワークイベントの後
  const path = await netLog.stopLogging()
  console.log('Net-logs written to', path)
})