CQWebSocket

• CQWebSocket
  • constructor
    • CQWebSocketOption
  • connect()
  • disconnect
  • reconnect
  • isSockConnected
  • isReady
  • on
  • once
  • off
  • API call
    • 範例

constructor

new CQWebSocket(opt)

• opt CQWebSocketOption

CQWebSocketOption

| 屬性 | 類型 | 默認值 | 說明 | - | - | - | - | | accessToken | string | "" | API 訪問 token 。見 CQHTTP API 之配置文件說明 | | enableAPI | boolean | true | 啟用 /api 連線 | | enableEvent | boolean | true | 啟用 /event 連線 | | protocol | string | "ws:" | 協議名 | | host | string | "127.0.0.1" | 酷Q伺服器 IP | | port | number | 6700 | 酷Q伺服器端口 | | baseUrl | string | 6700 | 酷Q伺服器位址 (SDK在建立連線時會依照此設定加上前綴項 ws:// 及後綴項 /<api|event>[?accessToken={token}]) | | qq | number | string | -1 | 觸發 @me 事件用的QQ帳號，通常同登入酷Q之帳號，用在討論組消息及群消息中辨認是否有人at此帳號 | | reconnection | boolean | true | 是否連線錯誤時自動重連 | | reconnectionAttempts | number | Infinity | 連續連線失敗的次數不超過這個值 | | reconnectionDelay | number | 1000 | 重複連線的延遲時間, 單位: ms | | fragmentOutgoingMessages | boolean | false | 由於 CQHTTP API 插件的 websocket 服務器尚未支持 fragment, 故建議維持 false 禁用 fragment。
※詳情請見 WebSocketClient 選項說明。 | | fragmentationThreshold | number | 0x4000 | 每個 frame 的最大容量, 默認為 16 KiB, 單位: byte
※詳情請見 WebSocketClient 選項說明。 | | tlsOptions | object | {} | 若需調用安全連線 https.request 時的選項 | | requestOptions | {
timeout: number
} | {} | 調用 API 方法時的全局默認選項。 |

connect()

bot.connect([socketType])

• socketType WebSocketType 未提供此項，則默認所有連線。
• 返回值： this
• 事件
  • ready 所有 socket 就緒。
  • socket.connecting 呼叫後立刻觸發，在任何連線嘗試之前。
  • socket.connect 連線成功。
  • socket.failed 連線失敗。
  • socket.error 連線失敗會一併觸發 error 事件。

disconnect

bot.disconnect([socketType])

• socketType WebSocketType 未提供此項，則默認所有連線。
• 返回值： this
• 事件
  • socket.closing 正在關閉連線。
  • socket.close 連線斷開後。

reconnect

bot.reconnect([delay[, socketType]])

• delay number 單位為 ms，表示socket.close事件觸發後的延遲時間, 延遲時間過後才會呼叫 connect()。
• socketType WebSocketType 未提供此項，則默認所有連線。
• 返回值： this
• 事件

  此方法會先呼叫 disconnect() 等待 socket.close 事件觸發後再呼叫 connect(), 可以參考以上兩個方法的事件。

isSockConnected

bot.isSockConnected(socketType)

• socketType WebSocketType
• 返回值： boolean

※若未給定 socketType，使用此方法會拋出錯誤。

isReady

bot.isReady()

• 返回值： boolean

檢查連線狀態是否就緒。

僅檢查已透過 enableAPI 及 enableEvent 啟用之連線。

on

bot.on(event, listener)

• event string
• listener EventListener
• 返回值： this

註冊常駐監聽器。

once

bot.once(event, listener)

• event string
• listener EventListener
• 返回值： this

註冊一次性監聽器。

off

bot.off([event[, listener]])

• event string
• listener EventListener
• 返回值： this

移除 event 事件中的 listener 監聽器。 若 event 不為字串，則移除所有監聽器。 若 listener 不為方法，則移除所有該事件的監聽器。

API call

bot(method[, params[, options]])

• method string 見 API 列表
• params object 見 API 列表

• options object

  number

  • timeout number (默認: Infinity)
• 返回值： Promise<ResObj>

返回值為一個 Promise 對象, 用作追蹤該次 API 調用的結果。

Promise 對象實現後第一個參數會拿到 ResObj 對象, 此為 CQHttp API 的回應對象。

若有配置 timeout 選項(原先默認為 Infinity, 不會對請求計時), 則發生超時之後, 將放棄收取本次調用的結果, 並拋出一個 ApiTimeoutError。

options 除了是一個對象外, 也可以直接給一個數值, 該數值會被直接當作 timeout 使用。

範例

bot('send_private_msg', {
  user_id: 123456789,
  message: 'Hello world!'
}, {
  timeout: 10000 // 10 sec
})
  .then((res) => {
    console.log(res)
    // {
    //   status: 'ok',
    //   retcode: 0,
    //   data: null
    // }
  })
  .catch((err) => {
    console.error('請求超時!')
  })