Skip to content

theme-system.md

Latest commit

 

History

History
92 lines (68 loc) · 3.69 KB

theme-system.md

File metadata and controls

92 lines (68 loc) · 3.69 KB
Raw

主题系统 (3.0)

Running Page 3.0 引入了可插拔的主题架构。你可以切换内置主题或创建自己的主题，无需修改源代码。

工作原理

主题位于 src/themes/<name>/ 目录下，每个主题导出一个 React 组件。应用入口 (src/App.tsx) 维护一个主题注册表，将主题名称映射到懒加载的组件：

// src/App.tsx
const themes: Record<string, React.LazyExoticComponent<React.ComponentType>> = {
  dashboard: lazy(() => import('./themes/dashboard')),
  classic: lazy(() => import('./themes/classic')),
  // 在此添加自定义主题
}

构建时，config.yml 中的 theme_preset 决定加载哪个主题。所有主题共享核心层 (src/core/)——类型、i18n 翻译、活动数据钩子和语言工具。

内置主题

Dashboard

Dashboard 主题是为跑者设计的现代化单页布局，提供丰富的小部件：

  • 统计卡片 — 年度/月度/周度进度条，含连续运动追踪
  • 热力图 — GitHub 风格的活动网格，每日详情，支持导出 PNG
  • 活动日志 — 分页表格，支持距离筛选（10km+、20km+、40km+），运动类型图标
  • 路线地图 — 基于 Mapbox 的路线可视化，点击活动高亮轨迹
  • 轨迹墙 — 全页轨迹网格，智能聚类（按起终点），支持导出 PNG
  • 中国地图 — 省份级活动热力图，点击筛选
  • 个人最佳 — 自动检测 PR（5K、10K、半马、全马）
  • 日历小部件 — 月度日历，气泡显示距离
  • 深色/浅色模式 — 跟随系统或手动切换

主要特性：

  • 所有数据在一个页面展示（无需路由跳转）
  • 点击任意活动即可在地图和日志中查看
  • 热力图和轨迹墙支持导出为 PNG 图片
  • 响应式两栏网格布局

Classic

Classic 主题保留了原始的多页面布局，每个视图有独立路由。使用 react-router-dom 导航和 react-map-gl 地图。如果你更喜欢原始风格，或从 v2.x 升级，推荐选择此主题。

注意： 如果你从 v2.x 升级，可在 config.yml 中设置 theme_preset: classic。

创建自定义主题

  1. 在 src/themes/<your-theme>/ 下创建新目录，例如 src/themes/minimal/
  2. 创建 index.tsx 导出默认 React 组件
  3. 使用共享核心层获取数据和 i18n：
// src/themes/minimal/index.tsx
import { getActivityData } from '@/hooks/useActivities'
import { useTheme } from '@/hooks/useTheme'
import { useLocale } from '@/hooks/useLocale'
import type { Activity } from '@/types'

export default function Minimal() {
  const activities = getActivityData() as Activity[]
  const { t } = useLocale()
  // ... 你的自定义布局
}
  1. 在 src/App.tsx 中注册你的主题：
const themes = {
  dashboard: lazy(() => import('./themes/dashboard')),
  classic: lazy(() => import('./themes/classic')),
  minimal: lazy(() => import('./themes/minimal')), // 添加这行
}
  1. 在 config.yml 中设置 theme_preset: minimal

共享核心层 API

所有主题可用的钩子和工具：

模块 导出
@/hooks/useActivities getActivityData()、useFilteredActivities()、getAvailableYears()、formatDistance()、formatPace()、formatDuration()、parseMovingTime()、extractProvince()
@/hooks/useLocale useLocale() → { t, locale } 用于 i18n
@/hooks/useTheme useTheme() → { dark, toggle } 用于深/浅色模式
@/types Activity、SportFilter 类型
@/config MAPBOX_TOKEN、AVATAR、GOALS、DEFAULT_LOCALE、THEME_PRESET

Dashboard 主题的组件 (src/components/) 也可复用 —— 如需要可在自定义主题中导入。