大网数据广告活动
Web 标准与前端开发

Serial: requestPort() method

· 52CE 我爱测

The **`requestPort()`** method of the Serial interface presents the user with a dialog asking them to select a serial device to connect to. It returns a Promise that resolves with an instance of SerialPort representing the device chosen by the user.

Web Serial API

The requestPort() method of the Serial interface presents the user with a dialog asking them to select a serial device to connect to. It returns a Promise that resolves with an instance of SerialPort representing the device chosen by the user.

Syntax

requestPort()
requestPort(options)

Parameters

  • options
    • : An object with the following properties:
      • filters
        • : A list of objects containing vendor, product, or Bluetooth service class IDs used to filter the specific device types made available for the user to request a connection to. If no filters are specified, the user is presented with a list of every available device to choose from. Filters can contain the following values:
          • bluetoothServiceClassId
            • : A positive integer or string representing a Bluetooth service class ID. This can be a 16- or 32-bit UUID alias, any valid UUID, or a valid name from a GATT assigned services key.
          • usbVendorId
            • : A positive integer that identifies a USB device vendor. The USB Implementors Forum assigns IDs to specific vendors.
          • usbProductId
            • : A positive integer that identifies a USB device. Each vendor assigns IDs to its products.
      • allowedBluetoothServiceClassIds
        • : A list of positive integers and/or strings representing Bluetooth service class IDs. Bluetooth ports with custom service class IDs are excluded from the list of ports presented to the user unless the service class ID is included in this list. This is true whether you filter the list or not.

Return value

A Promise that resolves with an instance of SerialPort.

Exceptions

  • SecurityError DOMException
    • : The returned Promise rejects with this error in either of the following situations:
      • A Permissions-Policy/serial Permissions Policy blocks the use of this feature.
      • A user permission prompt was denied.
  • NotFoundError DOMException
    • : The returned Promise rejects with this exception if the user does not select a port when prompted.

Description

When the user first visits a site it will not have permission to access any serial devices. A site must first call requestPort() to prompt the user to select which device the site should be allowed to control.

This method must be called via transient activation. The user has to interact with the page or a UI element in order for this feature to work.

Access to the site might also be blocked by the Permissions-Policy/serial Permissions Policy. If blocked, the user won't be prompted for access to devices.

Examples

Allow the user to select any device

This example prompts the user to select a device via requestPort() when a <button> is pressed. It does not include a filter, which means that the selection list will include all available devices:

<button id="connect">Connect</button>
const connectBtn = document.getElementById("connect");
connectBtn.addEventListener("click", async () => {
  try {
    const port = await navigator.serial.requestPort();
    // Connect to port or add it to the list of available ports
  } catch (e) {
    // The user didn't select a device
  }
});

Allow the user to select a specific vendor's device

In this case, a filter is passed to requestPort() with a USB vendor ID to limit the set of devices shown to the user to only USB devices built by a particular manufacturer.

connectBtn.addEventListener("click", async () => {
  const usbVendorId = 0xabcd;
  try {
    const port = await navigator.serial.requestPort({
      filters: [{ usbVendorId }],
    });
    // Connect to port or add it to the list of available ports
  } catch (e) {
    // The user didn't select a device
  }
});

Allow the user to select custom RFCOMM-based services

Although most devices expose SPP-based communication through the standardized Bluetooth Classic Serial Port Profile, some use custom radio frequency communication (RFCOMM) based services. These devices have a Service Class ID that is not in the standard Bluetooth UUID range.

You need to pass the allowedBluetoothServiceClassIds list to requestPort() to access these custom RFCOMM-based services:

const myBluetoothServiceUuid = "01234567-89ab-cdef-0123-456789abcdef";

// Prompt user to select any serial port
// Access to the custom Bluetooth RFCOMM service above will be allowed
const port = await navigator.serial.requestPort({
  allowedBluetoothServiceClassIds: [myBluetoothServiceUuid],
});

You can also use the bluetoothServiceClassId filter key when calling requestPort() to prompt the user with a list of filtered Bluetooth serial ports identified by Service Class IDs:

const myBluetoothServiceUuid = "01234567-89ab-cdef-0123-456789abcdef";

// Prompt the user to select Bluetooth serial ports with
// the custom Bluetooth RFCOMM service above.
const port = await navigator.serial.requestPort({
  allowedBluetoothServiceClassIds: [myBluetoothServiceUuid],
  filters: [{ bluetoothServiceClassId: myBluetoothServiceUuid }],
});

Specifications

Browser compatibility

来源:MDN Web Docs / Mozilla 贡献者 · 作者与贡献记录 · CC BY-SA 2.5。离线整理了版式、链接和媒体显示。

资料来源与适用范围

资料来源
MDN Web Docs / Mozilla 贡献者
适用范围
请按文中版本与环境说明核对
内容语言
中文;命令、路径和错误标识保留技术原文
本地收录日期
2026-11-15
授权说明
CC BY-SA 2.5

正文与所需资源由本站本地存储。查看来源及更新记录 ↗

请按适用版本和实际日志确认原因;本站没有对每一种系统或设备逐项执行文中的操作。