Firefly 分类页面美化

📖 概述#

/categories/ 是博客的分类标签聚合页面。改造前是一个简单的卡片网格；我们将它升级为包含分类玫瑰图 + 标签关系图谱的现代化可视化页面。

本文整理了改造过程中新增/修改的文件、采用的方法以及关键代码片段。

📂 文件清单#

新增文件（5 个）#

路径	作用
`src/utils/tag-graph-data.ts`	标签共现图谱构建算法
`src/components/common/PageTitle.astro`	通用页面标题组件（stacked / inline）
`src/components/widget/CategoryRose.astro`	分类玫瑰图 + 列表
`src/components/widget/TagGraph.astro`	标签关系图谱
`src/styles/pages/categories.css`	分类页专属样式

修改文件（9 个）#

路径	改动
`src/pages/categories/index.astro`	重写为薄壳路由页，仅组合子组件
`src/utils/content-utils.ts`	新增 `getTagGraphData()`
`src/styles/main.css`	引入 `./pages/categories.css`
`src/i18n/i18nKey.ts`	新增 8 个枚举 key
`src/i18n/languages/zh_CN.ts`	中文简体翻译
`src/i18n/languages/zh_TW.ts`	中文繁体翻译
`src/i18n/languages/en.ts`	英文翻译
`src/i18n/languages/ja.ts`	日文翻译
`src/i18n/languages/ru.ts`	俄文翻译

🛠️ 方法 & 关键代码#

1. 数据层：标签共现图谱算法#

新建 src/utils/tag-graph-data.ts，核心思路是遍历文章 → 聚合标签 → 枚举组合生成边。

1
// 伪代码
2
function buildTagGraphData(posts, getTagUrl, threshold = 2) {
3
  for (const post of posts) {
4
    const tags = unique(post.data.tags);
5
    // 节点：每个标签的 value = 文章数，posts = 文章列表
6
    for (const tag of tags) nodeMap[tag].value += 1;
7
    // 边：任意两标签组合，统计共现次数
8
    for (let i = 0; i < tags.length; i++)
9
      for (let j = i + 1; j < tags.length; j++)
10
        edgeMap[`${min(a,b)}\0${max(a,b)}`] += 1;
11
  }
12
  // 过滤掉 value < threshold 的边
13
  return { nodes, links, threshold };
14
}

然后在 content-utils.ts 中暴露一个面向页面的封装：

1
export async function getTagGraphData(threshold = 2) {
2
  const posts = await getSortedPostsList();
3
  return buildTagGraphData(posts, getTagUrl, threshold);
4
}

2. 通用标题组件 `PageTitle.astro`#

支持 stacked（eyebrow 在上、title 在下）和 inline（横排）两种变体，BEM 命名，CSS 变量绑定主题色。

1
---
2
interface Props {
3
  title: string;
4
  eyebrow?: string;
5
  variant?: "stacked" | "inline";
6
}
7
const { title, eyebrow, variant = "stacked" } = Astro.props;
8
---
9
<div class:list={["page-title", `page-title--${variant}`]}>
10
  {eyebrow && <span class="page-title__eyebrow">{eyebrow}</span>}
11
  <h1 class="page-title__title">{title}</h1>
12
</div>

3. CategoryRose 玫瑰图#

ECharts 配置要点（南丁格尔玫瑰图 + 暗色适配）：

1
{
2
  tooltip: { trigger: "item", /* 显示百分比 */ },
3
  series: [{
4
    type: "pie",
5
    radius: ["20%", "75%"],
6
    roseType: "area",           // 玫瑰图核心
7
    itemStyle: { borderRadius: 6 },
8
    label: { color: isDark() ? "..." : "..." },
9
    data: [...],
10
    animationType: "scale",     // 入场动画
11
    animationDelay: i => i * 100
12
  }]
13
}

CDN 延迟加载 + 全局只绑定一次监听（防止 Swup 路由切换导致重复绑定）：

1
if (!window.__categoryRoseBound) {
2
  window.__categoryRoseBound = true;
3
  document.addEventListener("astro:page-load", ensureEchartsThenInit);
4
  document.addEventListener("swup:contentReplaced", ensureEchartsThenInit);
5
  document.addEventListener("swup:willReplaceContent", destroyCategoryRose);
6
}

销毁逻辑：dispose chart + disconnect observer + remove resize 监听，避免内存泄漏。

主题切换：用 MutationObserver 监听 <html> 的 class 变化，重新 setOption() 重算颜色。

4. TagGraph 力导向图#

ECharts 配置要点（type: graph + layout: force）：

1
{
2
  tooltip: { /* 节点/边不同 formatter */ },
3
  legend: { data: ["高频", "常用", "低频"] },
4
  series: [{
5
    type: "graph",
6
    layout: "force",
7
    roam: true,            // 可拖拽缩放
8
    draggable: true,
9
    focusNodeAdjacency: true,  // 悬停聚焦
10
    emphasis: { focus: "adjacency", /* 线条变粗 */ },
11
    blur: { opacity: 0.15 },  // 非邻节点灰化
12
    force: { repulsion: 220, edgeLength: [60, 160] },
13
    categories: [...],     // 3 个分类
14
    data: nodes, links: links
15
  }]
16
}

节点大小（24~78px 之间，用 sqrt 避免小节点过小）：

1
function nodeSymbolSize(value) {
2
  const scaled = Math.sqrt(value) * 14;
3
  return Math.max(24, Math.min(78, scaled));
4
}

节点颜色按文章数分档：

文章数	类别	颜色
`value >= 5`	高频	`#fb7185`（红）
`value >= 2`	常用	`#fbbf24`（黄）
`value < 2`	低频	`#94a3b8`（灰）

5. 路由页面（薄壳）#

src/pages/categories/index.astro 仅 30 行左右，负责并行取数据 + 组合组件：

1
---
2
const [categories, tagGraph] = await Promise.all([
3
  getCategoryList(),
4
  getTagGraphData(),
5
]);
6
---
7
<MainGridLayout title={i18n(I18nKey.categoriesPageTitle)}>
8
  <div class="categories-page card-base">
9
    <PageTitle title={...} eyebrow="Taxonomy" variant="stacked" />
10
    <CategoryRose categories={categories} />
11
    {categories.length > 0 && tagGraph.nodes.length > 0 && (
12
      <Fragment>
13
        <hr class="categories-page__divider" />
14
        <TagGraph data={tagGraph} />
15
      </Fragment>
16
    )}
17
  </div>
18
</MainGridLayout>

6. 样式#

使用 card-base 提供圆角与背景，自定义 padding 由 .categories-page 提供
.category-rose__layout 桌面端横排（图表 flex:1 + 列表 220px），≤768px 上下排列
.tag-graph__chart 固定高度 620px，响应式递减至 360px
暗色模式用项目约定的 :where(.dark) 选择器，例如：

1
.category-rose__list a { color: rgba(0,0,0,0.85); }
2
:where(.dark) .category-rose__list a { color: rgba(255,255,255,0.85); }

7. i18n 国际化#

新增 8 个 key 覆盖五种语言：

1
enum I18nKey {
2
  taxonomy = "taxonomy",                       // eyebrow 副标题
3
  categoriesPageTitle = "categoriesPageTitle", // "分类标签"
4
  tagGraphTitle = "tagGraphTitle",             // 标签图谱标题
5
  tagGraphCount = "tagGraphCount",             // "N 个标签"
6
  totalPostsLabel = "totalPostsLabel",         // "共 N 篇文章"
7
  highFrequencyTag = "highFrequencyTag",
8
  commonTag = "commonTag",
9
  lowFrequencyTag = "lowFrequencyTag",
10
}

语言	categoriesPageTitle
zh_CN	分类标签
zh_TW	分類標籤
en	Categories & Tags
ja	カテゴリとタグ
ru	Категории и теги

✅ 验收结果#

pnpm check：0 errors / 0 warnings / 0 hints
pnpm lint：通过
暗色模式：分类名 / 汇总行 / 图例文字均正确切换为白色

💡 关键设计点回顾#

数据先行：buildTagGraphData 是纯函数，便于单测；getTagGraphData 负责注入 getTagUrl，职责分离
薄壳路由：页面文件只组合不实现，便于后续换实现（如 Svelte 化）
生命周期管理：astro:page-load 初始化 / swup:willReplaceContent 销毁，避免 Swup 切换后的内存泄漏
共享 ECharts 加载：两个组件共用 window.echarts 与 __echartsLoading，避免重复加载
CDN 兜底：ECharts 5.6.0 通过 cdn.jsdelivr.net 延迟加载，首屏不阻塞
可访问性：aria-label、role="img" 给图表命名；列表用 <nav> 包裹

AI 摘要

📖 概述#

📂 文件清单#

新增文件（5 个）#

修改文件（9 个）#

🛠️ 方法 & 关键代码#

1. 数据层：标签共现图谱算法#

2. 通用标题组件 `PageTitle.astro`#

3. CategoryRose 玫瑰图#

4. TagGraph 力导向图#

5. 路由页面（薄壳）#

6. 样式#

7. i18n 国际化#

✅ 验收结果#

💡 关键设计点回顾#

文章分享

文章目录

Firefly 分类页面美化

AI 摘要

📖 概述#

📂 文件清单#

新增文件（5 个）#

修改文件（9 个）#

🛠️ 方法 & 关键代码#

1. 数据层：标签共现图谱算法#

2. 通用标题组件 PageTitle.astro#

3. CategoryRose 玫瑰图#

4. TagGraph 力导向图#

5. 路由页面（薄壳）#

6. 样式#

7. i18n 国际化#

✅ 验收结果#

💡 关键设计点回顾#

文章分享

文章目录

2. 通用标题组件 `PageTitle.astro`#