91a0b77f7a
- 修改 shouldVerifyCacheManager_withMaximumIntegerTtl 为 shouldVerifyCacheManager_withMaximumAllowedTtl - 使用正确的最大TTL值（10080分钟，7天）而不是 Integer.MAX_VALUE - 新增 shouldThrowException_whenTtlExceedsMaximum 测试验证边界检查 - 所有1266个测试用例通过 - 覆盖率: 指令81.89%, 行88.48%, 分支51.55% docs: 添加项目状态报告 - 生成 PROJECT_STATUS_REPORT.md 详细记录项目当前状态 - 包含质量指标、已完成功能、待办事项和技术债务
369 lines
7.8 KiB
Markdown
369 lines
7.8 KiB
Markdown
# 🦟 蚊子项目 - 增强版Vue 3组件库
|
||
|
||
这是蚊子项目的Vue 3增强版组件库，提供完整的错误处理、加载状态管理和更好的用户体验。
|
||
|
||
## ✨ 新增特性
|
||
|
||
- 🔒 **错误处理**: 全面的错误处理和用户友好的错误提示
|
||
- ⏳ **加载状态**: 自动加载状态管理和骨架屏
|
||
- 🔄 **重试机制**: 自动重试和手动重试功能
|
||
- 🎨 **主题系统**: 支持明暗主题切换
|
||
- 📱 **响应式设计**: 完全响应式布局
|
||
- ♿ **无障碍支持**: 支持键盘导航和屏幕阅读器
|
||
- 🔧 **TypeScript**: 完整的TypeScript类型定义
|
||
|
||
## 📦 安装
|
||
|
||
```bash
|
||
npm install @mosquito/vue-enhanced
|
||
# 或
|
||
yarn add @mosquito/vue-enhanced
|
||
# 或
|
||
pnpm add @mosquito/vue-enhanced
|
||
```
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 1. 安装插件
|
||
|
||
```typescript
|
||
// main.ts
|
||
import { createApp } from 'vue'
|
||
import App from './App.vue'
|
||
import MosquitoEnhancedPlugin from '@mosquito/vue-enhanced'
|
||
import '@mosquito/vue-enhanced/style.css'
|
||
|
||
const app = createApp(App)
|
||
|
||
// 安装插件并配置
|
||
app.use(MosquitoEnhancedPlugin, {
|
||
baseUrl: 'https://api.your-domain.com',
|
||
apiKey: 'your-api-key',
|
||
timeout: 10000,
|
||
retryCount: 3,
|
||
enableLogging: true,
|
||
defaultTheme: 'light',
|
||
locale: 'zh-CN'
|
||
})
|
||
|
||
app.mount('#app')
|
||
```
|
||
|
||
### 2. 基础使用
|
||
|
||
```vue
|
||
<template>
|
||
<div>
|
||
<MosquitoShareButton
|
||
:activity-id="activityId"
|
||
:user-id="userId"
|
||
:template="'default'"
|
||
text="立即分享"
|
||
variant="primary"
|
||
size="lg"
|
||
@copied="onCopied"
|
||
@error="onError"
|
||
/>
|
||
|
||
<MosquitoPosterCard
|
||
:activity-id="activityId"
|
||
:user-id="userId"
|
||
:template="'premium'"
|
||
width="350px"
|
||
height="500px"
|
||
@click="onPosterClick"
|
||
@error="onPosterError"
|
||
@loaded="onPosterLoaded"
|
||
/>
|
||
|
||
<MosquitoLeaderboard
|
||
:activity-id="activityId"
|
||
:page="0"
|
||
:size="20"
|
||
:top-n="10"
|
||
:current-user-id="currentUserId"
|
||
@loaded="onLeaderboardLoaded"
|
||
@error="onLeaderboardError"
|
||
/>
|
||
</div>
|
||
</template>
|
||
|
||
<script setup lang="ts">
|
||
import { ref } from 'vue'
|
||
import { useMosquito, MosquitoError } from '@mosquito/vue-enhanced'
|
||
|
||
const activityId = ref(1)
|
||
const userId = ref(100)
|
||
const currentUserId = ref(100)
|
||
|
||
const { config, getShareUrl, getPosterImage, getLeaderboard } = useMosquito()
|
||
|
||
// 分享按钮事件
|
||
const onCopied = () => {
|
||
showToast('分享链接已复制到剪贴板')
|
||
}
|
||
|
||
const onError = (error: MosquitoError) => {
|
||
console.error('分享失败:', error)
|
||
showError('分享失败，请稍后重试')
|
||
}
|
||
|
||
// 海报卡片事件
|
||
const onPosterClick = () => {
|
||
console.log('海报被点击')
|
||
}
|
||
|
||
const onPosterError = (error: MosquitoError) => {
|
||
console.error('海报加载失败:', error)
|
||
showError('海报加载失败')
|
||
}
|
||
|
||
const onPosterLoaded = () => {
|
||
console.log('海报加载成功')
|
||
}
|
||
|
||
// 排行榜事件
|
||
const onLeaderboardLoaded = (entries: any[]) => {
|
||
console.log('排行榜数据:', entries)
|
||
}
|
||
|
||
const onLeaderboardError = (error: MosquitoError) => {
|
||
console.error('排行榜加载失败:', error)
|
||
showError('排行榜加载失败')
|
||
}
|
||
|
||
// 工具函数
|
||
const showToast = (message: string) => {
|
||
// 实现Toast提示
|
||
}
|
||
|
||
const showError = (message: string) => {
|
||
// 实现错误提示
|
||
}
|
||
</script>
|
||
```
|
||
|
||
## 📖 组件文档
|
||
|
||
### MosquitoShareButton
|
||
|
||
增强版的分享按钮组件，支持加载状态、错误处理和多种样式。
|
||
|
||
#### Props
|
||
|
||
| 属性 | 类型 | 默认值 | 说明 |
|
||
|------|------|--------|------|
|
||
| activityId | `number` | - | 活动ID（必需） |
|
||
| userId | `number` | - | 用户ID（必需） |
|
||
| template | `string` | 'default' | 分享模板 |
|
||
| text | `string` | '分享给好友' | 按钮文字 |
|
||
| disabled | `boolean` | false | 是否禁用 |
|
||
| variant | `'default'\|'primary'\|'secondary'\|'success'\|'danger' | 'primary' | 按钮样式 |
|
||
| size | `'sm'\|'md'\|'lg' | 'md' | 按钮大小 |
|
||
|
||
#### 事件
|
||
|
||
| 事件 | 参数 | 说明 |
|
||
|------|------|------|
|
||
| copied | - | 链接已复制到剪贴板 |
|
||
| error | `Error` | 获取分享链接失败 |
|
||
|
||
#### 示例
|
||
|
||
```vue
|
||
<MosquitoShareButton
|
||
:activity-id="activityId"
|
||
:user-id="userId"
|
||
variant="success"
|
||
size="lg"
|
||
@copied="handleCopy"
|
||
@error="handleError"
|
||
/>
|
||
```
|
||
|
||
### MosquitoPosterCard
|
||
|
||
增强版的海报展示组件，支持加载状态、错误处理和重试机制。
|
||
|
||
#### Props
|
||
|
||
| 属性 | 类型 | 默认值 | 说明 |
|
||
|------|------|--------|------|
|
||
| activityId | `number` | - | 活动ID（必需） |
|
||
| userId | `number` | - | 用户ID（必需） |
|
||
| template | `string` | 'default' | 海报模板 |
|
||
| width | `string` | '300px' | 宽度 |
|
||
| height | `string` | '400px' | 高度 |
|
||
|
||
#### 事件
|
||
|
||
| 事件 | 参数 | 说明 |
|
||
|------|------|------|
|
||
| click | - | 海报被点击 |
|
||
| error | `Error` | 海报加载失败 |
|
||
| loaded | - | 海报加载成功 |
|
||
|
||
#### 示例
|
||
|
||
```vue
|
||
<MosquitoPosterCard
|
||
:activity-id="activityId"
|
||
:user-id="userId"
|
||
template="premium"
|
||
width="350px"
|
||
height="500px"
|
||
@click="openPosterModal"
|
||
@error="handlePosterError"
|
||
@loaded="onPosterLoaded"
|
||
/>
|
||
```
|
||
|
||
### MosquitoLeaderboard
|
||
|
||
增强版的排行榜组件，支持分页、错误处理、高亮当前用户等功能。
|
||
|
||
#### Props
|
||
|
||
| 属性 | 类型 | 默认值 | 说明 |
|
||
|------|------|--------|------|
|
||
| activityId | `number` | - | 活动ID（必需） |
|
||
| page | `number` | 0 | 页码 |
|
||
| size | `number` | 20 | 每页大小 |
|
||
| topN | `number` | 10 | 显示前N名 |
|
||
| currentUserId | `number` | undefined | 当前用户ID |
|
||
|
||
#### 事件
|
||
|
||
| 事件 | 参数 | 说明 |
|
||
|------|------|------|
|
||
| loaded | `entries[]` | 排行榜数据加载完成 |
|
||
| error | `Error` | 排行榜加载失败 |
|
||
|
||
#### 示例
|
||
|
||
```vue
|
||
<MosquitoLeaderboard
|
||
:activity-id="activityId"
|
||
:page="currentPage"
|
||
:size="20"
|
||
:top-n="10"
|
||
:current-user-id="currentUserId"
|
||
@loaded="handleLeaderboardLoaded"
|
||
@error="handleLeaderboardError"
|
||
/>
|
||
```
|
||
|
||
## 🔧 高级用法
|
||
|
||
### 错误处理
|
||
|
||
```vue
|
||
<template>
|
||
<MosquitoShareButton
|
||
:activity-id="activityId"
|
||
:user-id="userId"
|
||
@error="handleError"
|
||
/>
|
||
</template>
|
||
|
||
<script setup lang="ts">
|
||
import { MosquitoError } from '@mosquito/vue-enhanced'
|
||
|
||
const handleError = (error: MosquitoError) => {
|
||
if (error.code === 'TIMEOUT') {
|
||
showError('请求超时，请检查网络连接')
|
||
} else if (error.code === 'RATE_LIMITED') {
|
||
showError('请求过于频繁，请稍后再试')
|
||
} else {
|
||
showError('操作失败，请稍后重试')
|
||
}
|
||
}
|
||
</script>
|
||
```
|
||
|
||
### 加载状态管理
|
||
|
||
```vue
|
||
<template>
|
||
<div>
|
||
<button
|
||
:disabled="loadingManager.isLoading('create-activity')"
|
||
@click="createActivity"
|
||
>
|
||
创建活动
|
||
</button>
|
||
|
||
<MosquitoLeaderboard
|
||
:activity-id="activityId"
|
||
@loaded="onLoaded"
|
||
@error="onError"
|
||
/>
|
||
</div>
|
||
</template>
|
||
|
||
<script setup lang="ts">
|
||
import { useMosquito } from '@mosquito/vue-enhanced'
|
||
|
||
const { loadingManager } = useMosquito()
|
||
|
||
const createActivity = async () => {
|
||
const unsubscribe = loadingManager.onLoadingChange('create-activity', (loading) => {
|
||
console.log('创建活动状态:', loading)
|
||
})
|
||
|
||
try {
|
||
// 创建活动逻辑
|
||
} finally {
|
||
unsubscribe()
|
||
}
|
||
}
|
||
</script>
|
||
```
|
||
|
||
### 主题配置
|
||
|
||
```typescript
|
||
// main.ts
|
||
import MosquitoEnhancedPlugin from '@mosquito/vue-enhanced'
|
||
|
||
app.use(MosquitoEnhancedPlugin, {
|
||
// ...其他配置
|
||
defaultTheme: 'dark', // 或 'light'
|
||
locale: 'en-US' // 或 'zh-CN'
|
||
})
|
||
```
|
||
|
||
## 🧪 测试
|
||
|
||
```bash
|
||
# 运行单元测试
|
||
npm run test
|
||
|
||
# 运行端到端测试
|
||
npm run test:e2e
|
||
|
||
# 运行类型检查
|
||
npm run type-check
|
||
```
|
||
|
||
## 📄 许可证
|
||
|
||
MIT License
|
||
|
||
## 🤝 贡献
|
||
|
||
欢迎提交Issue和Pull Request！
|
||
|
||
1. Fork本项目
|
||
2. 创建功能分支 (`git checkout -b feature/AmazingFeature`)
|
||
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
|
||
4. 推送到分支 (`git push origin feature/AmazingFeature`)
|
||
5. 创建Pull Request
|
||
|
||
## 📞 支持
|
||
|
||
如果您在使用过程中遇到问题，请：
|
||
|
||
1. 查看文档和FAQ
|
||
2. 提交GitHub Issue
|
||
3. 联系我们的技术支持团队 |