phoenix 1.7.14 | 文件繁體中文

phoenix

1.7.14

phoenix
頻道 ▸
- 執行個體成員
- #join
- #onClose
- #onError
- #on
- #off
- #push
- #leave
- #onMessage
推播 ▸
- 執行個體成員
- #resend
- #send
- #receive
計時器 ▸
- 執行個體成員
- #scheduleTimeout
在場 ▸
- 靜態成員
- .syncState
- .syncDiff
- .list
Socket ▸
- 執行個體成員
- #getLongPollTransport
- #replaceTransport
- #protocol
- #endPointURL
- #disconnect
- #connect
- #log
- #hasLogger
- #onOpen
- #onClose
- #onError
- #onMessage
- #ping
- #connectionState
- #isConnected
- #off
- #channel
- #push
- #makeRef

需要協助閱讀此內容嗎？

phoenix

Phoenix Channels JavaScript 程式用戶端

Socket 連線

與伺服器建立單一連線，並在連線中多工頻道。使用 Socket 類別連線至伺服器

Socket 建構函式採用 socket 的載入點、驗證參數，以及可以在 Socket 文件中找到的選項，例如設定 LongPoll** 運輸和心跳。**

頻道

頻道是伺服器上獨立的並行處理程序，訂閱主題並在用戶端和伺服器之間仲介事件。若要加入頻道，您必須提供同意權的主題和頻道參數。以下是一個聊天室範例，針對其中的"new_msg"事件進行監聽、將訊息推播到伺服器，且以 ok/error/timeout 比對加入頻道

加入

使用 socket.channel(topic, params) 建立頻道會將參數繫結到 channel.params，這些參數會在 channel.join() 上傳送。後續的重新加入會傳送修改的參數，以更新同意權參數或傳送最後_訊息_編號資訊。成功的加入會接收到「ok」狀態，而不成功的加入會接收到「error」。

在預設的序列化和 WebSocket 運輸中，JSON 文字架構是用於推播 JSON 物件文字。如果提供 ArrayBuffer 執行個體，將會使用二進位編碼，且訊息會以二進位 opcode 傳送。

請注意：僅 WebSocket 運輸支援二進位訊息。

重複加入訂閱

在用戶端可在任何數量的頻道上加入任何數量的主題時，用戶端在任何特定時間只能擁有每個唯一主題的單一訂閱。當嘗試建立重複訂閱時，伺服器會關閉現有頻道、記錄警告，並為該主題產生新的頻道。用戶端會針對現有頻道啟動其 channel.onClose 回呼，而新的頻道加入會以正常方式處理其接收掛鉤。

推播訊息

從之前的範例中，我們可以看到可以透過 channel.push(eventName, payload) 將訊息推送到伺服器，我們也可以選擇性地從推播中接收回應。此外，我們可以使用 receive("timeout", 回撥函式) 中止等待其他 receive 鉤子，並在等待一段時間後採取行動。預設逾時時間為 10000 毫秒。

Socket 鉤子

多路復用連線的生命週期事件可以透過 socket.onError() 和 socket.onClose() 事件來串接，例如

頻道鉤子

對於每個加入的頻道，您可以繫結到 onError 和 onClose 事件來監控頻道生命週期，例如

onError 鉤子

如果 Socket 連線中斷，或頻道在伺服器上崩潰，會呼叫 onError 鉤子。在這兩種情況下，都會嘗試以指數退讓的方式自動重新加入頻道。

onClose 鉤子

僅在兩種情況下呼叫 onClose 鉤子。1) 在伺服器上明確關閉頻道，或 2) 客戶端明確關閉，透過呼叫 channel.leave()

顯示狀態

顯示狀態 物件提供功能，讓伺服器與客戶端同步顯示狀態資訊，並處理顯示狀態加入和離開。

從伺服器同步狀態

若要從伺服器同步顯示狀態，請先建立一個物件，並傳入您的頻道，以追蹤生命週期事件

接下來，使用 presence.onSync 回撥函式回應伺服器的狀態變更。例如，若要在清單中的使用者變更時重新整理名單，您可以撰寫

顯示狀態清單

presence.list 用於根據資料的本地化狀態，傳回顯示狀態資訊的清單。預設情況下，會傳回所有顯示狀態資料，但可以提供 listBy 函式，讓客戶端選擇要為特定顯示狀態使用的資料。例如，您可能在不同裝置上以「線上」的資料狀態顯示使用者的線上狀態，但他們在另一個裝置上已將自己設為「離開」。在此情況下，應用程式可能會選擇使用「離開」狀態顯示在 UI 上。以下範例定義一個 listBy 函式，此函式會優先處理為每個使用者註冊的第一個資料。這可能是他們開啟的第一個分頁，或他們從那裡上線的第一個裝置

處理個人顯示狀態加入和離開事件

presence.onJoin 和 presence.onLeave 回撥函式可用於回應加入和離開應用程式的個別顯示狀態。例如

phoenix

頻道

new Channel(主題: 字串, 參數: (物件 | 函式), socket: Socket)

參數

主題 (字串)

params ((物件 | 函式))

socket (Socket)

執行個體成員

▸ join(timeout)

加入頻道

join(timeout: 整數): Push

參數

timeout (整數 = this.timeout)

傳回

Push:

▸ onClose(callback)

掛勾於頻道關閉

onClose(callback: 函式)

參數

callback (函式)

▸ onError(callback)

掛勾於頻道錯誤

onError(callback: 函式)

參數

callback (函式)

▸ on(event, callback)

訂閱頻道事件

訂閱傳回參考計數器，其可在稍後用於取消訂閱特定事件監聽器

on(event: 字串, callback: 函式): 整數

參數

event (字串)

callback (函式)

傳回

整數: ref

範例

const ref1 = channel.on("event", do_stuff)
const ref2 = channel.on("event", do_other_stuff)
channel.off("event", ref1)
// Since unsubscription, do_stuff won't fire,
// while do_other_stuff will keep firing on the "event"

▸ off(event, ref)

取消訂閱離線頻道事件

使用從 channel.on() 傳回的 ref 取消訂閱一個處理常式，或不傳入任何 ref 來取消訂閱給定事件的所有處理常式。

off(event: 字串, ref: 整數)

參數

event (字串)

ref (整數)

範例

// Unsubscribe the do_stuff handler
const ref1 = channel.on("event", do_stuff)
channel.off("event", ref1)

// Unsubscribe all handlers from event
channel.off("event")

▸ push(event, payload, timeout = this.timeout)

使用有效負載 payload 將訊息 event 傳送至 Phoenix。Phoenix 在 handle_in(event, payload, socket) 函式中收到此訊息。若 Phoenix 回覆或逾時 (預設為 10000 毫秒)，則可選擇接收回覆。

push(event: 字串, payload: 物件, timeout: 數字?): Push

參數

event (字串)

payload (物件)

timeout (數字? = this.timeout)

傳回

Push:

範例

channel.push("event")
  .receive("ok", payload => console.log("phoenix replied:", payload))
  .receive("error", err => console.log("phoenix errored", err))
  .receive("timeout", () => console.log("timed out pushing"))

▸ leave(timeout)

離開頻道

取消訂閱伺服器事件，並指示頻道在伺服器中終止

觸發 onClose() 鉤子函數

若要接收離開確認，請使用 receive 鉤子函數繫結到伺服器 ack，例如

leave(timeout: integer): 推播

參數

timeout (整數 = this.timeout)

傳回

Push:

範例

channel.leave().receive("ok", () => alert("left!") )

▸ onMessage(_event, payload, _ref, event, ref)

可覆寫訊息鉤子函數

在派送至頻道回呼函數之前，接收所有事件以進行特殊訊息處理。

必須傳回有效負載（經修改或未經修改）

onMessage(_event: any, payload: Object, _ref: any, event: string, ref: integer): Object

參數

_event (any)

payload (物件)

_ref (any)

event (字串)

ref (整數)

傳回

物件:

Push

初始化推播

new Push(channel: 頻道, event: string, payload: Object, timeout: number)

參數

channel (頻道) 頻道

event (string) 事件，例如 "phx_join"

payload (Object) 有效負載，例如 {user_id: 123}

timeout (number) 以毫秒為單位的推播逾時時間

執行個體成員

▸ resend(timeout)

resend(timeout: number)

參數

timeout (number)

▸ send()

send()

▸ receive(status, callback)

receive(status: any, callback: any)

參數

status (any)

callback (any)

計時器

建立一個計時器，接受 timerCalc 函數以執行計算逾時重試，例如指數遞增退避。

new Timer(callback: 函式, timerCalc: 函式)

參數

callback (函式)

timerCalc (函數)

範例

let reconnectTimer = new Timer(() => this.connect(), function(tries){
  return [1000, 5000, 10000][tries - 1] || 10000
})
reconnectTimer.scheduleTimeout() // fires after 1000
reconnectTimer.scheduleTimeout() // fires after 5000
reconnectTimer.reset()
reconnectTimer.scheduleTimeout() // fires after 1000

執行個體成員

▸ scheduleTimeout()

取消任何先前的 scheduleTimeout 並排程回呼

scheduleTimeout()

顯示狀態

初始化 Presence

new Presence(channel: Channel, opts: 物件)

參數

channel (頻道) 頻道

opts (物件 = {}) 選項，範例為 {events: {state: "state", diff: "diff"}}

靜態成員

▸ syncState(currentState, newState, onJoin, onLeave)

用於將伺服器的 presence 清單與客戶端狀態同步。可以提供一個選用的 onJoin 和 onLeave 回乎，用於回應客戶端與伺服器斷線和重新連線後的本地 presence 的變更。

syncState(currentState: any, newState: any, onJoin: any, onLeave: any): Presence

參數

currentState (any)

newState (any)

onJoin (any)

onLeave (any)

傳回

顯示狀態:

▸ syncDiff(state, diff, onJoin, onLeave)

用於同步伺服器中發生 presence 加入和離開事件的 diff。如同 syncState，syncDiff 會接受選用的 onJoin 和 onLeave 回乎，用於回應使用者從裝置中加入或離開。

syncDiff(state: any, diff: any, onJoin: any, onLeave: any): Presence

參數

state (any)

diff (any)

onJoin (any)

onLeave (any)

傳回

顯示狀態:

▸ list(presences, chooser)

傳回包含選取的元資料的 presence 陣列。

list(presences: 物件, chooser: 函數): Presence

參數

presences (物件)

chooser (函數)

傳回

顯示狀態:

Socket

初始化 Socket *

若要支援 IE8，請使用 ES5-shim (https://github.com/es-shims/es5-shim)

new Socket(endPoint: 字串, opts: 物件?)

參數

endPoint (字串) WebSocket 端點字串，例如 "ws://example.com/socket" 、 "wss://example.com" 或 "/socket" (繼承主機端與通訊協定)

選項 (物件? = {}) 可選設定

名稱	說明
選項.傳輸協定 `函式?`	Websocket 傳輸協定，例如 WebSocket 或 Phoenix.LongPoll。預設為 WebSocket，如果未定義 WebSocket 則自動遞減為 LongPoll。如需在進行 WebSocket 嘗試失敗時遞減為 LongPoll，請使用 `longPollFallbackMs: 2500`。
選項.遞減到長輪詢的毫秒數 `函式?`	在遞減到 LongPoll 傳輸協定之前嘗試主要傳輸協定的毫秒時間。預設停用。
選項.偵錯 `函式?`	如為 true，則啟用偵錯紀錄。預設為 false。
選項.編碼 `函式?`	對傳出的訊息進行編碼的函式。預設為 JSON 編碼器。
選項.解碼 `函式?`	對傳入的訊息進行解碼的函式。預設為 JSON
選項.逾時 `數字?`	觸發推播逾時的預設逾時（毫秒）。預設為 `DEFAULT_TIMEOUT`
選項.心跳間隔毫秒數 `數字?`	傳送心跳訊息的毫秒間隔
選項.重新連線後毫秒數 `數字?`	傳回毫秒 socket 重新連線間隔的選用函式。預設為逐次後退
選項.重新加入後毫秒數 `數字?`	傳回針對各頻道毫秒重新加入的選用函式。
選項.記錄器 `函式?`	專用紀錄的選用函式，例如
選項.長輪詢逾時 `數字?`	長輪詢 AJAX 要求的最長逾時時間。預設為 20 秒（伺服器長輪詢計時器的兩倍）。
選項.參數 `(物件 \| 函式)？`	連線時要傳遞的選用參數
選項.二進位類型 `字串?`	用於二進制 WebSocket 框架的二進制類型。預設為「arraybuffer」
opts.vsn `vsn?`	要於連線時傳送的序列化器通訊協定版本。預設為 DEFAULT_VSN。
opts.sessionStorage `物件?`	Phoenix 用於長期輪詢備援記錄選用的儲存物件相容性，覆寫儲存時有用，當 Phoenix 存取不到 `sessionStorage` 時。舉例來說，如果網站載入跨網域頻道至 iframe 框架中時就會發生這種情況。範例用法 `class InMemoryStorage { constructor() { this.storage = {} } getItem(keyName) { return this.storage[keyName] \|\| null } removeItem(keyName) { delete this.storage[keyName] } setItem(keyName, keyValue) { this.storage[keyName] = keyValue } }`

執行個體成員

▸ getLongPollTransport()

傳回 LongPoll 傳輸參考

getLongPollTransport()

▸ replaceTransport(newTransport)

中斷連線並取代作用中傳輸

replaceTransport(newTransport: 函式)

參數

newTransport (函式) 要執行個體化處理的新傳輸類別

▸ protocol()

傳回 socket 通訊協定

protocol(): 字串

傳回

字串:

▸ endPointURL()

完整的 socket url

endPointURL(): 字串

傳回

字串:

▸ disconnect(callback, code, reason)

中斷 socket 連線

更多有效的狀態碼，請參閱 https://developer.mozilla.org/en-US/docs/Web/API/CloseEvent#Status_codes。

disconnect(callback: 函式, code: 整數, reason: 字串)

參數

callback (函式) 在 socket 中斷後呼叫的選用回呼處理常式。

code (整數) 中斷連線的狀態碼 (選用)。

reason (字串) 中斷連線的文字描述。 (選用)

▸ connect(params)

connect(params: 物件)

參數

params (物件) 連線時要傳送的參數，例如 {user_id: userToken}

傳遞參數到連線已不建議使用；請改在 Socket 建構函式中傳遞這些參數：new Socket("/socket", {params: {user_id: userToken}})。

▸ log(kind, msg, data)

記錄訊息。覆寫 this.logger 以設定特定的記錄行為。預設為不執行任何操作。

log(kind: 字串, msg: 字串, data: 物件)

參數

kind (字串)

msg (字串)

data (物件)

▸ hasLogger()

如果已設定一個記錄器在此 Socket 上，則回傳 true。

hasLogger()

▸ onOpen(callback)

註冊連線開啟事件的回呼函式

onOpen(callback: 函式)

參數

callback (函式)

範例

socket.onOpen(function(){ console.info("the socket was opened") })

▸ onClose(callback)

註冊連線關閉事件的回呼函式

onClose(callback: 函式)

參數

callback (函式)

▸ onError(callback)

註冊連線錯誤事件的回呼函式

onError(callback: 函式)

參數

callback (函式)

範例

socket.onError(function(error){ alert("An error occurred") })

▸ onMessage(callback)

註冊連線訊息事件的回呼函式

onMessage(callback: 函式)

參數

callback (函式)

▸ ping(callback)

向伺服器發送 ping，並以毫秒為單位呼叫回呼函式傳回 RTT

ping(callback: 函式)

參數

callback (函式) 如果 ping 已發送，則回傳 true；如果無法發送，則回傳 false。

▸ connectionState()

connectionState(): 字串

傳回

字串:

▸ isConnected()

isConnected(): 布林值

傳回

布林值:

▸ off(refs, null-null)

移除 onOpen、onClose、onError和onMessage 註冊。

off(refs: any, null-null: refs)

參數

refs (any)

null-null (refs) onOpen、onClose、onError和onMessage 呼叫所傳回的 refs 清單

▸ channel(topic, chanParams)

啟動指定主題的新頻道

頻道（主題：字串，頻道參數：物件）：頻道

參數

主題 (字串)

頻道參數 (物件 = {}) 頻道的參數

傳回

頻道:

▸ push(資料)

push(資料：物件)

參數

data (物件)

▸ makeRef()

傳回下一則訊息參照，計算溢位

makeRef()：字串

傳回

字串: