在 Devin 中试用 DeepWiki 处理私有仓库
DeepWiki

anuraghazra/github-readme-stats

菜单

WakaTime 卡片

相关源文件

本文档介绍了 GitHub Readme Stats 项目中的 WakaTime 卡片子系统。WakaTime 卡片生成 SVG 卡片，显示用户在 WakaTime（一个面向开发者的时间跟踪服务）上的编码统计数据。有关系统中其他卡片类型的信息，请参阅 统计卡片、仓库卡片 和 热门语言卡片。

概述

WakaTime 卡片组件集成了 WakaTime 的 API，用于获取用户的编程时间统计数据，并将其渲染为可嵌入 GitHub README 文件的 SVG 卡片。它显示诸如特定时间段内的总编码时间和最常用的编程语言等统计信息。

来源：api/wakatime.js1-109

API 端点

WakaTime 卡片 API 端点在 /api/wakatime.js 文件中实现。该端点处理 HTTP 请求、提取查询参数、从 WakaTime 获取数据并返回渲染后的 SVG 卡片。

请求参数

该端点接受许多查询参数来定制卡片

参数描述
usernameWakaTime 用户名（必需）
api_domain自定义 WakaTime API 域名（可选）
hide_title是否隐藏卡片标题
hide_border是否隐藏卡片边框
custom_title卡片的自定义标题
hide_progress是否隐藏进度条
layout卡片布局样式
langs_count要显示的语言数量
hide要隐藏的特定项目列表
theme用于样式的颜色主题名称
bg_color背景颜色
title_color标题颜色
text_color文本颜色
icon_color图标颜色
border_color边框颜色
border_radius边框圆角
line_height文本行高
locale翻译的本地化设置
display_format时间统计的显示格式
disable_animations是否禁用动画

来源：api/wakatime.js12-35

请求处理

该端点的处理流程如下

  1. 提取并验证查询参数
  2. 为 SVG 响应设置合适的标头
  3. 如果提供了本地化设置，则验证本地化设置
  4. 使用 fetchWakatimeStats 函数获取 WakaTime 统计数据
  5. 根据配置设置缓存标头
  6. 使用 renderWakatimeCard 函数渲染并返回 SVG 卡片
  7. 处理错误并在必要时渲染错误卡片

来源：api/wakatime.js37-108

数据获取

WakaTime 卡片使用 src/fetchers/wakatime-fetcher.js 中的 fetchWakatimeStats 函数从 WakaTime API 获取统计数据。此函数

  1. 使用提供的用户名构建适当的 WakaTime API URL
  2. 向 WakaTime API 发送 HTTP 请求
  3. 将响应数据处理成适合卡片渲染的格式
  4. 处理错误情况和 API 限制

获取器返回结构化数据，其中包含

  • 总编码时间
  • 语言统计信息（名称、百分比、花费时间）
  • 时间段信息

来源：api/wakatime.js9 api/wakatime.js52

卡片渲染

src/cards/wakatime-card.js 中的 renderWakatimeCard 函数生成 WakaTime 卡片的 SVG 标记。与 Gist 卡片类似（供参考），渲染过程

  1. 处理 WakaTime 统计数据
  2. 应用颜色主题和样式自定义
  3. 根据内容计算布局尺寸
  4. 生成标题、进度条和统计数据的 SVG 元素
  5. 使用通用的 Card 组件作为容器
  6. 处理文本元素的国际化

卡片可视化通常包括

  • 标题部分（用户的 WakaTime 个人资料名称或自定义标题）
  • 带进度条的语言统计信息
  • 总编码时间信息
  • 基于所选颜色主题的视觉样式

来源：api/wakatime.js1 api/wakatime.js70-90

自定义功能

WakaTime 卡片通过查询参数支持广泛的自定义。主要自定义功能包括

主题化

卡片可以使用颜色主题系统中定义的任何颜色主题。颜色主题系统提供了应用于各种卡片元素的配色方案。

国际化

卡片文本可以根据提供的本地化设置进行翻译，使用与国际化中描述的相同的国际化系统。

布局选项

卡片支持用于显示语言统计信息的不同布局选项，这会影响进度条和百分比的排列方式。

内容过滤

用户可以使用 hide 参数自定义要在卡片上显示或隐藏的元素，以过滤特定语言或统计信息。

来源：api/wakatime.js70-90

错误处理

WakaTime 卡片实现包括强大的错误处理

  1. 无效本地化检测和相应的错误消息
  2. WakaTime API 错误（无效用户名、API 限制）
  3. 渲染错误和描述性消息
  4. 缩短错误响应的缓存时间，以便更快恢复

发生错误时，系统将渲染一个错误卡片，其中显示错误消息而不是统计信息。

来源：api/wakatime.js39-49 api/wakatime.js92-107

缓存策略

为了优化性能并减少 API 调用，WakaTime 卡片实现了一个缓存策略

  1. 默认缓存时长由 CONSTANTS.CARD_CACHE_SECONDS 值决定
  2. 缓存时间限制在 6 小时到 2 天之间
  3. 服务器端缓存使用 s-maxage 配置
  4. 使用 stale-while-revalidate 模式，容忍期为一天
  5. 环境变量可以覆盖默认缓存设置
  6. 错误响应使用较短的缓存时间（CONSTANTS.ERROR_CACHE_SECONDS）

此策略平衡了数据的时效性、性能和 API 速率限制。

来源：api/wakatime.js54-68 api/wakatime.js93-98