useOnlineCount

在线用户数量统计 Composable，用于实时显示系统在线用户数量。

功能特性

• 📊 实时统计 - 通过 SSE 实时获取在线用户数量
• 🎯 单例模式 - 全局共享一个连接实例
• 🔄 自动初始化 - 在组件中自动初始化和管理生命周期
• 🔌 自动重连 - 支持断线自动重连和指数退避
• ⏱️ 更新时间 - 记录最后更新时间

基础用法

<template>
  <div class="online-status">
    <span>当前在线：{{ onlineUserCount }} 人</span>
    <span v-if="isConnected" class="status connected">已连接</span>
    <span v-else class="status disconnected">未连接</span>
  </div>
</template>

<script setup lang="ts">
import { useOnlineCount } from "@/composables";

// 默认自动初始化
const { onlineUserCount, isConnected } = useOnlineCount();
</script>

手动控制初始化

import { useOnlineCount } from "@/composables";

// 禁用自动初始化
const { onlineUserCount, initialize, cleanup } = useOnlineCount({
  autoInit: false,
});

onMounted(() => {
  // 手动初始化
  initialize();
});

onUnmounted(() => {
  // 手动清理
  cleanup();
});

在布局组件中使用

<template>
  <div class="navbar">
    <!-- 其他导航内容 -->

    <div class="online-count">
      <el-tooltip :content="`在线用户：${onlineUserCount}`">
        <el-badge :value="onlineUserCount" :max="999" type="success">
          <el-icon><User /></el-icon>
        </el-badge>
      </el-tooltip>
    </div>
  </div>
</template>

<script setup lang="ts">
import { useOnlineCount } from "@/composables";
import { User } from "@element-plus/icons-vue";

const { onlineUserCount } = useOnlineCount();
</script>

显示更新时间

<template>
  <div class="online-info">
    <span>在线人数：{{ onlineUserCount }}</span>
    <span class="update-time"> 更新于：{{ formatTime(lastUpdateTime) }} </span>
  </div>
</template>

<script setup lang="ts">
import { useOnlineCount } from "@/composables";

const { onlineUserCount, lastUpdateTime } = useOnlineCount();

const formatTime = (timestamp: number) => {
  if (!timestamp) return "未更新";
  return new Date(timestamp).toLocaleTimeString();
};
</script>

类型定义

/**
 * useOnlineCount 配置选项
 */
interface OnlineCountOptions {
  /** 是否自动初始化，默认 true */
  autoInit?: boolean;
}

/**
 * useOnlineCount 返回值
 */
interface OnlineCountComposable {
  /** 在线用户数量（只读） */
  onlineUserCount: Readonly<Ref<number>>;
  /** 最后更新时间戳（只读） */
  lastUpdateTime: Readonly<Ref<number>>;
  /** 连接状态 */
  isConnected: Ref<boolean>;
  /** 连接状态详情 */
  connectionState: Ref<string>;
  /** 初始化连接 */
  initialize: () => void;
  /** 清理资源 */
  cleanup: () => void;
}

API

参数

参数	类型	默认值	说明
options.autoInit	boolean	true	是否在组件挂载时自动初始化

返回值

名称	类型	说明
onlineUserCount	Readonly<Ref<number>>	在线用户数量
lastUpdateTime	Readonly<Ref<number>>	最后更新时间戳
isConnected	Ref<boolean>	SSE 连接状态
connectionState	Ref<string>	连接状态详情
initialize	() => void	初始化 SSE 连接
cleanup	() => void	关闭连接并清理资源

消息格式

后端推送的消息支持两种格式：

// 格式1：直接数字
42

// 格式2：对象格式
{
  "count": 42,
  "timestamp": 1703577600000
}

配置说明

useOnlineCount 内部使用 useSse 进行实时通信（SSE 长连接）。

环境变量

需要在 .env 文件中配置 SSE 端点：

# SSE 端点地址
VITE_APP_SSE_ENDPOINT=http://localhost:8080/api/v1/sse/connect

初始化条件

useOnlineCount 在以下条件满足时才会初始化：

1. 配置了 VITE_APP_SSE_ENDPOINT 环境变量
2. 用户已登录（存在有效的 accessToken）

注意事项

1. 单例模式：useOnlineCount 采用单例模式，多次调用返回同一实例
2. 自动初始化：默认在组件挂载时自动初始化，可通过 autoInit: false 禁用
3. 连接共享：组件卸载时不会关闭连接，由全局统一管理
4. 只读状态：onlineUserCount 和 lastUpdateTime 是只读的，防止外部修改

相关链接

• 实时通信
• useSse
• useDictSync