使用 JavaScript SDK 发送实时消息和状态
aura.realtime的日常流程,以及针对正在运行的堆栈观察到的每个调用的行为。
频道及其状态#
通道是一个已命名的房间。打开相同名称的客户端会收到彼此的消息。当您订阅时,客户端会自行连接。
const room = aura.realtime.channel('room-1')
room.subscribe((status) => {
// “已订阅”| 'CHANNEL_ERROR'| '超时'| “关闭”
if (status === 'SUBSCRIBED') console.log('ready')
})
仅在 SUBSCRIBED之后发送。在此之前或拒绝之后,send() 返回诸如 not_connected 或 requires_subscription 之类的状态,而不是发送。频道的范围仅限于您的项目:两个项目可以使用相同的名称而不会互相看到。
广播消息#
// 接收
room.on('broadcast', { event: 'ping' }, (message) => {
console.log(message.payload) // { 事件:'ping',n:1,文本:'你好'}
})
// 订阅后发送
const status = await room.send({ type: 'broadcast', event: 'ping', payload: { n: 1, text: 'hello' } })
// →“好的”
在实际运行中,第二个登录的客户端在不到两秒的时间内收到了该消息。
您收到的消息已将事件名称添加到 payload: { "event": "ping", "n": 1, … }。具有自己的 event 密钥的负载将被拒绝(channel.send 返回 'invalid_payload', httpBroadcast 返回 realtime_payload_event_reserved):重命名该密钥,例如 kind。
- 默认情况下您不会收到自己的消息。 使用
{ config: { broadcast: { self: true } } }打开通道来接收它们。 - 消息携带
id、topic、timestamp、event和payload。
存在感#
状态显示谁连接到频道,以及您选择的状态。
const lobby = aura.realtime.channel('lobby', { config: { presence: { key: user.id } } })
lobby.on('presence', { event: 'sync' }, () => {
console.log(lobby.presenceState())
})
lobby.subscribe(async (status) => {
if (status === 'SUBSCRIBED') await lobby.track({ name: 'Bob' })
})
presenceState() 由用户 ID 键入。每个条目都列出了用户的连接:
{
"d6ba3994-…": [
{ "client_id": "936cb015-…", "user_id": "d6ba3994-…", "metadata": { "name": "Bob" },
"joined_at": "2026-10-12T19:32:19.093Z", "last_seen": "2026-10-12T19:32:19.096Z" }
]
}
untrack() 将您从列表中删除,离开频道或关闭页面会为您完成此操作。
数据库变更#
postgres_changes 使用自己的数据库处理项目。首先启用每个表: PUT /v1/db/schema/tables/{table}/realtime (或 aura db table realtime <table> on),其主体为 {"enabled": true} 和 service_role 键。当第一个客户订阅时开始监听,并在最后一个客户离开后几分钟停止。传递至少一次:服务器重新启动后,更改可能会到达两次,因此使您的处理程序具有幂等性,例如通过键入行的主键。繁忙的集群可能会因容量错误而拒绝新的侦听器;稍后重试。任何通道名称都可以:每个过滤器的 table 选择要监听的表,一个通道可以监听多个表。在未命名为 db:<schema>.<table>的通道上,每个过滤器都需要一个 table。第一个订阅者可以接收最多 5 秒的订阅前所做的更改。更改将保留一小时以供恢复,然后删除。当集群已满时,订阅失败并显示 capacité d'écoute postgres_changes atteinte pour la base de ce projet, réessayez。如果收听持续时间超过一分钟,频道将移至 CHANNEL_ERROR,然后在恢复收听后返回 SUBSCRIBED ;您无需再次订阅。如果中断超过一小时的保留时间,通道还会收到 CHANNEL_ERROR 和 changements postgres_changes perdus pendant l'interruption, resynchronisez:从数据库重新加载数据。更改每次交付时都会保持相同的 id,因此您也可以跳过已处理的 id。删除的行不再存在,因此无法对其评估行级安全性。因此,在具有行级安全性的表上, DELETE 仅传递给角色在表上具有 SELECT 策略的订阅者(或绕过 RLS,如 service_role):没有读取策略的访问者 (anon) 不会收到它。在没有行级安全性的表上,每个订阅者都会收到它。 DELETE 的 payload.old 仅保留主键列(如果表没有主键则不保留任何内容),任何其他列上的过滤器都不会匹配删除。对于 UPDATE, payload.old 还只保存前一行的主键列(如果键更改,则为它们之前的值),而不保存其他值:仅在新行上检查行级安全性。 UPDATE 的过滤器适用于新行。让敏感信息远离主键。
const changes = aura.realtime
.channel('todos')
.on('postgres_changes', { event: '*', schema: 'public', table: 'todos' }, (payload) => {
console.log(payload.eventType, payload.new)
})
.subscribe((status) => {
if (status === 'CHANNEL_ERROR') console.warn('database changes are not available for this project')
})
清理#
room.unsubscribe() // 留下一个频道
aura.realtime.removeChannel(room) // 离开并忘记它
aura.realtime.removeAllChannels() // 离开每个频道
aura.realtime.disconnect() // 关闭连接
观察与 aura.realtime.onStateChange(callback) 和 onError(callback)的连接。断开连接后,客户端会自行重新连接,除非您调用 setAutoReconnect(false)。