agentbase-docs

实时订阅

这是什么 / 何时用

Realtime 通过 WebSocket 把项目内的数据变更推送到浏览器:订阅某一行、某张表全部行、文件变化或账号事件,收到事件后即时刷新 UI(如看板、协作列表、上传进度)。客户端 SDK 建立 WebSocket 连接并按通道(channel)分发事件;服务端/Console 场景由 Console SDK 的 realtime 包装提供。

前置

使用骨架

关键参数与返回

错误与边界

SDK 类别差异

各语言调用示例

以下按使用骨架逐项给出各语言调用示例;每个卡片可切换语言(全页同步)。

订阅通道与事件处理

从 Channel 构造通道——行通道 .row('<rowId>') 为单行、省略行 ID 即订阅该表全部行,另有文件 Channel.files() 与账号 Channel.account();subscribe 接受单个通道或通道数组,回调里按 event.type / event.data 处理 create / update / delete 等负载。(仅 Web 客户端面:Server SDK 无 Realtime 服务、REST 无实时端点,均无页签。)

import { Realtime, Channel } from 'agentbase-web-sdk';   // 前提:用户已登录,client 已初始化

const realtime = new Realtime(client);
const sub = await realtime.subscribe(
    [
        Channel.tablesdb('app-db').table('tasks').row(),   // 全部行;.row('<rowId>') 为单行
        Channel.files(),                                   // 文件变化
        Channel.account()                                  // 当前账号事件
    ],
    (event) => {
        console.log(event.type, event.data);               // create / update / delete 等负载
    }
);

查询过滤

行通道支持 queries 过滤(Query 字符串数组),仅接收匹配条件的行事件;过滤条件用订阅对象的 update 原地设置,无需重连。(仅 Web 客户端面。)

import { Query } from 'agentbase-web-sdk';

await sub.update({
    queries: [Query.equal('status', 'open')]   // 仅推送 status=open 的行事件
});

拆卸与关闭

单订阅用 unsubscribe() 拆卸(连接保留给其他订阅);完全关闭用 Realtime.disconnect()。close() 是兼容别名:等价 unsubscribe,且在最后一个订阅拆卸时自动断连。(仅 Web 客户端面。)

await sub.unsubscribe();   // 拆卸单个订阅(保留连接给其他订阅)
Realtime.disconnect();     // 关闭整个连接
// sub.close() 为兼容别名:unsubscribe + 最后一个订阅时自动断连

动态调整

update({ channels, queries }) 在不重建 WebSocket 的情况下替换通道与过滤条件(服务端原地更新)。(仅 Web 客户端面。)

await sub.update({
    channels: [Channel.tablesdb('app-db').table('tasks').row()],   // 换通道(如改为全表行)
    queries: [Query.equal('status', 'done')]                       // 同时换过滤
});

示例指引

事实源