useOnlineCount

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

功能特性

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

基础用法

<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>	WebSocket 连接状态
connectionState	Ref<string>	连接状态详情
initialize	() => void	初始化 WebSocket 连接
cleanup	() => void	关闭连接并清理资源

消息格式

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

// 格式1：直接数字
42

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

配置说明

useOnlineCount 内部使用 useStomp 进行实时通信（WebSocket），默认配置：

配置项	默认值	说明
reconnectDelay	15000ms	重连延迟时间
connectionTimeout	10000ms	连接超时时间
maxReconnectAttempts	3	最大重连次数
useExponentialBackoff	true	使用指数退避重连
autoRestoreSubscriptions	true	自动恢复订阅

环境变量

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

# WebSocket 端点地址
VITE_APP_WS_ENDPOINT=ws://localhost:8080/ws

初始化条件

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

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

注意事项

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

相关链接

• 实时通信
• useStomp
• useDictSync