组件：SSE

SSE（Server-Sent Events）客户端组件是一个不可视组件，用于接收服务器通过 HTTP 协议推送的实时事件流。与 WebSocket 不同，SSE 是单向通信（仅服务器推送到客户端），基于标准 HTTP 协议，支持自动重连和事件 ID 追踪。适用于实时通知、数据更新、状态监控、消息推送等场景。

典型使用场景：

  • 实时通知（系统公告、消息提醒）
  • 数据更新（股票行情、体育比分、天气变化）
  • 状态监控（服务器状态、任务进度）
  • 新闻/资讯实时推送
  • 日志流或操作日志实时输出

快速索引

你想知道什么直接看这里
如何连接 SSE 服务器连接(地址)
如何关闭连接关闭()
如何获取连接状态取连接状态()
如何重新连接重新连接(地址)
如何接收服务器消息置收到消息回调(回调函数)
如何监听连接打开置连接被打开回调(回调函数)
如何监听错误置发生错误回调(回调函数)
连接状态码含义见下方“连接状态详解”

基础示例

最简单的 SSE 使用流程：连接服务器 → 接收消息 → 处理消息 → 关闭连接。

变量 sse = 创建 SSE()

' 1. 设置事件回调（需在连接前设置）
sse.置连接被打开回调((事件源) => {
    调试输出("SSE 连接已打开")
})

sse.置收到消息回调((事件源) => {
    调试输出("收到消息：" + 事件源.data)
})

sse.置发生错误回调((事件源) => {
    调试输出("SSE 错误：" + 事件源.message)
})

' 2. 发起连接
sse.连接("https://api.example.com/events")

' 3. 后续操作（例如在延时后关闭）
延时执行(() => {
    sse.关闭()
   调试输出("SSE 连接已关闭")
}, 30000)

综合示例：实时通知系统

本示例模拟一个实时通知系统，连接服务器后持续接收通知消息，并根据不同事件类型执行相应操作。

' ========== 创建 SSE 客户端 ==========
变量 sse = 创建 SSE()

' ========== 设置事件回调 ==========
' 连接打开
sse.置连接被打开回调((事件源) => {
    调试输出("✅ SSE 连接已打开")
    弹出提示("已连接到通知服务器")
})

' 收到消息
sse.置收到消息回调((事件源) => {
    变量 数据 = 事件源.data
    变量 事件类型 = 事件源.type  ' 事件类型（如 message, ping, update 等）
    调试输出("📨 收到事件：" + 事件类型 + "，数据：" + 数据)

    ' 根据事件类型处理不同逻辑
    判断(事件类型)
        分支 "notification"
            ' 处理普通通知
            显示通知(数据)
        分支 "alert"
            ' 处理紧急告警
            显示告警(数据)
        分支 "ping"
            ' 心跳消息，无需处理
        分支 默认
            调试输出("未知事件类型：" + 事件类型)
    结束 判断
})

' 发生错误
sse.置发生错误回调((事件源) => {
    调试输出("❌ SSE 发生错误：" + 事件源.message)
    弹出提示("连接出错，请检查网络或服务器状态")
})

' ========== 连接服务器 ==========
sse.连接("https://api.example.com/notifications")

' ========== 辅助函数：显示通知 ==========
函数 显示通知(消息)
    ' 实际开发中可在此更新 UI，例如添加一条通知到列表
    调试输出("🔔 通知：" + 消息)
结束 函数

函数 显示告警(消息)
    ' 实际开发中可在此显示红色告警
    调试输出("🚨 告警：" + 消息)
结束 函数

' ========== 在页面关闭时断开连接 ==========
事件 页面被关闭()
    sse.关闭()
结束 事件

函数详解

连接(地址)

  • 功能： 建立与 SSE 服务器的连接，开始接收服务器推送的事件流。
  • 参数： 地址（文本型），SSE 服务的 URL 地址（支持 HTTP/HTTPS）。
  • 返回值： 无。连接结果需通过 置连接被打开回调 和 置发生错误回调 来监听。
  • 示例： sse.连接("https://api.example.com/events")

关闭()

  • 功能： 主动关闭 SSE 连接，停止接收事件流，释放资源。
  • 返回值： 无。
  • 示例： sse.关闭()

取连接状态()

  • 功能： 获取当前连接状态码。
  • 返回值： 数值型，可能的取值及含义：
    • 0：正在连接（Connecting）
    • 1：已连接（Open）
    • 2：已关闭（Closed）
  • 示例： 如果(sse.取连接状态() == 1) 调试输出("SSE 已连接")

重新连接(地址)

  • 功能： 关闭当前连接（如果存在）并重新连接到 SSE 服务器。可指定新的地址（可选，若不传则使用上次的地址）。
  • 参数： 地址（文本型，可选），新的 SSE 服务 URL；若省略则复用上次连接地址。
  • 返回值： 无。
  • 示例： sse.重新连接() 或 sse.重新连接("https://new-api.example.com/events")

回调设置函数

所有回调函数必须在调用 连接() 之前设置，否则可能错过连接打开等早期事件。

置连接被打开回调(回调函数)

  • 功能： 设置 SSE 连接成功打开时的回调函数。
  • 参数： 回调函数，格式为 (事件源) => { ... }，其中 事件源 是原生 EventSource 事件对象。
  • 示例： 
    sse.置连接被打开回调((事件源) => {
    调试输出("连接已打开，协议：" + 事件源.target.url)
})

置收到消息回调(回调函数)

  • 功能： 设置接收到服务器消息时的回调函数。
  • 参数： 回调函数，格式为 (事件源) => { ... }，事件源 包含以下常用属性：
    • eventSource.data：消息内容（文本字符串）
    • eventSource.type：事件类型（默认 "message"，可通过服务器设置自定义类型）
    • eventSource.lastEventId：最后一条消息的 ID（用于断线重连）
  • 示例： 
    sse.置收到消息回调((事件源) => {
    变量 类型 = 事件源.type
    变量 数据 = 事件源.data
    调试输出("[" + 类型 + "] " + 数据)
})

置发生错误回调(回调函数)

  • 功能： 设置发生错误时的回调函数（例如连接失败、网络中断、服务器返回错误状态码等）。
  • 参数： 回调函数，格式为 (事件源) => { ... }，事件源.message 包含错误描述。
  • 示例： 
    sse.置发生错误回调((事件源) => {
    调试输出("SSE 错误：" + 事件源.message)
})

事件说明

SSE 组件的事件与上述回调函数一一对应，适用于在 .spldg 设计文件中使用 VB6 风格事件绑定。

事件对应回调触发时机
连接被打开(事件源)置连接被打开回调SSE 连接成功建立
收到消息(事件源)置收到消息回调接收到服务器消息
发生错误(事件源)置发生错误回调发生错误（如连接失败）

与 WebSocket 的区别

维度SSEWebSocket
通信方向单向（服务器 → 客户端）双向（全双工）
协议HTTP（标准，兼容性好）WS/WSS（独立协议）
自动重连内置支持（EventSource 自动重连）需手动实现
消息格式纯文本（UTF-8）文本或二进制
支持的事件类型可自定义（通过 event: 字段）需自行约定协议
使用场景通知推送、状态监控、数据更新聊天、游戏、实时协作
浏览器支持所有现代浏览器（除 IE）所有现代浏览器（除 IE）

⚠️ 注意事项

  1. 回调设置顺序：所有回调函数应在调用 连接() 之前设置，否则可能错过连接打开等早期事件。
  2. 自动重连：SSE 协议原生支持断线重连，当连接意外断开时，浏览器会自动尝试重新连接。可通过 置发生错误回调 监控重连过程。
  3. 消息格式：服务器发送的消息格式为 data: 消息内容\n\n，可自定义 event: 字段来区分事件类型。
  4. 连接状态检查：发送操作前建议通过 取连接状态() 检查是否为 1（已连接）。
  5. 安全性：生产环境建议使用 https:// 协议，确保数据传输安全。
  6. 资源释放：在页面关闭或组件销毁时，应主动调用 关闭() 释放连接资源，避免内存泄漏。
  7. 浏览器限制：同一域名下的 SSE 连接数通常有限制（一般为 6 个），超出后可能需要复用连接或使用 HTTP/2。
  8. 跨域问题：若 SSE 服务与页面不同源，服务器需配置 CORS 头（Access-Control-Allow-Origin）。
  9. URL 长度限制：SSE 连接 URL 过长可能导致某些浏览器拦截（建议不超过 2048 字符）。
  10. 消息大小限制：虽然 SSE 没有明确限制消息大小，但过大的消息可能影响性能，建议分片发送。

相关文档

  • 文档不可视类型组件_WS客户端 —— WebSocket 双向通信
  • 文档前端(JavaScript)函数_网络操作类 —— HTTP 请求相关函数
  • 文档轻语言网站：轻语言语法速查 —— 拉姆达表达式、异常处理等
  • 文档综合演示：实时通知系统 —— 实际应用示例