JSSZ 会议组件库

一个基于 Vue 3 + TypeScript 开发的音视频会议组件库，提供完整的会议功能，包括创建会议、加入会议、音视频通话、屏幕共享等功能。

📋 目录

• 功能特性
• 安装使用
• 快速开始
• API 文档
• 组件说明
• 配置说明
• 开发指南
• 常见问题

✨ 功能特性

核心功能

• 🎥 音视频通话 - 支持高清音视频通话
• 📺 屏幕共享 - 支持桌面和窗口共享
• 👥 多人会议 - 支持多人同时参与会议
• 📱 设备管理 - 自动检测和管理音视频设备
• 🎨 多种布局 - 支持网格布局、演讲者模式等
• 💬 实时聊天 - 会议内文字聊天功能
• 📋 成员管理 - 邀请成员、踢出成员、权限管理

技术特性

• 🚀 Vue 3 - 基于最新的 Vue 3 Composition API
• 📦 TypeScript - 完整的类型支持
• 🎯 组件化 - 高度模块化的组件设计
• 🎨 主题支持 - 支持明暗主题切换
• 📱 响应式 - 适配不同屏幕尺寸
• 🔧 可配置 - 丰富的配置选项

🚀 安装使用

环境要求

• Node.js >= 16.0.0
• Vue >= 3.0.0

安装依赖

# 使用 npm
npm install jssz-meeting

# 使用 yarn
yarn add jssz-meeting

# 使用 pnpm
pnpm add jssz-meeting

🎯 快速开始

1. 全局注册组件

⚠️ 重要提示：注册组件时必须提供有效的认证token

// main.ts
import { createApp } from 'vue'
import App from './App.vue'
import JSSZMeetingPlugin, { type PluginInstallOptions } from 'jssz-meeting'

const app = createApp(App)

// 注册插件时必须提供token
app.use(JSSZMeetingPlugin, {
  authToken: 'your-authentication-token-here' // 必填：你的认证token
})

app.mount('#app')

Token说明：

• token 参数是必填的，用于API请求认证
• 插件会自动将token存储到localStorage中
• 所有组件和API调用都会使用此token进行认证
• 如果没有提供token或token为空，插件注册会失败并抛出错误

2. 在组件中使用

<template>
  <div>
    <!-- 会议组件 -->
    <js-meeting 
      :theme="'light'" 
      draggable
    />
    
    <!-- 通话组件 -->
    <js-call 
      :theme="'light'" 
      draggable
    />
    
    <!-- 用户列表组件 -->
    <js-user 
      v-model="showUserList"
      :theme="'light'"
    />
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue'

const showUserList = ref(false)
</script>

3. 使用 API 方法

import { jsCreateMeeting, jsJoinMeeting, jsDial } from 'jssz-meeting'

// 创建会议
const createMeeting = async () => {
  try {
    const result = await jsCreateMeeting({
      memberId: '1924822985366048770',
      meetingName: '我的会议',
      cameraStatus: '1',
      audioStatus: '1'
    })
    console.log('会议创建成功:', result)
  } catch (error) {
    console.error('会议创建失败:', error)
  }
}

// 加入会议
const joinMeeting = async () => {
  try {
    await jsJoinMeeting({
      meetingId: '33d9a5bd59094e2fad68d553a162f24f',
      memberId: '1924822985366048770',
      cameraStatus: '1',
      audioStatus: '1'
    })
    console.log('加入会议成功')
  } catch (error) {
    console.error('加入会议失败:', error)
  }
}

// 拨打电话
const dial = async () => {
  try {
    const result = await jsDial({
      caller: '1924822985366048770',
      callee: '1927626022732173314',
      calleeName: '张灵'
    })
    console.log('拨号成功:', result)
  } catch (error) {
    console.error('拨号失败:', error)
  }
}

📚 API 文档

插件安装配置

PluginInstallOptions - 插件安装选项

interface PluginInstallOptions {
  authToken: string; // 必填：认证token
}

使用示例：

import { createApp } from 'vue'
import JSSZMeetingPlugin, { type PluginInstallOptions } from 'jssz-meeting'

const app = createApp(App)

// 注册插件时必须提供token
app.use(JSSZMeetingPlugin, {
  authToken: 'your-authentication-token'
})

app.mount('#app')

核心 API 方法

jsCreateMeeting - 创建会议

jsCreateMeeting(data: NewMeetingDialogTypes): Promise<MeetingCreateResult>

参数说明：

• memberId (string, 必需): 会议创建人ID
• callee (string[], 可选): 参会人员ID列表
• meetingName (string, 可选): 会议名称
• cameraStatus (string, 可选): 摄像头状态，'1'开启，'0'关闭
• audioStatus (string, 可选): 麦克风状态，'1'开启，'0'关闭

jsJoinMeeting - 加入会议

jsJoinMeeting(data: JoinMeetingDialogTypes): Promise<void>

参数说明：

• meetingId (string, 必需): 会议ID
• memberId (string, 必需): 用户ID
• cameraStatus (string, 可选): 摄像头状态
• audioStatus (string, 可选): 麦克风状态

jsDial - 拨打电话

jsDial(data: DialDialogTypes): Promise<MeetingCreateResult>

参数说明：

• caller (string, 必需): 发起人ID
• callee (string, 必需): 被叫号码
• calleeName (string, 必需): 被叫名称
• calleeAvatar (string, 可选): 被叫人头像

类型定义

// 创建会议参数
interface NewMeetingDialogTypes {
  memberId: string
  callee?: string[]
  meetingName?: string
  cameraStatus?: string
  audioStatus?: string
}

// 加入会议参数
interface JoinMeetingDialogTypes {
  meetingId: string
  memberId: string
  cameraStatus?: '1' | '2'
  audioStatus?: '1' | '2'
}

// 拨号参数
interface DialDialogTypes {
  caller: string
  callee: string
  calleeName: string
  calleeAvatar?: string
}

// 会议创建结果
interface MeetingCreateResult {
  meetingId: string
  memberId: string
  meetingName?: string
  [key: string]: any
}

🧩 组件说明

js-meeting 会议组件

会议主界面组件，提供完整的会议功能。

<js-meeting 
  :theme="'light' | 'dark'"
  :draggable="boolean"
/>

Props:

• theme: 主题样式，'light' | 'dark'
• draggable: 是否允许拖拽窗口

js-call 通话组件

音视频通话组件，用于一对一通话。

<js-call 
  :theme="'light' | 'dark'"
  :draggable="boolean"
/>

Props:

• theme: 主题样式
• draggable: 是否允许拖拽

js-user 用户组件

用户列表组件，显示通讯录和用户管理。

<js-user 
  v-model="boolean"
  :theme="'light' | 'dark'"
  :draggable="boolean"
/>

Props:

• v-model: 控制组件显示/隐藏
• theme: 主题样式
• draggable: 是否允许拖拽

⚙️ 配置说明

环境配置

在 vite.config.ts 中配置代理：

export default defineConfig({
  server: {
    proxy: {
      '/meeting': {
        target: 'http://your-api-server/meeting',
        changeOrigin: true,
        ws: true,
        rewrite: (path) => path.replace(/^\/meeting/, ''),
      },
      '/user': {
        target: 'http://your-api-server/user',
        changeOrigin: true,
        ws: true,
        rewrite: (path) => path.replace(/^\/user/, ''),
      },
    },
  },
})

认证配置

使用前需要先进行用户认证：

import { getLogin } from 'jssz-meeting'

const handleLogin = async () => {
  const params = {
    username: 'your-username',
    password: 'your-password',
    grant_type: 'password',
    comfirmLogin: '',
    deviceType: 'web'
  }
  
  try {
    const res = await getLogin(params)
    if (res.code === 0) {
      localStorage.setItem('token', res.data.access_token)
    }
  } catch (error) {
    console.error('登录失败:', error)
  }
}

🛠️ 开发指南

项目结构

src/
├── components/          # 主要组件
│   ├── meeting.vue     # 会议组件
│   ├── call.vue        # 通话组件
│   └── user.vue        # 用户组件
├── internal/           # 内部组件
├── api/               # API 接口
├── utils/             # 工具函数
├── types/             # 类型定义
└── styles/            # 样式文件

开发命令

# 开发模式
npm run dev

# 构建项目
npm run build

# 构建组件库
npm run build:lib

# 类型检查
npm run type-check

# 代码格式化
npm run format

# 代码检查
npm run lint

自定义主题

组件支持明暗主题切换，可以通过 CSS 变量自定义样式：

/* 浅色主题 */
:root {
  --js-bg-color: #ffffff;
  --js-text-color: #333333;
  --js-border-color: #e0e0e0;
}

/* 深色主题 */
.dark-theme {
  --js-bg-color: #1a1a1a;
  --js-text-color: #ffffff;
  --js-border-color: #333333;
}

❓ 常见问题

Q: 插件注册时提示"必须提供有效的token参数"怎么办？

A: 这是因为注册插件时没有提供token参数。请确保在注册插件时传入有效的token：

// 错误的用法
app.use(JSSZMeetingPlugin) // ❌ 缺少token参数

// 正确的用法
app.use(JSSZMeetingPlugin, {
  token: 'your-valid-token' // ✅ 提供有效token
})

Q: 如何获取认证token？

A: token通常由后端服务提供，用于API请求认证。请联系你的后端开发人员获取有效的认证token。

Q: token过期了怎么办？

A: 当token过期时，API请求会失败。你需要：

1. 重新获取有效的token
2. 重新注册插件：app.use(JSSZMeetingPlugin, { token: 'new-token' })

Q: 如何获取用户权限？

A: 浏览器会自动请求麦克风和摄像头权限，如果用户拒绝，会显示权限提示信息。

Q: 支持哪些浏览器？

A: 支持现代浏览器，包括 Chrome、Firefox、Safari、Edge 等，需要支持 WebRTC。

Q: 如何处理网络断开？

A: 组件内置了网络状态检测和重连机制，会自动处理网络异常情况。

Q: 如何自定义样式？

A: 可以通过 CSS 变量或覆盖组件样式来自定义外观。

Q: 支持移动端吗？

A: 支持移动端浏览器，但建议在桌面端使用以获得最佳体验。

📄 许可证

MIT License

🤝 贡献

欢迎提交 Issue 和 Pull Request 来帮助改进项目。

📞 支持

如有问题，请联系开发团队或查看项目文档。

网络质量监控

SDK 提供了实时网络质量监控功能，可以在加入频道后自动获取网络质量指标。

功能特点

• 自动监控：加入频道后自动开始监控
• 实时更新：每3秒更新一次网络质量数据
• 多维度指标：包含音频、视频码率、丢包、抖动、延迟等

使用方法

import { networkMetrics, type NetworkMetric } from 'jssz-meeting'

// 监听网络质量变化
watch(() => networkMetrics, (metrics) => {
  Object.entries(metrics).forEach(([uid, metric]) => {
    console.log(`用户 ${uid} 的网络质量:`, {
      音频码率: metric.audioBitrate,
      视频码率: metric.videoBitrate,
      音频丢包: metric.audioPacketsLost,
      视频丢包: metric.videoPacketsLost,
      抖动: metric.jitter,
      延迟: metric.rtt
    })
  })
}, { deep: true })

指标说明

| 指标 | 类型 | 说明 | |------|------|------| | uid | string | 用户ID | | timestamp | number | 时间戳 | | audioBitrate | number | 音频码率（bps） | | videoBitrate | number | 视频码率（bps） | | audioPacketsLost | number | 音频丢包数 | | videoPacketsLost | number | 视频丢包数 | | audioPackets | number | 音频包数 | | videoPackets | number | 视频包数 | | jitter | number | 网络抖动（ms） | | rtt | number | 往返延迟（ms） |

注意事项

• 网络质量数据会在加入频道后自动更新
• 离开频道后自动停止监控
• networkMetrics 是一个响应式对象，可以直接在组件中使用