文档›指南›Realtime and presence (SDK) 使用 JavaScript SDK 发送实时消息和状态
aura.realtime的日常流程，以及针对正在运行的堆栈观察到的每个调用的行为。
7分钟 读取·级别 中间·修改于 2026年10月12日
该英文文本是根据法文原文自动生成的，尚未经过审查。
自此翻译以来，英文来源已发生变化。某些信息可能已过时。
该页面已自动翻译。英文版具有权威性。
通道是一个已命名的房间。打开相同名称的客户端会收到彼此的消息。当您订阅时，客户端会自行连接。
channel.tstypescript
const room = aura.realtime.channel('room-1')
room.subscribe((status) => {
// “已订阅”| 'CHANNEL_ERROR'| '超时'| “关闭”
if (status === 'SUBSCRIBED') console.log('ready')
})
仅在 SUBSCRIBED之后发送。在此之前或拒绝之后，send() 返回诸如 not_connected 或 requires_subscription 之类的状态，而不是发送。频道的范围仅限于您的项目：两个项目可以使用相同的名称而不会互相看到。
broadcast.tstypescript
// 接收
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' } })
// →“好的”
在实际运行中，第二个登录的客户端在不到两秒的时间内收到了该消息。
有效负载携带 event 密钥
你收到的消息中，事件名会被添加到 payload：{ "event": "ping", "n": 1, … }。自带 event 键的 payload 会被拒绝（channel.send 返回 'invalid_payload'，httpBroadcast 返回 realtime_payload_event_reserved）：请重命名该键，例如 kind。
- 默认情况下您不会收到自己的消息。 使用
{ config: { broadcast: { self: true } } } 打开通道来接收它们。
- 消息携带
id、 topic、 timestamp、 event 和 payload。
状态显示谁连接到频道，以及您选择的状态。
presence.tstypescript
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 键入。每个条目都列出了用户的连接：
presenceState()json
{
"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/{project_id}/schema/tables/{table}/realtime，请求体为 {"enabled": true}，并使用 service_role 密钥。第一个客户端订阅时开始监听，最后一个客户端离开几分钟后停止。投递语义为至少一次：服务器重启后，同一变更可能到达两次，因此请让处理函数保持幂等，例如以行的主键为依据。繁忙的集群可能以容量错误拒绝新的监听；请稍后重试。 请按表命名频道，即 db:public.<table>：变更会发布到该频道。第一个订阅者可能会收到订阅前最多 5 秒内的变更。变更会保留一小时用于恢复，然后删除。集群已满时，订阅会以 capacité d'écoute postgres_changes atteinte pour la base de ce projet, réessayez 失败。如果监听中断超过一分钟，频道会进入 CHANNEL_ERROR；恢复后请重新订阅。中断时间超过一小时保留期时，期间的变更会丢失。
changes.tstypescript
const changes = aura.realtime
.channel('db:public.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')
})
cleanup.tstypescript
room.unsubscribe() // 留下一个频道
aura.realtime.removeChannel(room) // 离开并忘记它
aura.realtime.removeAllChannels() // 离开每个频道
aura.realtime.disconnect() // 关闭连接
观察与 aura.realtime.onStateChange(callback) 和 onError(callback)的连接。断开连接后，客户端会自行重新连接，除非您调用 setAutoReconnect(false)。
