Gist 卡片

相关源文件

• api/gist.js
• api/wakatime.js
• src/cards/gist-card.js

目的与范围

本文详细介绍了 GitHub Readme Stats 中的 Gist 卡组件，该组件用于生成显示 GitHub Gist 信息的 SVG 卡片。Gist 卡片显示特定 GitHub Gist 的信息，包括其名称、描述、语言、星标数和分支数。有关其他卡片类型的信息，请参阅 卡片生成系统。

系统概览

Gist 卡片系统遵循 GitHub Readme Stats 项目中其他卡片的模式，包括 API 端点、数据获取器和渲染器。

来源：api/gist.js11-89 src/cards/gist-card.js44-149

API 端点

Gist 卡可通过 /api/gist 端点访问。该端点负责参数解析、错误处理、缓存以及数据获取器和渲染器之间的协调。

所需参数

• id：要显示的 GitHub Gist ID

可选参数

Gist 卡通过查询参数支持多种自定义选项。

来源：api/gist.js12-25

数据获取过程

该端点使用 fetchGist 函数从 GitHub API 检索指定 Gist 的数据。

获取的 Gist 数据包括：

• name：Gist 的名称
• nameWithOwner：包含所有者用户名的名称
• description：Gist 描述
• language：Gist 使用的主要语言
• starsCount：星标数
• forksCount：分支数

来源：api/gist.js42 src/cards/gist-card.js45-46

渲染过程

src/cards/gist-card.js 中的 renderGistCard 函数负责渲染 Gist 卡。它处理 Gist 数据和自定义选项以生成 SVG 图像。

渲染过程：

1. 获取带有正确覆盖的基于主题的颜色
2. 处理并换行描述文本
3. 根据描述长度计算卡片高度
4. 格式化星标和分支计数
5. 创建具有适当颜色的语言节点
6. 使用 flex 布局排列组件
7. 创建带有标题和图标的卡片基础
8. 应用 CSS 样式
9. 渲染最终 SVG

来源：src/cards/gist-card.js44-149

卡片结构

Gist 卡遵循特定的布局结构。

卡片的关键组件：

1. 标题：显示 Gist 名称，可选择包含所有者的用户名。
2. 描述：显示 Gist 描述，如有必要则换行显示。
3. 统计数据：显示使用的语言、星标数和分支数。

标题的最大长度为 35 个字符，之后会用省略号截断。

来源：src/cards/gist-card.js29-31 src/cards/gist-card.js113-131 src/cards/gist-card.js140-148

卡片自定义

Gist 卡可通过各种查询参数进行自定义。

参数	描述	默认
title_color	卡片标题的颜色	基于主题
icon_color	图标颜色	基于主题
text_color	文本颜色	基于主题
bg_color	背景颜色	基于主题
theme	要使用的主题名称	默认主题
border_radius	卡片的圆角半径	默认半径
border_color	卡片边框的颜色	基于主题
show_owner	是否显示 Gist 所有者的用户名	false
hide_border	是否隐藏卡片边框	false
locale	本地化语言	null（默认语言）

有关主题和其他自定义选项的更多详细信息，请参阅 自定义。

来源：api/gist.js12-25 src/cards/gist-card.js47-57

实现细节

文本处理

Gist 卡实现了多项文本处理功能：

1. 描述换行：长描述会被换行至多 10 行。
2. 标题截断：长度超过 35 个字符的标题将被截断并显示省略号。
3. Emoji 解析：描述中的 Emoji 会被正确解析。
4. HTML 编码：文本会经过适当编码，以防止 SVG 注入。

来源：src/cards/gist-card.js71-77 src/cards/gist-card.js116-119

动态尺寸调整

卡片的高度会根据描述的长度进行调整。

• 单行描述的基本高度为 110px。
• 描述超过 3 行时，每行增加 12px。
• 描述有 1-3 行时，每行增加 10px。

来源：src/cards/gist-card.js79-81

统计数据格式化

统计数据已格式化以方便阅读。

• 大数字会缩写（例如：1000 → 1k）。
• 为星标和分支添加了图标。
• 统计数据使用 flex 布局进行适当间距排列。

来源：src/cards/gist-card.js83-111

使用示例

要在 GitHub README 中使用 Gist 卡：

带自定义项

错误处理

Gist 卡端点实现了对常见问题的错误处理。

1. 无效的 Gist ID：返回一个带有 GitHub API 消息的错误卡片。
2. 无效的 locale：返回一个表示语言未找到的错误卡片。
3. GitHub API 问题：返回一个带有具体错误消息的错误卡片。

错误卡片的缓存时间比成功响应的缓存时间短。

来源：api/gist.js29-39 api/gist.js72-88

缓存机制

Gist 卡实现了缓存以提高性能并减少 GitHub API 的负载。

• 默认缓存时长：2 天
• 最大缓存时长：6 天
• 错误缓存时长：比成功响应的缓存时间短得多。
• 缓存时长可以通过 cache_seconds 参数进行自定义，但有范围限制。

来源：api/gist.js44-56