chrome.serial

說明

使用 chrome.serial API 讀取及寫入連接至序列埠的裝置。

權限

serial

可用性

僅適用於 ChromeOS

類型

ConnectionInfo

屬性

  • bitrate

    數字 選填

    請參閱 ConnectionOptions.bitrate。如果使用非標準位元率，或查詢基礎裝置時發生錯誤，系統可能會省略這個欄位或顯示不準確的值。

  • bufferSize

    數字

    查看ConnectionOptions.bufferSize

  • connectionId

    數字

    序列埠連線的 ID。

  • ctsFlowControl

    布林值 選填

    請參閱 ConnectionOptions.ctsFlowControl。如果查詢基礎裝置時發生錯誤，系統可能會省略這個欄位。

  • dataBits

    DataBits 選填

    請參閱 ConnectionOptions.dataBits。如果查詢基礎裝置時發生錯誤，系統可能會省略這個欄位。

  • 名稱

    字串

    查看ConnectionOptions.name

  • parityBit

    ParityBit 選填

    請參閱 ConnectionOptions.parityBit。如果查詢基礎裝置時發生錯誤，系統可能會省略這個欄位。

  • 已暫停

    布林值

    此標記用於註明是否禁止連線觸發 onReceive 事件。

  • 永久

    布林值

    查看ConnectionOptions.persistent

  • receiveTimeout

    數字

    查看ConnectionOptions.receiveTimeout

  • sendTimeout

    數字

    查看ConnectionOptions.sendTimeout

  • stopBits

    StopBits 選填

    請參閱 ConnectionOptions.stopBits。如果查詢基礎裝置時發生錯誤，系統可能會省略這個欄位。

ConnectionOptions

屬性

  • bitrate

    數字 選填

    要開啟的連線要求的位元率。為盡可能與各種硬體相容，這個數字應與常見的位元率相符，例如 110、300、1200、2400、4800、9600、14400、19200、38400、57600、115200。當然，即使通訊埠本身支援要求的位元率，也無法保證連接至序列埠的裝置會支援該位元率。根據預設，系統會傳遞 9600。

  • bufferSize

    數字 選填

    用於接收資料的緩衝區大小。預設值為 4096。

  • ctsFlowControl

    布林值 選填

    這個標記用於指出是否要啟用 RTS/CTS 硬體流量控制。預設值為 false。

  • dataBits

    DataBits 選填

    系統預設會傳遞 "eight"。

  • 名稱

    字串 選填

    與連線相關聯的應用程式定義字串。

  • parityBit

    ParityBit 選填

    系統預設會傳遞 "no"。

  • 永久

    布林值 選填

    這個標記指出應用程式暫停時，是否應保持連線開啟 (請參閱「管理應用程式生命週期」)。預設值為「false」。載入應用程式後，先前以 persistent=true 開啟的任何序列連線，都可以透過 getConnections 擷取。

  • receiveTimeout

    數字 選填

    等待新資料的時間上限 (以毫秒為單位)，超過這個時間就會引發 onReceiveError 事件，並顯示「逾時」錯誤。如果設為 0，系統就不會針對連線引發接收逾時錯誤。預設為 0。

  • sendTimeout

    數字 選填

    等待 send 作業完成的時間上限 (以毫秒為單位)，超過後系統會呼叫回呼並傳回「逾時」錯誤。如果設為 0，就不會觸發傳送逾時錯誤。預設為 0。

  • stopBits

    StopBits 選填

    系統預設會傳遞 "one"。

DataBits

列舉

"seven"

"eight"

DeviceControlSignals

屬性

  • cts

    布林值

    CTS (允許傳送)。

  • dcd

    布林值

    DCD (資料載波偵測) 或 RLSD (接收線路訊號/偵測)。

  • dsr

    布林值

    DSR (Data Set Ready)。

  • ri

    布林值

    RI (響鈴指標)。

DeviceInfo

屬性

  • displayName

    字串 選填

    基礎裝置的人類可讀顯示名稱 (如果可以從主機驅動程式查詢)。

  • 路徑

    字串

    裝置的系統路徑。這應做為 path 引數傳遞至 chrome.serial.connect，以便連線至這部裝置。

  • productId

    數字 選填

    USB 產品 ID (如果可以判斷基礎裝置)。

  • vendorId

    數字 選填

    PCI 或 USB 供應商 ID (如果可以判斷基礎裝置)。

HostControlSignals

屬性

  • dtr

    布林值 選填

    DTR (資料終端機就緒)。

  • rts

    布林值 選填

    RTS (傳送請求)。

ParityBit

列舉

"no"

"odd"

"even"

ReceiveError

列舉

「disconnected」
連線已中斷。

「timeout」
receiveTimeout 毫秒內未收到任何資料。

"device_lost"
裝置可能已與主機中斷連線。

「break」
裝置偵測到中斷條件。

"frame_error"
裝置偵測到框架錯誤。

"overrun"
字元緩衝區溢位。下一個角色迷路了。

"buffer_overflow"
輸入緩衝區溢位。輸入緩衝區沒有空間，或是在檔案結尾 (EOF) 字元後收到字元。

"parity_error"
裝置偵測到同位檢查錯誤。

"system_error"
發生系統錯誤，連線可能無法復原。

ReceiveErrorInfo

屬性

  • connectionId

    數字

    連線 ID。

  • 錯誤

    ReceiveError

    指出錯誤原因的錯誤代碼。

ReceiveInfo

屬性

  • connectionId

    數字

    連線 ID。

  • 資料

    ArrayBuffer

    收到的資料。

SendError

列舉

「disconnected」
連線已中斷。

"pending"
已有待處理的傳送作業。

「timeout」
傳送逾時。

"system_error"
發生系統錯誤，連線可能無法復原。

SendInfo

屬性

  • bytesSent

    數字

    傳送的位元組數。

  • 錯誤

    SendError 選填

    發生錯誤時的錯誤代碼。

StopBits

列舉

"one"

"two"

方法

clearBreak()

Promise Chrome 45 以上版本 
chrome.serial.clearBreak(
  connectionId: number,
  callback?: function,
): Promise<boolean>

還原指定連線上的字元傳輸，並將傳輸線置於非中斷狀態。

參數

  • connectionId

    數字

    連線 ID。

  • callback

    函式 選填

    callback 參數如下： 

    (result: boolean) => void

    • 結果

      布林值

傳回

  • Promise<boolean>

    Chrome 117 以上版本

    Promise 僅適用於 Manifest V3 以上版本，其他平台則須使用回呼。

connect()

Promise 
chrome.serial.connect(
  path: string,
  options?: ConnectionOptions,
  callback?: function,
): Promise<ConnectionInfo>

連線至指定的序列埠。

參數

  • 路徑

    字串

    要開啟的序列埠系統路徑。

  • 選項

    ConnectionOptions 選填

    通訊埠設定選項。

  • callback

    函式 選填

    callback 參數如下： 

    (connectionInfo: ConnectionInfo) => void

傳回

  • Promise<ConnectionInfo>

    Chrome 117 以上版本

    Promise 僅適用於 Manifest V3 以上版本，其他平台則須使用回呼。

disconnect()

Promise 
chrome.serial.disconnect(
  connectionId: number,
  callback?: function,
): Promise<boolean>

中斷與序列埠的連線。

參數

  • connectionId

    數字

    已開啟連線的 ID。

  • callback

    函式 選填

    callback 參數如下： 

    (result: boolean) => void

    • 結果

      布林值

傳回

  • Promise<boolean>

    Chrome 117 以上版本

    Promise 僅適用於 Manifest V3 以上版本，其他平台則須使用回呼。

flush()

Promise 
chrome.serial.flush(
  connectionId: number,
  callback?: function,
): Promise<boolean>

清除指定連線輸入和輸出緩衝區中的所有位元組。

參數

  • connectionId

    數字

  • callback

    函式 選填

    callback 參數如下： 

    (result: boolean) => void

    • 結果

      布林值

傳回

  • Promise<boolean>

    Chrome 117 以上版本

    Promise 僅適用於 Manifest V3 以上版本，其他平台則須使用回呼。

getConnections()

Promise 
chrome.serial.getConnections(
  callback?: function,
): Promise<ConnectionInfo[]>

擷取應用程式目前開啟的序列埠連線清單。

參數

傳回

  • Promise<ConnectionInfo[]>

    Chrome 117 以上版本

    Promise 僅適用於 Manifest V3 以上版本，其他平台則須使用回呼。

getControlSignals()

Promise 
chrome.serial.getControlSignals(
  connectionId: number,
  callback?: function,
): Promise<DeviceControlSignals>

擷取指定連線的控制信號狀態。

參數

傳回

  • Chrome 117 以上版本

    Promise 僅適用於 Manifest V3 以上版本，其他平台則須使用回呼。

getDevices()

Promise 
chrome.serial.getDevices(
  callback?: function,
): Promise<DeviceInfo[]>

傳回系統中可用序列裝置的相關資訊。每次呼叫這個方法時，系統都會重新產生清單。

參數

  • callback

    函式 選填

    callback 參數如下： 

    (ports: DeviceInfo[]) => void

傳回

  • Promise<DeviceInfo[]>

    Chrome 117 以上版本

    Promise 僅適用於 Manifest V3 以上版本，其他平台則須使用回呼。

getInfo()

Promise 
chrome.serial.getInfo(
  connectionId: number,
  callback?: function,
): Promise<ConnectionInfo>

擷取指定連線的狀態。

參數

  • connectionId

    數字

    已開啟連線的 ID。

  • callback

    函式 選填

    callback 參數如下： 

    (connectionInfo: ConnectionInfo) => void

傳回

  • Promise<ConnectionInfo>

    Chrome 117 以上版本

    Promise 僅適用於 Manifest V3 以上版本，其他平台則須使用回呼。

send()

Promise 
chrome.serial.send(
  connectionId: number,
  data: ArrayBuffer,
  callback?: function,
): Promise<SendInfo>

將資料寫入指定連線。

參數

  • connectionId

    數字

    連線 ID。

  • 資料

    ArrayBuffer

    要傳送的資料。

  • callback

    函式 選填

    callback 參數如下： 

    (sendInfo: SendInfo) => void

傳回

  • Promise<SendInfo>

    Chrome 117 以上版本

    Promise 僅適用於 Manifest V3 以上版本，其他平台則須使用回呼。

setBreak()

Promise Chrome 45 以上版本 
chrome.serial.setBreak(
  connectionId: number,
  callback?: function,
): Promise<boolean>

暫停指定連線上的字元傳輸，並將傳輸線置於中斷狀態，直到呼叫 clearBreak 為止。

參數

  • connectionId

    數字

    連線 ID。

  • callback

    函式 選填

    callback 參數如下： 

    (result: boolean) => void

    • 結果

      布林值

傳回

  • Promise<boolean>

    Chrome 117 以上版本

    Promise 僅適用於 Manifest V3 以上版本，其他平台則須使用回呼。

setControlSignals()

Promise 
chrome.serial.setControlSignals(
  connectionId: number,
  signals: HostControlSignals,
  callback?: function,
): Promise<boolean>

設定指定連線的控制信號狀態。

參數

  • connectionId

    數字

    連線 ID。

  • 要傳送至裝置的信號變更組合。

  • callback

    函式 選填

    callback 參數如下： 

    (result: boolean) => void

    • 結果

      布林值

傳回

  • Promise<boolean>

    Chrome 117 以上版本

    Promise 僅適用於 Manifest V3 以上版本，其他平台則須使用回呼。

setPaused()

Promise 
chrome.serial.setPaused(
  connectionId: number,
  paused: boolean,
  callback?: function,
): Promise<void>

暫停或取消暫停開啟的連線。

參數

  • connectionId

    數字

    已開啟連線的 ID。

  • 已暫停

    布林值

    用於指出是否要暫停或取消暫停的標記。

  • callback

    函式 選填

    callback 參數如下： 

    () => void

傳回

  • 承諾<void>

    Chrome 117 以上版本

    Promise 僅適用於 Manifest V3 以上版本，其他平台則須使用回呼。

update()

Promise 
chrome.serial.update(
  connectionId: number,
  options: ConnectionOptions,
  callback?: function,
): Promise<boolean>

更新開啟的序列埠連線選項設定。

參數

  • connectionId

    數字

    已開啟連線的 ID。

  • 通訊埠設定選項。

  • callback

    函式 選填

    callback 參數如下： 

    (result: boolean) => void

    • 結果

      布林值

傳回

  • Promise<boolean>

    Chrome 117 以上版本

    Promise 僅適用於 Manifest V3 以上版本，其他平台則須使用回呼。

事件

onReceive

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

從連線讀取資料時引發的事件。

參數

onReceiveError

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

執行階段等待序列埠資料時發生錯誤，就會引發這個事件。事件發生後，連線可能會設為 paused。"timeout" 錯誤不會暫停連線。

參數