phoenix 1.7.14 | 文档中文

phoenix

1.7.14

phoenix
通道 ▸
- 实例成员
- #join
- #onClose
- #onError
- #on
- #off
- #push
- #leave
- #onMessage
推送 ▸
- 实例成员
- #resend
- #send
- #receive
计时器 ▸
- 实例成员
- #scheduleTimeout
状态 ▸
- 静态成员
- .syncState
- .syncDiff
- .list
套接字 ▸
- 实例成员
- #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 文档中找到的选项，例如配置 LongPoll 传输和心跳。

通道

通道是服务器上独立的并发进程，它们订阅主题并在客户端和服务器之间代理事件。要加入通道，您必须提供主题和用于授权的通道参数。以下是一个聊天室示例，其中监听 "new_msg" 事件，将消息推送到服务器，并使用 ok/error/timeout 匹配加入通道

加入

使用 socket.channel(topic, params) 创建一个通道，将参数绑定到 channel.params，这些参数在 channel.join() 上发送。后续重新加入将发送修改后的参数以更新授权参数，或传递上上次消息 ID 信息。成功加入会收到“ok”状态，而失败加入会收到“error”。

使用默认序列化器和 WebSocket 传输，JSON 文本帧用于推送 JSON 对象文字。如果提供 ArrayBuffer 实例，将使用二进制编码，并且消息将使用二进制操作码发送。

注意：二进制消息仅在 WebSocket 传输上受支持。

重复加入订阅

虽然客户端可以在任意数量的通道上加入任意数量的主题，但客户端在任何给定时间只能对每个唯一主题拥有单个订阅。当尝试创建重复订阅时，服务器将关闭现有通道，记录警告，并为该主题生成一个新通道。客户端将收到其现有通道的 channel.onClose 回调，并且新通道加入将按正常方式处理其接收钩子。

推送消息

从前面的示例中我们可以看到，将消息推送到服务器可以通过 channel.push(eventName, payload) 完成，我们可以选择接收来自推送的响应。此外，我们可以使用 receive("timeout", callback) 来中止等待我们的其他 receive 钩子，并在等待一段时间后采取行动。默认超时时间为 10000 毫秒。

套接字钩子

可以通过 socket.onError() 和 socket.onClose() 事件来钩入多路复用连接的生命周期事件，例如

通道钩子

对于每个加入的通道，您可以绑定到 onError 和 onClose 事件以监视通道生命周期，例如

onError 钩子

如果套接字连接断开或通道在服务器上崩溃，将调用 onError 钩子。在这两种情况下，都将以指数回退方式自动尝试重新加入通道。

onClose 钩子

onClose 钩子仅在两种情况下调用。1) 通道在服务器上显式关闭，或 2) 客户端显式关闭，通过调用 channel.leave()

状态

Presence 对象提供了用于将服务器上的状态信息与客户端同步以及处理状态加入和离开的功能。

从服务器同步状态

要从服务器同步状态信息，首先实例化一个对象并将您的通道传递进去以跟踪生命周期事件

接下来，使用 presence.onSync 回调对来自服务器的状态更改做出反应。例如，要在每次列表更改时呈现用户列表，您可以编写

列出状态

presence.list 用于根据本地状态的元数据返回状态信息列表。默认情况下，将返回所有状态元数据，但可以提供 listBy 函数以允许客户端为给定状态选择要使用的元数据。例如，用户可能从不同的设备在线，元数据状态为“online”，但他们在另一台设备上将自己设置为“away”。在这种情况下，应用程序可以选择使用“away”状态来显示在 UI 上。以下示例定义了一个 listBy 函数，该函数优先考虑为每个用户注册的第一个元数据。这可能是他们打开的第一个选项卡，或者他们首次上线的第一个设备

处理单个状态加入和离开事件

可以使用 presence.onJoin 和 presence.onLeave 回调对单个状态加入和离开应用程序做出反应。例如

phoenix

通道

new Channel(topic: string, params: (Object | function), socket: Socket)

参数

topic (string)

params ((Object | function))

socket (Socket)

实例成员

▸ join(timeout)

加入通道

join(timeout: integer): Push

参数

timeout (integer = this.timeout)

返回值

Push:

▸ onClose(callback)

钩入通道关闭

onClose(callback: Function)

参数

callback (Function)

▸ onError(callback)

钩入通道错误

onError(callback: Function)

参数

callback (Function)

▸ on(event, callback)

订阅通道事件

订阅返回一个引用计数器，稍后可以使用该计数器取消订阅确切的事件侦听器

on(event: string, callback: Function): integer

参数

event (string)

callback (Function)

返回值

integer: 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: string, ref: integer)

参数

event (string)

ref (integer)

示例

// 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)

将消息 event 发送到 phoenix，并带有有效载荷 payload。Phoenix 在 handle_in(event, payload, socket) 函数中接收此消息。如果 phoenix 回复或超时（默认 10000 毫秒），则可以选择接收回复。

push(event: string, payload: Object, timeout: number?): Push

参数

event (string)

payload (Object)

timeout (number? = 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 钩子绑定到服务器确认，例如

leave(timeout: integer): Push

参数

timeout (integer = 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 (Object)

_ref (any)

event (string)

ref (integer)

返回值

Object:

Push

初始化 Push

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

参数

channel (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: Function, timerCalc: Function)

参数

callback (Function)

timerCalc (Function)

示例

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: Object)

参数

channel (Channel) 通道

opts (Object = {}) 选项，例如 {events: {state: "state", diff: "diff"}}

静态成员

▸ syncState(currentState, newState, onJoin, onLeave)

用于将服务器上的存在列表与客户端的状态同步。可以提供可选的 onJoin 和 onLeave 回调，以对客户端本地存在跨断开连接和与服务器重新连接时的更改做出反应。

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

参数

currentState (any)

newState (any)

onJoin (any)

onLeave (any)

返回值

状态:

▸ syncDiff(state, diff, onJoin, onLeave)

用于同步来自服务器的存在加入和离开事件的差异，这些事件会发生。与 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)

返回存在数组，其中包含选定的元数据。

list(presences: Object, chooser: Function): Presence

参数

presences (Object)

chooser (Function)

返回值

状态:

套接字

初始化套接字*

对于 IE8 支持，请使用 ES5-shim (https://github.com/es-shims/es5-shim)

new Socket(endPoint: string, opts: Object?)

参数

endPoint (string) WebSocket 端点字符串，例如 "ws://example.com/socket" , "wss://example.com" "/socket" （继承主机和协议）

opts (Object? = {}) 可选配置

名称	描述
opts.transport `Function?`	WebSocket 传输，例如 WebSocket 或 Phoenix.LongPoll。默认情况下为 WebSocket，如果未定义 WebSocket，则自动回退到 LongPoll。要使 WebSocket 尝试失败时回退到 LongPoll，请使用 `longPollFallbackMs: 2500`。
opts.longPollFallbackMs `Function?`	尝试主要传输之前回退到 LongPoll 传输的毫秒时间。默认情况下禁用。
opts.debug `Function?`	如果为 true，则启用调试日志记录。默认值为 false。
opts.encode `Function?`	用于编码传出消息的函数。默认情况下为 JSON 编码器。
opts.decode `Function?`	用于解码传入消息的函数。默认情况下为 JSON
opts.timeout `number?`	触发推送超时事件的默认超时时间（以毫秒为单位）。默认值为 `DEFAULT_TIMEOUT`
opts.heartbeatIntervalMs `number?`	发送心跳消息的毫秒间隔
opts.reconnectAfterMs `number?`	返回套接字重新连接间隔（以毫秒为单位）的可选函数。默认情况下为逐步回退
opts.rejoinAfterMs `number?`	返回单个通道的重新加入间隔（以毫秒为单位）的可选函数。
opts.logger `Function?`	用于专门日志记录的可选函数，例如
opts.longpollerTimeout `number?`	长轮询 AJAX 请求的最大超时时间。默认值为 20 秒（服务器长轮询计时器的两倍）。
opts.params `(Object \| function)?`	连接时要传递的可选参数
opts.binaryType `string?`	用于二进制 WebSocket 帧的二进制类型。默认值为 "arraybuffer"
opts.vsn `vsn?`	连接时要发送的序列化程序协议版本。默认值为 DEFAULT_VSN。
opts.sessionStorage `Object?`	Phoenix 使用 sessionStorage 作为长轮询回退历史记录的可选兼容 Storage 对象。当 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: Function)

参数

newTransport (Function) 要实例化的新的传输类

▸ protocol()

返回套接字协议

protocol(): string

返回值

字符串:

▸ endPointURL()

完全限定的套接字 URL

endPointURL(): string

返回值

字符串:

▸ disconnect(callback, code, reason)

断开套接字连接

有关有效状态码，请参见 https://mdn.org.cn/en-US/docs/Web/API/CloseEvent#Status_codes。

disconnect(callback: Function, code: integer, reason: string)

参数

callback (Function) 套接字断开连接后调用的可选回调。

code (integer) 断开连接的状态码（可选）。

reason (string) 断开连接原因的文本描述。（可选）

▸ connect(params)

connect(params: Object)

参数

params (Object) 连接时要发送的参数，例如 {user_id: userToken}

传递参数以连接已弃用；请改为在 Socket 构造函数中传递它们：new Socket("/socket", {params: {user_id: userToken}})。

▸ log(kind, msg, data)

记录消息。覆盖 this.logger 以进行专门的日志记录。默认情况下为 noops

log(kind: string, msg: string, data: Object)

参数

kind (string)

msg (string)

data (Object)

▸ hasLogger()

如果在此套接字上设置了记录器，则返回 true。

hasLogger()

▸ onOpen(callback)

注册连接打开事件的回调

onOpen(callback: Function)

参数

callback (Function)

示例

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

▸ onClose(callback)

注册连接关闭事件的回调

onClose(callback: Function)

参数

callback (Function)

▸ onError(callback)

注册连接错误事件的回调

onError(callback: Function)

参数

callback (Function)

示例

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

▸ onMessage(callback)

注册连接消息事件的回调

onMessage(callback: Function)

参数

callback (Function)

▸ ping(callback)

ping 服务器并使用毫秒为单位的 RTT 调用回调

ping(callback: Function)

参数

callback (Function) 如果 ping 已推送，则返回 true，否则如果无法推送，则返回 false。

▸ connectionState()

connectionState(): string

返回值

字符串:

▸ isConnected()

isConnected(): boolean

返回值

布尔值:

▸ off(refs, null-null)

删除 onOpen、onClose、onError 和 onMessage 注册。

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

参数

refs (any)

null-null (refs) onOpen、onClose、onError 和 onMessage 调用的返回值列表

▸ channel(topic, chanParams)

为给定主题启动一个新的通道

channel(topic: string, chanParams: Object): Channel

参数

topic (string)

chanParams (Object = {}) 通道的参数

返回值

通道:

▸ push(data)

push(data: 对象)

参数

data (Object)

▸ makeRef()

返回下一个消息引用，考虑溢出

makeRef(): 字符串

返回值

字符串: