wenzi/frontend

🦟 蚊子项目 - 增强版Vue 3组件库

这是蚊子项目的Vue 3增强版组件库，提供完整的错误处理、加载状态管理和更好的用户体验。

✨ 新增特性

• 🔒 错误处理: 全面的错误处理和用户友好的错误提示
• ⏳ 加载状态: 自动加载状态管理和骨架屏
• 🔄 重试机制: 自动重试和手动重试功能
• 🎨 主题系统: 支持明暗主题切换
• 📱 响应式设计: 完全响应式布局
• ♿ 无障碍支持: 支持键盘导航和屏幕阅读器
• 🔧 TypeScript: 完整的TypeScript类型定义

📦 安装

npm install @mosquito/vue-enhanced
# 或
yarn add @mosquito/vue-enhanced
# 或
pnpm add @mosquito/vue-enhanced

🚀 快速开始

1. 安装插件

// 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. 基础使用

<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	获取分享链接失败

示例

<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	-	海报加载成功

示例

<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	排行榜加载失败

示例

<MosquitoLeaderboard
  :activity-id="activityId"
  :page="currentPage"
  :size="20"
  :top-n="10"
  :current-user-id="currentUserId"
  @loaded="handleLeaderboardLoaded"
  @error="handleLeaderboardError"
/>

🔧 高级用法

错误处理

<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>

加载状态管理

<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>

主题配置

// main.ts
import MosquitoEnhancedPlugin from '@mosquito/vue-enhanced'

app.use(MosquitoEnhancedPlugin, {
  // ...其他配置
  defaultTheme: 'dark', // 或 'light'
  locale: 'en-US' // 或 'zh-CN'
})

🧪 测试

# 运行单元测试
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. 联系我们的技术支持团队