仓库卡片

相关源文件

• api/index.js
• api/pin.js
• src/cards/repo-card.js
• tests/pin.test.js
• tests/renderRepoCard.test.js
• tests/top-langs.test.js
• tests/utils.test.js

仓库卡片（也称为“pin card”）是一个动态 SVG 组件，可以以一种视觉上吸引人的方式展示 GitHub 仓库。用户可以将这些卡片嵌入到他们的 GitHub README 文件中，以突出特定仓库，显示诸如仓库名称、描述、主要语言、星数和关注数等关键信息。

有关 GitHub Readme Stats 系统中其他卡片类型的信息，请参阅

• 统计卡片 统计卡片
• 热门语言卡片 热门语言卡片
• WakaTime 卡片 WakaTime 卡片
• Gist 卡片 Gist 卡片

概述

仓库卡片系统遵循请求-处理-渲染的流程。当用户将仓库卡片嵌入其 README 时，会向 `/api/pin` 端点发出请求，该端点从 GitHub 的 API 获取仓库数据并返回生成的 SVG 图像。

仓库卡片示例

https://github-readme-stats.vercel.app/api/pin/?username=anuraghazra&repo=github-readme-stats

渲染为显示仓库信息的 SVG 卡片。

系统流程图

来源：api/pin.js12-105 src/cards/repo-card.js57-91

API 端点

仓库卡片通过 `/api/pin` 端点访问，该端点处理用户请求并返回生成的 SVG。

查询参数

参数	描述	默认
username	仓库所有者的 GitHub 用户名	必填
repo	仓库名称	必填
title_color	卡片标题颜色	基于主题
text_color	正文文本颜色	基于主题
icon_color	图标颜色	基于主题
bg_color	背景颜色	基于主题
hide_border	隐藏卡片边框	false
theme	主题名称	"default_repocard"
border_color	卡片边框颜色	基于主题
border_radius	圆角半径	4.5
show_owner	显示包含所有者的完整仓库名称	false
description_lines_count	要显示的描述行数	最多 3 行
locale	翻译的语言代码	英语

来源：api/pin.js12-29

API 请求流程

来源：api/pin.js12-105

仓库数据获取

系统从 GitHub 的 GraphQL API 获取仓库数据。数据结构包含关于仓库的全面信息。

仓库数据结构

来源：src/cards/repo-card.js57-67 tests/renderRepoCard.test.js9-22

卡片渲染

renderRepoCard 函数根据仓库数据和用户指定的选项生成 SVG 卡片。

卡片结构

来源：src/cards/repo-card.js57-191

渲染详情

渲染过程处理几个方面

1. 标题渲染：显示仓库名称（如果请求了，则显示所有者）
2. 描述处理:
   • 解析描述中的表情符号
   • 将文本包裹以适应卡片宽度
   • 将描述限制为指定的行数
3. 统计信息显示:
   • 带颜色指示器的主要语言
   • 星数（使用“k”表示千）
   • 关注数
4. 徽章渲染：在适用时显示“已归档”或“模板”徽章
5. 样式:
   • 应用基于主题或自定义颜色
   • 控制边框显示
   • 根据内容设置卡片尺寸

来源：src/cards/repo-card.js82-107 src/cards/repo-card.js113-151

卡片组件详解

描述处理

对描述进行处理，确保其在卡片内妥善显示

1. 如果未提供描述，则显示“未提供描述”
2. 长描述将被换行（默认最多 3 行）
3. 描述中的表情符号会被正确解析和渲染
4. 卡片高度将根据描述长度进行调整

来源：src/cards/repo-card.js90-106 tests/renderRepoCard.test.js92-102 tests/renderRepoCard.test.js146-160

语言和统计信息显示

卡片使用灵活的布局系统显示仓库统计信息

1. 主要语言：显示带颜色指示符的语言名称
2. 星数：显示带星形图标的星数
3. 关注数：显示带关注图标的关注数

这些元素仅在可用时显示（例如，语言可能为 null，零星/关注数将被隐藏）。

来源：src/cards/repo-card.js123-150 tests/renderRepoCard.test.js248-274

主题系统集成

仓库卡片与主题系统集成，可在不同卡片间提供一致的样式。

主题应用

1. 用户可以使用 `theme` 参数指定主题
2. 每个主题都为各种卡片元素定义了颜色
3. 自定义颜色可以覆盖主题的默认设置
4. 无效颜色将回退到主题默认值

来源：src/cards/repo-card.js108-121 tests/renderRepoCard.test.js175-199 tests/renderRepoCard.test.js201-221

国际化

仓库卡片支持文本元素的本地化

1. 徽章文本（“已归档”、“模板”）会根据 locale 进行翻译
2. 错误消息可以本地化
3. 回退文本（例如，“未提供描述”）会进行本地化

来源：src/cards/repo-card.js108-111 tests/renderRepoCard.test.js298-321 api/pin.js44-54

使用示例

要将仓库卡片添加到您的 GitHub README 中，请使用以下 markdown

自定义示例

显示仓库所有者

https://github-readme-stats.vercel.app/api/pin/?username=anuraghazra&repo=github-readme-stats&show_owner=true

自定义主题

https://github-readme-stats.vercel.app/api/pin/?username=anuraghazra&repo=github-readme-stats&theme=radical

自定义颜色

https://github-readme-stats.vercel.app/api/pin/?username=anuraghazra&repo=github-readme-stats&title_color=f00&icon_color=0f0&text_color=00f&bg_color=fff

来源：tests/renderRepoCard.test.js46-53 tests/renderRepoCard.test.js147-221

错误处理

仓库卡片系统处理各种错误情况

1. 缺少必需的参数（username，repo）
2. 黑名单用户名
3. 无效的 locale
4. 未找到仓库（针对用户或组织）

发生错误时，将渲染一个错误卡片而不是仓库卡片。

来源：api/pin.js32-54 api/pin.js88-104 tests/pin.test.js98-203

实现细节

卡片高度计算

卡片高度根据描述长度动态调整

• 基础高度：110px（单行描述）
• 每增加一行描述，高度增加 10px
• 通过 `description_lines_count` 参数可以控制最大描述行数

来源： src/cards/repo-card.js104-106 tests/renderRepoCard.test.js343-371

文本截断

为了保持卡片的视觉美观

1. 长度超过 35 个字符的仓库名称将以省略号截断
2. 描述会换行以适应卡片宽度
3. 如果描述超过最大行数，将以省略号截断

来源： src/cards/repo-card.js153 tests/renderRepoCard.test.js55-89

测试

仓库卡片系统拥有全面的测试

1. 渲染测试：验证所有卡片元素的正确渲染
2. API 测试：验证 API 端点的行为
3. 边缘情况测试：测试特殊情况的处理（空描述、缺失语言等）
4. 主题测试：验证主题的应用
5. 自定义测试：验证自定义选项是否正常工作

来源： tests/renderRepoCard.test.js1-372 tests/pin.test.js1-204