338 lines
9.1 KiB
Markdown
338 lines
9.1 KiB
Markdown
# 系统公告功能使用说明
|
||
|
||
## 功能概述
|
||
|
||
本次更新为项目添加了完整的系统公告弹窗功能，包括活动展示、公告通知、轮播图等。用户可以通过不同的关闭选项来控制弹窗的显示频率。
|
||
|
||
---
|
||
|
||
## 已实现的功能
|
||
|
||
### 1. 系统公告弹窗
|
||
|
||
- **自动弹出**: 用户进入应用时自动检测并显示公告弹窗
|
||
- **手动打开**: 右上角有公告按钮（铃铛图标），随时可以点击打开公告弹窗
|
||
- **未读提示**: 公告按钮上显示红色徽章，标识最新公告数量
|
||
- **Tab切换**: 支持"活动"和"公告"两个Tab页面
|
||
- **关闭选项**: 提供三种关闭方式
|
||
- 今日关闭：24小时内不再自动弹出，但仍可通过按钮手动打开
|
||
- 本周关闭：7天内不再自动弹出，但仍可通过按钮手动打开
|
||
- 关闭公告：永久不再自动弹出（除非清除浏览器缓存），但仍可通过按钮手动打开
|
||
|
||
### 2. 活动页面
|
||
|
||
- **轮播图**: 顶部展示活动轮播图，支持自动播放
|
||
- **活动列表**: 显示所有活动，包含标题、简介、状态标签
|
||
- **状态标识**:
|
||
- 进行中：绿色标签
|
||
- 已结束：灰色标签
|
||
- **查看详情**: 点击可跳转到活动详情页面
|
||
|
||
### 3. 公告页面
|
||
|
||
- **最新公告**: 顶部显示最新发布的公告，带蓝色边框高亮
|
||
- **重要标识**: 重要公告显示警告图标
|
||
- **历史公告**: 使用时间线形式展示历史公告
|
||
- **查看详情**: 点击可跳转到公告详情页面
|
||
|
||
### 4. 详情页面
|
||
|
||
#### 活动详情页面
|
||
- 活动标题和状态
|
||
- 浏览次数和参与人数
|
||
- 活动封面图
|
||
- 活动简介
|
||
- 活动时间信息（开始、结束、发布、更新时间）
|
||
- 完整的活动内容（支持HTML格式）
|
||
|
||
#### 公告详情页面
|
||
- 公告标题和类型
|
||
- 重要公告标识（带动画效果）
|
||
- 浏览次数
|
||
- 发布时间
|
||
- 完整的公告内容（支持HTML格式）
|
||
- 创建和更新时间
|
||
|
||
---
|
||
|
||
## 文件结构
|
||
|
||
```
|
||
Yi.Ai.Vue3/
|
||
├── src/
|
||
│ ├── api/
|
||
│ │ └── announcement/
|
||
│ │ ├── index.ts # API接口定义
|
||
│ │ └── types.ts # TypeScript类型定义
|
||
│ ├── components/
|
||
│ │ └── SystemAnnouncementDialog/
|
||
│ │ └── index.vue # 系统公告弹窗组件
|
||
│ ├── layouts/
|
||
│ │ └── components/
|
||
│ │ └── Header/
|
||
│ │ ├── components/
|
||
│ │ │ └── AnnouncementBtn.vue # 公告按钮组件（新增）
|
||
│ │ └── index.vue # Header组件（已更新）
|
||
│ ├── pages/
|
||
│ │ ├── activity/
|
||
│ │ │ └── detail.vue # 活动详情页面
|
||
│ │ └── announcement/
|
||
│ │ └── detail.vue # 公告详情页面
|
||
│ ├── stores/
|
||
│ │ └── modules/
|
||
│ │ └── announcement.ts # 公告状态管理
|
||
│ ├── data/
|
||
│ │ └── mockAnnouncementData.ts # 模拟数据
|
||
│ ├── routers/
|
||
│ │ └── modules/
|
||
│ │ └── staticRouter.ts # 路由配置（已更新）
|
||
│ ├── utils/
|
||
│ │ └── request.ts # HTTP请求工具（已修复Pinia初始化问题）
|
||
│ └── App.vue # 主应用文件（已更新）
|
||
├── 系统公告API接口文档.md # API接口文档
|
||
└── 系统公告功能使用说明.md # 本文档
|
||
```
|
||
|
||
---
|
||
|
||
## 如何使用
|
||
|
||
### 开发环境测试（使用模拟数据）
|
||
|
||
1. **导入模拟数据**
|
||
|
||
在 `src/App.vue` 中临时替换API调用：
|
||
|
||
```typescript
|
||
// 导入模拟数据函数
|
||
import { getMockSystemAnnouncements } from '@/data/mockAnnouncementData'
|
||
|
||
// 替换 getSystemAnnouncements() 为 getMockSystemAnnouncements()
|
||
onMounted(async () => {
|
||
if (announcementStore.shouldShowDialog) {
|
||
try {
|
||
// 使用模拟数据
|
||
const res = await getMockSystemAnnouncements()
|
||
if (res.data) {
|
||
announcementStore.setAnnouncementData(res.data)
|
||
announcementStore.openDialog()
|
||
}
|
||
}
|
||
catch (error) {
|
||
console.error('获取系统公告失败:', error)
|
||
}
|
||
}
|
||
})
|
||
```
|
||
|
||
2. **同样的方式更新详情页面**
|
||
|
||
在 `src/pages/activity/detail.vue` 和 `src/pages/announcement/detail.vue` 中也可以使用模拟数据函数进行测试。
|
||
|
||
3. **启动开发服务器**
|
||
|
||
```bash
|
||
npm run dev
|
||
```
|
||
|
||
4. **测试功能**
|
||
|
||
- 打开浏览器访问应用
|
||
- 应该会自动弹出系统公告弹窗
|
||
- 测试不同的关闭选项
|
||
- 点击"查看详情"按钮测试跳转
|
||
|
||
### 生产环境部署（使用真实API）
|
||
|
||
1. **后端实现API接口**
|
||
|
||
参考 `系统公告API接口文档.md` 实现以下三个接口：
|
||
- `GET /announcement/system` - 获取系统公告数据
|
||
- `GET /announcement/activity/{id}` - 获取活动详情
|
||
- `GET /announcement/detail/{id}` - 获取公告详情
|
||
|
||
2. **确认API调用**
|
||
|
||
确保 `src/App.vue` 和详情页面使用的是真实的API函数（默认配置）：
|
||
- `getSystemAnnouncements()`
|
||
- `getActivityDetail(id)`
|
||
- `getAnnouncementDetail(id)`
|
||
|
||
3. **构建部署**
|
||
|
||
```bash
|
||
npm run build
|
||
```
|
||
|
||
---
|
||
|
||
## 自定义配置
|
||
|
||
### 修改关闭时间
|
||
|
||
在 `src/stores/modules/announcement.ts` 中修改时间计算逻辑：
|
||
|
||
```typescript
|
||
const shouldShowDialog = computed(() => {
|
||
// ... 现有代码
|
||
|
||
if (closeType.value === 'today') {
|
||
// 修改为其他时间，如12小时
|
||
return elapsed > 12 * 60 * 60 * 1000
|
||
}
|
||
|
||
if (closeType.value === 'week') {
|
||
// 修改为其他时间，如3天
|
||
return elapsed > 3 * 24 * 60 * 60 * 1000
|
||
}
|
||
|
||
// ... 现有代码
|
||
})
|
||
```
|
||
|
||
### 修改弹窗样式
|
||
|
||
在 `src/components/SystemAnnouncementDialog/index.vue` 中修改样式：
|
||
|
||
- 修改弹窗宽度：`width="700px"` 改为其他值
|
||
- 修改轮播图高度：`height="250px"` 改为其他值
|
||
- 修改CSS样式：在 `<style>` 部分进行调整
|
||
|
||
### 添加新的Tab页
|
||
|
||
1. 在弹窗组件中添加新的 `<el-tab-pane>`
|
||
2. 添加对应的数据类型定义
|
||
3. 更新API接口和store
|
||
|
||
---
|
||
|
||
## 管理功能
|
||
|
||
### 手动触发弹窗
|
||
|
||
用户可以通过以下方式打开公告弹窗：
|
||
|
||
1. **点击右上角公告按钮**（推荐）
|
||
- 位于Header右侧的铃铛图标
|
||
- 显示未读公告数量的红色徽章
|
||
- 点击即可打开公告弹窗
|
||
|
||
2. **在代码中手动调用**
|
||
|
||
在任何组件中可以手动打开公告弹窗：
|
||
|
||
```typescript
|
||
import { useAnnouncementStore } from '@/stores'
|
||
|
||
const announcementStore = useAnnouncementStore()
|
||
|
||
// 打开弹窗
|
||
announcementStore.openDialog()
|
||
```
|
||
|
||
### 重置关闭状态
|
||
|
||
如果需要重置用户的关闭状态（例如有重要公告需要强制显示）：
|
||
|
||
```typescript
|
||
// 重置关闭状态
|
||
announcementStore.resetCloseStatus()
|
||
|
||
// 然后重新打开弹窗
|
||
announcementStore.openDialog()
|
||
```
|
||
|
||
### 查看当前状态
|
||
|
||
```typescript
|
||
const announcementStore = useAnnouncementStore()
|
||
|
||
// 查看是否应该显示弹窗
|
||
console.log(announcementStore.shouldShowDialog)
|
||
|
||
// 查看关闭类型
|
||
console.log(announcementStore.closeType)
|
||
|
||
// 查看关闭时间
|
||
console.log(announcementStore.closedAt)
|
||
```
|
||
|
||
---
|
||
|
||
## 注意事项
|
||
|
||
1. **XSS防护**: 公告和活动内容使用 `v-html` 渲染，请确保后端返回的HTML内容是安全的，建议进行内容过滤和转义。
|
||
|
||
2. **图片资源**: 轮播图和封面图需要可访问的URL地址，建议使用CDN。
|
||
|
||
3. **性能优化**:
|
||
- 弹窗数据会在应用启动时加载，确保接口响应快速
|
||
- 考虑添加加载状态和错误处理
|
||
|
||
4. **响应式设计**: 当前设计主要针对PC端，如需移动端适配，需要调整样式和布局。
|
||
|
||
5. **浏览器兼容**: 使用了现代CSS特性，建议在主流现代浏览器中使用。
|
||
|
||
6. **状态持久化**: 关闭状态存储在 localStorage 中，清除浏览器缓存会重置状态。
|
||
|
||
---
|
||
|
||
## 后续优化建议
|
||
|
||
1. **数据统计**: 添加打点统计，记录用户查看公告的行为
|
||
2. **推送通知**: 对重要公告支持浏览器推送通知
|
||
3. **多语言支持**: 支持国际化（i18n）
|
||
4. **个性化推荐**: 根据用户兴趣推荐相关活动
|
||
5. **评论功能**: 允许用户对活动和公告进行评论
|
||
6. **分享功能**: 支持将活动和公告分享到社交媒体
|
||
7. **搜索功能**: 添加公告和活动的搜索功能
|
||
8. **管理后台**: 开发管理后台用于创建和管理公告活动
|
||
|
||
---
|
||
|
||
## 技术栈
|
||
|
||
- **Vue 3.5.17**: 核心框架，使用 Composition API
|
||
- **TypeScript**: 类型安全
|
||
- **Element Plus**: UI组件库
|
||
- **Pinia**: 状态管理，支持持久化
|
||
- **Vue Router 4**: 路由管理
|
||
- **Vite**: 构建工具
|
||
|
||
---
|
||
|
||
## 问题排查
|
||
|
||
### 弹窗不显示
|
||
|
||
1. 检查 `announcementStore.shouldShowDialog` 的值
|
||
2. 检查API是否返回数据
|
||
3. 查看浏览器控制台是否有错误
|
||
4. 尝试调用 `announcementStore.resetCloseStatus()` 重置状态
|
||
|
||
### 详情页面404
|
||
|
||
1. 确认路由配置是否正确
|
||
2. 检查路由名称是否匹配
|
||
3. 确认ID参数是否正确传递
|
||
|
||
### 样式显示异常
|
||
|
||
1. 检查Element Plus是否正确安装
|
||
2. 确认 SCSS 预处理器是否配置
|
||
3. 清除浏览器缓存重试
|
||
|
||
---
|
||
|
||
## 联系支持
|
||
|
||
如有问题或建议，请通过以下方式联系：
|
||
|
||
- GitHub Issues
|
||
- 项目文档
|
||
- 技术支持团队
|
||
|
||
---
|
||
|
||
**祝使用愉快！**
|