mirror of https://github.com/Moe-Sakura/frontend.git synced 2026-03-15 04:53:18 +08:00

Files

AdingApkgg 052f9c5ed9 feat: 添加环境变量支持与PWA功能增强

* 更新 `.gitignore` 文件以包含环境变量文件 `.env` 和相关配置。
* 在 `env.d.ts` 中定义环境变量类型，支持 API 配置、功能开关和主题设置。
* 更新 `index.html`，添加 PWA 相关的 manifest 和 meta 标签，提升应用的安装体验。
* 引入 `lazysizes` 和 `quicklink` 以优化图片加载和链接预加载，提升性能。
* 更新多个组件以使用新的 UI 状态管理，确保一致性和可读性。
* 删除不再使用的 Font Awesome 图标，替换为 lucide-vue-next 图标，提升视觉一致性。
* 更新 `README.md`，添加环境变量配置说明和项目文档链接。

2025-11-27 18:21:09 +08:00

6.1 KiB

Raw Blame History

Pinia Store 使用指南

SearchGal 使用 Pinia 进行状态管理，已充分优化和模块化。

Store 模块

1. Search Store (`useSearchStore`)

用途：管理搜索相关的状态和逻辑

import { useSearchStore } from '@/stores'

const searchStore = useSearchStore()

// 状态
searchStore.searchQuery      // 搜索关键词
searchStore.searchMode        // 搜索模式 ('game' | 'patch')
searchStore.platformResults   // 平台搜索结果
searchStore.vndbInfo          // VNDB 游戏信息
searchStore.isSearching       // 是否正在搜索
searchStore.searchProgress    // 搜索进度

// 计算属性
searchStore.hasResults        // 是否有搜索结果
searchStore.isVndbMode        // 是否为 VNDB 模式
searchStore.searchDisabled    // 是否禁用搜索（冷却时间）

// 方法
searchStore.setSearchQuery('关键词')
searchStore.setSearchMode('game')
searchStore.startSearch()
searchStore.endSearch()
searchStore.setPlatformResult('platform', data)
searchStore.loadMoreResults('platform', 20)
searchStore.clearResults()

2. UI Store (`useUIStore`)

用途：管理UI相关状态（主题、模态框、通知等）

import { useUIStore } from '@/stores'

const uiStore = useUIStore()

// 主题
uiStore.isDarkMode
uiStore.toggleDarkMode()
uiStore.setDarkMode(true)

// 模态框
uiStore.isCommentsModalOpen
uiStore.isVndbPanelOpen
uiStore.isSettingsModalOpen
uiStore.toggleCommentsModal()
uiStore.closeAllModals()

// Toast 通知
uiStore.showToast('success', '操作成功！', 3000)
uiStore.showToast('error', '操作失败！')

// 浮动按钮
uiStore.showScrollToTop
uiStore.showPlatformNav
uiStore.togglePlatformNav()

// 加载状态
uiStore.setLoading(true, '加载中...')
uiStore.setLoading(false)

3. Settings Store (`useSettingsStore`)

用途：管理用户设置

import { useSettingsStore } from '@/stores'

const settingsStore = useSettingsStore()

// 访问设置
settingsStore.settings.customApi
settingsStore.settings.autoLoadMore
settingsStore.settings.resultsPerPage

// 更新单个设置
settingsStore.updateSetting('resultsPerPage', 20)

// 批量更新
settingsStore.updateSettings({
  customApi: 'https://api.example.com',
  autoLoadMore: true,
})

// 重置设置
settingsStore.resetSettings()

// 导入导出
const json = settingsStore.exportSettings()
settingsStore.importSettings(json)

4. History Store (`useHistoryStore`)

用途：管理搜索历史

import { useHistoryStore } from '@/stores'

const historyStore = useHistoryStore()

// 访问历史
historyStore.searchHistory        // 所有历史
historyStore.recentHistory        // 最近10条
historyStore.popularQueries       // 热门查询

// 添加历史
historyStore.addHistory({
  query: '关键词',
  mode: 'game',
  resultCount: 10,
})

// 删除历史
historyStore.removeHistory(0)
historyStore.removeHistoryByQuery('关键词')
historyStore.clearHistory()

// 搜索历史
const results = historyStore.searchInHistory('关键词')

// 统计信息
const stats = historyStore.getHistoryStats()

5. Cache Store (`useCacheStore`)

用途：管理缓存数据

import { useCacheStore } from '@/stores'

const cacheStore = useCacheStore()

// VNDB 缓存
cacheStore.cacheVndbInfo('query', vndbData)
const cached = cacheStore.getVndbInfo('query')
const hasCache = cacheStore.hasVndbCache('query')

// 搜索结果缓存
cacheStore.cacheSearchResults('query', 'game', results)
const results = cacheStore.getSearchResults('query', 'game')

// 清理缓存
cacheStore.clearVndbCache()
cacheStore.clearSearchCache()
cacheStore.clearAllCache()
cacheStore.cleanExpiredCache() // 清理过期缓存

// 缓存统计
const stats = cacheStore.getCacheStats()

Store 插件

开发环境日志

在开发环境自动记录所有 action 调用和状态变化

性能监控

自动记录每个 action 的执行时间和调用次数

// 获取性能统计
const stats = searchStore.getPerformanceStats()
console.log(stats)
// {
//   startSearch: { calls: 5, avgDuration: '12.50ms', totalDuration: '62.50ms' },
//   ...
// }

错误处理

自动捕获和记录 store 中的错误

最佳实践

1. 组件中使用 Store

<script setup lang="ts">
import { useSearchStore, useUIStore } from '@/stores'

const searchStore = useSearchStore()
const uiStore = useUIStore()

// 使用 computed 访问状态
const hasResults = computed(() => searchStore.hasResults)

// 调用 actions
function handleSearch() {
  searchStore.startSearch()
  // ...
  searchStore.endSearch()
}
</script>

2. Store 之间通信

// 在 searchStore 中使用 historyStore
const historyStore = useHistoryStore()
const cacheStore = useCacheStore()

// 搜索完成后添加历史
historyStore.addHistory({...})

// 使用缓存
const cached = cacheStore.getVndbInfo(query)
if (cached) {
  // 使用缓存数据
}

3. 响应式更新

// ✅ 正确：使用 ref 或 computed
const searchQuery = computed(() => searchStore.searchQuery)

// ❌ 错误：直接解构会失去响应性
const { searchQuery } = searchStore

// ✅ 正确：使用 storeToRefs
import { storeToRefs } from 'pinia'
const { searchQuery } = storeToRefs(searchStore)

4. 性能优化

// 使用缓存避免重复请求
function searchGame(query: string) {
  // 检查缓存
  const cached = cacheStore.getSearchResults(query, 'game')
  if (cached) {
    searchStore.setPlatformResult('platform', cached)
    return
  }
  
  // 执行搜索并缓存结果
  // ...
}

调试技巧

1. Vue DevTools

安装 Vue DevTools 扩展，可以实时查看所有 store 的状态

2. 控制台日志

开发环境会自动记录所有 action 和状态变化

3. 性能分析

// 在控制台查看性能统计
console.log(useSearchStore().getPerformanceStats())
console.log(useCacheStore().getCacheStats())
console.log(useHistoryStore().getHistoryStats())

4. 手动清理

// 清除所有缓存
useCacheStore().clearAllCache()

// 清除历史记录
useHistoryStore().clearHistory()

// 重置设置
useSettingsStore().resetSettings()

6.1 KiB Raw Blame History Unescape Escape