裝置存取

如同基於 Chromium 的瀏覽器，Electron 透過 Web API 提供對裝置硬體的存取。在大多數情況下，這些 API 的運作方式與在瀏覽器中相同，但有些差異需要考慮。Electron 和瀏覽器之間的主要差異在於請求裝置存取時會發生的情況。在瀏覽器中，使用者會看到一個彈出視窗，他們可以在其中授與對個別裝置的存取權。在 Electron 中，提供了開發人員可以使用的 API，以自動選擇裝置或提示使用者透過開發人員建立的介面選擇裝置。

Web Bluetooth API

Web Bluetooth API 可用於與藍牙裝置通訊。為了在 Electron 中使用此 API，開發人員需要處理與裝置請求相關聯的 webContents 上的 select-bluetooth-device 事件。

此外，當需要額外的驗證（例如 PIN 碼）時，可以使用 ses.setBluetoothPairingHandler(handler) 來處理 Windows 或 Linux 上與藍牙裝置的配對。

範例

此範例示範了一個 Electron 應用程式，當按下 Test Bluetooth 按鈕時，會自動選擇第一個可用的藍牙裝置。

docs/fiddles/features/web-bluetooth (34.0.0)在 Fiddle 中開啟

main.js
preload.js
index.html
renderer.js

const { app, BrowserWindow, ipcMain } = require('electron/main')
const path = require('node:path')

let bluetoothPinCallback
let selectBluetoothCallback

function createWindow () {
  const mainWindow = new BrowserWindow({
    width: 800,
    height: 600,
    webPreferences: {
      preload: path.join(__dirname, 'preload.js')
    }
  })

  mainWindow.webContents.on('select-bluetooth-device', (event, deviceList, callback) => {
    event.preventDefault()
    selectBluetoothCallback = callback
    const result = deviceList.find((device) => {
      return device.deviceName === 'test'
    })
    if (result) {
      callback(result.deviceId)
    } else {
      // The device wasn't found so we need to either wait longer (eg until the
      // device is turned on) or until the user cancels the request
    }
  })

  ipcMain.on('cancel-bluetooth-request', (event) => {
    selectBluetoothCallback('')
  })

  // Listen for a message from the renderer to get the response for the Bluetooth pairing.
  ipcMain.on('bluetooth-pairing-response', (event, response) => {
    bluetoothPinCallback(response)
  })

  mainWindow.webContents.session.setBluetoothPairingHandler((details, callback) => {
    bluetoothPinCallback = callback
    // Send a message to the renderer to prompt the user to confirm the pairing.
    mainWindow.webContents.send('bluetooth-pairing-request', details)
  })

  mainWindow.loadFile('index.html')
}

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

  app.on('activate', function () {
    if (BrowserWindow.getAllWindows().length === 0) createWindow()
  })
})

app.on('window-all-closed', function () {
  if (process.platform !== 'darwin') app.quit()
})

const { contextBridge, ipcRenderer } = require('electron/renderer')

contextBridge.exposeInMainWorld('electronAPI', {
  cancelBluetoothRequest: () => ipcRenderer.send('cancel-bluetooth-request'),
  bluetoothPairingRequest: (callback) => ipcRenderer.on('bluetooth-pairing-request', () => callback()),
  bluetoothPairingResponse: (response) => ipcRenderer.send('bluetooth-pairing-response', response)
})

<!DOCTYPE html>
<html>
  <head>
    <meta charset="UTF-8">
    <meta http-equiv="Content-Security-Policy" content="default-src 'self'; script-src 'self'">
    <title>Web Bluetooth API</title>
  </head>
  <body>
    <h1>Web Bluetooth API</h1>

    <button id="clickme">Test Bluetooth</button>
    <button id="cancel">Cancel Bluetooth Request</button>

    <p>Currently selected bluetooth device: <strong id="device-name"></strong></p>

    <script src="./renderer.js"></script>
  </body>
</html>

async function testIt () {
  const device = await navigator.bluetooth.requestDevice({
    acceptAllDevices: true
  })
  document.getElementById('device-name').innerHTML = device.name || `ID: ${device.id}`
}

document.getElementById('clickme').addEventListener('click', testIt)

function cancelRequest () {
  window.electronAPI.cancelBluetoothRequest()
}

document.getElementById('cancel').addEventListener('click', cancelRequest)

window.electronAPI.bluetoothPairingRequest((event, details) => {
  const response = {}

  switch (details.pairingKind) {
    case 'confirm': {
      response.confirmed = window.confirm(`Do you want to connect to device ${details.deviceId}?`)
      break
    }
    case 'confirmPin': {
      response.confirmed = window.confirm(`Does the pin ${details.pin} match the pin displayed on device ${details.deviceId}?`)
      break
    }
    case 'providePin': {
      const pin = window.prompt(`Please provide a pin for ${details.deviceId}.`)
      if (pin) {
        response.pin = pin
        response.confirmed = true
      } else {
        response.confirmed = false
      }
    }
  }

  window.electronAPI.bluetoothPairingResponse(response)
})

WebHID API

WebHID API 可用於存取 HID 裝置，例如鍵盤和遊戲手把。Electron 提供了多個 API 用於處理 WebHID API。

當呼叫 navigator.hid.requestDevice 時，可以使用 Session 上的 select-hid-device 事件來選擇 HID 裝置。此外，當處理 select-hid-device 事件時，可以使用 Session 上的 hid-device-added 和 hid-device-removed 事件來處理裝置的插入或拔除。注意：這些事件只會在呼叫 select-hid-device 的回呼函數之前觸發。它們不打算用作通用的 hid 裝置監聽器。
可以使用 ses.setDevicePermissionHandler(handler) 為裝置提供預設權限，而無需先透過 navigator.hid.requestDevice 請求裝置的權限。此外，Electron 的預設行為是在對應的 WebContents 的生命週期內儲存授與的裝置權限。如果需要長期儲存，開發人員可以儲存授與的裝置權限（例如，在處理 select-hid-device 事件時），然後使用 setDevicePermissionHandler 從該儲存讀取。
可以使用 ses.setPermissionCheckHandler(handler) 來停用特定來源的 HID 存取。

封鎖清單

預設情況下，Electron 使用與 Chromium 相同的封鎖清單。如果您希望覆寫此行為，可以設定 disable-hid-blocklist 旗標

app.commandLine.appendSwitch('disable-hid-blocklist')

範例

此範例示範了一個 Electron 應用程式，該應用程式透過 ses.setDevicePermissionHandler(handler) 和當按下 Test WebHID 按鈕時，透過 Session 上的 select-hid-device 事件自動選擇 HID 裝置。

docs/fiddles/features/web-hid (34.0.0)在 Fiddle 中開啟

main.js
index.html
renderer.js

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

function createWindow () {
  const mainWindow = new BrowserWindow({
    width: 800,
    height: 600
  })

  mainWindow.webContents.session.on('select-hid-device', (event, details, callback) => {
    // Add events to handle devices being added or removed before the callback on
    // `select-hid-device` is called.
    mainWindow.webContents.session.on('hid-device-added', (event, device) => {
      console.log('hid-device-added FIRED WITH', device)
      // Optionally update details.deviceList
    })

    mainWindow.webContents.session.on('hid-device-removed', (event, device) => {
      console.log('hid-device-removed FIRED WITH', device)
      // Optionally update details.deviceList
    })

    event.preventDefault()
    if (details.deviceList && details.deviceList.length > 0) {
      callback(details.deviceList[0].deviceId)
    }
  })

  mainWindow.webContents.session.setPermissionCheckHandler((webContents, permission, requestingOrigin, details) => {
    if (permission === 'hid' && details.securityOrigin === 'file:///') {
      return true
    }
  })

  mainWindow.webContents.session.setDevicePermissionHandler((details) => {
    if (details.deviceType === 'hid' && details.origin === 'file://') {
      return true
    }
  })

  mainWindow.loadFile('index.html')
}

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

  app.on('activate', function () {
    if (BrowserWindow.getAllWindows().length === 0) createWindow()
  })
})

app.on('window-all-closed', function () {
  if (process.platform !== 'darwin') app.quit()
})

<!DOCTYPE html>
<html>
  <head>
    <meta charset="UTF-8">
    <meta http-equiv="Content-Security-Policy" content="default-src 'self'; script-src 'self'">
    <title>WebHID API</title>
  </head>
  <body>
    <h1>WebHID API</h1>

    <button id="clickme">Test WebHID</button>

    <h3>HID devices automatically granted access via <i>setDevicePermissionHandler</i></h3>
    <div id="granted-devices"></div>

    <h3>HID devices automatically granted access via <i>select-hid-device</i></h3>
    <div id="granted-devices2"></div>

    <script src="./renderer.js"></script>
  </body>
</html>

function formatDevices (devices) {
  return devices.map(device => device.productName).join('<hr>')
}

async function testIt () {
  document.getElementById('granted-devices').innerHTML = formatDevices(await navigator.hid.getDevices())
  document.getElementById('granted-devices2').innerHTML = formatDevices(await navigator.hid.requestDevice({ filters: [] }))
}

document.getElementById('clickme').addEventListener('click', testIt)

Web Serial API

Web Serial API 可用於存取透過串列埠、USB 或藍牙連線的串列裝置。為了在 Electron 中使用此 API，開發人員需要處理與串列埠請求相關聯的 Session 上的 select-serial-port 事件。

還有其他幾個 API 用於處理 Web Serial API。

當處理 select-serial-port 事件時，可以使用 Session 上的 serial-port-added 和 serial-port-removed 事件來處理裝置的插入或拔除。注意：這些事件只會在呼叫 select-serial-port 的回呼函數之前觸發。它們不打算用作通用的串列埠監聽器。
可以使用 ses.setDevicePermissionHandler(handler) 為裝置提供預設權限，而無需先透過 navigator.serial.requestPort 請求裝置的權限。此外，Electron 的預設行為是在對應的 WebContents 的生命週期內儲存授與的裝置權限。如果需要長期儲存，開發人員可以儲存授與的裝置權限（例如，在處理 select-serial-port 事件時），然後使用 setDevicePermissionHandler 從該儲存讀取。
可以使用 ses.setPermissionCheckHandler(handler) 來停用特定來源的串列存取。

範例

此範例示範了一個 Electron 應用程式，該應用程式透過 ses.setDevicePermissionHandler(handler) 自動選擇串列裝置，並示範了當按下 Test Web Serial 按鈕時，透過 Session 上的 select-serial-port 事件選擇第一個可用的 Arduino Uno 串列裝置（如果已連線）。

docs/fiddles/features/web-serial (34.0.0)在 Fiddle 中開啟

main.js
index.html
renderer.js

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

function createWindow () {
  const mainWindow = new BrowserWindow({
    width: 800,
    height: 600
  })

  mainWindow.webContents.session.on('select-serial-port', (event, portList, webContents, callback) => {
    // Add listeners to handle ports being added or removed before the callback for `select-serial-port`
    // is called.
    mainWindow.webContents.session.on('serial-port-added', (event, port) => {
      console.log('serial-port-added FIRED WITH', port)
      // Optionally update portList to add the new port
    })

    mainWindow.webContents.session.on('serial-port-removed', (event, port) => {
      console.log('serial-port-removed FIRED WITH', port)
      // Optionally update portList to remove the port
    })

    event.preventDefault()
    if (portList && portList.length > 0) {
      callback(portList[0].portId)
    } else {
      // eslint-disable-next-line n/no-callback-literal
      callback('') // Could not find any matching devices
    }
  })

  mainWindow.webContents.session.setPermissionCheckHandler((webContents, permission, requestingOrigin, details) => {
    if (permission === 'serial' && details.securityOrigin === 'file:///') {
      return true
    }

    return false
  })

  mainWindow.webContents.session.setDevicePermissionHandler((details) => {
    if (details.deviceType === 'serial' && details.origin === 'file://') {
      return true
    }

    return false
  })

  mainWindow.loadFile('index.html')

  mainWindow.webContents.openDevTools()
}

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

  app.on('activate', function () {
    if (BrowserWindow.getAllWindows().length === 0) createWindow()
  })
})

app.on('window-all-closed', function () {
  if (process.platform !== 'darwin') app.quit()
})

<!DOCTYPE html>
<html>
  <head>
    <meta charset="UTF-8">
    <meta http-equiv="Content-Security-Policy" content="default-src 'self'; script-src 'self'">
    <title>Web Serial API</title>
  <body>
    <h1>Web Serial API</h1>

    <button id="clickme">Test Web Serial API</button>

    <p>Matching Arduino Uno device: <strong id="device-name""></strong></p>

    <script src="./renderer.js"></script>
  </body>
</html>

async function testIt () {
  const filters = [
    { usbVendorId: 0x2341, usbProductId: 0x0043 },
    { usbVendorId: 0x2341, usbProductId: 0x0001 }
  ]
  try {
    const port = await navigator.serial.requestPort({ filters })
    const portInfo = port.getInfo()
    document.getElementById('device-name').innerHTML = `vendorId: ${portInfo.usbVendorId} | productId: ${portInfo.usbProductId} `
  } catch (ex) {
    if (ex.name === 'NotFoundError') {
      document.getElementById('device-name').innerHTML = 'Device NOT found'
    } else {
      document.getElementById('device-name').innerHTML = ex
    }
  }
}

document.getElementById('clickme').addEventListener('click', testIt)

WebUSB API

WebUSB API 可用於存取 USB 裝置。Electron 提供了多個 API 用於處理 WebUSB API。

當呼叫 navigator.usb.requestDevice 時，可以使用 Session 上的 select-usb-device 事件來選擇 USB 裝置。此外，當處理 select-usb-device 事件時，可以使用 Session 上的 usb-device-added 和 usb-device-removed 事件來處理裝置的插入或拔除。注意：這兩個事件只會在呼叫 select-usb-device 的回呼函數之前觸發。它們不打算用作通用的 usb 裝置監聽器。
當在 USB 裝置上呼叫 device.forget() 時，可以使用 Session 上的 usb-device-revoked 事件來回應。
可以使用 ses.setDevicePermissionHandler(handler) 為裝置提供預設權限，而無需先透過 navigator.usb.requestDevice 請求裝置的權限。此外，Electron 的預設行為是在對應的 WebContents 的生命週期內儲存授與的裝置權限。如果需要長期儲存，開發人員可以儲存授與的裝置權限（例如，在處理 select-usb-device 事件時），然後使用 setDevicePermissionHandler 從該儲存讀取。
可以使用 ses.setPermissionCheckHandler(handler) 來停用特定來源的 USB 存取。
`ses.setUSBProtectedClassesHandler 可以用來允許使用預設情況下不可用的受保護的 USB 類別。

範例

這個範例展示了一個 Electron 應用程式，當點擊「測試 WebUSB」按鈕時，它會透過 ses.setDevicePermissionHandler(handler) 和 Session 上的 select-usb-device 事件，自動選擇 USB 裝置（如果已連接）。

docs/fiddles/features/web-usb (34.0.0)在 Fiddle 中開啟

main.js
index.html
renderer.js

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

function createWindow () {
  const mainWindow = new BrowserWindow({
    width: 800,
    height: 600
  })

  let grantedDeviceThroughPermHandler

  mainWindow.webContents.session.on('select-usb-device', (event, details, callback) => {
    // Add events to handle devices being added or removed before the callback on
    // `select-usb-device` is called.
    mainWindow.webContents.session.on('usb-device-added', (event, device) => {
      console.log('usb-device-added FIRED WITH', device)
      // Optionally update details.deviceList
    })

    mainWindow.webContents.session.on('usb-device-removed', (event, device) => {
      console.log('usb-device-removed FIRED WITH', device)
      // Optionally update details.deviceList
    })

    event.preventDefault()
    if (details.deviceList && details.deviceList.length > 0) {
      const deviceToReturn = details.deviceList.find((device) => {
        return !grantedDeviceThroughPermHandler || (device.deviceId !== grantedDeviceThroughPermHandler.deviceId)
      })
      if (deviceToReturn) {
        callback(deviceToReturn.deviceId)
      } else {
        callback()
      }
    }
  })

  mainWindow.webContents.session.setPermissionCheckHandler((webContents, permission, requestingOrigin, details) => {
    if (permission === 'usb' && details.securityOrigin === 'file:///') {
      return true
    }
  })

  mainWindow.webContents.session.setDevicePermissionHandler((details) => {
    if (details.deviceType === 'usb' && details.origin === 'file://') {
      if (!grantedDeviceThroughPermHandler) {
        grantedDeviceThroughPermHandler = details.device
        return true
      } else {
        return false
      }
    }
  })

  mainWindow.webContents.session.setUSBProtectedClassesHandler((details) => {
    return details.protectedClasses.filter((usbClass) => {
      // Exclude classes except for audio classes
      return usbClass.indexOf('audio') === -1
    })
  })

  mainWindow.loadFile('index.html')
}

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

  app.on('activate', function () {
    if (BrowserWindow.getAllWindows().length === 0) createWindow()
  })
})

app.on('window-all-closed', function () {
  if (process.platform !== 'darwin') app.quit()
})

<!DOCTYPE html>
<html>
  <head>
    <meta charset="UTF-8">
    <meta http-equiv="Content-Security-Policy" content="default-src 'self'; script-src 'self'">
    <title>WebUSB API</title>
  </head>
  <body>
    <h1>WebUSB API</h1>

    <button id="clickme">Test WebUSB</button>

    <h3>USB devices automatically granted access via <i>setDevicePermissionHandler</i></h3>
    <div id="granted-devices"></div>

    <h3>USB devices automatically granted access via <i>select-usb-device</i></h3>
    <div id="granted-devices2"></div>

    <script src="./renderer.js"></script>
  </body>
</html>

function getDeviceDetails (device) {
  return device.productName || `Unknown device ${device.deviceId}`
}

async function testIt () {
  const noDevicesFoundMsg = 'No devices found'
  const grantedDevices = await navigator.usb.getDevices()
  let grantedDeviceList = ''
  if (grantedDevices.length > 0) {
    for (const device of grantedDevices) {
      grantedDeviceList += `<hr>${getDeviceDetails(device)}</hr>`
    }
  } else {
    grantedDeviceList = noDevicesFoundMsg
  }
  document.getElementById('granted-devices').innerHTML = grantedDeviceList

  grantedDeviceList = ''
  try {
    const grantedDevice = await navigator.usb.requestDevice({
      filters: []
    })
    grantedDeviceList += `<hr>${getDeviceDetails(grantedDevice)}</hr>`
  } catch (ex) {
    if (ex.name === 'NotFoundError') {
      grantedDeviceList = noDevicesFoundMsg
    }
  }
  document.getElementById('granted-devices2').innerHTML = grantedDeviceList
}

document.getElementById('clickme').addEventListener('click', testIt)

Web Bluetooth API​

範例​

WebHID API​

封鎖清單​

範例​

Web Serial API​

範例​

WebUSB API​

範例​

Web Bluetooth API

範例

WebHID API

封鎖清單

範例

Web Serial API

範例

WebUSB API

範例