chrome.serial

说明

使用 chrome.serial API 对连接到串行端口的设备执行读写操作。

权限

serial

类型

ConnectionInfo

属性

• 比特率

  编号（选填）

  请参阅 ConnectionOptions.bitrate。如果使用的是非标准比特率，或者在查询底层设备时出错，则此字段可能被省略或不准确。

• bufferSize

  number

  查看ConnectionOptions.bufferSize

• connectionId

  number

  串行端口连接的 ID。

• ctsFlowControl

  布尔值（可选）

  请参阅 ConnectionOptions.ctsFlowControl。如果在查询底层设备时出错，此字段可以省略。

• dataBits

  DataBits 可选

  请参阅 ConnectionOptions.dataBits。如果在查询底层设备时出错，此字段可以省略。

• name

  字符串

  查看ConnectionOptions.name

• parityBit

  ParityBit 可选

  请参阅 ConnectionOptions.parityBit。如果在查询底层设备时出错，此字段可以省略。

• 已暂停

  布尔值

  此标记指示是否禁止连接触发 onReceive 事件。

• 持久性

  布尔值

  查看ConnectionOptions.persistent

• receiveTimeout

  number

  查看ConnectionOptions.receiveTimeout

• sendTimeout

  number

  查看ConnectionOptions.sendTimeout

• stopBits

  StopBits 可选

  请参阅 ConnectionOptions.stopBits。如果在查询底层设备时出错，此字段可以省略。

ConnectionOptions

属性

• 比特率

  编号（选填）

  请求要打开的连接的比特率。为了与最广泛的硬件兼容，此数字应与常用比特率之一相匹配，例如 110、300、1200、2400、4800、9600、14400、19200、38400、57600、115200。当然，无法保证连接到串行端口的设备将支持请求的比特率，即使端口本身支持该比特率也是如此。默认情况下，系统会传递 9600。

• bufferSize

  编号（选填）

  用于接收数据的缓冲区大小。默认值为 4096。

• ctsFlowControl

  布尔值（可选）

  此标记指示是否启用 RTS/CTS 硬件流控制。默认值为 false。

• dataBits

  DataBits 可选

  默认情况下，系统会传递 "eight"。

• name

  字符串（可选）

  与连接关联的应用定义的字符串。

• parityBit

  ParityBit 可选

  默认情况下，系统会传递 "no"。

• 持久性

  布尔值（可选）

  此标记指示在应用暂停时是否应让连接保持打开状态（请参阅管理应用生命周期）。默认值为“false”。加载应用时，可以使用 getConnections 提取之前使用 persistent=true 打开的任何串行连接。

• receiveTimeout

  编号（选填）

  在引发具有“超时”的 onReceiveError 事件之前等待新数据的最长时间（以毫秒为单位）错误。如果为零，则连接不会引发接收超时错误。默认值为 0。

• sendTimeout

  编号（选填）

  在调用包含“超时”的回调之前，等待 send 操作完成的最长时间（以毫秒为单位）错误。如果为零，则不会触发发送超时错误。默认值为 0。

• stopBits

  StopBits 可选

  默认情况下，系统会传递 "one"。

DataBits

枚举

"seven"

“eight”

DeviceControlSignals

属性

• ct

  布尔值

  CTS（清除即可发送）。

• dcd

  布尔值

  DCD（数据载波检测）或 RLSD（接收线路信号/ 检测）。

• dsr

  布尔值

  DSR（数据集就绪）。

• 日

  布尔值

  RI（环形指示器）。

DeviceInfo

属性

• displayName

  字符串（可选）

  底层设备的直观易懂的显示名称（如果可从主机驱动程序查询）。

• 路径

  字符串

  设备的系统路径。要连接到此设备，应将其作为 path 参数传递给 chrome.serial.connect。

• productId

  编号（选填）

  USB 产品 ID（如果可以为底层设备确定）。

• vendorId

  编号（选填）

  PCI 或 USB 供应商 ID（如果可以为底层设备确定）。

HostControlSignals

属性

• dtr

  布尔值（可选）

  DTR（数据终端就绪）。

• RTS

  布尔值（可选）

  RTS（请求发送）。

ParityBit

枚举

“否”

"odd"

“均匀”

ReceiveError

枚举

"disconnect"
连接已断开。

"timeout"
在 receiveTimeout 毫秒内未收到任何数据。

"device_lost"
设备很可能已与主机断开连接。

"break"
设备检测到中断情况。

"frame_error"
设备检测到取景错误。

"overrun"
发生了字符缓冲区溢出。下一个字符会丢失。

"buffer_overflow"
发生了输入缓冲区溢出。输入缓冲区内没有任何空间，或者系统收到的某个字符位于文件结束 (EOF) 字符后。

"parity_error"
设备检测到奇偶错误。

"system_error"
发生了系统错误，连接可能无法恢复。

ReceiveErrorInfo

属性

• connectionId

  number

  连接标识符。

• 错误

  ReceiveError

  一个错误代码，指示出了什么问题。

ReceiveInfo

属性

• connectionId

  number

  连接标识符。

• 数据

  数组缓冲区

  收到的数据。

SendError

枚举

"disconnect"
连接已断开。

"pending"
发送已在待处理。

"timeout"
发送超时。

"system_error"
发生了系统错误，连接可能无法恢复。

SendInfo

属性

• bytesSent

  number

  发送的字节数。

• 错误

  SendError（可选）

  发生错误时给出的错误代码。

StopBits

枚举

“one”

“two”

方法

clearBreak()

<ph type="x-smartling-placeholder"></ph> 承诺 Chrome 45 及更高版本

chrome.serial.clearBreak(
  connectionId: number,
  callback?: function,
)

在给定连接上恢复字符传输，并将传输线路置于不间断状态。

参数

• connectionId

  number

  连接的 ID。

• callback

  函数（可选）

  callback 参数如下所示：

  (result: boolean) => void

  • 结果

    布尔值

返回

• Promise&lt;boolean&gt;

  Chrome 117 及更高版本

  只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

connect()

<ph type="x-smartling-placeholder"></ph> 承诺

chrome.serial.connect(
  path: string,
  options?: ConnectionOptions,
  callback?: function,
)

连接到指定的串行端口。

参数

• 路径

  字符串

  要打开的串行端口的系统路径。

• 选项

  ConnectionOptions 可选

  端口配置选项。

• callback

  函数（可选）

  callback 参数如下所示：

  (connectionInfo: ConnectionInfo) => void

  • connectionInfo

    ConnectionInfo

返回

• Promise&lt;ConnectionInfo&gt;

  Chrome 117 及更高版本

  只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

disconnect()

<ph type="x-smartling-placeholder"></ph> 承诺

chrome.serial.disconnect(
  connectionId: number,
  callback?: function,
)

断开与串行端口的连接。

参数

• connectionId

  number

  已打开连接的 ID。

• callback

  函数（可选）

  callback 参数如下所示：

  (result: boolean) => void

  • 结果

    布尔值

返回

• Promise&lt;boolean&gt;

  Chrome 117 及更高版本

  只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

flush()

<ph type="x-smartling-placeholder"></ph> 承诺

chrome.serial.flush(
  connectionId: number,
  callback?: function,
)

清空指定连接的输入和输出缓冲区中的所有字节。

参数

• connectionId

  number

• callback

  函数（可选）

  callback 参数如下所示：

  (result: boolean) => void

  • 结果

    布尔值

返回

• Promise&lt;boolean&gt;

  Chrome 117 及更高版本

  只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

getConnections()

<ph type="x-smartling-placeholder"></ph> 承诺

chrome.serial.getConnections(
  callback?: function,
)

检索应用拥有的当前打开的串行端口连接的列表。

参数

• callback

  函数（可选）

  callback 参数如下所示：

  (connectionInfos: ConnectionInfo[]) => void

  • connectionInfos

    ConnectionInfo[]

返回

• Promise&lt;ConnectionInfo[]&gt;

  Chrome 117 及更高版本

  只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

getControlSignals()

<ph type="x-smartling-placeholder"></ph> 承诺

chrome.serial.getControlSignals(
  connectionId: number,
  callback?: function,
)

检索指定连接上的控制信号状态。

参数

• connectionId

  number

  连接的 ID。

• callback

  函数（可选）

  callback 参数如下所示：

  (signals: DeviceControlSignals) => void

  • 信号

    DeviceControlSignals

返回

• Promise&lt;DeviceControlSignals&gt;

  Chrome 117 及更高版本

  只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

getDevices()

<ph type="x-smartling-placeholder"></ph> 承诺

chrome.serial.getDevices(
  callback?: function,
)

返回有关系统中可用串行设备的信息。每次调用此方法时，系统都会重新生成该列表。

参数

• callback

  函数（可选）

  callback 参数如下所示：

  (ports: DeviceInfo[]) => void

  • ports

    DeviceInfo[]

返回

• Promise&lt;DeviceInfo[]&gt;

  Chrome 117 及更高版本

  只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

getInfo()

<ph type="x-smartling-placeholder"></ph> 承诺

chrome.serial.getInfo(
  connectionId: number,
  callback?: function,
)

检索给定连接的状态。

参数

• connectionId

  number

  已打开连接的 ID。

• callback

  函数（可选）

  callback 参数如下所示：

  (connectionInfo: ConnectionInfo) => void

  • connectionInfo

    ConnectionInfo

返回

• Promise&lt;ConnectionInfo&gt;

  Chrome 117 及更高版本

  只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

send()

<ph type="x-smartling-placeholder"></ph> 承诺

chrome.serial.send(
  connectionId: number,
  data: ArrayBuffer,
  callback?: function,
)

将数据写入指定连接。

参数

• connectionId

  number

  连接的 ID。

• 数据

  数组缓冲区

  要发送的数据。

• callback

  函数（可选）

  callback 参数如下所示：

  (sendInfo: SendInfo) => void

  • sendInfo

    SendInfo

返回

• Promise&lt;SendInfo&gt;

  Chrome 117 及更高版本

  只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

setBreak()

<ph type="x-smartling-placeholder"></ph> 承诺 Chrome 45 及更高版本

chrome.serial.setBreak(
  connectionId: number,
  callback?: function,
)

暂停给定连接上的字符传输，并将传输行置于中断状态，直到调用 clearBreak。

参数

• connectionId

  number

  连接的 ID。

• callback

  函数（可选）

  callback 参数如下所示：

  (result: boolean) => void

  • 结果

    布尔值

返回

• Promise&lt;boolean&gt;

  Chrome 117 及更高版本

  只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

setControlSignals()

<ph type="x-smartling-placeholder"></ph> 承诺

chrome.serial.setControlSignals(
  connectionId: number,
  signals: HostControlSignals,
  callback?: function,
)

设置给定连接上的控制信号状态。

参数

• connectionId

  number

  连接的 ID。

• 信号

  HostControlSignals

  更改要发送到设备的信号集。

• callback

  函数（可选）

  callback 参数如下所示：

  (result: boolean) => void

  • 结果

    布尔值

返回

• Promise&lt;boolean&gt;

  Chrome 117 及更高版本

  只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

setPaused()

<ph type="x-smartling-placeholder"></ph> 承诺

chrome.serial.setPaused(
  connectionId: number,
  paused: boolean,
  callback?: function,
)

暂停或取消暂停打开的连接。

参数

• connectionId

  number

  已打开连接的 ID。

• 已暂停

  布尔值

  指示是暂停还是取消暂停的标志。

• callback

  函数（可选）

  callback 参数如下所示：

  () => void

返回

• 承诺<void>

  Chrome 117 及更高版本

  只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

update()

<ph type="x-smartling-placeholder"></ph> 承诺

chrome.serial.update(
  connectionId: number,
  options: ConnectionOptions,
  callback?: function,
)

更新打开的串行端口连接上的选项设置。

参数

• connectionId

  number

  已打开连接的 ID。

• 选项

  ConnectionOptions

  端口配置选项。

• callback

  函数（可选）

  callback 参数如下所示：

  (result: boolean) => void

  • 结果

    布尔值

返回

• Promise&lt;boolean&gt;

  Chrome 117 及更高版本

  只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

事件

onReceive

chrome.serial.onReceive.addListener(
  callback: function,
)

从连接中读取数据时引发的事件。

参数

• callback

  函数

  callback 参数如下所示：

  (info: ReceiveInfo) => void

  • 资讯

    ReceiveInfo

onReceiveError

chrome.serial.onReceiveError.addListener(
  callback: function,
)

运行时在等待串行端口上的数据时发生错误时引发的事件。引发此事件后，连接可设置为 paused。"timeout" 错误不会暂停连接。

参数

• callback

  函数

  callback 参数如下所示：

  (info: ReceiveErrorInfo) => void

  • 资讯

    ReceiveErrorInfo