OpenIM Web

一个基于 Vue 3 的即时通讯组件库，提供简单易用的聊天界面和功能。

特性

• 🚀 基于 Vue 3 + TypeScript
• 💪 支持明暗主题切换
• 🌍 支持中英文国际化
• 📱 响应式设计
• 🎨 可自定义样式
• 🔌 完整的事件系统

安装

# npm
npm install openim-web

# yarn
yarn add openim-web

# pnpm
pnpm add openim-web

使用

基础配置

在使用组件之前，需要先配置必要的依赖：

// main.ts
import { createApp } from 'vue'
import { createPinia } from 'pinia'
import piniaPluginPersistedstate from 'pinia-plugin-persistedstate'
import App from './App.vue'
import OpenIMWeb from 'openim-web'
import 'openim-web/dist/style.css'

const app = createApp(App)

// 配置 Pinia
const pinia = createPinia()
pinia.use(piniaPluginPersistedstate)
app.use(pinia)

// 注册组件库
app.use(OpenIMWeb)
app.mount('#app')

使用组件

<template>
  <ChatWindow api-url="https://api.example.com" ws-url="wss://ws.example.com" token="your-token" />
</template>

<script setup lang="ts">
import { ChatWindow } from 'openim-web'
</script>

依赖说明

本库需要以下依赖：

{
  "dependencies": {
    "vue": "^3.0.0",
    "pinia": "^2.0.0",
    "pinia-plugin-persistedstate": "^4.0.0"
  }
}

重要说明

1. Pinia 配置

   • 必须在使用组件库之前配置 Pinia
   • 必须安装并配置 pinia-plugin-persistedstate
   • 建议在使用组件库之前注册 Pinia，以避免状态管理冲突

2. 样式文件

   • 必须引入 openim-web/dist/style.css
   • 确保样式文件在组件之前引入

3. 主题配置

   • 组件库支持亮色/暗色主题
   • 可以通过 Pinia store 控制主题切换

组件 Props

属性名	类型	必填	说明
api-url	string	是	OpenIM API 地址
ws-url	string	是	WebSocket 地址
token	string	是	用户认证令牌

事件

事件名	参数	说明
connect	-	连接成功时触发
disconnect	reason: string	断开连接时触发
error	error: Error	发生错误时触发
message	message: Message	收到新消息时触发
message-sent	message: Message	消息发送成功时触发
message-received	message: Message	消息接收成功时触发
typing	userId: string	用户正在输入时触发
online-status-change	userId: string, status: 'online' | 'offline'	用户在线状态变更时触发

方法

方法名	参数	说明
sendMessage	content: string, type?: MessageType	发送消息

类型定义

type MessageType = 'text' | 'image' | 'file' | 'audio' | 'video' | 'location' | 'custom'

interface Message {
  id: string
  type: MessageType
  content: string
  senderId: string
  receiverId: string
  timestamp: number
  status: 'sending' | 'sent' | 'delivered' | 'read' | 'failed'
  metadata?: Record<string, unknown>
}

开发

# 安装依赖
pnpm install

# 启动开发服务器
pnpm dev

# 构建库
pnpm build:lib

# 运行测试
pnpm test:unit

许可证

MIT