R1ng13 Blog

待办

Sat, 09 May 2026 00:00:00 GMT

功能#

BUG#

修复生产环境下顶部滚动条刷新页面不显示
自定义Footer页面生产环境不显示主题版本号，本地环境显示
浏览量一直加载中…

优化#

右侧滚动条优化，和teek保持一致

快速开始

Tue, 05 May 2026 00:00:00 GMT

快速开始#

Firefly 是一款基于 Astro 框架和 Fuwari 模板开发的清新美观且现代化个人博客主题，专为技术爱好者和内容创作者设计。该主题融合了现代 Web 技术栈，提供了丰富的功能模块和高度可定制的界面，让您能够轻松打造出专业且美观的个人博客网站。

环境要求#

Node.js 22.0 或更高版本
pnpm 包管理器（推荐）
Git

安装#

克隆仓库

Terminal window

1
git clone https://github.com/CuteLeaf/Firefly.git
2
cd Firefly

安装依赖

Terminal window

1
pnpm install

启动开发服务器

Terminal window

1
pnpm dev

构建生产版本

Terminal window

1
pnpm build

项目结构#

1
Firefly/
2
├── src/
3
│   ├── config/          # 配置文件目录
4
│   ├── components/      # 组件目录
5
│   ├── content/         # 内容目录（文章、页面）
6
│   ├── layouts/         # 布局模板
7
│   ├── pages/           # 页面路由
8
│   └── types/           # 类型定义
9
├── public/              # 静态资源
10
└── astro.config.mjs     # Astro 配置

配置文件概览#

所有配置文件位于 src/config/ 目录下：

配置文件	说明	文档
`siteConfig.ts`	站点基础配置	站点配置
`navBarConfig.ts`	导航栏配置	导航栏
`sidebarConfig.ts`	侧边栏布局配置	侧边栏
`profileConfig.ts`	个人资料配置	个人资料
`backgroundWallpaper.ts`	背景壁纸配置	背景壁纸
`commentConfig.ts`	评论系统配置	评论系统
`musicConfig.ts`	音乐播放器配置	音乐播放器
`fontConfig.ts`	字体配置	字体
`coverImageConfig.ts`	封面图片配置	封面图片
`expressiveCodeConfig.ts`	代码块配置	代码块
`sakuraConfig.ts`	樱花特效配置	樱花特效
`announcementConfig.ts`	公告配置	公告
`footerConfig.ts`	页脚配置	页脚
`licenseConfig.ts`	许可证配置	许可证
`friendsConfig.ts`	友链配置	友链
`sponsorConfig.ts`	赞助配置	赞助
`adConfig.ts`	广告配置	广告
`pioConfig.ts`	Live2D/Spine 模型配置	看板娘

集成朋友圈与笔记本功能

Sun, 21 Jun 2026 00:00:00 GMT

提示

本文是在博主团子和蛋糕文章：用 GitHub Gist 做博客后端：零成本的说说与笔记方案基础上增加了自己实践过程的一些细节，转载无需和我联系，但请注明文章来源。如果侵权之处，请联系博主进行删除，谢谢~

目录结构#

以下是朋友圈和笔记本功能相关的核心目录结构：

1
Firefly-hyde/
2
├── astro.config.mjs                                    # 修改 - 添加路径别名
3
│
4
├── src/
5
│   ├── components/
6
│   │   └── moments/                                    # 新增目录
7
│   │       ├── MomentCard.astro                       # 新增 - 朋友圈卡片组件
8
│   │       └── MomentsCover.astro                     # 新增 - 朋友圈封面组件
9
│   │
10
│   ├── config/
11
│   │   ├── externalMomentsConfig.ts                   # 新增 - 朋友圈配置
12
│   │   ├── externalNotebooksConfig.ts                 # 新增 - 笔记本配置
13
│   │   ├── navBarConfig.ts                            # 修改 - 添加导航链接
14
│   │   └── siteConfig.ts                              # 修改 - 添加封面配置
15
│   │
16
│   ├── content/
17
│   │   ├── config.ts                                  # 修改 - 添加moments集合
18
│   │   └── moments/                                    # 新增目录
19
│   │       └── *.md                                   # 新增 - 本地朋友圈内容文件
20
│   │
21
│   ├── data/
22
│   │   └── moments.ts                                 # 新增 - 获取远程朋友圈数据脚本
23
│   │
24
│   ├── pages/
25
│   │   ├── admin/                                     # 新增目录
26
│   │   │   ├── index.astro                           # 新增 - 登录页
27
│   │   │   ├── moments.astro                         # 新增 - 朋友圈管理
28
│   │   │   └── notebooks.astro                       # 新增 - 笔记本管理
29
│   │   ├── life/notebooks/
30
│   │   │   └── remote-entry.astro                    # 新增 - 远程笔记页
31
│   │   ├── moments.astro                              # 新增 - 朋友圈主页
32
│   │   └── moments/
33
│   │       └── pinned.astro                           # 新增 - 精选朋友圈
34
│   │
35
│   ├── types/
36
│   │   └── siteConfig.ts                              # 修改 - 添加momentsCover类型
37
│   │
38
│   └── utils/
39
│       ├── content-utils.ts                           # 修改 - 添加数据获取
40
│       └── gist-api.ts                                # 新增 - Gist API工具
41
└──

展开收起

新增朋友圈/封面卡片组件#

文件路径：src/components/moments/MomentCard.astro和src/components/moments/MomentsCover.astro

完整代码：MomentCard.astro

完整代码：MomentsCover.astro

创建 Gist API 工具文件#

文件路径: src/utils/gist-api.ts

完整代码: gist-api.ts

创建朋友圈配置#

文件路径: src/config/externalMomentsConfig.ts

1
// 外部朋友圈数据源配置（基于 GitHub Gist，完全免费）
2
// 数据存储在 GitHub Gist 中，通过 GitHub API 读写
3

4
export const externalMomentsConfig = {
5
    // 是否启用外部朋友圈数据源
6
    enable: true,
7

8
    // GitHub Gist ID（创建 Gist 后从 URL 中获取）
9
    // 替换为你的 Gist ID。https://gist.github.com/Seasir-Hyde/xxxx，其中 xxxx 即为 Gist ID
10
    gistId: "替换为你的 Gist ID",
11

12
    // Gist 中的文件名
13
    fileName: "moments.json",
14

15
    // 默认作者信息
16
    defaultAuthor: "Hyde",
17
    defaultAvatar: "https://你的头像URL.jpg",
18

19
    // 后台登录密码的 SHA-256 哈希
20
    // 生成方式：在线工具:https://www.strongpasswordgenerator.org/zh-cn/sha256-hash-generator/
21
    adminPasswordHash:
22
        "b5d9ded2ab2812e8653f06fc4d3246a4b13642e8371bc74a7f1003eb4fb4e637",
23

24
    // GitHub Token（优先从环境变量 GITHUB_TOKEN 读取）
25
    githubToken: process.env.GITHUB_TOKEN || "",
26
};

展开收起

创建笔记本配置#

文件路径: src/config/externalNotebooksConfig.ts

1
// 外部笔记数据源配置（基于 GitHub Gist）
2
// 每个笔记本有独立的 Gist 仓库
3

4
export const externalNotebooksConfig = {
5
    // 是否启用外部笔记数据源
6
    enable: true,
7

8
    // 每个笔记本对应的 Gist ID
9
    // 在 https://gist.github.com 创建 Secret Gist，文件名 notebooks-entries.json，内容 []
10
    notebookGists: {
11
        "每日总结": "your-gist-id-here",
12
        "日记": "your-gist-id-here",
13
        "日常琐记": "your-gist-id-here",
14
        "学习笔记": "your-gist-id-here",
15
    } as Record<string, string>,
16

17
    // 笔记模板（Admin 页面快速选择）
18
    // {name} 会被替换为今天的日期
19
    templates: [
20
        {
21
            id: "daily",
22
            icon: "📝",
23
            name: "每日总结",
24
            title: "{name} 每日总结",
25
            content: "📍今天做了什么：\n📅今日感想：\n🔮明日计划：",
26
        },
27
        {
28
            id: "diary",
29
            icon: "📔",
30
            name: "日记",
31
            title: "{name}",
32
            content: "## 天气\n\n## 今天发生了什么\n\n## 心情\n\n",
33
        },
34
        {
35
            id: "reading",
36
            icon: "📚",
37
            name: "读书笔记",
38
            title: "",
39
            content: "## 📚 书籍信息\n\n- 书名：\n- 作者：\n\n## 核心观点\n\n## 我的感想\n\n",
40
        },
41
        {
42
            id: "free",
43
            icon: "📄",
44
            name: "空白",
45
            title: "",
46
            content: "",
47
        },
48
    ] as Array<{
49
        id: string;
50
        icon: string;
51
        name: string;
52
        title: string;
53
        content: string;
54
    }>,
55

56
    // 后台登录密码的 SHA-256 哈希（与朋友圈后台共用同一密码）
57
    adminPasswordHash:
58
        "b5d9ded2ab2812e8653f06fc4d3246a4b13642e8371bc74a7f1003eb4fb4e637",
59

60
    // GitHub Token
61
    githubToken: process.env.GITHUB_TOKEN || "",
62
};

展开收起

修改站点配置#

文件路径: src/config/siteConfig.ts

操作: 添加朋友圈封面配置

插入位置: 在 defaultAvatar 配置之后

添加代码:

1
// 朋友圈页面封面配置（微信朋友圈风格）
2
momentsCover: {
3
    enable: true,
4
    image: "https://你的封面图片URL.jpg",
5
},

修改类型定义#

文件路径: src/types/siteConfig.ts

1
// 朋友圈页面封面配置
2
momentsCover: {
3
    enable: boolean;
4
  image?: string;
5
},

修改导航栏配置#

文件路径: src/config/navBarConfig.ts

修改1 - 添加朋友圈链接:

在导航链接列表中添加：

1
LinkPresets.Moments,

修改2 - 定义链接预设:

在 LinkPresets 对象中添加：

1
Moments: {
2
  name: "朋友圈",
3
  url: "/moments/",
4
  icon: "mdi:wechat",
5
},

修改3 - 添加登录链接:

文件路径：src/components/layout/Navbar.astro

1
<LightDarkSwitch client:load></LightDarkSwitch>
2
    <a aria-label="Admin" href="/admin/" class="btn-plain scale-animation rounded-lg h-11 w-11 active:scale-90">
3
        <Icon is:inline name="material-symbols:account-circle" class="text-[1.25rem]"></Icon>
4
    </a>

修改内容配置#

文件路径: src/content.config.ts

1
// 朋友圈集合
2
const momentsCollection = defineCollection({
3
    loader: glob({ pattern: "**/*.{md,mdx}", base: "./src/content/moments" }),
4
    schema: ({ image }) =>
5
        z.object({
6
            author: z.string().optional().default(""),
7
            avatar: z.string().optional().default(""),
8
            pinned: z.boolean().optional().default(false),
9
            published: z.date(),
10
            images: z
11
                .array(image().or(z.string()))
12
                .or(z.string())
13
                .optional()
14
                .default([]),
15
            tags: z.array(z.string()).optional().default([]),
16
            location: z.string().optional().default(""),
17
            device: z.string().optional().default(""),
18
        }),
19
});
20

21
// 导出朋友圈集合
22
export const collections = {
23
    posts: postsCollection,
24
    spec: specCollection,
25
    ziyuan: ziyuanCollection,
26
    moments: momentsCollection,  // 朋友圈集合
27
};

展开收起

创建朋友圈数据获取脚本#

文件路径: src/data/moments.ts

提示

此脚本从布局文件抽离，便于维护。负责从 GitHub Gist 加载朋友圈数据并动态插入页面。

完整代码: moments.ts

创建精选朋友圈页面#

文件路径: src/pages/moments/pinned.astro

完整代码: pinned.astro

Admin 管理后台#

创建登录页#

文件路径: src/pages/admin/index.astro

核心功能: SHA-256 密码验证，登录成功后存储 token 到 localStorage

完整代码: index.astro

创建朋友圈管理页#

文件路径: src/pages/admin/moments.astro

核心功能:

从 Gist 读取朋友圈数据
新增/编辑/删除朋友圈
支持图片上传（转为 base64）
支持置顶、标签、位置

完整代码: moments.astro

创建笔记本管理页#

文件路径: src/pages/admin/notebooks.astro

核心功能:

多笔记本支持
笔记模板选择
Markdown 编辑
时间线展示

完整代码: notebooks.astro

环境变量配置#

文件路径: .env

1
# GitHub Token（用于 Gist API 认证）
2
# 获取方式：https://github.com/settings/tokens
3
# 需要 gist 权限
4
GITHUB_TOKEN=your_github_token_here

路径别名配置#

修改 Astro 配置#

文件路径: astro.config.mjs

1
import { defineConfig } from 'astro/config';
2

3
export default defineConfig({
4
    vite: {
5
        resolve: {
6
            alias: {
7
                "@": "./src",
8
                "@components": "./src/components",
9
                "@layouts": "./src/layouts",
10
                "@config": "./src/config",
11
                "@utils": "./src/utils",
12
                "@data": "./src/data",
13
            },
14
        },
15
    },
16
});

展开收起

文件清单#

文件路径	操作	说明
`src/utils/gist-api.ts`	新建	Gist API 工具函数
`src/config/externalMomentsConfig.ts`	新建	朋友圈配置
`src/config/externalNotebooksConfig.ts`	新建	笔记本配置
`src/config/siteConfig.ts`	修改	添加封面配置
`src/config/navBarConfig.ts`	修改	添加导航链接
`src/types/siteConfig.ts`	修改	添加类型定义
`src/content.config.ts`	修改	添加 moments 集合
`src/data/moments.ts`	新建	朋友圈数据获取脚本
`src/utils/content-utils.ts`	修改	添加数据获取
`src/components/moments/MomentCard.astro`	新建	朋友圈卡片组件
`src/components/moments/MomentsCover.astro`	新建	朋友圈封面组件
`src/pages/moments.astro`	新建	朋友圈主页
`src/pages/moments/pinned.astro`	新建	精选朋友圈
`src/pages/admin/index.astro`	新建	登录页
`src/pages/admin/moments.astro`	新建	朋友圈管理
`src/pages/admin/notebooks.astro`	新建	笔记本管理
`src/pages/life/notebooks/remote-entry.astro`	新建	远程笔记页
`.env`	新建	环境变量配置
`astro.config.mjs`	修改	添加路径别名

隐藏封面图

Wed, 03 Jun 2026 00:00:00 GMT

添加类型定义#

文件路径：src/types/config.ts

1
// 文章列表布局配置
2
  postListLayout: {
3
    allowCoverSwitch?: boolean; // 是否允许用户切换文章封面图显示
4
    showCover?: boolean; // 默认是否显示文章封面图
5
  };

添加配置项#

文件路径：src/config/siteConfig.ts

1
postListLayout: {
2
  allowCoverSwitch: true,  // 新增：允许切换封面图显示
3
  showCover: true,         // 新增：默认显示封面图
4
},

设置工具函数#

文件路径：src/utils/setting-utils.ts

1
// 获取默认封面图显示状态
2
export function getDefaultPostCoverImageEnabled(): boolean {
3
  return siteConfig.postListLayout.showCover ?? true;
4
}
5

6
// 从localStorage读取封面图显示状态
7
export function getStoredPostCoverImageEnabled(): boolean {
8
  if (
9
    typeof localStorage === "undefined" ||
10
    typeof localStorage.getItem !== "function"
11
  ) {
12
    return getDefaultPostCoverImageEnabled();
13
  }
14
  const stored = localStorage.getItem("postCoverImageEnabled");
15
  if (stored === null) {
16
    return getDefaultPostCoverImageEnabled();
17
  }
18
  return stored === "true";
19
}
20

21
// 设置封面图显示状态
22
export function setPostCoverImageEnabled(enabled: boolean): void {
23
  if (
24
    typeof localStorage === "undefined" ||
25
    typeof localStorage.setItem !== "function"
26
  ) {
27
    return;
28
  }
29
  localStorage.setItem("postCoverImageEnabled", String(enabled));
30
  applyPostCoverImageEnabledToDocument(enabled);
31
  if (typeof window !== "undefined") {
32
    window.dispatchEvent(
33
      new CustomEvent("postCoverImageChange", {
34
        detail: { enabled },
35
      }),
36
    );
37
  }
38
}
39

40
// 将封面图状态应用到文档
41
export function applyPostCoverImageEnabledToDocument(enabled: boolean): void {
42
  if (typeof document === "undefined") {
43
    return;
44
  }
45
  document.documentElement.setAttribute(
46
    "data-post-cover-enabled",
47
    String(enabled),
48
  );
49
}

展开收起

添加设置面板开关#

文件路径：src/components/controls/DisplaySettingsIntegrated.svelte

导入相关函数#

在文件顶部导入新添加的工具函数：

1
import {
2
  // ... 其他导入
3
  getDefaultPostCoverImageEnabled,
4
  getStoredPostCoverImageEnabled,
5
  setPostCoverImageEnabled,
6
  applyPostCoverImageEnabledToDocument,
7
} from "@utils/setting-utils";

添加状态变量#

在脚本部分添加以下状态变量：

1
const defaultPostCoverImageEnabled = getDefaultPostCoverImageEnabled();
2
const isPostCoverImageSwitchable = siteConfig.postListLayout.allowCoverSwitch ?? true;
3
let postCoverImageEnabled = $state(true);

添加切换函数#

添加切换封面图状态的函数：数：

1
function togglePostCoverImageEnabled() {
2
  postCoverImageEnabled = !postCoverImageEnabled;
3
  setPostCoverImageEnabled(postCoverImageEnabled);
4
}

在 onMount 中初始化状态#

1
// 从localStorage读取文章封面图状态
2
postCoverImageEnabled = getStoredPostCoverImageEnabled();
3
// 将状态应用到文档
4
applyPostCoverImageEnabledToDocument(postCoverImageEnabled);

添加开关 UI#

在 HTML 模板部分（布局切换区域后）添加：

1
<!-- Post Cover Image Switch Section -->
2
{#if isPostCoverImageSwitchable}
3
  <div class="mt-2 mb-2">
4
    <div class="flex gap-2 font-bold text-lg text-neutral-900 dark:text-neutral-100 transition relative ml-3 mb-2
5
        before:w-1 before:h-4 before:rounded-md before:bg-(--primary)
6
        before:absolute before:-left-3 before:top-1/2 before:-translate-y-1/2"
7
    >
8
      {i18n(I18nKey.postCoverImage)}
9
      <button aria-label="Reset to Default" class="btn-regular w-7 h-7 rounded-md active:scale-90"
10
              class:opacity-0={postCoverImageEnabled === defaultPostCoverImageEnabled}
11
              class:pointer-events-none={postCoverImageEnabled === defaultPostCoverImageEnabled}
12
              onclick={() => {
13
                postCoverImageEnabled = defaultPostCoverImageEnabled;
14
                setPostCoverImageEnabled(defaultPostCoverImageEnabled);
15
              }}>
16
        <div class="text-(--btn-content)">
17
          <Icon icon="fa7-solid:arrow-rotate-left" class="text-[0.875rem]"></Icon>
18
        </div>
19
      </button>
20
    </div>
21
    <div class="space-y-1">
22
      <button
23
        class="w-full btn-regular rounded-md py-2 px-3 flex items-center gap-3 text-left active:scale-95 transition-all relative overflow-hidden"
24
        class:bg-(--btn-regular-bg-hover)={postCoverImageEnabled}
25
        onclick={togglePostCoverImageEnabled}
26
      >
27
        <Icon icon="material-symbols:image" class="text-[1.25rem] shrink-0"></Icon>
28
        <span class="text-sm flex-1">{i18n(I18nKey.postCoverImage)}</span>
29
        <div class="w-10 h-5 rounded-full transition-all duration-200 relative"
30
             class:bg-(--primary)={postCoverImageEnabled}
31
             class:bg-(--btn-regular-bg-active)={!postCoverImageEnabled}>
32
          <div class="absolute top-0.5 w-4 h-4 bg-white rounded-full shadow transition-all duration-200"
33
               class:left-0.5={!postCoverImageEnabled}
34
               class:left-5={postCoverImageEnabled}></div>
35
        </div>
36
      </button>
37
    </div>
38
  </div>
39
{/if}

展开收起

添加样式控制#

文件路径：src/components/layout/PostCard.astro

1
/* === Hide Post Cover Image === */
2
/* 当 data-post-cover-enabled="false" 时隐藏封面图 */
3
:global([data-post-cover-enabled="false"]) .post-card-image {
4
  display: none !important;
5
}
6

7
:global([data-post-cover-enabled="false"]) .has-cover {
8
  &.post-card-wrapper {
9
    .post-card-content {
10
      width: calc(100% - 52px - 12px) !important;
11
    }
12
  }
13
}
14

15
:global([data-post-cover-enabled="false"]) .has-cover .post-card-enter-btn {
16
  display: flex !important;
17
}

展开收起

语言配置#

文件路径：src/i18n/i18nKey.ts

1
postCoverImage = "postCoverImage",

文件路径：src/i18n/languages/en.ts

1
[Key.postCoverImage]: "Post Cover Image",

文件路径：src/i18n/languages/ja.ts

1
[Key.postCoverImage]: "記事のカバー画像",

文件路径：src/i18n/languages/ru.ts

1
[Key.postCoverImage]: "Обложка поста",

文件路径：src/i18n/languages/zh_CN.ts

1
[Key.postCoverImage]: "文章封面图",

文件路径：src/i18n/languages/zh_TW.ts

1
[Key.postCoverImage]: "文章封面圖",

归档统计

Tue, 02 Jun 2026 00:00:00 GMT

获取归档列表#

文件路径：src/pages/archive.astro

1
---
2
import { getSortedPostsList } from "@/utils/content-utils";  // [!code --]
3
const sortedPostsList = await getSortedPostsList();     // [!code --]
4
<ArchivePanel sortedPosts={sortedPostsList} client:only="svelte" /> // [!code --]
5

6
import { getArchiveList } from "@/utils/content-utils";
7

8
// 获取归档列表（posts + moments + bangumi + life）
9
const archiveList = await getArchiveList();
10

11
// 计算各类型数量
12
const postsCount = archiveList.filter(item => item.type === "post").length;
13
const momentsCount = archiveList.filter(item => item.type === "moment").length;
14
const bangumiCount = archiveList.filter(item => item.type === "bangumi").length;
15
const lifeCount = archiveList.filter(item => item.type === "life").length;
16
const totalCount = postsCount + momentsCount + bangumiCount + lifeCount;
17
---
18

19
<MainGridLayout title={i18n(I18nKey.archive)}>
20
      <!-- 统计信息 -->
21
    <div class="card-base px-8 py-6 mb-6">
22
        <div class="flex flex-wrap gap-6 justify-center text-center">
23
            <div class="flex flex-col">
24
                <span class="text-3xl font-bold text-amber-500">{postsCount}</span>
25
                <span class="text-sm text-30 mt-1">{i18n(I18nKey.postList)}</span>
26
            </div>
27
            <div class="w-px bg-neutral-200 dark:bg-neutral-700"></div>
28
            <div class="flex flex-col">
29
                <span class="text-3xl font-bold text-(--primary)">{momentsCount}</span>
30
                <span class="text-sm text-30 mt-1">{i18n(I18nKey.moments)}</span>
31
            </div>
32
            <div class="w-px bg-neutral-200 dark:bg-neutral-700"></div>
33
            <div class="flex flex-col">
34
                <span class="text-3xl font-bold text-red-500 dark:text-red-400">{bangumiCount}</span>
35
                <span class="text-sm text-30 mt-1">{i18n(I18nKey.bangumi)}</span>
36
            </div>
37
            <div class="w-px bg-neutral-200 dark:bg-neutral-700"></div>
38
            <div class="flex flex-col">
39
                <span class="text-3xl font-bold text-emerald-600 dark:text-emerald-400">{lifeCount}</span>
40
                <span class="text-sm text-30 mt-1">生活</span>
41
            </div>
42
            <div class="w-px bg-neutral-200 dark:bg-neutral-700"></div>
43
            <div class="flex flex-col">
44
                <span class="text-3xl font-bold text-(--primary)">{totalCount}</span>
45
                <span class="text-sm text-30 mt-1">总计</span>
46
            </div>
47
        </div>
48
    </div>
49
  <ArchivePanel sortedPosts={archiveList} client:only="svelte" />
50
</MainGridLayout>

展开收起

更新内容工具函数文件#

文件路径：src/utils/content-utils.ts

1
---
2
import { getCategoryUrl, getPostUrlBySlug } from "@utils/url-utils";
3
import { getDiaryList } from "@/data/diary"
4
---
5

6
export interface ArchiveItem {
7
  id: string;
8
  type: "post" | "moment" | "bangumi" | "life";
9
  link?: string;
10
  data: {
11
    title: string;
12
    published: Date;
13
    tags: string[];
14
    category?: string | null;
15
  };
16
}
17

18
export async function getArchiveList(): Promise<ArchiveItem[]> {
19
  const posts = await getCollection("posts", ({ data }) => {
20
    return import.meta.env.PROD ? data.draft !== true : true;
21
  });
22
  const diaryList = getDiaryList();
23

24
  const postItems: ArchiveItem[] = posts.map((post) => ({
25
    id: post.id,
26
    type: "post",
27
    link: getPostUrlBySlug(post.id),
28
    data: {
29
      title: post.data.title,
30
      published: post.data.published,
31
      tags: post.data.tags,
32
      category: post.data.category || null,
33
    },
34
  }));
35

36
  // 将日记数据转换为归档项
37
  const momentItems: ArchiveItem[] = diaryList.map((diary) => {
38
    let title = diary.content || "";
39
    title = title.replace(/[#*`]/g, "").trim();
40
    if (title.length > 50) title = `${title.substring(0, 50)}...`;
41
    if (!title) title = i18n(I18nKey.moments) || "日常动态";
42

43
    return {
44
      id: String(diary.id),
45
      type: "moment",
46
      link: "/diary/",
47
      data: {
48
        title: title,
49
        published: new Date(diary.date),
50
        tags: diary.tags || [],
51
        category: null,
52
      },
53
    };
54
  });
55

56
  // 空数组，用于保持接口兼容性
57
  const bangumiItems: ArchiveItem[] = [];
58
  const lifeItems: ArchiveItem[] = [];
59

60
  return [...postItems, ...momentItems, ...bangumiItems, ...lifeItems].sort((a, b) => {
61
    const timeA = a.data.published.getTime();
62
    const timeB = b.data.published.getTime();
63
    return timeB - timeA;
64
  });
65
}

展开收起

定义类型#

文件路径：src/components/controls/ArchivePanel.svelte

1
interface Post {
2
  id: string;
3
  type?: "post" | "moment" | "bangumi" | "life";
4
  link?: string;
5
  data: {
6
    title: string;
7
    tags: string[];
8
    category?: string | null;
9
    published: Date;
10
  };
11
}
12

13
{@const postLink = post.link || getPostUrlBySlug(post.id)}
14
<a
15
  href={getPostUrlBySlug(post.id)}  // [!code --]
16
    href={postLink}  // [!code ++]
17
  aria-label={post.data.title}
18
  class="group btn-plain block! h-10 w-full rounded-lg hover:text-[initial]"
19
>
20

21
<div
22
                class="w-[70%] md:max-w-[65%] md:w-[65%] text-left font-bold
23
                     group-hover:translate-x-1 transition-all group-hover:text-(--primary)
24
                     text-75 pr-8 whitespace-nowrap text-ellipsis overflow-hidden flex items-center gap-2"
25
            >
26
              {#if post.type === 'post'}
27
                <span class="px-1.5 py-0.5 text-[10px] bg-amber-500 text-white rounded-md shrink-0 uppercase tracking-wider opacity-80 font-normal">
28
                  文章
29
                </span>
30
              {:else if post.type === 'moment'}
31
                <span class="px-1.5 py-0.5 text-[10px] bg-(--primary) text-white rounded-md shrink-0 uppercase tracking-wider opacity-80 font-normal">
32
                  {i18n(I18nKey.moments) || 'Moment'}
33
                </span>
34
              {:else if post.type === 'bangumi'}
35
                <span class="px-1.5 py-0.5 text-[10px] bg-red-500 text-white rounded-md shrink-0 uppercase tracking-wider opacity-80 font-normal">
36
                  {i18n(I18nKey.bangumi) || 'Record'}
37
                </span>
38
              {:else if post.type === 'life'}
39
                <span class="px-1.5 py-0.5 text-[10px] bg-emerald-600 text-white rounded-md shrink-0 uppercase tracking-wider opacity-80 font-normal">
40
                  生活
41
                </span>
42
              {/if}
43
              <span class="truncate">{post.data.title}</span>
44
            </div>

展开收起

语言配置#

文件路径：src/i18n/i18nKey.ts

1
moments = "moments",

文件路径：src/i18n/languages/en.ts

1
[Key.moments]: "Dynamic",

文件路径：src/i18n/languages/ja.ts

1
[Key.moments]: "ダイナミック",

文件路径：src/i18n/languages/ru.ts

1
[Key.moments]: "Динамика",

文件路径：src/i18n/languages/zh_CN.ts

1
[Key.moments]: "动态",

文件路径：src/i18n/languages/zh_TW.ts

1
[Key.moments]: "動態",

给博客增加单个和全部分类页面

Tue, 02 Jun 2026 00:00:00 GMT

文件目录#

1
src/
2
├── components/
3
│   └── layout/
4
│       ├── CategoryBar.astro          [分类栏组件：显示主页、归档、分类按钮，支持横向滚动]
5
├── config/
6
│   └── navBarConfig.ts                [导航栏配置：动态生成导航链接，添加分类菜单项]
7
├── i18n/
8
│   ├── i18nKey.ts                     [国际化键定义：新增 allCategories 和 searchAlbums 键]
9
│   └── languages/
10
│       ├── en.ts                      [英文翻译文件]
11
│       ├── ja.ts                      [日文翻译文件]
12
│       ├── ru.ts                      [俄文翻译文件]
13
│       ├── zh_CN.ts                   [简体中文翻译文件]
14
│       └── zh_TW.ts                   [繁体中文翻译文件]
15
├── pages/
16
│   ├── categories.astro               [全部分类页面：显示所有分类卡片列表（新增）]
17
│   └── categories/
18
│       └── [category].astro           [单个分类详情页：显示该分类文章和标签筛选（新增）]
19
└── utils/
20
    └── url-utils.ts                   [URL工具函数：新增分类相关URL生成函数]

展开收起

创建全部分类页面#

文件路径：src/pages/categories.astro

1
---
2
import { Icon } from "astro-icon/components";
3
import MainGridLayout from "@layouts/MainGridLayout.astro";
4
import { getCategoryList } from "@/utils/content-utils";
5
import I18nKey from "@i18n/i18nKey";
6
import { i18n } from "@i18n/translation";
7

8
const categories = await getCategoryList();
9
const totalPosts = categories.reduce((sum, cat) => sum + cat.count, 0);
10
---
11

12
<MainGridLayout title={i18n(I18nKey.categories)}>
13
    <!-- 页面标题 -->
14
    <div class="card-base px-8 py-6 mb-6">
15
        <h1 class="text-2xl font-bold text-(--primary) mb-2">
16
            {i18n(I18nKey.categories)}
17
        </h1>
18
        <p class="text-30 text-sm">
19
            {i18n(I18nKey.allCategories)} · {totalPosts} {i18n(I18nKey.postsCount)}
20
        </p>
21
    </div>
22

23
    <!-- 分类卡片列表 -->
24
    <div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4 mb-6">
25
        {
26
            categories.map((category, index) => (
27
                <a
28
                    href={category.url}
29
                    class="card-base p-6 flex items-center gap-4 transition-all duration-300
30
                           hover:scale-[1.02] hover:shadow-lg active:scale-[0.98]
31
                           onload-animation"
32
                    style={`animation-delay: calc(var(--content-delay) + ${index * 50}ms);`}
33
                >
34
                    <div class="flex-shrink-0 w-12 h-12 rounded-full bg-(--primary)/10 flex items-center justify-center">
35
                        <Icon
36
                            name="material-symbols:folder-open"
37
                            class="text-2xl text-(--primary)"
38
                        />
39
                    </div>
40
                    <div class="flex-1 min-w-0">
41
                        <h2 class="text-lg font-bold text-90 truncate">
42
                            {category.name}
43
                        </h2>
44
                        <p class="text-sm text-30 mt-1">
45
                            {category.count} {i18n(I18nKey.postsCount)}
46
                        </p>
47
                    </div>
48
                    <div class="flex-shrink-0">
49
                        <Icon
50
                            name="material-symbols:chevron-right-rounded"
51
                            class="text-2xl text-30 transition-transform duration-200 group-hover:translate-x-1"
52
                        />
53
                    </div>
54
                </a>
55
            ))
56
        }
57
    </div>
58

59
    <!-- 空状态 -->
60
    {
61
        categories.length === 0 && (
62
            <div class="card-base px-8 py-12 text-center">
63
                <Icon
64
                    name="material-symbols:folder-off"
65
                    class="text-5xl text-30 mx-auto mb-4"
66
                />
67
                <p class="text-30">{i18n(I18nKey.bangumiNoData)}</p>
68
            </div>
69
        )
70
    }
71
</MainGridLayout>
72

73
<style>
74
    .card-base {
75
        background: var(--card-bg);
76
        border: 1px solid var(--card-border);
77
        border-radius: var(--radius-large);
78
    }
79

80
    a.card-base:hover {
81
        border-color: var(--primary);
82
    }
83

84
    a.card-base:active {
85
        background: var(--card-bg-active);
86
    }
87
</style>

展开收起

创建单个分类详情页#

文件路径：src/pages/categories/[category].astro

1
---
2
import type { GetStaticPaths } from "astro";
3
import type { CollectionEntry } from "astro:content";
4
import { getCollection } from "astro:content";
5
import { Icon } from "astro-icon/components";
6
import PostCard from "@/components/layout/PostCard.astro";
7
import MainGridLayout from "@layouts/MainGridLayout.astro";
8
import { getCategoryList } from "@/utils/content-utils";
9
import { getTagUrl, getCategoryPageUrl, getPostUrlBySlug } from "@/utils/url-utils";
10
import I18nKey from "@i18n/i18nKey";
11
import { i18n } from "@i18n/translation";
12
import { siteConfig } from "@/config";
13

14
type PostEntry = CollectionEntry<"posts">;
15

16
interface Props {
17
  categoryName: string;
18
  posts: PostEntry[];
19
  totalPosts: number;
20
  tags: { name: string; count: number }[];
21
}
22

23
export const getStaticPaths = (async () => {
24
  const categories = await getCategoryList();
25
  const allPosts = await getCollection("posts", ({ data }) => {
26
    return import.meta.env.PROD ? data.draft !== true : true;
27
  }) as PostEntry[];
28

29
  const paths: any[] = [];
30

31
  for (const category of categories) {
32
    // 过滤该分类下的文章
33
    const categoryPosts = allPosts.filter((post) => {
34
      const postCategory = post.data.category?.trim() || "";
35
      const uncategorized = i18n(I18nKey.uncategorized).toLowerCase();
36

37
      if (!category.name || category.name.toLowerCase() === uncategorized) {
38
        // 未分类：没有分类或分类为空/未分类
39
        return !postCategory || postCategory.toLowerCase() === uncategorized;
40
      }
41
      return postCategory === category.name;
42
    });
43

44
    // 按日期排序
45
    categoryPosts.sort((a, b) => {
46
      if (a.data.pinned && !b.data.pinned) return -1;
47
      if (!a.data.pinned && b.data.pinned) return 1;
48
      return new Date(b.data.published).getTime() - new Date(a.data.published).getTime();
49
    });
50

51
    // 收集该分类下所有标签
52
    const tagCountMap: Record<string, number> = {};
53
    categoryPosts.forEach((post) => {
54
      (post.data.tags || []).forEach((tag: string) => {
55
        tagCountMap[tag] = (tagCountMap[tag] || 0) + 1;
56
      });
57
    });
58
    const tags = Object.entries(tagCountMap)
59
      .sort((a, b) => b[1] - a[1])
60
      .map(([name, count]) => ({ name, count }));
61

62
    paths.push({
63
      params: { category: category.name },
64
      props: {
65
        categoryName: category.name,
66
        posts: categoryPosts,
67
        totalPosts: categoryPosts.length,
68
        tags,
69
      },
70
    });
71
  }
72

73
  return paths;
74
}) satisfies GetStaticPaths;
75

76
const { categoryName, posts, totalPosts, tags } = Astro.props;
77

78
// 解码分类名称
79
const decodedCategory = decodeURIComponent(categoryName);
80

81
let delay = 0;
82
const interval = 50;
83

84
const masonryEnabled = siteConfig.postListLayout.grid.masonry;
85
const columnWidth = siteConfig.postListLayout.grid.columnWidth || 280;
86

87
const defaultLayout = siteConfig.postListLayout.defaultMode || "list";
88
const mobileDefaultLayout =
89
  siteConfig.postListLayout.mobileDefaultMode || defaultLayout;
90
const initialLayoutClass =
91
  defaultLayout === "grid"
92
    ? "post-grid-auto grid-mode"
93
    : "flex flex-col gap-4 md:gap-4 list-mode";
94
---
95

96
<MainGridLayout title={`${decodedCategory} - ${i18n(I18nKey.categories)}`}>
97
    <!-- 面包屑导航 -->
98
    <div class="card-base px-6 py-4 mb-6">
99
        <nav class="flex items-center gap-2 text-sm text-30">
100
            <a href="/" class="hover:text-(--primary) transition-colors">
101
                <Icon name="material-symbols:home" class="inline-block align-middle" />
102
            </a>
103
            <span class="opacity-50">/</span>
104
            <a href={getCategoryPageUrl()} class="hover:text-(--primary) transition-colors">
105
                {i18n(I18nKey.categories)}
106
            </a>
107
            <span class="opacity-50">/</span>
108
            <span class="text-90 font-medium">{decodedCategory}</span>
109
        </nav>
110
    </div>
111

112
    <!-- 分类标题 -->
113
    <div class="card-base px-8 py-6 mb-6">
114
        <div class="flex items-center gap-4">
115
            <div class="w-14 h-14 rounded-full bg-(--primary)/10 flex items-center justify-center flex-shrink-0">
116
                <Icon name="material-symbols:folder-open" class="text-3xl text-(--primary)" />
117
            </div>
118
            <div>
119
                <h1 class="text-2xl font-bold text-90">{decodedCategory}</h1>
120
                <p class="text-sm text-30 mt-1">
121
                    {totalPosts} {i18n(I18nKey.postsCount)}
122
                </p>
123
            </div>
124
        </div>
125
    </div>
126

127
    <!-- 标签筛选区域 -->
128
    {
129
        tags.length > 0 && (
130
            <div class="card-base px-6 py-5 mb-6">
131
                <div class="flex items-center gap-3 mb-3">
132
                    <Icon name="material-symbols:label" class="text-lg text-(--primary)" />
133
                    <span class="text-sm font-medium text-90">{i18n(I18nKey.tags)}</span>
134
                    <span class="text-xs text-30">({tags.length})</span>
135
                </div>
136
                <div class="flex flex-wrap gap-2">
137
                    {tags.map((tag: { name: string; count: number }) => (
138
                        <a
139
                            href={getTagUrl(tag.name)}
140
                            class="btn-regular px-3 py-1.5 text-sm rounded-md
141
                                     transition-all duration-200
142
                                     hover:scale-105 hover:bg-(--primary)/20
143
                                     active:scale-95"
144
                        >
145
                            #{tag.name}
146
                            <span class="ml-1 text-xs opacity-60">({tag.count})</span>
147
                        </a>
148
                    ))}
149
                </div>
150
            </div>
151
        )
152
    }
153

154
    <!-- 文章列表 -->
155
    <div
156
        id="post-list-container"
157
        class={`transition-all duration-500 ease-in-out mb-4 ${initialLayoutClass}`}
158
        data-default-layout={defaultLayout}
159
        data-mobile-default-layout={mobileDefaultLayout}
160
        data-masonry-enabled={masonryEnabled}
161
        data-column-width={columnWidth}
162
        style={`--post-card-min-width: ${columnWidth}px;`}
163
    >
164
        {
165
            posts.length > 0 ? (
166
                posts.map((entry: PostEntry, index: number) => (
167
                    <PostCard
168
                        entry={entry}
169
                        title={entry.data.title}
170
                        tags={entry.data.tags}
171
                        category={entry.data.category}
172
                        published={entry.data.published}
173
                        updated={entry.data.updated}
174
                        url={getPostUrlBySlug(entry.id)}
175
                        image={entry.data.image}
176
                        description={entry.data.description}
177
                        draft={entry.data.draft}
178
                        pinned={entry.data.pinned}
179
                        password={!!entry.data.password}
180
                        loading={index < 2 ? "eager" : "lazy"}
181
                        class:list="onload-animation post-card-item"
182
                        style={`animation-delay: calc(var(--content-delay) + ${delay++ * interval}ms);`}
183
                    />
184
                ))
185
            ) : (
186
                <div class="card-base px-8 py-12 text-center w-full">
187
                    <Icon name="material-symbols:article" class="text-5xl text-30 mx-auto mb-4" />
188
                    <p class="text-30">{i18n(I18nKey.bangumiNoData)}</p>
189
                </div>
190
            )
191
        }
192
    </div>
193
</MainGridLayout>
194

195
<script is:inline define:vars={{ defaultLayout, mobileDefaultLayout, columnWidth }}>
196
    (function() {
197
        const savedLayout = localStorage.getItem('postListLayout');
198
        const effectiveDefault = window.innerWidth < 780 ? mobileDefaultLayout : defaultLayout;
199
        const effectiveLayout = window.innerWidth < 380 ? 'grid' : (savedLayout || effectiveDefault);
200

201
        if (effectiveLayout !== defaultLayout) {
202
            const container = document.getElementById('post-list-container');
203

204
            if (container) {
205
                container.style.transition = 'none';
206
                container.classList.remove('list-mode', 'grid-mode', 'post-grid-auto', 'flex', 'flex-col', 'gap-4', 'md:gap-4');
207

208
                if (effectiveLayout === 'grid') {
209
                    container.classList.add('grid-mode', 'post-grid-auto');
210
                } else {
211
                    container.classList.add('list-mode', 'flex', 'flex-col', 'gap-4', 'md:gap-4');
212
                }
213

214
                container.offsetHeight;
215
                container.style.transition = '';
216
            }
217
        }
218
    })();
219
</script>
220

221
<script>
222
    function initLayout() {
223
        const postListContainer = document.getElementById("post-list-container");
224
        if (!postListContainer) return;
225

226
        const savedLayout = localStorage.getItem("postListLayout");
227
        const defaultLayout =
228
            postListContainer.getAttribute("data-default-layout") || "list";
229
        const mobileDefaultLayout =
230
            postListContainer.getAttribute("data-mobile-default-layout") || defaultLayout;
231

232
        const effectiveDefault = window.innerWidth < 780 ? mobileDefaultLayout : defaultLayout;
233
        let currentLayout = savedLayout || effectiveDefault;
234

235
        if (window.innerWidth < 380) {
236
            currentLayout = "grid";
237
        }
238

239
        updatePostListLayout(currentLayout);
240
    }
241

242
    function updatePostListLayout(layout: string) {
243
        const postListContainer = document.getElementById("post-list-container");
244
        if (!postListContainer) return;
245

246
        const isCurrentGrid = postListContainer.classList.contains("grid-mode");
247
        const isCurrentList = postListContainer.classList.contains("list-mode");
248
        const currentLayout = isCurrentGrid ? "grid" : (isCurrentList ? "list" : null);
249

250
        const masonryEnabled = postListContainer.getAttribute("data-masonry-enabled") === "true";
251

252
        const applyClasses = () => {
253
            postListContainer.classList.remove("list-mode", "grid-mode", "post-grid-auto");
254
            if (layout === "grid") {
255
                postListContainer.classList.add("grid-mode");
256
                postListContainer.classList.remove("flex", "flex-col");
257
                if (masonryEnabled) {
258
                    postListContainer.classList.remove("post-grid-auto");
259
                    applyMasonryLayout();
260
                } else {
261
                    postListContainer.classList.add("post-grid-auto");
262
                    resetMasonryLayout();
263
                }
264
            } else {
265
                postListContainer.classList.add("list-mode");
266
                postListContainer.classList.add("flex", "flex-col", "gap-4", "md:gap-4");
267
                postListContainer.classList.remove("post-grid-auto");
268
                resetMasonryLayout();
269
            }
270
        };
271

272
        if (!currentLayout) {
273
            applyClasses();
274
            return;
275
        }
276

277
        if (currentLayout === layout) {
278
            if (layout === "grid" && masonryEnabled) {
279
                applyMasonryLayout();
280
            }
281
            return;
282
        }
283

284
        postListContainer.classList.add("layout-switching");
285

286
        setTimeout(() => {
287
            applyClasses();
288

289
            requestAnimationFrame(() => {
290
                postListContainer.classList.remove("layout-switching");
291
            });
292
        }, 200);
293
    }
294

295
    function resetMasonryLayout() {
296
        const container = document.getElementById("post-list-container");
297
        if (!container) return;
298

299
        container.style.height = "";
300
        container.style.position = "";
301
        container.style.display = "";
302

303
        const items = container.querySelectorAll(".post-card-item");
304
        items.forEach((item) => {
305
            // @ts-ignore
306
            item.style.position = "";
307
            // @ts-ignore
308
            item.style.top = "";
309
            // @ts-ignore
310
            item.style.left = "";
311
            // @ts-ignore
312
            item.style.width = "";
313
        });
314
    }
315

316
    function applyMasonryLayout() {
317
        const container = document.getElementById("post-list-container");
318
        if (!container) return;
319

320
        const masonryEnabled = container.getAttribute("data-masonry-enabled") === "true";
321
        if (!masonryEnabled) return;
322

323
        if (!container.classList.contains("grid-mode")) return;
324

325
        const items = Array.from(container.querySelectorAll(".post-card-item"));
326
        if (items.length === 0) return;
327

328
        const gap = 16;
329
        const columnWidth = parseInt(container.getAttribute("data-column-width") || "280");
330

331
        container.style.position = "relative";
332
        container.style.display = "block";
333

334
        const containerWidth = container.offsetWidth;
335
        const colCount = Math.max(1, Math.floor((containerWidth + gap) / (columnWidth + gap)));
336
        const itemWidth = (containerWidth - (colCount - 1) * gap) / colCount;
337

338
        const colHeights = new Array(colCount).fill(0);
339

340
        items.forEach((item) => {
341
            const colIndex = colHeights.indexOf(Math.min(...colHeights));
342
            // @ts-ignore
343
            item.style.position = "absolute";
344
            // @ts-ignore
345
            item.style.width = `${itemWidth}px`;
346
            // @ts-ignore
347
            item.style.setProperty('height', 'auto', 'important');
348

349
            // @ts-ignore
350
            const height = item.offsetHeight;
351
            const top = colHeights[colIndex];
352
            const left = colIndex * (itemWidth + gap);
353

354
            // @ts-ignore
355
            item.style.top = `${top}px`;
356
            // @ts-ignore
357
            item.style.left = `${left}px`;
358

359
            colHeights[colIndex] += height + gap;
360
        });
361

362
        container.style.height = `${Math.max(...colHeights)}px`;
363
    }
364

365
    document.addEventListener("DOMContentLoaded", function () {
366
        setTimeout(initLayout, 50);
367

368
        const imgs = document.querySelectorAll('#post-list-container img');
369
        imgs.forEach(img => {
370
            // @ts-ignore
371
            if(img.complete) return;
372
            img.addEventListener('load', () => {
373
                applyMasonryLayout();
374
            });
375
        });
376
    });
377

378
    document.addEventListener("visibilitychange", function () {
379
        if (!document.hidden) {
380
            setTimeout(initLayout, 100);
381
        }
382
    });
383

384
    window.addEventListener("layoutChange", function (event) {
385
        // @ts-ignore
386
        const newLayout = event.detail.layout;
387
        const postListContainer = document.getElementById("post-list-container");
388
        if (!postListContainer) return;
389

390
        updatePostListLayout(newLayout);
391
    });
392

393
    let resizeTimeout: any;
394
    window.addEventListener("resize", function () {
395
        clearTimeout(resizeTimeout);
396
        resizeTimeout = setTimeout(function () {
397
            initLayout();
398
        }, 250);
399
    });
400

401
    document.addEventListener("astro:page-load", function () {
402
        setTimeout(initLayout, 50);
403

404
        const imgs = document.querySelectorAll('#post-list-container img');
405
        imgs.forEach(img => {
406
            // @ts-ignore
407
            if(img.complete) return;
408
            img.addEventListener('load', () => {
409
                applyMasonryLayout();
410
            });
411
        });
412
    });
413

414
    document.addEventListener("astro:after-swap", function () {
415
        setTimeout(initLayout, 50);
416
    });
417

418
    setTimeout(initLayout, 0);
419
</script>
420

421
<style is:global>
422
    .post-grid-auto {
423
        display: grid;
424
        grid-template-columns: repeat(auto-fill, minmax(var(--post-card-min-width, 320px), 1fr));
425
        gap: 1rem;
426
    }
427

428
    @media (max-width: 767px) {
429
        .list-mode .post-meta-root {
430
            transform: scale(0.72) !important;
431
            transform-origin: top left !important;
432
            margin-bottom: 0.25rem !important;
433
            width: 139% !important;
434
        }
435
        .list-mode :global(.post-meta) {
436
            margin-bottom: 0.25rem !important;
437
            gap: 0.25rem !important;
438
        }
439
    }
440
</style>
441

442
<style>
443
    #post-list-container {
444
        transition: opacity 0.5s cubic-bezier(0.4, 0, 0.2, 1),
445
                    transform 0.5s cubic-bezier(0.4, 0, 0.2, 1);
446
    }
447

448
    #post-list-container > :global(*) {
449
        transition: opacity 0.4s cubic-bezier(0.4, 0, 0.2, 1),
450
                    transform 0.4s cubic-bezier(0.4, 0, 0.2, 1);
451
    }
452

453
    #post-list-container {
454
        transition: opacity 0.2s ease-out, transform 0.2s ease-out;
455
    }
456

457
    #post-list-container.layout-switching {
458
        opacity: 0;
459
        transform: translateY(10px);
460
    }
461

462
    #post-list-container.grid-mode :global(.post-card-wrapper) {
463
        flex-direction: column-reverse !important;
464
    }
465

466
    #post-list-container.grid-mode :global(.post-card-image) {
467
        width: 100% !important;
468
        position: relative !important;
469
        top: auto !important;
470
        right: auto !important;
471
        bottom: auto !important;
472
        border-radius: var(--radius-large) var(--radius-large) 0 0 !important;
473
    }
474

475
    #post-list-container.grid-mode :global(.post-card-content) {
476
        width: 100% !important;
477
        padding: 1rem !important;
478
    }
479

480
    #post-list-container.grid-mode :global(.no-cover .post-card-content) {
481
        padding-right: 4.5rem !important;
482
    }
483

484
    #post-list-container.grid-mode :global(.post-card-title) {
485
        font-size: 1.35rem !important;
486
        line-height: 1.75rem !important;
487
        margin-bottom: 0.5rem !important;
488
    }
489

490
    #post-list-container.grid-mode :global(.post-card-title::before) {
491
        display: none !important;
492
    }
493

494
    #post-list-container.grid-mode :global(.post-meta) {
495
        margin-bottom: 0.5rem !important;
496
        gap: 0.5rem !important;
497
    }
498

499
    #post-list-container.grid-mode :global(.post-meta .text-xl) {
500
        font-size: 1rem !important;
501
        line-height: 1.25rem !important;
502
    }
503

504
    #post-list-container.grid-mode :global(.meta-icon) {
505
        width: 1.5rem !important;
506
        height: 1.5rem !important;
507
        margin-right: 0.25rem !important;
508
    }
509

510
    #post-list-container.grid-mode :global(.post-meta .text-sm) {
511
        font-size: 0.75rem !important;
512
        line-height: 1rem !important;
513
    }
514

515
    #post-list-container.grid-mode :global(.post-meta .pinned-btn) {
516
        padding: 0.25rem 0.375rem !important;
517
    }
518
</style>

展开收起

创建URL工具函数#

文件路径：src/utils/url-utils.ts

1
export function getCategoryUrl(category: string | null): string {
2
  if (
3
    !category ||
4
    category.trim() === "" ||
5
    category.trim().toLowerCase() === i18n(I18nKey.uncategorized).toLowerCase()
6
  )
7
    return url("/categories/uncategorized/");
8
  return url(`/categories/${encodeURIComponent(category.trim())}/`);
9
}
10

11
export function getCategoryPageUrl(): string {
12
  return url("/categories/");
13
}

更新分类栏组件#

文件路径：src/components/layout/CategoryBar.astro

1
---
2
import { url, getCategoryPageUrl } from "@/utils/url-utils";
3
const categoriesUrl = getCategoryPageUrl();
4
---
5

6
<a
7
      href={categoriesUrl}
8
      class="category-pill text-sm px-3 py-1 rounded-lg whitespace-nowrap flex-shrink-0
9
             transition-colors duration-200 flex items-center justify-center"
10
      data-category-name="__categories__"
11
    >
12
      {i18n(I18nKey.categories)}
13
      <span class="text-xs opacity-60 ml-1">{categories.length}</span>
14
</a>

导航栏配置#

文件路径：src/config/navBarConfig.ts

1
// 根据页面开关动态生成导航栏配置
2
const getDynamicNavBarConfig = (): NavBarConfig => {
3
  // 基础导航栏链接
4
  const links: (NavBarLink | LinkPreset)[] = [
5
    // 主页
6
    LinkPreset.Home,
7

8
    // 文章分类
9
    {
10
      name: "分类",
11
      url: "/categories/",
12
      icon: "material-symbols:folder-open",
13
    },
14

15
    // 归档
16
    LinkPreset.Archive,
17
  ];
18
}

展开收起

语言配置#

文件路径：src/i18n/i18nKey.ts

1
allCategories = "allCategories",

文件路径：src/i18n/languages/en.ts

1
[Key.allCategories]: "All Categories",

文件路径：src/i18n/languages/ja.ts

1
[Key.allCategories]: "すべてのカテゴリ",

文件路径：src/i18n/languages/ru.ts

1
[Key.allCategories]: "Все категории",

文件路径：src/i18n/languages/zh_CN.ts

1
  [Key.allCategories]: "全部分类",

文件路径：src/i18n/languages/zh_TW.ts

1
  [Key.allCategories]: "全部分類",

恋爱计时组件

Tue, 02 Jun 2026 00:00:00 GMT

创建组件#

文件路径：src/components/widget/RelationshipTimer.astro

1
<!-- 恋爱倒计时组件 -->
2
---
3
import WidgetLayout from "@/components/common/WidgetLayout.astro";
4
import { relationshipConfig } from "@/config/relationshipConfig";
5

6
const config = relationshipConfig;
7

8
interface Props {
9
  class?: string;
10
  style?: string;
11
}
12
const className = Astro.props.class;
13
const style = Astro.props.style;
14
---
15

16
<WidgetLayout
17
  name={config.title || "恋爱时光"}
18
  id="relationship"
19
  class={className}
20
  style={style}
21
>
22
  <div class="flex flex-col items-center p-2">
23
    <!-- 顶部名称栏 -->
24
    <div class="flex items-center justify-center gap-2 mb-4 text-sm font-medium text-neutral-600 dark:text-neutral-400">
25
      <span>{config.name1}</span>
26
      <span class="text-red-500 animate-pulse">❤️</span>
27
      <span>{config.name2}</span>
28
    </div>
29

30
    <!-- 头像和爱心 -->
31
    <div class="flex items-center justify-center gap-4 mb-6">
32
      <div class="w-16 h-16 rounded-full overflow-hidden border-2 border-white dark:border-neutral-800 shadow-md transition-transform hover:scale-110">
33
        <img src={config.avatar1} alt={config.name1} class="w-full h-full object-cover" />
34
      </div>
35
      <div class="text-2xl text-red-500 transform transition-all hover:scale-125 hover:rotate-12 cursor-pointer">
36
        ❤️
37
      </div>
38
      <div class="w-16 h-16 rounded-full overflow-hidden border-2 border-white dark:border-neutral-800 shadow-md transition-transform hover:scale-110">
39
        <img src={config.avatar2} alt={config.name2} class="w-full h-full object-cover" />
40
      </div>
41
    </div>
42

43
    <!-- 计时器 -->
44
    <div class="relationship-timer flex items-center justify-center gap-x-1 text-sm whitespace-nowrap overflow-x-auto">
45
      <span class="timer-num" data-timer-years>0</span><span class="timer-unit bg-red-400">年</span>
46
      <span class="timer-num" data-timer-months>0</span><span class="timer-unit bg-red-300">月</span>
47
      <span class="timer-num" data-timer-days>0</span><span class="timer-unit bg-blue-400">天</span>
48
      <span class="timer-num" data-timer-hours>0</span><span class="timer-unit bg-orange-400">时</span>
49
      <span class="timer-num" data-timer-minutes>0</span><span class="timer-unit bg-blue-500">分</span>
50
      <span class="timer-num" data-timer-seconds>00</span><span class="timer-unit bg-purple-400">秒</span>
51
    </div>
52
  </div>
53
</WidgetLayout>
54

55
<style>
56
  @reference "tailwindcss";
57

58
  .timer-num {
59
    @apply font-bold text-neutral-700 dark:text-neutral-200 min-w-[0rem] text-center;
60
    color: var(--primary);
61
  }
62
  .timer-unit {
63
    @apply px-1 py-0.5 rounded text-[10px] text-white font-medium shrink-0;
64
  }
65
</style>
66

67
<script is:inline define:vars={{ startDateStr: config.startDate }}>
68
  function updateRelationshipTimer() {
69
    const startDate = new Date(startDateStr);
70
    const now = new Date();
71

72
    let diff = now.getTime() - startDate.getTime();
73

74
    if (diff < 0) return;
75

76
    // 计算年月日时分秒的差值
77
    let years = now.getFullYear() - startDate.getFullYear();
78
    let months = now.getMonth() - startDate.getMonth();
79
    let days = now.getDate() - startDate.getDate();
80
    let hours = now.getHours() - startDate.getHours();
81
    let minutes = now.getMinutes() - startDate.getMinutes();
82
    let seconds = now.getSeconds() - startDate.getSeconds();
83

84
    // 处理借位逻辑
85
    if (seconds < 0) {
86
      seconds += 60;
87
      minutes--;
88
    }
89
    if (minutes < 0) {
90
      minutes += 60;
91
      hours--;
92
    }
93
    if (hours < 0) {
94
      hours += 24;
95
      days--;
96
    }
97
    if (days < 0) {
98
      const lastMonth = new Date(now.getFullYear(), now.getMonth(), 0);
99
      days += lastMonth.getDate();
100
      months--;
101
    }
102
    if (months < 0) {
103
      months += 12;
104
      years--;
105
    }
106

107
    // 更新所有实例，避免移动端和电脑端 ID 冲突
108
    const update = (attr, value) => {
109
      const elements = document.querySelectorAll(`[data-timer-${attr}]`);
110
      elements.forEach(el => {
111
        el.innerText = value;
112
      });
113
    };
114

115
    update('years', years);
116
    update('months', months);
117
    update('days', days);
118
    update('hours', hours);
119
    update('minutes', minutes);
120
    update('seconds', seconds.toString().padStart(2, '0'));
121
  }
122

123
  // 立即运行并每秒更新
124
  updateRelationshipTimer();
125
  if (!window.relationshipTimerInterval) {
126
    window.relationshipTimerInterval = setInterval(updateRelationshipTimer, 1000);
127
  }
128

129
  // 监听 Swup 页面切换
130
  document.addEventListener('swup:content:replace', updateRelationshipTimer);
131
</script>

展开收起

注册组件#

文件路径：src/components/layout/SideBar.astro

1
---
2
import RelationshipTimer from "@/components/widget/RelationshipTimer.astro";  // 引入恋爱计时组件
3
---
4

5
// 组件映射表
6
const componentMap = {
7
    <!-- 恋爱计时组件 -->
8
  relationship: RelationshipTimer,
9
} satisfies Record<WidgetComponentType, typeof Profile>;

启用组件#

文件路径：src/config/sidebarConfig.ts

右侧边栏配置

1
{
2
  type: "relationship",    // 组件类型，与 componentMap 中的 key 对应
3
  enable: true,            // 是否启用
4
  position: "top",         // 组件位置：top（固定顶部）或 sticky（粘性定位）
5
  showOnPostPage: true,    // 是否在文章详情页显示
6
},

移动端配置

1
{
2
// 组件类型：恋爱计时小组件
3
type: "relationship",
4
// 是否启用该组件
5
enable: true,
6
// 是否在文章详情页显示
7
showOnPostPage: true,
8
},

配置类型定义#

文件路径：src/types/config.ts

1
// 组件配置类型定义
2
export type WidgetComponentType =
3
  | "relationship";

双方信息配置#

文件路径：src/config/relationshipConfig.ts

1
import type { RelationshipConfig } from "../types/config";
2

3
export const relationshipConfig: RelationshipConfig = {
4
  // 恋爱开始日期
5
  startDate: "2026-01-06",
6
  // 双方名称
7
  name1: "---------TSH",
8
  name2: "CXY---------",
9
  // 双方头像
10
  avatar1: "https://re.tsh520.cn/zl/tsh.jpg",
11
  avatar2: "https://re.tsh520.cn/zl/cxy.jpg",
12
  // 小组件标题
13
  title: "我和宝宝在一起已经",
14
};

Umami 访问统计卡片

Tue, 02 Jun 2026 00:00:00 GMT

提示

本文是在博主 THW 文章：为 Fuwari 添加 Umami 访问统计卡片基础上增加了自己实践过程的一些细节，转载无需和我联系，但请注明文章来源。如果侵权之处，请联系博主进行删除，谢谢~

开始#

对于静态博客而言，了解访客来源与流量趋势是很有必要的。在不自建服务器的前提下，配置简单，功能强大的 Umami 往往是我们的首选。

然而，直接挂载 Umami 的分享外链不够直观且破坏页面一致性。本文将教你如何将 Umami 的统计数据以原生组件的形式集成到 Firefly 主题的侧边栏中，让你的博客实时展示访问数据。

Umami 访问统计卡片

准备工作#

一个已部署好的Firefly博客
无服务器部署Umami统计教程：Vercel 部署
启用Umami统计的站点

获取数据#

为了获取到图中的这些数据，我们需要启用 Umami 统计的分享 URL。

你应该会得到一个类似 https://umami.seasir.top/share/xxxxxxxxxxxx 格式的链接。记下这个链接，现在我们只需要它就能完成所有配置。

alt text

创建组件#

文件路径：src/components/widget/UmamiStats.astro

1
---
2
import WidgetLayout from "@/components/common/WidgetLayout.astro";
3

4
interface Props {
5
  class?: string;
6
  style?: string;
7
}
8
const { class: className, style } = Astro.props;
9
---
10

11
<WidgetLayout id="umami-stats" name="统计" class:list={["umami-stats-container", className, "cursor-pointer transition-opacity active:scale-95"]} {style}>
12
    <a target="_blank" rel="noopener noreferrer" class="block umami-link">
13
        <div class="text-center py-2">
14
            <div class="text-3xl font-bold text-neutral-900 dark:text-neutral-100 umami-total-pageviews">-</div>
15
            <div class="text-sm text-neutral-500 dark:text-neutral-400">总浏览量</div>
16
        </div>
17
        <div class="grid grid-cols-2 divide-x divide-neutral-200 dark:divide-neutral-700 text-center pt-2">
18
            <div class="px-2">
19
                <div class="text-xl font-bold text-neutral-900 dark:text-neutral-100 umami-total-visits">-</div>
20
                <div class="text-sm text-neutral-500 dark:text-neutral-400">访问数</div>
21
            </div>
22
            <div class="px-2">
23
                <div class="text-xl font-bold text-neutral-900 dark:text-neutral-100 umami-total-visitors">-</div>
24
                <div class="text-sm text-neutral-500 dark:text-neutral-400">游客数</div>
25
            </div>
26
        </div>
27
    </a>
28
</WidgetLayout>
29

30
<script>
31
const UMAMI_CONFIG = {
32
    shareUrl: 'https://umami.seasir.top/share/xxxxxxxxxxxx',
33
};
34

35
let __UMAMI_INTERNAL = {
36
    baseUrl: '',
37
    websiteId: '',
38
    shareToken: '',
39
    shareId: '',
40
    isReady: false
41
};
42

43
const FALLBACK_STATS = {
44
    pageviews: 1000,
45
    visits: 1000,
46
    visitors: 1000,
47
};
48

49
async function initUmamiConfig() {
50
    try {
51
        const sharePath = UMAMI_CONFIG.shareUrl.split('/share/')[1];
52
        if (!sharePath) throw new Error('Invalid Umami Share URL');
53

54
        let apiBase = '';
55
        if (UMAMI_CONFIG.shareUrl.includes('cloud.umami.is') || UMAMI_CONFIG.shareUrl.includes('analytics.umami.is')) {
56
            const region = UMAMI_CONFIG.shareUrl.includes('/analytics/eu/') ? 'eu' : 'us';
57
            apiBase = `https://cloud.umami.is/analytics/${region}/api`;
58
        } else {
59
            const urlObj = new URL(UMAMI_CONFIG.shareUrl);
60
            apiBase = `${urlObj.origin}/api`;
61
        }
62

63
        const res = await fetch(`${apiBase}/share/${sharePath}`);
64
        if (!res.ok) throw new Error(`Failed to fetch share config: ${res.status}`);
65
        const data = await res.json();
66

67
        __UMAMI_INTERNAL = {
68
            baseUrl: apiBase,
69
            websiteId: data.websiteId,
70
            shareToken: data.token,
71
            shareId: data.shareId,
72
            isReady: true
73
        };
74

75
        const links = document.querySelectorAll('.umami-link');
76
        links.forEach(link => link.setAttribute('href', UMAMI_CONFIG.shareUrl));
77

78
    } catch (e) {
79
        console.error('Umami Config Init Failed:', e);
80
    }
81
}
82

83
function formatNumber(num: number): string {
84
    if (num >= 1000000) {
85
        return (num / 1000000).toFixed(1) + 'M';
86
    } else if (num >= 1000) {
87
        return (num / 1000).toFixed(1) + 'K';
88
    }
89
    return Math.round(num).toString();
90
}
91

92
function setStats(values: { pageviews: number; visits: number; visitors: number }) {
93
    const pageviewsElements = document.querySelectorAll('.umami-total-pageviews');
94
    const visitsElements = document.querySelectorAll('.umami-total-visits');
95
    const visitorsElements = document.querySelectorAll('.umami-total-visitors');
96

97
    const easeOutCubic = (t: number) => 1 - Math.pow(1 - t, 3);
98
    const animHandles = new Map<HTMLElement, number>();
99

100
    const animateStat = (el: HTMLElement | null, to: number, duration = 2000) => {
101
        if (!el) return;
102

103
        const prev = animHandles.get(el);
104
        if (prev) cancelAnimationFrame(prev);
105

106
        const from = 0;
107
        const startTime = performance.now();
108

109
        const tick = (now: number) => {
110
            const elapsed = now - startTime;
111
            const progress = Math.min(1, elapsed / duration);
112
            const easedProgress = easeOutCubic(progress);
113

114
            const current = from + (to - from) * easedProgress;
115
            el.textContent = formatNumber(current);
116

117
            if (progress < 1) {
118
                animHandles.set(el, requestAnimationFrame(tick));
119
            }
120
        };
121
        animHandles.set(el, requestAnimationFrame(tick));
122
    };
123

124
    pageviewsElements.forEach(el => animateStat(el as HTMLElement, values.pageviews));
125
    visitsElements.forEach(el => animateStat(el as HTMLElement, values.visits));
126
    visitorsElements.forEach(el => animateStat(el as HTMLElement, values.visitors));
127
}
128

129
async function fetchUmamiStats() {
130
    if (!__UMAMI_INTERNAL.isReady) {
131
        await initUmamiConfig();
132
    }
133

134
    if (!__UMAMI_INTERNAL.isReady) {
135
        setStats(FALLBACK_STATS);
136
        return;
137
    }
138

139
    try {
140
        const endAt = Date.now();
141
        const startAt = 0;
142
        const url = `${__UMAMI_INTERNAL.baseUrl}/websites/${__UMAMI_INTERNAL.websiteId}/stats?startAt=${startAt}&endAt=${endAt}&unit=hour&timezone=Asia%2FShanghai`;
143

144
        const response = await fetch(url, {
145
            headers: {
146
                'x-umami-share-context': '1',
147
                'x-umami-share-token': __UMAMI_INTERNAL.shareToken
148
            }
149
        });
150

151
        if (!response.ok) throw new Error(`HTTP ${response.status}`);
152
        const data = await response.json();
153
        const getValue = (field: any) => (typeof field === 'object' ? field?.value : field) || 0;
154

155
        setStats({
156
            pageviews: getValue(data.pageviews),
157
            visits: getValue(data.visits),
158
            visitors: getValue(data.visitors),
159
        });
160

161
    } catch (error) {
162
        console.error('Umami Fetch Failed:', error);
163
        setStats(FALLBACK_STATS);
164
    }
165
}
166

167
let __umamiStatsStarted = false;
168
function startUmamiStats() {
169
    if (__umamiStatsStarted) return;
170
    __umamiStatsStarted = true;
171
    fetchUmamiStats();
172
}
173

174
function initUmamiStatsVisibility() {
175
    const containers = document.querySelectorAll('.umami-stats-container');
176
    const io = new IntersectionObserver((entries) => {
177
        let isAnyVisible = false;
178
        entries.forEach(entry => {
179
            if (entry.isIntersecting) isAnyVisible = true;
180
        });
181

182
        if (isAnyVisible) {
183
            startUmamiStats();
184
            io.disconnect();
185
        }
186
    }, { threshold: 0.1 });
187

188
    containers.forEach(container => io.observe(container));
189
}
190

191
initUmamiStatsVisibility();
192

193
if (window.swup) {
194
    window.swup.hooks.on('page:view', () => {
195
        __umamiStatsStarted = false;
196
        initUmamiStatsVisibility();
197
    });
198
}
199
</script>

展开收起

配置参数#

在代码文件的 script 部分，填入你的分享链接：

1
const UMAMI_CONFIG = {
2
    shareUrl: 'https://umami.seasir.top/share/xxxxxxxxxxxx',  // ← 这里改成你自己的
3
};

系统会自动解析 API 路径、Website ID 和验证 Token。

注册组件#

文件路径：src/components/layout/SideBar.astro

1
---
2
import UmamiStats from "@/components/widget/UmamiStats.astro";  // 引入 Umami 组件
3
---
4

5
// 组件映射表
6
const componentMap = {
7
  umamiStats: UmamiStats,
8
} satisfies Record<WidgetComponentType, typeof Profile>;

配置侧边栏#

文件路径：src/config/sidebarConfig.ts

1
{
2
    // 组件类型：Umami 统计组件
3
    type: "umamiStats",
4
    // 是否启用该组件
5
    enable: true,
6
    // 组件位置
7
    position: "top",
8
    // 是否在文章详情页显示
9
    showOnPostPage: true,
10
},

修改统计周期#

默认为所有时间，如果你想要调整浏览量统计的时间范围，可以修改 fetchUmamiStats 函数内的 startAt 参数。

常用时间周期公式（单位：毫秒）：

24小时：24 * 60 * 60 * 1000 = 86400000

最近30天：30 * 24 * 60 * 60 * 1000 = 2592000000

最近90天：90 * 24 * 60 * 60 * 1000 = 7776000000

修改示例（例如改为最近 30 天）：

1
try {
2
    const endAt = Date.now();
3
    const startAt = 0; // [!code --]
4
    const startAt = Date.now() - 2592000000; //[!code ++]
5
}

这将从 30 天前开始统计浏览量。

##配置备用数据

如果遇到 API 请求失败，全新的组件会显示你配置的备用数据以保持 UI 美观。你可以在 FALLBACK_STATS 对象中修改这些数值（默认为1000）：

1
const FALLBACK_STATS = {
2
    pageviews: 1000, // 备用总浏览量
3
    visits: 1000,    // 备用访问数
4
    visitors: 1000,  // 备用游客数
5
};

结尾#

通过以上步骤，你就成功为 Fuwari 添加了具有丰富交互感、自动解析配置且支持点击查看详情的 Umami 统计卡片。

欢迎提示组件

Tue, 02 Jun 2026 00:00:00 GMT

提示

本文是在博主年华文章：Firefly 主题 WelcomeToast 组件分析基础上增加了自己实践过程的一些细节，转载无需和我联系，但请注明文章来源。如果侵权之处，请联系博主进行删除，谢谢~

欢迎提示组件

创建组件#

文件路径：src/components/widget/WelcomeToast.astro

src/components/WelcomeToast.astro展开收起

1
<script>
2
    // const VISIT_SESSION_KEY = 'blog_visit_flag';
3
    let hasShownToast = false;
4

5
    function createWelcomeToast() {
6
        const toast = document.createElement('div');
7
        toast.id = 'welcome-toast';
8
        // Tailwind 样式控制：自动适配深色模式
9
        toast.className = 'fixed bottom-4 right-4 z-50 transform translate-y-full opacity-0 transition-all duration-500 ease-out';
10

11
        //使用 bg-white dark:bg-zinc-800 强制适配颜色
12
        toast.innerHTML = `
13
            <div class="bg-white dark:bg-zinc-800 border border-gray-200 dark:border-zinc-700 rounded-lg shadow-lg p-4 max-w-xs">
14
                <div class="flex items-start gap-3">
15
                    <div class="flex-shrink-0 text-2xl">👋</div>
16
                    <div class="flex-1 min-w-0">
17
                        <p id="welcome-message" class="text-sm font-semibold text-gray-900 dark:text-gray-100">
18
                            正在加载...
19
                        </p>
20
                        <p class="text-xs text-gray-600 dark:text-gray-400 mt-2 italic">
21
                            欢迎来到我的博客
22
                        </p>
23
                    </div>
24
                    <button
25
                        onclick="closeWelcomeToast()"
26
                        class="flex-shrink-0 text-gray-400 hover:text-gray-800 dark:hover:text-gray-200 transition-colors"
27
                        aria-label="关闭"
28
                    >
29
                        <svg class="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
30
                            <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M6 18L18 6M6 6l12 12"></path>
31
                        </svg>
32
                    </button>
33
                </div>
34
            </div>
35
        `;
36
        document.body.appendChild(toast);
37
        return toast;
38
    }
39

40
    function closeWelcomeToast() {
41
        const toast = document.getElementById('welcome-toast');
42
        if (toast) {
43
            toast.classList.add('translate-y-full', 'opacity-0');
44
            toast.classList.remove('translate-y-0', 'opacity-100');
45
            setTimeout(() => { toast.remove(); }, 500);
46
        }
47
    }
48

49
    async function fetchLocation() {
50
        try {
51
            const response = await fetch('https://v2.xxapi.cn/api/ip');
52
            const data = await response.json();
53
            if (data.code === 200 && data.data) {
54
                const locationText = `你好，来自${data.data.address}的朋友`;
55
                const messageEl = document.getElementById('welcome-message');
56
                if (messageEl) messageEl.textContent = locationText;
57
            }
58
        } catch (error) {
59
            const messageEl = document.getElementById('welcome-message');
60
            if (messageEl) messageEl.textContent = '你好，欢迎来到我的博客';
61
        }
62
    }
63

64
    async function showWelcomeToast() {
65
        if (hasShownToast) return;
66
        const toast = createWelcomeToast();
67
        setTimeout(() => {
68
            toast.classList.remove('translate-y-full', 'opacity-0');
69
            toast.classList.add('translate-y-0', 'opacity-100');
70
        }, 100);
71
        hasShownToast = true;
72
        await fetchLocation();
73
        setTimeout(() => { closeWelcomeToast(); }, 5000);
74
    }
75

76
    function initWelcome() {
77
        // 检查是否已显示过欢迎弹窗
78
        // if (!sessionStorage.getItem(VISIT_SESSION_KEY)) {
79
        //     sessionStorage.setItem(VISIT_SESSION_KEY, 'true');
80
        //     showWelcomeToast();
81
        // }
82
        // 显示欢迎弹窗
83
        showWelcomeToast();
84
    }
85

86
    if (document.readyState === 'loading') {
87
        document.addEventListener('DOMContentLoaded', initWelcome);
88
        document.addEventListener('astro:page-load', initWelcome);
89
    } else {
90
        initWelcome();
91
    }
92

93
    (window as any).closeWelcomeToast = closeWelcomeToast;
94
</script>
95

96
<style>
97
    /* 样式保持不变 */
98
    #welcome-toast { max-width: calc(100vw - 2rem); }
99
    @media (max-width: 640px) {
100
        #welcome-toast {
101
            top: auto; bottom: 1rem; left: 50%; right: auto;
102
            transform: translateX(-50%) translateY(100%);
103
            width: 90%; max-width: none;
104
            transition: transform 0.5s ease-out, opacity 0.5s ease-out;
105
        }
106
        #welcome-toast.translate-y-0 { transform: translateX(-50%) translateY(0); }
107
        #welcome-toast.translate-y-full { transform: translateX(-50%) translateY(100%); }
108
    }
109
</style>

展开收起

使用组件#

文件路径：src/layouts/MainGridLayout.astro

1
---
2
import WelcomeToast from "@components/widget/WelcomeToast.astro"; //欢迎提示组件
3
---
4

5
<!-- 欢迎提示组件 -->
6
<WelcomeToast></WelcomeToast>

显示逻辑配置#

访客只在首次访问时显示欢迎弹窗（原作者）

1
    function initWelcome() {
2
        // 检查是否已显示过欢迎弹窗
3
        if (!sessionStorage.getItem(VISIT_SESSION_KEY)) {
4
            sessionStorage.setItem(VISIT_SESSION_KEY, 'true');
5
            showWelcomeToast(); // 显示欢迎弹窗
6
        }
7
    }

访客只会在首页刷新时显示，非首页刷新不会显示（正在使用）

1
    function initWelcome() {
2
        // 检查是否为首页（路径为 "/" 或 "/index.html"）
3
        const isHomePage = window.location.pathname === '/' || window.location.pathname === '/index.html';
4

5
        // 只在首页显示欢迎弹窗
6
        if (isHomePage) {
7
            showWelcomeToast();
8
        }
9
    }

访客每次刷新页面时，欢迎提示组件会重新显示，不限于文章页。

1
    function initWelcome() {
2
        // 显示欢迎弹窗
3
        showWelcomeToast();
4
    }

实现今日一言功能

Sat, 30 May 2026 00:00:00 GMT

创建数据文件#

文件路径：src/content/ziyuan/ 目录并添加文件：quote.md

1
---
2
title: "每日一言"
3
quotes:
4
  - text: "生活不是等待暴风雨过去，而是学会在雨中跳舞。"
5
    author: "塞维涅夫人"
6
  - text: "世界上只有一种英雄主义，就是在认清生活真相之后依然热爱生活。"
7
    author: "罗曼·罗兰"
8
---

创建组件文件#

文件路径：src/components/widget/QuoteOfTheDay.astro

1
---
2
import WidgetLayout from "@/components/common/WidgetLayout.astro";
3
import { getCollection } from "astro:content";
4

5
// 从 content/ziyuan/quote.md 读取名言数据
6
const ziyuanEntries = await getCollection("ziyuan");
7
const quoteEntry = ziyuanEntries.find((e) => e.id === "quote");
8
const quoteData = quoteEntry?.data as any;
9
const quotes = quoteData?.quotes || [];
10

11
interface Props {
12
  class?: string;
13
  style?: string;
14
}
15

16
const { class: className, style } = Astro.props;
17

18
// 使用日期作为随机种子，确保同一天显示相同的名言
19
const today = new Date();
20
const dateStr = today.toISOString().split("T")[0];
21
const seed = dateStr.split("").reduce((acc, char) => acc + char.charCodeAt(0), 0);
22
const randomIndex = seed % quotes.length;
23
const quote = quotes[randomIndex] || { text: "暂无名言", author: "" };
24
---
25

26
<WidgetLayout name="✨ 今日一言" id="quote-of-the-day" class={className} style={style}>
27
  <div class="quote-content">
28
    <blockquote class="quote-text">
29
      <span class="quote-mark">"</span>
30
      {quote.text}
31
      <span class="quote-mark">"</span>
32
    </blockquote>
33
    <cite class="quote-author">—— {quote.author}</cite>
34
  </div>
35
</WidgetLayout>
36

37
<style>
38
  .quote-content {
39
    display: flex;
40
    flex-direction: column;
41
    gap: 0.75rem;
42
    padding: 0.5rem 0;
43
  }
44

45
  .quote-text {
46
    position: relative;
47
    font-style: italic;
48
    font-size: 0.9rem;
49
    line-height: 1.6;
50
    color: var(--text-color);
51
    padding: 0 0.5rem;
52
    margin: 0;
53
  }
54

55
  .quote-mark {
56
    font-size: 1.5rem;
57
    line-height: 0;
58
    vertical-align: middle;
59
    color: var(--primary);
60
    opacity: 0.6;
61
    font-family: Georgia, serif;
62
  }
63

64
  .quote-author {
65
    display: block;
66
    text-align: right;
67
    font-size: 0.75rem;
68
    color: var(--content-meta);
69
    font-style: normal;
70
    margin-top: 0.25rem;
71
  }
72

73
  /* 深色模式优化 */
74
  :global(html.dark) .quote-text {
75
    color: var(--text-color);
76
  }
77

78
  /* 悬停效果 */
79
  :global(.quote-content:hover .quote-text) {
80
    color: var(--primary);
81
    transition: color 0.2s ease;
82
  }
83
</style>

展开收起

配置数据加载方式#

在 src/content.config.ts 配置数据加载方式：

1
const ziyuanCollection = defineCollection({
2
  loader: glob({ pattern: "**/*.md", base: "./src/content/ziyuan" }),
3
  schema: z.union([
4
    z.object({
5
      title: z.string(),
6
      content: z.string(),
7
      closable: z.boolean().optional().default(true),
8
      link: z
9
        .object({
10
          enable: z.boolean().optional().default(true),
11
          text: z.string(),
12
          url: z.string(),
13
          external: z.boolean().optional().default(false),
14
        })
15
        .optional(),
16
      quotes: z.undefined().optional(),
17
    }),
18
    z.object({
19
      title: z.string(),
20
      quotes: z.array(
21
        z.object({
22
          text: z.string(),
23
          author: z.string(),
24
        })
25
      ),
26
      content: z.undefined().optional(),
27
      closable: z.undefined().optional(),
28
      link: z.undefined().optional(),
29
    }),
30
  ]),
31
});
32

33
export const collections = {
34
  ziyuan: ziyuanCollection,
35
};

展开收起

注册组件#

文件路径：src/components/layout/SideBar.astro

1
import QuoteOfTheDay from "@/components/widget/QuoteOfTheDay.astro";

添加到组件映射表：

1
const componentMap = {
2
  quoteOfTheDay: QuoteOfTheDay,  // 添加这一行
3
};

侧边栏配置#

文件路径：src/config/sidebarConfig.ts

添加到右侧边栏

1
rightComponents: [
2
  {
3
    type: "quoteOfTheDay",  // 必须与 componentMap 的 key 一致
4
    enable: true,           // true = 启用，false = 禁用
5
    position: "sticky",        // "top" = 固定顶部，"sticky" = 粘性定位
6
    showOnPostPage: true,   // 是否在文章详情页显示
7
  },
8
  // ... 其他组件
9
],

添加到移动端底部

1
mobileBottomComponents: [
2
  {
3
      // 组件类型：今日一言
4
      type: "quoteOfTheDay",
5
      // 是否启用该组件
6
      enable: true,
7
      // 是否在文章详情页显示
8
      showOnPostPage: true,
9
  },
10
  // ... 其他组件
11
],

类型定义#

文件路径：src/types/config.ts

1
export type WidgetComponentType =
2
  | "profile"
3
  | "announcement"
4
  // ... 其他类型
5
  | "quoteOfTheDay";  // 确保这一行存在

年轻的时候是旅游重要还是攒钱重要？

Thu, 30 Apr 2026 00:00:00 GMT

独特价值#

18岁时，我们揣着打工兼职存下的钱，就能在绿皮火车的硬座上熬一整夜

住青旅像回到大学宿舍般自在，和萍水相逢的陌生人聊起梦想，眼睛里都闪着光

那时的快乐很简单：有耗不尽的体力，特种兵旅行一整天，到第二天还有精力继续开启旅行

少年心气是不可再生之物，一场说走就走的旅行，一次毫不犹豫的出发，都是青春最滚烫的印记

人生有无数个夏天，却只有一次少年的烟火人间

我们只来一次，不如真诚一点，过得肆意，活成自己并永远热烈且自由

旅行心境#

或许到了30多岁，我们终于有能力选择喝着咖啡在沙滩边看日出日落、睡一觉就能抵达异国他乡的飞机，去往年轻时日思夜想的雪山

可站在山脚下的那一刻，却少了当年的激动，多了几分家里的柴米油盐和下班的疲惫

不再忙着打卡拍照发朋友圈，只想独自坐在山顶晒晒太阳发着呆

原来，最好的旅行从来不是在准备和计划中，而是在出发的那一刻

感悟人生#

大家常说：“欲买桂花同载酒，终不似少年游”

可也别忘了，“莫道桑榆晚，为霞尚满天”

人生还很长，一程有一程的风景

20岁没有完成的事情，30岁去完成也没关系；

就算是朝花夕拾，你觉得没有意义了，那也无所谓

人生于天地间，若白驹过隙，忽然而已

所以岁月不待人，及时当勉励，重在的是”诗酒趁年华”

遗憾错过#

你一生追求的东西，其实一开始就有

18岁的你想去旅行，可你囊中羞涩，止于心动

20岁的你，朋友都叫你出去玩，可你说学业要紧，止于行动

我们总说来日方长，却忘了人只活这一次

很多事情错过一次，可能就再也没有机会了；很多远方，错过一次就再也去不成了

所有的错过，最终都成为这辈子难以忘怀的遗憾；

或许等我老了，躺在床上回想起这一生，要是因为一些事而一次次错过自己的梦想与决定，那我该多懊悔啊！

出发勇气#

很多幸福和快乐都是后知后觉，当我们身在其中的时候，或许觉得并没有什么，但过了很久以后，就会开始怀念

在所有不确定的时间里，好好珍惜当下才是最珍贵的

愿你我永远有出发的勇气和说走就走的行动力，并一直朝着梦想远航