1618 lines
47 KiB
Markdown
1618 lines
47 KiB
Markdown
# NL-IM UniApp 移动端开发手册
|
||
|
||
> 基于 nl-im-vue-ts Web 端项目迁移，支持 App（Android/iOS）和微信小程序
|
||
|
||
## 目录
|
||
|
||
- [一、项目概述](#一项目概述)
|
||
- [二、目录结构](#二目录结构)
|
||
- [三、页面设计](#三页面设计qq-风格)
|
||
- [四、API 接口](#四api-接口文档)
|
||
- [五、类型定义](#五类型定义)
|
||
- [六、状态管理](#六状态管理pinia-store)
|
||
- [七、WebSocket](#七websocket-通讯)
|
||
- [八、主题系统](#八主题系统)
|
||
- [九、平台适配](#九平台适配)
|
||
- [十、UI 组件](#十ui-组件wot-design-uni)
|
||
- [十一、工具函数](#十一工具函数)
|
||
- [十二、开发规范](#十二开发规范)
|
||
- [十三、快速开始](#十三快速开始)
|
||
- [十四、功能清单](#十四功能清单)
|
||
|
||
---
|
||
|
||
## 一、项目概述
|
||
|
||
### 1.1 技术栈
|
||
|
||
| 技术 | 版本 | 说明 |
|
||
|------|------|------|
|
||
| UniApp | 3.0+ | 跨平台框架 |
|
||
| Vue | 3.4.x | 前端框架 |
|
||
| TypeScript | 5.x | 类型支持 |
|
||
| Pinia | 2.2.x | 状态管理 |
|
||
| wot-design-uni | 1.13+ | UI 组件库 |
|
||
| Vite | 5.x | 构建工具 |
|
||
|
||
### 1.2 支持平台
|
||
|
||
| 平台 | 状态 | 说明 |
|
||
|------|------|------|
|
||
| Android | 支持 | App |
|
||
| iOS | 支持 | App |
|
||
| 微信小程序 | 支持 | 主要平台 |
|
||
| H5 | 可选 | 移动端网页 |
|
||
|
||
### 1.3 设计风格
|
||
|
||
- UI 参考**手机 QQ**
|
||
- 支持**浅色/暗色**两种主题
|
||
- 适配不同屏幕尺寸
|
||
- 遵循各平台设计规范
|
||
|
||
---
|
||
|
||
## 二、目录结构
|
||
|
||
```
|
||
nl-im-uniapp/src/
|
||
├── api/ # API 接口层
|
||
│ ├── modules/ # 业务模块
|
||
│ │ ├── auth.ts # 认证（登录/注册/验证码）
|
||
│ │ ├── user.ts # 用户（信息/列表）
|
||
│ │ ├── contact.ts # 联系人（好友/分组/申请）
|
||
│ │ ├── conversation.ts # 会话（列表/未读/置顶）
|
||
│ │ ├── message.ts # 消息（发送/历史/同步）
|
||
│ │ ├── room.ts # 群聊（创建/成员/设置）
|
||
│ │ ├── moment.ts # 朋友圈（动态/点赞/评论）
|
||
│ │ ├── attachment.ts # 附件（上传/下载）
|
||
│ │ └── system.ts # 系统（健康检查/配置）
|
||
│ ├── request/ # 请求封装
|
||
│ │ ├── index.ts # uni.request 封装
|
||
│ │ └── types.ts # 请求/响应类型
|
||
│ └── websocket/ # 实时通讯
|
||
│ └── index.ts # WebSocket 管理器
|
||
│
|
||
├── components/ # 公共组件
|
||
│ ├── chat/ # 聊天组件
|
||
│ │ ├── MessageBubble.vue # 消息气泡容器
|
||
│ │ ├── MessageInput.vue # 消息输入框
|
||
│ │ ├── MessageList.vue # 消息列表
|
||
│ │ └── bubble/ # 气泡类型
|
||
│ │ ├── TextBubble.vue
|
||
│ │ ├── ImageBubble.vue
|
||
│ │ ├── AudioBubble.vue
|
||
│ │ ├── VideoBubble.vue
|
||
│ │ └── FileBubble.vue
|
||
│ ├── common/ # 通用组件
|
||
│ │ ├── AppNavBar.vue # 导航栏
|
||
│ │ ├── AppTabBar.vue # 底部标签栏
|
||
│ │ ├── AppDrawer.vue # 侧边抽屉
|
||
│ │ ├── AppAvatar.vue # 头像
|
||
│ │ ├── AppSearch.vue # 搜索框
|
||
│ │ ├── AppEmpty.vue # 空状态
|
||
│ │ └── AppLoading.vue # 加载状态
|
||
│ ├── contact/ # 联系人组件
|
||
│ │ ├── ContactItem.vue # 联系人项
|
||
│ │ └── ContactGroup.vue # 联系人分组
|
||
│ └── moment/ # 朋友圈组件
|
||
│ ├── MomentCard.vue # 动态卡片
|
||
│ ├── MomentPublisher.vue # 发布器
|
||
│ └── MomentComment.vue # 评论组件
|
||
│
|
||
├── composables/ # 组合式函数
|
||
│ ├── useTheme.ts # 主题管理
|
||
│ ├── useAuth.ts # 认证状态
|
||
│ ├── useSocket.ts # WebSocket
|
||
│ └── useUpload.ts # 文件上传
|
||
│
|
||
├── pages/ # 页面
|
||
│ ├── index/ # 首页（会话）
|
||
│ │ └── index.vue
|
||
│ ├── chat/ # 聊天
|
||
│ │ ├── index.vue # 聊天详情
|
||
│ │ └── group-info.vue # 群信息
|
||
│ ├── contact/ # 联系人
|
||
│ │ ├── index.vue # 联系人列表
|
||
│ │ ├── detail.vue # 好友详情
|
||
│ │ ├── add.vue # 添加好友
|
||
│ │ ├── requests.vue # 好友申请
|
||
│ │ └── groups.vue # 群聊列表
|
||
│ ├── moment/ # 朋友圈
|
||
│ │ ├── index.vue # 动态列表
|
||
│ │ ├── detail.vue # 动态详情
|
||
│ │ ├── publish.vue # 发布动态
|
||
│ │ └── notify.vue # 消息通知
|
||
│ ├── login/ # 登录
|
||
│ │ └── index.vue
|
||
│ ├── profile/ # 个人中心
|
||
│ │ ├── index.vue # 个人资料
|
||
│ │ └── edit.vue # 编辑资料
|
||
│ ├── settings/ # 设置
|
||
│ │ └── index.vue
|
||
│ └── search/ # 搜索
|
||
│ └── index.vue
|
||
│
|
||
├── stores/ # Pinia Store
|
||
│ ├── auth.ts # 认证
|
||
│ ├── chat.ts # 聊天
|
||
│ ├── contact.ts # 联系人
|
||
│ ├── conversation.ts # 会话
|
||
│ ├── moment.ts # 朋友圈
|
||
│ └── app.ts # 全局应用
|
||
│
|
||
├── types/ # 类型定义
|
||
│ ├── api.ts # API 类型
|
||
│ ├── conversation.ts # 会话类型
|
||
│ ├── message.ts # 消息类型
|
||
│ ├── moment.ts # 朋友圈类型
|
||
│ └── user.ts # 用户类型
|
||
│
|
||
├── utils/ # 工具函数
|
||
│ ├── storage.ts # 本地存储
|
||
│ ├── format.ts # 格式化
|
||
│ ├── message.ts # 消息处理
|
||
│ └── platform.ts # 平台判断
|
||
│
|
||
├── styles/ # 样式
|
||
│ ├── variables.scss # CSS 变量
|
||
│ ├── theme.scss # 主题定义
|
||
│ └── common.scss # 公共样式
|
||
│
|
||
├── static/ # 静态资源
|
||
│ ├── images/
|
||
│ └── icons/
|
||
│
|
||
├── App.vue # 根组件
|
||
├── main.ts # 入口文件
|
||
├── pages.json # 页面配置
|
||
├── manifest.json # 应用配置
|
||
├── theme.json # 主题配置
|
||
└── uni.scss # uni 变量
|
||
```
|
||
|
||
---
|
||
|
||
## 三、页面设计（QQ 风格）
|
||
|
||
### 3.1 页面路由配置
|
||
|
||
```json
|
||
// pages.json
|
||
{
|
||
"pages": [
|
||
{ "path": "pages/index/index", "style": { "navigationStyle": "custom" } },
|
||
{ "path": "pages/chat/index", "style": { "navigationBarTitleText": "聊天" } },
|
||
{ "path": "pages/contact/index", "style": { "navigationStyle": "custom" } },
|
||
{ "path": "pages/moment/index", "style": { "navigationStyle": "custom" } },
|
||
{ "path": "pages/login/index", "style": { "navigationBarTitleText": "登录" } }
|
||
],
|
||
"tabBar": {
|
||
"list": [
|
||
{ "pagePath": "pages/index/index", "text": "消息", "iconPath": "...", "selectedIconPath": "..." },
|
||
{ "pagePath": "pages/contact/index", "text": "联系人", "iconPath": "...", "selectedIconPath": "..." },
|
||
{ "pagePath": "pages/moment/index", "text": "朋友圈", "iconPath": "...", "selectedIconPath": "..." }
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
### 3.2 首页（会话页）
|
||
|
||
**路径**: `pages/index/index.vue`
|
||
|
||
```
|
||
┌─────────────────────────────────────┐
|
||
│ [头像] 消息 [+] │ ← 自定义导航栏
|
||
├─────────────────────────────────────┤
|
||
│ 🔍 搜索 │ ← 搜索框
|
||
├─────────────────────────────────────┤
|
||
│ ┌─────────────────────────────┐ │
|
||
│ │ [头像] 张三 14:30 │ │
|
||
│ │ 你好，在吗？ [3] │ │ ← 会话项
|
||
│ └─────────────────────────────┘ │
|
||
│ ┌─────────────────────────────┐ │
|
||
│ │ [头像] 工作群 昨天 │ │
|
||
│ │ 李四: 收到 🔇 │ │
|
||
│ └─────────────────────────────┘ │
|
||
│ ... │
|
||
├─────────────────────────────────────┤
|
||
│ 消息 联系人 朋友圈 │ ← TabBar
|
||
└─────────────────────────────────────┘
|
||
```
|
||
|
||
**功能点**:
|
||
- 点击头像 → 弹出左侧抽屉
|
||
- 点击加号 → 显示菜单（创建群聊/添加好友/扫一扫）
|
||
- 点击搜索 → 跳转搜索页
|
||
- 长按会话 → 显示操作菜单（置顶/删除/免打扰）
|
||
- 左滑会话 → 快捷操作
|
||
|
||
**左侧抽屉内容**:
|
||
```
|
||
┌────────────────────┐
|
||
│ [大头像] │
|
||
│ 昵称 │
|
||
│ 个性签名 │
|
||
├────────────────────┤
|
||
│ 👤 个人资料 │
|
||
│ ⚙️ 设置 │
|
||
│ 🌙 深色模式 [开关]│
|
||
├────────────────────┤
|
||
│ 📤 退出登录 │
|
||
└────────────────────┘
|
||
```
|
||
|
||
### 3.3 聊天页
|
||
|
||
**路径**: `pages/chat/index.vue`
|
||
|
||
```
|
||
┌─────────────────────────────────────┐
|
||
│ [<] 张三 / 工作群(10) [···] │ ← 导航栏（群聊显示成员数和更多按钮）
|
||
├─────────────────────────────────────┤
|
||
│ │
|
||
│ ┌──────────┐ │
|
||
│ │ 你好 │ 14:30 │ ← 对方消息（左侧）
|
||
│ └──────────┘ │
|
||
│ │
|
||
│ ┌──────────┐ │
|
||
│ 14:31 │ 在的 │ │ ← 我的消息（右侧）
|
||
│ └──────────┘ │
|
||
│ │
|
||
│ 系统消息 │ ← 系统/通知消息（居中）
|
||
│ │
|
||
├─────────────────────────────────────┤
|
||
│ [😊] [📷] [📁] 输入消息... [发送] │ ← 输入栏
|
||
└─────────────────────────────────────┘
|
||
```
|
||
|
||
**消息类型展示**:
|
||
| 类型 | 展示方式 |
|
||
|------|----------|
|
||
| 文本 | 气泡+文字 |
|
||
| 图片 | 缩略图，点击预览 |
|
||
| 语音 | 播放条+时长 |
|
||
| 视频 | 封面+播放按钮 |
|
||
| 文件 | 图标+文件名+大小 |
|
||
| 系统 | 居中灰色文字 |
|
||
|
||
### 3.4 联系人页
|
||
|
||
**路径**: `pages/contact/index.vue`
|
||
|
||
```
|
||
┌─────────────────────────────────────┐
|
||
│ 联系人 │
|
||
├─────────────────────────────────────┤
|
||
│ 🔍 搜索 │
|
||
├─────────────────────────────────────┤
|
||
│ ┌─────────────────────────────┐ │
|
||
│ │ [👥] 新朋友 [2] │ │ ← 功能入口
|
||
│ │ [👪] 群聊 │ │
|
||
│ │ [🔔] 群通知 [1] │ │
|
||
│ └─────────────────────────────┘ │
|
||
├─────────────────────────────────────┤
|
||
│ A ───────────────────────── │
|
||
│ │ [头像] 阿明 │ ← 按字母分组
|
||
│ │ [头像] 阿强 │
|
||
│ B ───────────────────────── │
|
||
│ │ [头像] 白云 │
|
||
│ ... │ ← 右侧字母索引
|
||
└─────────────────────────────────────┘
|
||
```
|
||
|
||
### 3.5 朋友圈页
|
||
|
||
**路径**: `pages/moment/index.vue`
|
||
|
||
```
|
||
┌─────────────────────────────────────┐
|
||
│ 朋友圈 │
|
||
├─────────────────────────────────────┤
|
||
│ ┌─────────────────────────────┐ │
|
||
│ │ [封面背景图] │ │
|
||
│ │ [头像] │ │ ← 个人封面区
|
||
│ │ 昵称 │ │
|
||
│ └─────────────────────────────┘ │
|
||
├─────────────────────────────────────┤
|
||
│ ┌─────────────────────────────┐ │
|
||
│ │ [头像] 张三 2小时前 │ │
|
||
│ │ 今天天气真好！ │ │
|
||
│ │ [图片] [图片] [图片] │ │ ← 动态卡片
|
||
│ │ ──────────────────── │ │
|
||
│ │ ❤️ 李四、王五 │ │
|
||
│ │ 李四: 确实不错 │ │
|
||
│ │ [评论输入...] [❤️] │ │
|
||
│ └─────────────────────────────┘ │
|
||
│ ... │
|
||
│ [📷] │ ← 悬浮发布按钮
|
||
└─────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 四、API 接口文档
|
||
|
||
> 基础路径: `/api`，所有接口返回统一格式 `{ code: 0, message: "", result: {} }`
|
||
|
||
### 4.1 认证模块 `/auth`
|
||
|
||
| 接口 | 方法 | 路径 | 参数 | 说明 |
|
||
|------|------|------|------|------|
|
||
| 登录 | POST | `/login` | `{ account, password, remember? }` | 返回 token 和用户信息 |
|
||
| 注册 | POST | `/register` | `{ email, phone, password, confirm_password, code, agree_terms }` | - |
|
||
| 发送邮箱验证码 | POST | `/send-email-code` | `{ target, type: 'email' }` | - |
|
||
| 发送短信验证码 | POST | `/send-sms-code` | `{ target, type: 'sms' }` | - |
|
||
| 检查Token | GET | `/check-token` | - | 验证登录状态 |
|
||
|
||
### 4.2 用户模块 `/user`
|
||
|
||
| 接口 | 方法 | 路径 | 参数 | 说明 |
|
||
|------|------|------|------|------|
|
||
| 获取我的信息 | GET | `/user/my-info` | - | - |
|
||
| 获取用户列表 | GET | `/user/list` | `?page=1&page_size=20` | 分页 |
|
||
| 更新用户信息 | POST | `/user/update` | `{ id, updates: {...} }` | - |
|
||
|
||
### 4.3 联系人模块 `/contacts`
|
||
|
||
| 接口 | 方法 | 路径 | 参数 | 说明 |
|
||
|------|------|------|------|------|
|
||
| 获取联系人列表 | GET | `/contacts` | - | - |
|
||
| 搜索用户 | GET | `/contacts/search` | `?keyword=xxx&limit=20` | - |
|
||
| 添加好友 | POST | `/contacts/add-friend` | `{ to_user_id, message? }` | 发送申请 |
|
||
| 获取好友申请 | GET | `/contacts/friend-requests` | - | - |
|
||
| 接受申请 | POST | `/contacts/accept-request` | `{ request_id }` | - |
|
||
| 拒绝申请 | POST | `/contacts/reject-request` | `{ request_id }` | - |
|
||
| 获取好友详情 | GET | `/contacts/{id}` | - | - |
|
||
| 更新好友信息 | POST | `/contacts/update/{id}` | `{ remark_name?, is_top?, is_muted?, ... }` | - |
|
||
| 删除好友 | POST | `/contacts/delete/{id}` | - | - |
|
||
| 获取分组列表 | GET | `/contacts/groups` | - | - |
|
||
| 创建分组 | POST | `/contacts/groups` | `{ group_name }` | - |
|
||
|
||
### 4.4 会话模块 `/conversations`
|
||
|
||
| 接口 | 方法 | 路径 | 参数 | 说明 |
|
||
|------|------|------|------|------|
|
||
| 获取会话列表 | GET | `/conversations` | - | - |
|
||
| 重置未读数 | POST | `/conversations/reset-unread` | `{ target_id }` | - |
|
||
| 更新会话 | POST | `/conversations/update` | `{ target_id, is_top?, is_muted? }` | - |
|
||
| 删除会话 | POST | `/conversations/delete` | `{ target_id }` | - |
|
||
| 按房间获取会话 | GET | `/conversations/by-room/{roomId}` | - | - |
|
||
|
||
### 4.5 消息模块 `/messages`
|
||
|
||
| 接口 | 方法 | 路径 | 参数 | 说明 |
|
||
|------|------|------|------|------|
|
||
| 发送消息 | POST | `/send` | `{ room_id, message_type, content, duration?, extra? }` | - |
|
||
| 获取历史消息 | GET | `/messages` | `?room_id=xxx&page=1&page_size=50` | - |
|
||
| 同步消息 | GET | `/messages/sync` | `?room_id=xxx&page=1&page_size=50` | - |
|
||
|
||
### 4.6 群聊模块 `/groups`
|
||
|
||
| 接口 | 方法 | 路径 | 参数 | 说明 |
|
||
|------|------|------|------|------|
|
||
| 获取群列表 | GET | `/groups` | - | 带分组信息 |
|
||
| 创建群聊 | POST | `/groups` | `{ name, avatar?, member_ids, admin_ids? }` | - |
|
||
| 获取群信息 | GET | `/groups/{roomId}` | - | - |
|
||
| 获取群成员 | GET | `/groups/{roomId}/members` | `?keyword=xxx` | 可搜索 |
|
||
| 邀请成员 | POST | `/groups/{roomId}/members` | `{ member_ids: [] }` | - |
|
||
| 移除成员 | POST | `/groups/{roomId}/members/{userId}/remove` | - | - |
|
||
| 修改群信息 | POST | `/groups/{roomId}/update` | `{ name?, avatar? }` | - |
|
||
| 修改成员角色 | POST | `/groups/{roomId}/members/{userId}/role` | `{ role: 0\|1\|2 }` | 0成员/1管理/2群主 |
|
||
| 退出群聊 | POST | `/groups/{roomId}/quit` | - | - |
|
||
| 解散群聊 | POST | `/groups/{roomId}/dissolve` | - | 仅群主 |
|
||
| 获取群公告 | GET | `/groups/{roomId}/announcement` | - | - |
|
||
| 更新群公告 | POST | `/groups/{roomId}/announcement` | `{ announcement }` | - |
|
||
| 群通知列表 | GET | `/group-notifications` | `?page=1&page_size=20` | - |
|
||
|
||
### 4.7 朋友圈模块 `/moments`
|
||
|
||
| 接口 | 方法 | 路径 | 参数 | 说明 |
|
||
|------|------|------|------|------|
|
||
| 获取动态列表 | GET | `/moments` | `?page=1&page_size=20` | - |
|
||
| 发布动态 | POST | `/moments` | `{ content, media_type, media_urls?, visibility, ... }` | - |
|
||
| 获取动态详情 | GET | `/moments/{id}` | - | - |
|
||
| 删除动态 | DELETE | `/moments/{id}` | - | 仅自己 |
|
||
| 获取用户动态 | GET | `/moments/user/{userId}` | `?page=1&page_size=20` | - |
|
||
| 点赞 | POST | `/moments/{id}/like` | - | - |
|
||
| 取消点赞 | DELETE | `/moments/{id}/like` | - | - |
|
||
| 获取评论 | GET | `/moments/{id}/comments` | - | - |
|
||
| 发表评论 | POST | `/moments/{id}/comments` | `{ content, reply_to_comment_id? }` | - |
|
||
| 删除评论 | DELETE | `/moments/comments/{commentId}` | - | - |
|
||
| 获取通知 | GET | `/moments/notifications` | `?page=1&page_size=20` | - |
|
||
| 标记已读 | POST | `/moments/notifications/read` | `{ ids?: [], all?: true }` | - |
|
||
| 未读数 | GET | `/moments/notifications/unread-count` | - | - |
|
||
|
||
### 4.8 附件模块 `/attachments`
|
||
|
||
| 接口 | 方法 | 路径 | 参数 | 说明 |
|
||
|------|------|------|------|------|
|
||
| 上传附件 | POST | `/attachments/upload` | FormData: `{ file, type }` | multipart |
|
||
| 获取附件 | GET | `/attachments/{id}` | - | - |
|
||
| 附件列表 | GET | `/attachments` | `?type=xxx&page=1&page_size=20` | - |
|
||
| 删除附件 | POST | `/attachments/delete/{id}` | - | - |
|
||
|
||
### 4.9 系统模块
|
||
|
||
| 接口 | 方法 | 路径 | 参数 | 说明 |
|
||
|------|------|------|------|------|
|
||
| 健康检查 | GET | `/health` | - | - |
|
||
| ICE服务器 | GET | `/ice-servers` | `?user_id=xxx` | WebRTC配置 |
|
||
| 在线状态 | GET | `/check-user-online` | `?user_id=xxx` | - |
|
||
| 绑定客户端 | POST | `/bind` | `{ user_id, client_id }` | WebSocket |
|
||
|
||
---
|
||
|
||
## 五、类型定义
|
||
|
||
### 5.1 基础类型
|
||
|
||
```typescript
|
||
// types/api.ts
|
||
|
||
/** 用户 */
|
||
interface User {
|
||
id: string
|
||
email: string
|
||
phone: string
|
||
name: string
|
||
avatar: string
|
||
desc: string
|
||
region: string
|
||
created_at: string
|
||
updated_at: string
|
||
}
|
||
|
||
/** 联系人 */
|
||
interface Contact {
|
||
id: string
|
||
user_id: string
|
||
contact_user_id: string
|
||
room_id?: string
|
||
room_type?: 'p2p' | 'group'
|
||
is_group?: boolean
|
||
member_count?: number
|
||
owner_id?: string
|
||
remark_name?: string
|
||
group_id?: number
|
||
is_top: boolean
|
||
is_muted: boolean
|
||
is_special_care?: boolean
|
||
is_blocked?: boolean
|
||
user?: User
|
||
}
|
||
|
||
/** 好友申请 */
|
||
interface FriendRequest {
|
||
id: number
|
||
from_user_id: string
|
||
to_user_id: string
|
||
message: string
|
||
status: 'pending' | 'accepted' | 'rejected'
|
||
created_at: string
|
||
from_user?: User
|
||
to_user?: User
|
||
}
|
||
|
||
/** 分页响应 */
|
||
interface PaginatedResponse<T> {
|
||
data: T[]
|
||
total: number
|
||
page: number
|
||
size: number
|
||
}
|
||
```
|
||
|
||
### 5.2 会话类型
|
||
|
||
```typescript
|
||
// types/conversation.ts
|
||
|
||
interface Conversation {
|
||
id: number
|
||
user_id: string
|
||
target_id: string
|
||
type: number // 1:私聊 2:群聊
|
||
room_type?: 'p2p' | 'group'
|
||
room_id?: string
|
||
is_group?: boolean
|
||
member_count?: number
|
||
owner_id?: string
|
||
name?: string
|
||
avatar?: string
|
||
unread_count: number
|
||
is_top: boolean
|
||
is_muted: boolean
|
||
is_special_care?: boolean
|
||
last_message: string
|
||
last_time: number
|
||
target_user?: User
|
||
}
|
||
```
|
||
|
||
### 5.3 消息类型
|
||
|
||
```typescript
|
||
// types/message.ts
|
||
|
||
/** 消息类型枚举 */
|
||
enum MessageType {
|
||
TEXT = 0, // 文本
|
||
IMAGE = 1, // 图片
|
||
AUDIO = 2, // 语音
|
||
VIDEO = 3, // 视频
|
||
SYSTEM = 4, // 系统消息
|
||
FRIEND_NOTIFY = 5, // 好友通知
|
||
SIGNAL = 6, // WebRTC信令
|
||
GROUP_NOTIFY = 7, // 群通知
|
||
FILE = 8, // 文件
|
||
MOMENTS_NOTIFY = 9, // 朋友圈通知
|
||
}
|
||
|
||
/** 聊天消息 */
|
||
interface ChatMessage {
|
||
id: number
|
||
room_id: string
|
||
sender_user_id: string
|
||
receiver_user_id?: string
|
||
message_type: number
|
||
content: string
|
||
duration: number
|
||
extra?: string | Record<string, any>
|
||
created_at: string
|
||
isSelf?: boolean // 前端标记
|
||
}
|
||
|
||
/** 消息扩展信息 */
|
||
interface MessageExtra {
|
||
url?: string // 媒体URL
|
||
name?: string // 文件名
|
||
size?: number // 文件大小
|
||
duration?: number // 时长（秒）
|
||
width?: number // 图片/视频宽
|
||
height?: number // 图片/视频高
|
||
attachment_id?: number
|
||
}
|
||
|
||
/** 发送消息请求 */
|
||
interface SendMessageRequest {
|
||
room_id: string
|
||
message_type: number
|
||
content: string
|
||
duration?: number
|
||
extra?: string
|
||
}
|
||
```
|
||
|
||
### 5.4 朋友圈类型
|
||
|
||
```typescript
|
||
// types/moment.ts
|
||
|
||
/** 动态 */
|
||
interface Moment {
|
||
id: number
|
||
user_id: string
|
||
content: string
|
||
media_type: 0 | 1 | 2 // 0=纯文字 1=图片 2=视频
|
||
media_urls: string[]
|
||
location?: string
|
||
visibility: 0 | 1 | 2 | 3 // 0=公开 1=仅好友 2=部分可见 3=部分不可见
|
||
visible_user_ids?: string[]
|
||
mention_user_ids?: string[]
|
||
like_count: number
|
||
comment_count: number
|
||
created_at: string
|
||
user?: User
|
||
is_liked: boolean
|
||
likes?: MomentLike[]
|
||
comments?: MomentComment[]
|
||
}
|
||
|
||
/** 点赞 */
|
||
interface MomentLike {
|
||
id: number
|
||
moment_id: number
|
||
user_id: string
|
||
created_at: string
|
||
user?: User
|
||
}
|
||
|
||
/** 评论 */
|
||
interface MomentComment {
|
||
id: number
|
||
moment_id: number
|
||
user_id: string
|
||
reply_to_comment_id?: number
|
||
reply_to_user_id?: string
|
||
content: string
|
||
created_at: string
|
||
user?: User
|
||
reply_to_user?: User
|
||
}
|
||
|
||
/** 通知 */
|
||
interface MomentNotification {
|
||
id: number
|
||
user_id: string
|
||
from_user_id: string
|
||
moment_id: number
|
||
type: 1 | 2 | 3 | 4 // 1=点赞 2=评论 3=回复 4=@提及
|
||
comment_id?: number
|
||
is_read: boolean
|
||
created_at: string
|
||
from_user?: User
|
||
moment?: Moment
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 六、状态管理（Pinia Store）
|
||
|
||
### 6.1 Auth Store
|
||
|
||
```typescript
|
||
// stores/auth.ts
|
||
import { defineStore } from 'pinia'
|
||
import { ref } from 'vue'
|
||
import * as authApi from '@/api/modules/auth'
|
||
import * as userApi from '@/api/modules/user'
|
||
import { storage } from '@/utils/storage'
|
||
import type { User, LoginRequest } from '@/types/api'
|
||
|
||
export const useAuthStore = defineStore('auth', () => {
|
||
const token = ref<string | null>(storage.getToken())
|
||
const user = ref<User | null>(storage.getUserInfo())
|
||
const isAuthenticated = ref(!!token.value)
|
||
|
||
async function login(data: LoginRequest) {
|
||
const res = await authApi.login(data)
|
||
token.value = res.token
|
||
user.value = res.user
|
||
isAuthenticated.value = true
|
||
storage.setToken(res.token)
|
||
storage.setUserId(res.user.id)
|
||
storage.setUserInfo(res.user)
|
||
return res
|
||
}
|
||
|
||
async function register(data: any) {
|
||
await authApi.register(data)
|
||
}
|
||
|
||
function logout() {
|
||
token.value = null
|
||
user.value = null
|
||
isAuthenticated.value = false
|
||
storage.clear()
|
||
}
|
||
|
||
async function checkAuth() {
|
||
if (!token.value) return false
|
||
try {
|
||
await authApi.checkToken()
|
||
const userInfo = await userApi.getMyInfo()
|
||
user.value = userInfo
|
||
storage.setUserInfo(userInfo)
|
||
return true
|
||
} catch {
|
||
logout()
|
||
return false
|
||
}
|
||
}
|
||
|
||
function updateUserInfo(userInfo: User) {
|
||
user.value = userInfo
|
||
storage.setUserInfo(userInfo)
|
||
}
|
||
|
||
return {
|
||
token, user, isAuthenticated,
|
||
login, register, logout, checkAuth, updateUserInfo
|
||
}
|
||
})
|
||
```
|
||
|
||
### 6.2 Conversation Store
|
||
|
||
```typescript
|
||
// stores/conversation.ts
|
||
import { defineStore } from 'pinia'
|
||
import { ref, computed } from 'vue'
|
||
import type { Conversation } from '@/types/conversation'
|
||
import * as conversationApi from '@/api/modules/conversation'
|
||
|
||
export const useConversationStore = defineStore('conversation', () => {
|
||
const conversations = ref<Conversation[]>([])
|
||
const loading = ref(false)
|
||
|
||
const totalUnread = computed(() =>
|
||
conversations.value.reduce((acc, c) => acc + (c.is_muted ? 0 : c.unread_count), 0)
|
||
)
|
||
|
||
async function loadConversations() {
|
||
loading.value = true
|
||
try {
|
||
const list = await conversationApi.getConversationList()
|
||
conversations.value = list.map(processConversation).sort(sortByTopAndTime)
|
||
} finally {
|
||
loading.value = false
|
||
}
|
||
}
|
||
|
||
function handleMessageUpdate(message: ChatMessage, isSelf: boolean, isCurrentChat: boolean) {
|
||
// 更新会话最后消息和未读数
|
||
}
|
||
|
||
async function clearUnread(targetId: string) {
|
||
const conv = conversations.value.find(c => c.target_id === targetId || c.room_id === targetId)
|
||
if (conv && conv.unread_count > 0) {
|
||
conv.unread_count = 0
|
||
await conversationApi.resetUnread(targetId)
|
||
}
|
||
}
|
||
|
||
return {
|
||
conversations, loading, totalUnread,
|
||
loadConversations, handleMessageUpdate, clearUnread
|
||
}
|
||
})
|
||
```
|
||
|
||
### 6.3 Chat Store
|
||
|
||
```typescript
|
||
// stores/chat.ts
|
||
import { defineStore } from 'pinia'
|
||
import { ref, computed } from 'vue'
|
||
import type { ChatMessage, Contact } from '@/types/api'
|
||
|
||
export const useChatStore = defineStore('chat', () => {
|
||
const currentTarget = ref<Contact | null>(null)
|
||
const messages = ref<Record<string, ChatMessage[]>>({})
|
||
const contacts = ref<Contact[]>([])
|
||
|
||
const totalUnread = computed(() =>
|
||
contacts.value.reduce((acc, c) => acc + (c.unread || 0), 0)
|
||
)
|
||
|
||
function setCurrentTarget(contact: Contact | null) {
|
||
currentTarget.value = contact
|
||
if (contact) contact.unread = 0
|
||
}
|
||
|
||
function addMessage(roomId: string, message: ChatMessage) {
|
||
if (!messages.value[roomId]) messages.value[roomId] = []
|
||
messages.value[roomId].push(message)
|
||
}
|
||
|
||
function getRoomMessages(roomId: string): ChatMessage[] {
|
||
return messages.value[roomId] || []
|
||
}
|
||
|
||
function setRoomMessages(roomId: string, msgs: ChatMessage[]) {
|
||
messages.value[roomId] = msgs
|
||
}
|
||
|
||
function setContacts(newContacts: Contact[]) {
|
||
contacts.value = newContacts
|
||
}
|
||
|
||
return {
|
||
currentTarget, messages, contacts, totalUnread,
|
||
setCurrentTarget, addMessage, getRoomMessages, setRoomMessages, setContacts
|
||
}
|
||
})
|
||
```
|
||
|
||
### 6.4 Moment Store
|
||
|
||
```typescript
|
||
// stores/moment.ts
|
||
import { defineStore } from 'pinia'
|
||
import { ref, computed } from 'vue'
|
||
import * as momentApi from '@/api/modules/moment'
|
||
import type { Moment, MomentNotification } from '@/types/moment'
|
||
|
||
export const useMomentStore = defineStore('moment', () => {
|
||
const moments = ref<Moment[]>([])
|
||
const currentMoment = ref<Moment | null>(null)
|
||
const notifications = ref<MomentNotification[]>([])
|
||
const unreadCount = ref(0)
|
||
const loading = ref(false)
|
||
const pagination = ref({ page: 1, pageSize: 20, total: 0, hasMore: true })
|
||
|
||
const hasUnread = computed(() => unreadCount.value > 0)
|
||
|
||
async function fetchMoments() {
|
||
loading.value = true
|
||
try {
|
||
const res = await momentApi.getMoments(1, pagination.value.pageSize)
|
||
moments.value = res.data || []
|
||
pagination.value.total = res.total
|
||
pagination.value.hasMore = moments.value.length < res.total
|
||
} finally {
|
||
loading.value = false
|
||
}
|
||
}
|
||
|
||
async function toggleLike(momentId: number) {
|
||
const moment = moments.value.find(m => m.id === momentId)
|
||
if (!moment) return
|
||
if (moment.is_liked) {
|
||
await momentApi.unlikeMoment(momentId)
|
||
moment.is_liked = false
|
||
moment.like_count--
|
||
} else {
|
||
await momentApi.likeMoment(momentId)
|
||
moment.is_liked = true
|
||
moment.like_count++
|
||
}
|
||
}
|
||
|
||
async function addComment(momentId: number, data: { content: string; reply_to_comment_id?: number }) {
|
||
const comment = await momentApi.createComment(momentId, data)
|
||
const moment = moments.value.find(m => m.id === momentId)
|
||
if (moment) {
|
||
if (!moment.comments) moment.comments = []
|
||
moment.comments.push(comment)
|
||
moment.comment_count++
|
||
}
|
||
return comment
|
||
}
|
||
|
||
return {
|
||
moments, currentMoment, notifications, unreadCount, loading, pagination, hasUnread,
|
||
fetchMoments, toggleLike, addComment
|
||
}
|
||
})
|
||
```
|
||
|
||
---
|
||
|
||
## 七、WebSocket 通讯
|
||
|
||
### 7.1 WebSocket 管理器
|
||
|
||
```typescript
|
||
// api/websocket/index.ts
|
||
import type { ChatMessage } from '@/types/api'
|
||
import type { MomentNotifPayload } from '@/types/moment'
|
||
|
||
export interface WebSocketMessage {
|
||
request_type?: string
|
||
clientId?: string
|
||
data?: ChatMessage | MomentNotifPayload
|
||
}
|
||
|
||
export type MessageHandler = (message: ChatMessage) => void
|
||
export type MomentNotifHandler = (payload: MomentNotifPayload) => void
|
||
|
||
class WebSocketManager {
|
||
private socketTask: UniApp.SocketTask | null = null
|
||
private clientId: string | null = null
|
||
private userId: string | null = null
|
||
private messageHandlers: MessageHandler[] = []
|
||
private momentNotifHandlers: MomentNotifHandler[] = []
|
||
private reconnectAttempts = 0
|
||
private maxReconnectAttempts = 5
|
||
private reconnectDelay = 3000
|
||
|
||
connect(userId: string): Promise<void> {
|
||
return new Promise((resolve, reject) => {
|
||
if (this.socketTask) {
|
||
resolve()
|
||
return
|
||
}
|
||
|
||
this.userId = userId
|
||
const wsUrl = `ws://your-server/ws?user_id=${userId}`
|
||
|
||
this.socketTask = uni.connectSocket({
|
||
url: wsUrl,
|
||
success: () => console.log('WebSocket connecting...'),
|
||
fail: (err) => reject(err)
|
||
})
|
||
|
||
this.socketTask.onOpen(() => {
|
||
console.log('WebSocket connected')
|
||
this.reconnectAttempts = 0
|
||
resolve()
|
||
})
|
||
|
||
this.socketTask.onMessage((res) => {
|
||
try {
|
||
const payload: WebSocketMessage = JSON.parse(res.data as string)
|
||
if (payload.clientId) this.clientId = payload.clientId
|
||
if (payload.request_type === 'receive_message' && payload.data) {
|
||
this.messageHandlers.forEach(h => h(payload.data as ChatMessage))
|
||
}
|
||
if (payload.request_type === 'moment_notification' && payload.data) {
|
||
this.momentNotifHandlers.forEach(h => h(payload.data as MomentNotifPayload))
|
||
}
|
||
} catch (e) {
|
||
console.error('Parse message error:', e)
|
||
}
|
||
})
|
||
|
||
this.socketTask.onClose(() => {
|
||
console.log('WebSocket closed')
|
||
this.socketTask = null
|
||
this.attemptReconnect()
|
||
})
|
||
|
||
this.socketTask.onError((err) => {
|
||
console.error('WebSocket error:', err)
|
||
reject(err)
|
||
})
|
||
})
|
||
}
|
||
|
||
disconnect() {
|
||
if (this.socketTask) {
|
||
this.socketTask.close({})
|
||
this.socketTask = null
|
||
}
|
||
this.clientId = null
|
||
this.userId = null
|
||
this.messageHandlers = []
|
||
this.momentNotifHandlers = []
|
||
}
|
||
|
||
getClientId(): string | null {
|
||
return this.clientId
|
||
}
|
||
|
||
onMessage(handler: MessageHandler) {
|
||
if (!this.messageHandlers.includes(handler)) {
|
||
this.messageHandlers.push(handler)
|
||
}
|
||
}
|
||
|
||
offMessage(handler: MessageHandler) {
|
||
const index = this.messageHandlers.indexOf(handler)
|
||
if (index > -1) this.messageHandlers.splice(index, 1)
|
||
}
|
||
|
||
onMomentNotification(handler: MomentNotifHandler) {
|
||
if (!this.momentNotifHandlers.includes(handler)) {
|
||
this.momentNotifHandlers.push(handler)
|
||
}
|
||
}
|
||
|
||
offMomentNotification(handler: MomentNotifHandler) {
|
||
const index = this.momentNotifHandlers.indexOf(handler)
|
||
if (index > -1) this.momentNotifHandlers.splice(index, 1)
|
||
}
|
||
|
||
private attemptReconnect() {
|
||
if (this.reconnectAttempts >= this.maxReconnectAttempts || !this.userId) return
|
||
this.reconnectAttempts++
|
||
setTimeout(() => {
|
||
if (this.userId) this.connect(this.userId).catch(console.error)
|
||
}, this.reconnectDelay)
|
||
}
|
||
}
|
||
|
||
export const wsManager = new WebSocketManager()
|
||
```
|
||
|
||
---
|
||
|
||
## 八、主题系统
|
||
|
||
### 8.1 CSS 变量
|
||
|
||
```scss
|
||
// styles/variables.scss
|
||
page {
|
||
// 浅色主题（默认）
|
||
--color-primary: #07c160;
|
||
--color-danger: #fa5151;
|
||
--color-warning: #ffc300;
|
||
--color-success: #07c160;
|
||
|
||
--bg-page: #ededed;
|
||
--bg-content: #ffffff;
|
||
--bg-hover: #f5f5f5;
|
||
--bg-mask: rgba(0, 0, 0, 0.5);
|
||
|
||
--text-primary: #333333;
|
||
--text-secondary: #666666;
|
||
--text-tertiary: #999999;
|
||
--text-placeholder: #cccccc;
|
||
|
||
--border-color: #e5e5e5;
|
||
--divider-color: #f0f0f0;
|
||
|
||
--nav-bg: #ededed;
|
||
--tabbar-bg: #f7f7f7;
|
||
}
|
||
|
||
page.dark {
|
||
// 暗色主题
|
||
--bg-page: #111111;
|
||
--bg-content: #1e1e1e;
|
||
--bg-hover: #2a2a2a;
|
||
--bg-mask: rgba(0, 0, 0, 0.7);
|
||
|
||
--text-primary: #e5e5e5;
|
||
--text-secondary: #a0a0a0;
|
||
--text-tertiary: #666666;
|
||
--text-placeholder: #444444;
|
||
|
||
--border-color: #333333;
|
||
--divider-color: #2a2a2a;
|
||
|
||
--nav-bg: #1a1a1a;
|
||
--tabbar-bg: #1a1a1a;
|
||
}
|
||
```
|
||
|
||
### 8.2 主题切换
|
||
|
||
```typescript
|
||
// composables/useTheme.ts
|
||
import { ref, watch } from 'vue'
|
||
|
||
const isDark = ref(false)
|
||
|
||
export function useTheme() {
|
||
function initTheme() {
|
||
// 读取缓存
|
||
const cached = uni.getStorageSync('theme')
|
||
if (cached) {
|
||
isDark.value = cached === 'dark'
|
||
} else {
|
||
// 跟随系统
|
||
const info = uni.getSystemInfoSync()
|
||
isDark.value = info.theme === 'dark'
|
||
}
|
||
applyTheme()
|
||
|
||
// 监听系统主题变化
|
||
uni.onThemeChange?.((res) => {
|
||
if (!uni.getStorageSync('theme')) {
|
||
isDark.value = res.theme === 'dark'
|
||
applyTheme()
|
||
}
|
||
})
|
||
}
|
||
|
||
function toggleTheme() {
|
||
isDark.value = !isDark.value
|
||
uni.setStorageSync('theme', isDark.value ? 'dark' : 'light')
|
||
applyTheme()
|
||
}
|
||
|
||
function applyTheme() {
|
||
// 设置页面根元素 class
|
||
// #ifdef H5
|
||
document.documentElement.className = isDark.value ? 'dark' : ''
|
||
// #endif
|
||
|
||
// 设置导航栏颜色
|
||
uni.setNavigationBarColor({
|
||
frontColor: isDark.value ? '#ffffff' : '#000000',
|
||
backgroundColor: isDark.value ? '#1a1a1a' : '#ededed'
|
||
})
|
||
|
||
// 设置 TabBar 样式
|
||
uni.setTabBarStyle({
|
||
backgroundColor: isDark.value ? '#1a1a1a' : '#f7f7f7',
|
||
borderStyle: isDark.value ? 'black' : 'white'
|
||
})
|
||
}
|
||
|
||
return { isDark, initTheme, toggleTheme }
|
||
}
|
||
```
|
||
|
||
### 8.3 使用示例
|
||
|
||
```vue
|
||
<template>
|
||
<view class="container">
|
||
<text class="title">标题</text>
|
||
<text class="desc">描述文字</text>
|
||
</view>
|
||
</template>
|
||
|
||
<style lang="scss" scoped>
|
||
.container {
|
||
background: var(--bg-content);
|
||
padding: 20rpx;
|
||
}
|
||
.title {
|
||
color: var(--text-primary);
|
||
font-size: 32rpx;
|
||
}
|
||
.desc {
|
||
color: var(--text-secondary);
|
||
font-size: 28rpx;
|
||
}
|
||
</style>
|
||
```
|
||
|
||
---
|
||
|
||
## 九、平台适配
|
||
|
||
### 9.1 条件编译
|
||
|
||
```typescript
|
||
// 代码中
|
||
// #ifdef APP-PLUS
|
||
console.log('这是 App')
|
||
// #endif
|
||
|
||
// #ifdef MP-WEIXIN
|
||
console.log('这是微信小程序')
|
||
// #endif
|
||
|
||
// #ifdef H5
|
||
console.log('这是 H5')
|
||
// #endif
|
||
|
||
// #ifndef MP-WEIXIN
|
||
console.log('不是微信小程序的平台')
|
||
// #endif
|
||
```
|
||
|
||
```vue
|
||
<!-- 模板中 -->
|
||
<!-- #ifdef APP-PLUS -->
|
||
<view>仅 App 显示</view>
|
||
<!-- #endif -->
|
||
|
||
<!-- #ifdef MP-WEIXIN -->
|
||
<button open-type="share">分享</button>
|
||
<!-- #endif -->
|
||
```
|
||
|
||
### 9.2 平台工具函数
|
||
|
||
```typescript
|
||
// utils/platform.ts
|
||
|
||
/** 是否 App */
|
||
export function isApp(): boolean {
|
||
// #ifdef APP-PLUS
|
||
return true
|
||
// #endif
|
||
// #ifndef APP-PLUS
|
||
return false
|
||
// #endif
|
||
}
|
||
|
||
/** 是否微信小程序 */
|
||
export function isWeixin(): boolean {
|
||
// #ifdef MP-WEIXIN
|
||
return true
|
||
// #endif
|
||
// #ifndef MP-WEIXIN
|
||
return false
|
||
// #endif
|
||
}
|
||
|
||
/** 选择图片 */
|
||
export function chooseImage(count = 9): Promise<string[]> {
|
||
return new Promise((resolve, reject) => {
|
||
uni.chooseImage({
|
||
count,
|
||
sizeType: ['compressed'],
|
||
sourceType: ['album', 'camera'],
|
||
success: (res) => resolve(res.tempFilePaths),
|
||
fail: reject
|
||
})
|
||
})
|
||
}
|
||
|
||
/** 选择文件 */
|
||
export function chooseFile(): Promise<UniApp.ChooseFileSuccessCallbackResult> {
|
||
return new Promise((resolve, reject) => {
|
||
// #ifdef APP-PLUS
|
||
uni.chooseFile({
|
||
count: 1,
|
||
success: resolve,
|
||
fail: reject
|
||
})
|
||
// #endif
|
||
|
||
// #ifdef MP-WEIXIN
|
||
wx.chooseMessageFile({
|
||
count: 1,
|
||
type: 'file',
|
||
success: resolve,
|
||
fail: reject
|
||
})
|
||
// #endif
|
||
})
|
||
}
|
||
|
||
/** 扫码 */
|
||
export function scanCode(): Promise<string> {
|
||
return new Promise((resolve, reject) => {
|
||
uni.scanCode({
|
||
onlyFromCamera: false,
|
||
success: (res) => resolve(res.result),
|
||
fail: reject
|
||
})
|
||
})
|
||
}
|
||
```
|
||
|
||
### 9.3 存储封装
|
||
|
||
```typescript
|
||
// utils/storage.ts
|
||
const KEYS = {
|
||
TOKEN: 'nl_im_token',
|
||
USER_ID: 'nl_im_user_id',
|
||
USER_INFO: 'nl_im_user_info',
|
||
THEME: 'nl_im_theme',
|
||
}
|
||
|
||
export const storage = {
|
||
// Token
|
||
setToken(token: string) {
|
||
uni.setStorageSync(KEYS.TOKEN, token)
|
||
},
|
||
getToken(): string | null {
|
||
return uni.getStorageSync(KEYS.TOKEN) || null
|
||
},
|
||
removeToken() {
|
||
uni.removeStorageSync(KEYS.TOKEN)
|
||
},
|
||
|
||
// User ID
|
||
setUserId(id: string) {
|
||
uni.setStorageSync(KEYS.USER_ID, id)
|
||
},
|
||
getUserId(): string | null {
|
||
return uni.getStorageSync(KEYS.USER_ID) || null
|
||
},
|
||
|
||
// User Info
|
||
setUserInfo(info: any) {
|
||
uni.setStorageSync(KEYS.USER_INFO, JSON.stringify(info))
|
||
},
|
||
getUserInfo(): any | null {
|
||
const str = uni.getStorageSync(KEYS.USER_INFO)
|
||
return str ? JSON.parse(str) : null
|
||
},
|
||
|
||
// Theme
|
||
setTheme(theme: 'light' | 'dark') {
|
||
uni.setStorageSync(KEYS.THEME, theme)
|
||
},
|
||
getTheme(): 'light' | 'dark' | null {
|
||
return uni.getStorageSync(KEYS.THEME) || null
|
||
},
|
||
|
||
// Clear all
|
||
clear() {
|
||
Object.values(KEYS).forEach(key => uni.removeStorageSync(key))
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 十、UI 组件（wot-design-uni）
|
||
|
||
### 10.1 常用组件
|
||
|
||
| 组件 | 用途 | 示例 |
|
||
|------|------|------|
|
||
| `wd-button` | 按钮 | `<wd-button type="primary">提交</wd-button>` |
|
||
| `wd-input` | 输入框 | `<wd-input v-model="value" placeholder="请输入" />` |
|
||
| `wd-cell` | 单元格 | `<wd-cell title="标题" value="内容" />` |
|
||
| `wd-popup` | 弹出层 | `<wd-popup v-model="show" position="bottom">...</wd-popup>` |
|
||
| `wd-toast` | 轻提示 | `uni.$wot.toast('提示内容')` |
|
||
| `wd-dialog` | 对话框 | `uni.$wot.confirm({ title: '提示', msg: '确定删除？' })` |
|
||
| `wd-action-sheet` | 动作面板 | 底部弹出选项 |
|
||
| `wd-search` | 搜索框 | `<wd-search v-model="keyword" />` |
|
||
| `wd-badge` | 徽标 | `<wd-badge :value="99" />` |
|
||
| `wd-icon` | 图标 | `<wd-icon name="chat" />` |
|
||
| `wd-image` | 图片 | 支持懒加载、预览 |
|
||
| `wd-swipe-action` | 滑动操作 | 左滑删除等 |
|
||
|
||
### 10.2 自动导入配置
|
||
|
||
```typescript
|
||
// vite.config.ts
|
||
import Components from '@uni-helper/vite-plugin-uni-components'
|
||
import { WotResolver } from '@uni-helper/vite-plugin-uni-components/resolvers'
|
||
|
||
export default defineConfig({
|
||
plugins: [
|
||
Components({
|
||
resolvers: [WotResolver()]
|
||
})
|
||
]
|
||
})
|
||
```
|
||
|
||
---
|
||
|
||
## 十一、工具函数
|
||
|
||
### 11.1 格式化函数
|
||
|
||
```typescript
|
||
// utils/format.ts
|
||
|
||
/** 格式化相对时间 */
|
||
export function formatTime(timestamp: number | string): string {
|
||
const date = new Date(timestamp)
|
||
const now = new Date()
|
||
const diff = now.getTime() - date.getTime()
|
||
const seconds = Math.floor(diff / 1000)
|
||
const minutes = Math.floor(seconds / 60)
|
||
const hours = Math.floor(minutes / 60)
|
||
const days = Math.floor(hours / 24)
|
||
|
||
if (seconds < 60) return '刚刚'
|
||
if (minutes < 60) return `${minutes}分钟前`
|
||
if (hours < 24) return `${hours}小时前`
|
||
if (days === 1) return '昨天'
|
||
if (days < 7) return `${days}天前`
|
||
|
||
return date.toLocaleDateString('zh-CN', { month: 'short', day: 'numeric' })
|
||
}
|
||
|
||
/** 格式化文件大小 */
|
||
export function formatSize(bytes: number): string {
|
||
if (!bytes) return '0 B'
|
||
const k = 1024
|
||
const sizes = ['B', 'KB', 'MB', 'GB']
|
||
const i = Math.floor(Math.log(bytes) / Math.log(k))
|
||
return parseFloat((bytes / Math.pow(k, i)).toFixed(2)) + ' ' + sizes[i]
|
||
}
|
||
|
||
/** 格式化时长（秒转 MM:SS） */
|
||
export function formatDuration(seconds: number): string {
|
||
const m = Math.floor(seconds / 60)
|
||
const s = seconds % 60
|
||
return `${m.toString().padStart(2, '0')}:${s.toString().padStart(2, '0')}`
|
||
}
|
||
```
|
||
|
||
### 11.2 消息处理
|
||
|
||
```typescript
|
||
// utils/message.ts
|
||
import { MessageType } from '@/types/message'
|
||
import type { ChatMessage } from '@/types/api'
|
||
|
||
/** 获取消息摘要 */
|
||
export function getMessageSummary(msg: ChatMessage): string {
|
||
switch (msg.message_type) {
|
||
case MessageType.TEXT:
|
||
return msg.content || ''
|
||
case MessageType.IMAGE:
|
||
return '[图片]'
|
||
case MessageType.AUDIO:
|
||
return '[语音]'
|
||
case MessageType.VIDEO:
|
||
return '[视频]'
|
||
case MessageType.FILE:
|
||
return '[文件]'
|
||
case MessageType.SYSTEM:
|
||
case MessageType.GROUP_NOTIFY:
|
||
return msg.content || '[系统消息]'
|
||
default:
|
||
return '[未知消息]'
|
||
}
|
||
}
|
||
|
||
/** 是否系统消息 */
|
||
export function isSystemMessage(type: number): boolean {
|
||
return [
|
||
MessageType.SYSTEM,
|
||
MessageType.FRIEND_NOTIFY,
|
||
MessageType.GROUP_NOTIFY
|
||
].includes(type)
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 十二、开发规范
|
||
|
||
### 12.1 命名规范
|
||
|
||
| 类型 | 规范 | 示例 |
|
||
|------|------|------|
|
||
| 文件夹 | 小写连字符 | `chat-bubble/` |
|
||
| 页面文件 | 小写 | `index.vue`, `detail.vue` |
|
||
| 组件文件 | PascalCase | `MessageBubble.vue` |
|
||
| 变量/函数 | camelCase | `handleSend`, `isLoading` |
|
||
| 常量 | UPPER_SNAKE | `MESSAGE_TYPE`, `API_BASE` |
|
||
| 类型/接口 | PascalCase | `User`, `ChatMessage` |
|
||
| CSS 类名 | BEM 或小写连字符 | `.message-bubble__content` |
|
||
|
||
### 12.2 组件模板
|
||
|
||
```vue
|
||
<template>
|
||
<view class="component-name">
|
||
<!-- 内容 -->
|
||
</view>
|
||
</template>
|
||
|
||
<script setup lang="ts">
|
||
/**
|
||
* 组件名称
|
||
* @description 组件描述
|
||
*/
|
||
import { ref, computed, onMounted } from 'vue'
|
||
|
||
// Props
|
||
interface Props {
|
||
title: string
|
||
disabled?: boolean
|
||
}
|
||
const props = withDefaults(defineProps<Props>(), {
|
||
disabled: false
|
||
})
|
||
|
||
// Emits
|
||
const emit = defineEmits<{
|
||
click: [id: string]
|
||
change: [value: string]
|
||
}>()
|
||
|
||
// State
|
||
const loading = ref(false)
|
||
|
||
// Computed
|
||
const displayTitle = computed(() => props.title.toUpperCase())
|
||
|
||
// Methods
|
||
function handleClick() {
|
||
emit('click', 'some-id')
|
||
}
|
||
|
||
// Lifecycle
|
||
onMounted(() => {
|
||
// 初始化
|
||
})
|
||
</script>
|
||
|
||
<style lang="scss" scoped>
|
||
.component-name {
|
||
// 样式
|
||
}
|
||
</style>
|
||
```
|
||
|
||
### 12.3 Git 提交规范
|
||
|
||
```
|
||
<type>(<scope>): <subject>
|
||
|
||
类型：
|
||
- feat: 新功能
|
||
- fix: 修复 bug
|
||
- docs: 文档变更
|
||
- style: 代码格式（不影响功能）
|
||
- refactor: 重构
|
||
- perf: 性能优化
|
||
- test: 测试
|
||
- chore: 构建/工具变动
|
||
|
||
示例：
|
||
feat(chat): 添加语音消息发送功能
|
||
fix(contact): 修复好友列表不刷新问题
|
||
docs: 更新开发手册
|
||
```
|
||
|
||
---
|
||
|
||
## 十三、快速开始
|
||
|
||
### 13.1 环境准备
|
||
|
||
```bash
|
||
# 安装 Node.js 18+
|
||
# 安装 pnpm
|
||
npm install -g pnpm
|
||
|
||
# 安装 HBuilderX（可选，用于 App 开发）
|
||
```
|
||
|
||
### 13.2 项目启动
|
||
|
||
```bash
|
||
# 进入项目
|
||
cd nl-im-uniapp
|
||
|
||
# 安装依赖
|
||
pnpm install
|
||
|
||
# 开发模式
|
||
pnpm dev # H5
|
||
pnpm dev:mp-weixin # 微信小程序
|
||
pnpm dev:app # App
|
||
|
||
# 构建
|
||
pnpm build:mp-weixin # 微信小程序
|
||
pnpm build:app # App
|
||
```
|
||
|
||
### 13.3 微信小程序调试
|
||
|
||
1. 运行 `pnpm dev:mp-weixin`
|
||
2. 打开**微信开发者工具**
|
||
3. 导入 `dist/dev/mp-weixin` 目录
|
||
4. 填写 AppID
|
||
|
||
### 13.4 App 调试
|
||
|
||
1. 运行 `pnpm dev:app`
|
||
2. 打开 HBuilderX
|
||
3. 运行到手机或模拟器
|
||
|
||
---
|
||
|
||
## 十四、功能清单
|
||
|
||
### 已规划功能
|
||
|
||
| 模块 | 功能 | 优先级 | 状态 |
|
||
|------|------|--------|------|
|
||
| 基础 | 项目框架搭建 | P0 | 待开发 |
|
||
| 基础 | 主题系统（浅色/暗色） | P0 | 待开发 |
|
||
| 基础 | API 请求封装 | P0 | 待开发 |
|
||
| 基础 | WebSocket 适配 | P0 | 待开发 |
|
||
| 基础 | Pinia Store | P0 | 待开发 |
|
||
| 登录 | 登录/注册页 | P0 | 待开发 |
|
||
| 首页 | 会话列表 | P0 | 待开发 |
|
||
| 首页 | 左侧抽屉 | P1 | 待开发 |
|
||
| 首页 | 加号菜单 | P1 | 待开发 |
|
||
| 聊天 | 聊天详情页 | P0 | 待开发 |
|
||
| 聊天 | 多类型消息展示 | P0 | 待开发 |
|
||
| 聊天 | 消息输入框 | P0 | 待开发 |
|
||
| 聊天 | 图片/文件发送 | P1 | 待开发 |
|
||
| 聊天 | 语音消息 | P2 | 待开发 |
|
||
| 联系人 | 联系人列表 | P0 | 待开发 |
|
||
| 联系人 | 好友详情 | P1 | 待开发 |
|
||
| 联系人 | 添加好友 | P1 | 待开发 |
|
||
| 联系人 | 好友申请 | P1 | 待开发 |
|
||
| 群聊 | 群聊列表 | P1 | 待开发 |
|
||
| 群聊 | 创建群聊 | P1 | 待开发 |
|
||
| 群聊 | 群信息/成员管理 | P2 | 待开发 |
|
||
| 朋友圈 | 动态列表 | P1 | 待开发 |
|
||
| 朋友圈 | 发布动态 | P1 | 待开发 |
|
||
| 朋友圈 | 点赞/评论 | P1 | 待开发 |
|
||
| 朋友圈 | 消息通知 | P2 | 待开发 |
|
||
| 设置 | 个人资料 | P1 | 待开发 |
|
||
| 设置 | 设置页 | P2 | 待开发 |
|
||
| 高级 | 消息推送 | P2 | 待开发 |
|
||
| 高级 | 语音/视频通话 | P3 | 待开发 |
|
||
|
||
---
|
||
|
||
## 附录
|
||
|
||
### A. 相关资源
|
||
|
||
- [UniApp 官方文档](https://uniapp.dcloud.net.cn/)
|
||
- [wot-design-uni 组件库](https://wot-design-uni.cn/)
|
||
- [Pinia 文档](https://pinia.vuejs.org/)
|
||
- [Vue 3 文档](https://cn.vuejs.org/)
|
||
|
||
### B. 后端 API 文档
|
||
|
||
请参考 `nl-im-vue-ts` 项目或后端接口文档。
|
||
|
||
### C. 更新日志
|
||
|
||
| 日期 | 版本 | 更新内容 |
|
||
|------|------|----------|
|
||
| 2024-12-08 | v0.1.0 | 初始化开发手册 |
|