WebChat客户端API

WebChat客户端(webchat-client.html)是WebChatQQ的用户界面组件，提供了友好的交互界面和丰富的功能。本文档详细介绍了客户端的API及其使用方法。

客户端概述

WebChat客户端是一个基于HTML、CSS和JavaScript的单页面应用，通过WebSocket与服务器通信，实现实时消息收发和群聊功能。

主要特性

1. 响应式设计，支持移动端和桌面端
2. 实时消息收发
3. 成员列表显示
4. 图片发送和查看
5. 历史消息加载
6. 戳一戳功能
7. 群文件管理

全局变量

客户端使用以下全局变量管理状态：

// 全局变量
let ws;                  // WebSocket连接
let clientId;            // 由后端welcome消息分配的客户端ID
let currentNickname;     // 当前用户昵称
let currentGroupId;      // 当前加入的群聊ID
let currentUserAvatar;   // 当前用户头像URL
let isConnected = false; // 连接状态

核心函数

连接管理

connect()

建立WebSocket连接并设置事件监听器。

返回值: void

示例:

connect();

reconnect()

重新连接到WebSocket服务器，在连接断开时自动调用。

返回值: void

示例:

reconnect();

用户操作

joinGroup()

加入指定的群组。

返回值: void

示例:

joinGroup();

sendMsg()

发送消息到当前群组。

返回值: void

示例:

sendMsg();

handleKeyDown(event)

处理键盘事件，支持按Enter发送消息。

参数:

• event (KeyboardEvent): 键盘事件对象

返回值: void

示例:

msgInput.addEventListener('keydown', handleKeyDown);

消息处理

renderMessage(message)

渲染消息到聊天界面。

参数:

• message (Object): 消息对象

返回值: HTMLElement - 渲染后的消息元素

示例:

const messageElement = renderMessage({
  type: 'groupMsg',
  sender: { user_id: 'user1', nickname: '用户1' },
  message: [{ type: 'text', data: { text: '你好！' } }]
});
messagesContainer.appendChild(messageElement);

addSystemMessage(content)

添加系统消息到聊天界面。

参数:

• content (String): 系统消息内容

返回值: void

示例:

addSystemMessage('用户已加入群聊');

成员管理

updateMemberList(members)

更新成员列表显示。

参数:

• members (Array): 成员对象数组

返回值: void

示例:

updateMemberList([
  { user_id: 'user1', nickname: '用户1' },
  { user_id: 'user2', nickname: '用户2' }
]);

addMember(member)

添加成员到成员列表。

参数:

• member (Object): 成员对象

返回值: HTMLElement - 添加的成员元素

示例:

addMember({ user_id: 'user1', nickname: '用户1' });

历史记录

loadHistory(history)

加载历史消息记录。

参数:

• history (Array): 历史消息对象数组

返回值: void

示例:

loadHistory([
  {
    type: 'groupMsg',
    sender: { user_id: 'user1', nickname: '用户1' },
    message: [{ type: 'text', data: { text: '你好！' } }]
  }
]);

loadMoreMessages()

加载更多历史消息。

返回值: Promise<void>

示例:

loadMoreMessages();

图片处理

uploadImage(file)

上传并发送图片。

参数:

• file (File): 图片文件对象

返回值: Promise<void>

示例:

uploadImage(imageFileInput.files[0]);

showImageViewer(imageUrl)

显示图片查看器。

参数:

• imageUrl (String): 图片URL

返回值: void

示例:

showImageViewer('https://example.com/image.jpg');

WebSocket消息处理

客户端通过WebSocket与服务器通信，处理以下类型的消息：

接收的消息类型

消息类型	描述
welcome	服务器欢迎消息，包含分配的clientId
joinSuccess	成功加入群聊的确认
memberJoin	新成员加入通知
memberLeave	成员离开通知
memberList	成员列表更新
groupMsg	群聊消息
systemMsg	系统消息
error	错误消息
msgAck	消息确认回执
clearHistory	清除历史记录通知

发送的消息类型

消息类型	描述
join	请求加入群聊
leave	离开群聊
groupMsg	发送群聊消息
getHistory	请求历史消息
getQQAvatar	请求QQ用户头像
getQQGroupMembers	请求QQ群成员列表
poke	戳一戳请求
getGroupFiles	请求群文件列表
downloadGroupFile	下载群文件
uploadGroupFile	上传群文件

用户界面组件

登录界面

<div id="login">
  <h2>加入群聊</h2>
  <div class="input-group">
    <label for="nickname">你的昵称</label>
    <input type="text" id="nickname" placeholder="输入你的昵称" autocomplete="nickname">
  </div>
  <div class="input-group">
    <label for="group-id">群号</label>
    <input type="text" id="group-id" placeholder="输入群号" value="1">
  </div>
  <div class="input-group">
    <label for="password">密码</label>
    <input type="password" id="password" placeholder="输入密码">
  </div>
  <button id="join-button" onclick="joinGroup()">加入群聊</button>
</div>

聊天界面

聊天界面由以下主要部分组成：

1. 侧边栏: 显示群信息和成员列表
2. 消息区域: 显示聊天消息
3. 输入区域: 用于输入和发送消息

<div id="chat">
  <div id="chat-container">
    <!-- 侧边栏 -->
    <div id="chat-sidebar">
      <!-- 群组信息和成员列表 -->
    </div>
    
    <!-- 主聊天区域 -->
    <div id="chat-main" class="sidebar-visible">
      <div id="messages">
        <!-- 消息内容 -->
      </div>
      <div id="input-area">
        <!-- 消息输入和发送控件 -->
      </div>
    </div>
  </div>
</div>

事件处理

客户端通过以下事件监听器处理用户交互：

// 初始化事件监听
document.addEventListener('DOMContentLoaded', function() {
  // 设置各种事件监听器
  elements.joinButton.addEventListener('click', joinGroup);
  elements.sendButton.addEventListener('click', sendMsg);
  elements.msgInput.addEventListener('keydown', handleKeyDown);
  elements.reconnectButton.addEventListener('click', reconnect);
  
  // 其他事件监听器...
});

样式定制

客户端使用CSS变量定义主题样式，可以通过修改这些变量来自定义界面外观：

:root {
  --primary-color: #FF8C00; /* 橙色主题 */
  --primary-color-rgb: 255, 140, 0; /* RGB形式，用于透明度设置 */
  --primary-light: #FFB347;
  --primary-dark: #E67300;
  --text-color: #333333;
  /* 其他样式变量... */
}

最佳实践

自定义客户端

要自定义WebChat客户端，可以：

1. 修改CSS变量更改主题颜色
2. 调整布局参数适应不同屏幕
3. 添加自定义功能按钮
4. 扩展消息类型支持

消息发送示例

// 发送文本消息
function sendTextMessage(text) {
  const message = {
    type: 'groupMsg',
    groupId: currentGroupId,
    msg: [{ type: 'text', data: { text: text } }]
  };
  ws.send(JSON.stringify(message));
}

// 发送图片消息
function sendImageMessage(imageUrl) {
  const message = {
    type: 'groupMsg',
    groupId: currentGroupId,
    msg: [{ type: 'image', data: { url: imageUrl } }]
  };
  ws.send(JSON.stringify(message));
}

扩展客户端功能

要为客户端添加新功能，可以按照以下步骤操作：

1. 在HTML中添加必要的UI元素
2. 在CSS中定义相关样式
3. 在JavaScript中实现功能逻辑
4. 添加适当的事件监听器

例如，添加表情选择器：

// 添加表情选择器功能
function setupEmojiPicker() {
  const emojiButton = document.getElementById('emoji-btn');
  const emojiPicker = document.getElementById('emoji-picker');
  
  // 填充表情
  const emojis = ['😀', '😂', '😍', '🤔', '😎', '👍', '❤️', '🎉'];
  emojis.forEach(emoji => {
    const emojiItem = document.createElement('div');
    emojiItem.className = 'emoji-item';
    emojiItem.textContent = emoji;
    emojiItem.onclick = () => {
      msgInput.value += emoji;
      emojiPicker.classList.remove('active');
    };
    emojiPicker.appendChild(emojiItem);
  });
  
  // 切换表情选择器显示/隐藏
  emojiButton.addEventListener('click', () => {
    emojiPicker.classList.toggle('active');
  });
}