组件标签目录说明

本文档梳理 src/components/ 下的一级标签目录及其用途、典型组件与使用场景，帮助快速定位与复用。

总览

• about/：关于页相关布局与模块
• base/：全站基础与布局组件（头部、底部、背景、基础布局）
• blog/：博客文章与列表视图、交互（点赞、阅读量、分享等）
• common/：通用组件（按钮、面包屑、分页、目录、分享等）
• common/shortcodes/：Markdown/MDX 短代码（React 组件）
• home/：首页模块（文章日历、作者卡片、首页布局）
• not-found/：404 页面布局与样式
• notes/：笔记/动态内容相关视图与列表
• search/：站内搜索页与交互组件
• terms/：条款/术语页面布局
• ui/：基础 UI 原子组件（如玻璃态按钮）

---

about/

• 用途：关于页面的入口与布局。
• 路径：src/components/about/

组件详解（about）

• EntryLayout.astro
  • 用途：渲染关于页内容，负责标题、摘要、首图与正文的展示
  • 参数：
    • entry：CollectionEntry<"about">，通过 Astro.props.entry 传入
  • 参考：src/components/about/EntryLayout.astro:13

base/

• 用途：全站基础结构与公共区域组件，承载 SEO、主题、背景等。
• 路径：src/components/base/
• 参考：src/components/base/BaseLayout.astro:1–120

组件详解（base）

• BaseLayout.astro
  • 用途：页面基础骨架与 SEO 元信息容器
  • 参数：
    • title?: string
    • description?: string | null
    • image?: string
    • noindex?: boolean
    • canonical?: string
    • keywords?: string
  • 参考：src/components/base/BaseLayout.astro:13–23
• Header.astro
  • 用途：站点头部导航、Logo、主题切换按钮
  • 参数：无（使用 SITE_INFO 与内置 menu）
  • 参考：src/components/base/Header.astro:10–18
• Footer.astro
  • 用途：站点底部信息、社交链接、统计信息与回到顶部按钮
  • 参数：无（内部获取 SITE_INFO 与内容统计）
  • 参考：src/components/base/Footer.astro:47–66
• Background.astro
  • 用途：全局日/夜双背景切换（CSS）
  • 参数：无
  • 参考：src/components/base/Background.astro:1–36
• ObserverScript.astro
  • 用途：IntersectionObserver 驱动的进场动画控制
  • 参数：无
  • 参考：src/components/base/ObserverScript.astro:3–104
• ThemeScript.astro
  • 用途：读取/写入本地主题（light/dark/system）并应用到 html.dark
  • 参数：无
  • 参考：src/components/base/ThemeScript.astro:1–40
• ThemeSwitcher.astro
  • 用途：主题切换 UI，配合 ThemeScript 生效
  • 参数：无
  • 参考：src/components/base/ThemeSwitcher.astro:5–46

blog/

• 用途：博客内容相关的展示与交互，包括文章列表、侧栏、统计与分享。
• 路径：src/components/blog/
• 参考：src/components/blog/LikeButton.astro:1–30

组件详解（blog）

• BlogListCard.astro
  • 用途：博客列表页的文章卡片（紧凑、高度固定）
  • 参数：
    • entry: BlogEntry
  • 参考：src/components/blog/BlogListCard.astro:17–23
• Card.astro
  • 用途：主要用于首页的文章卡片（含图片、摘要、日期）
  • 参数：
    • entry: BlogEntry
  • 参考：src/components/blog/Card.astro:11–17
• CollectionLayout.astro
  • 用途：博客列表页布局（分页、侧栏、头部信息）
  • 参数：
    • entryIndex: BlogEntry
    • entries: BlogEntry[]
    • tags: string[]
    • categories: string[] | { name: string; slug: string; count: number }[]
    • pageIndex: number
    • pageCount: number
    • allBlogCount?: number
    • basePath?: string
  • 参考：src/components/blog/CollectionLayout.astro:15–37
• EntryLayout.astro
  • 用途：单篇文章页布局（头图、目录、正文、推荐）
  • 参数：
    • entry: CollectionEntry<"blog">
  • 参考：src/components/blog/EntryLayout.astro:18–24
• Sidebar.astro
  • 用途：侧栏（作者信息、分类、标签）
  • 参数：
    • tags: string[]
    • categories: string[] | { name: string; slug: string; count: number }[]
    • allBlogCount?: number
  • 参考：src/components/blog/Sidebar.astro:16–23
• ArticleStats.astro
  • 用途：文章统计区域（当前版本浏览量/点赞已取消）
  • 参数：
    • slug: string
  • 参考：src/components/blog/ArticleStats.astro:4
• ShareButton.astro
  • 用途：一键复制/分享当前文章链接并弹出提示
  • 参数：
    • title?: string
    • description?: string
    • folder?: string
    • id?: string
  • 参考：src/components/blog/ShareButton.astro:4–13
• RecommendedReadCard.astro
  • 用途：推荐阅读卡片（可选图片/阅读时间/紧凑模式）
  • 参数：
    • entry: BlogEntry
    • showImage?: boolean
    • showReadingTime?: boolean
    • compact?: boolean
  • 参考：src/components/blog/RecommendedReadCard.astro:11–23
• RelatedCardCompact.astro
  • 用途：紧凑样式的相关文章卡片（支持宽高/比例自定义）
  • 参数：
    • entry: BlogEntry
    • width?: string
    • height?: string
    • imageAspect?: string
    • showDescription?: boolean
  • 参考：src/components/blog/RelatedCardCompact.astro:8–22
• PlaceholderImage.astro
  • 用途：无图时的占位图（根据标题生成渐变与字母）
  • 参数：
    • title: string
    • className?: string
  • 参考：src/components/blog/PlaceholderImage.astro:2–7

common/

• 用途：跨页面复用的通用组件集合，涵盖按钮、导航、分页、分享等。
• 路径：src/components/common/

组件详解（common）

• Button.astro
  • 用途：链接按钮（封装 GlassButton 或扁平按钮）
  • 参数：
    • label: string
    • link?: string
    • newtab?: boolean
    • type?: "primary" | "secondary"
    • color?: string
    • hoverInvert?: boolean
    • glass?: boolean
  • 参考：src/components/common/Button.astro:4–22
• Breadcrumbs.astro
  • 用途：面包屑导航（基于当前路径）
  • 参数：
    • className?: string
  • 参考：src/components/common/Breadcrumbs.astro:4
• Pagination.astro
  • 用途：分页导航（支持数字页与 pageIDs 模式）
  • 参数：
    • collection?: string
    • pageIndex?: number
    • pageCount?: number
    • pageIDs?: string[]
    • basePath?: string
  • 参考：src/components/common/Pagination.astro:5–19
• TableOfContents.astro
  • 用途：根据 headings 生成目录并绑定平滑滚动
  • 参数：
    • headings: MarkdownHeading[]
    • tocDepth?: number
  • 参考：src/components/common/TableOfContents.astro:7–14
• Share.astro
  • 用途：社交平台分享按钮集合（Email/Twitter/Facebook/Pinterest）
  • 参数：
    • title?: string
    • description?: string | null
    • folder?: string
    • id?: string
  • 参考：src/components/common/Share.astro:9–16
• PageHeader.astro
  • 用途：列表页顶部标题、描述与面包屑
  • 参数：
    • title?: string
    • description?: string
    • articleCount?: number
  • 参考：src/components/common/PageHeader.astro:5–12
• FriendLinks.astro
  • 用途：客户端加载并展示 public/data/friends.json 的友情链接
  • 参数：无
  • 参考：src/components/common/FriendLinks.astro
• FriendLinkCard.astro
  • 用途：单个友链卡片展示
  • 参数：
    • link: { name: string; url: string; description?: string; avatar?: string; status?: string }
  • 参考：src/components/common/FriendLinkCard.astro:6–10
• Toast.astro
  • 用途：通用提示气泡（支持类型、位置、自动消失）
  • 参数：
    • title?: string
    • content: string
    • type?: 'success' | 'info' | 'warning' | 'error'
    • position?: 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left' | 'top-center' | 'bottom-center'
    • duration?: number
    • showIcon?: boolean
    • closable?: boolean
  • 参考：src/components/common/Toast.astro:3–21
• Social.astro
  • 用途：社交链接入口（微信/小红书/Email/RSS 等）
  • 参数：
    • links?: SocialLinks
  • 参考：src/components/common/Social.astro:14–18
• EntryHeader.astro
  • 用途：文章页头部信息（标题、作者、日期、阅读时间、分类、标签）
  • 参数：
    • entry: GenericEntry
    • showInfo?: boolean
    • showImage?: boolean
    • showTitle?: boolean
    • showAuthor?: boolean
    • showDate?: boolean
    • showPubDate?: boolean
    • showModDate?: boolean
    • showReadingTime?: boolean
    • showCategories?: boolean
    • showTags?: boolean
  • 参考：src/components/common/EntryHeader.astro:37–62
• LinksEntryLayout.astro
  • 用途：友情链接页面布局（含展示与申请说明）
  • 参数：无（内部使用 BaseLayout 设置标题与描述）
  • 参考：src/components/common/LinksEntryLayout.astro:10–13
• LiquidGlassLess.astro
  • 用途：玻璃态容器（可选动画、效果；支持扁平化关闭效果）
  • 参数：
    • containerType?: 'div' | 'section' | 'nav' | 'header' | 'footer'
    • containerClass?: string
    • wrapperClass?: string
    • textClass?: string
    • animation?: 'fadeLeft' | 'fadeRight' | 'fadeUp' | 'fadeDown' | 'none'
    • heavy?: boolean
    • showContainer?: boolean
    • enableGlassEffect?: boolean
    • effectClass?: string
    • tintClass?: string
    • shineClass?: string
  • 参考：src/components/common/LiquidGlassLess.astro:2–59
• LiquidGlassNone.astro
  • 用途：无玻璃效果的轻量容器（统一容器与动画接口）
  • 参数：
    • containerType?: 'div' | 'section' | 'nav' | 'header' | 'footer'
    • containerClass?: string
    • wrapperClass?: string
    • textClass?: string
    • animation?: 'fadeLeft' | 'fadeRight' | 'fadeUp' | 'fadeDown' | 'none'
    • heavy?: boolean
    • showContainer?: boolean
    • effectClass?: string
    • tintClass?: string
    • shineClass?: string
  • 参考：src/components/common/LiquidGlassNone.astro:2–54
• authorSidebar.astro
  • 用途：作者信息与站点统计简介
  • 参数：无
  • 参考：src/components/common/authorSidebar.astro

common/shortcodes/

• 用途：用于 Markdown/MDX 的短代码组件（React 实现），为富内容提供折叠、标签页、提示等交互能力。
• 路径：src/components/common/shortcodes/
• 参考：src/components/common/shortcodes/Tabs.tsx:1–20

组件详解（shortcodes）

• Accordion.tsx
  • 用途：内容折叠面板
  • 参数：
    • title: string
    • children: React.ReactNode
  • 参考：src/components/common/shortcodes/Accordion.tsx:3–12
• Notice.tsx
  • 用途：提示块（note/tip/info/warning）
  • 参数：
    • type: string
    • children: React.ReactNode
  • 参考：src/components/common/shortcodes/Notice.tsx:4–10
• Tabs.tsx
  • 用途：标签页容器（从 children.props.value 解析 Tab 面板）
  • 参数：
    • children: React.ReactElement
  • 参考：src/components/common/shortcodes/Tabs.tsx:9–14
• Tab.tsx
  • 用途：单个标签页面板（供 Tabs 解析）
  • 参数：
    • name: string
    • children: React.ReactNode
  • 参考：src/components/common/shortcodes/Tab.tsx:3–4
• ScrollArea.tsx
  • 用途：带滚动条的容器（Radix UI 封装）
  • 参数：透传 @radix-ui/react-scroll-area 的 Root/Scrollbar 属性
  • 参考：src/components/common/shortcodes/ScrollArea.tsx:11–26
• Youtube.tsx
  • 用途：轻量 YouTube 视频嵌入
  • 参数：
    • id: string
    • title: string
    • 其他属性透传到 LiteYouTubeEmbed
  • 参考：src/components/common/shortcodes/Youtube.tsx:5–13

home/

• 用途：站点首页的展示模块与布局。
• 路径：src/components/home/

组件详解（home）

• EntryLayout.astro
  • 用途：首页入口内容块布局（图文、按钮）
  • 参数：
    • entry：集合项数据（Astro.props.entry）
  • 参考：src/components/home/EntryLayout.astro:12–14
• ArticleCalendar.astro
  • 用途：文章日历视图
  • 参数：无
• AuthorProfile.astro
  • 用途：作者档案/简介
  • 参数：无

not-found/

• 用途：404（Not Found）页面布局与样式。
• 路径：src/components/not-found/

组件详解（not-found）

• EntryLayout.astro
  • 用途：404 页面布局
  • 参数：无或页面内置文案

notes/

• 用途：笔记/动态内容的集合、列表与预览展示。
• 路径：src/components/notes/

组件详解（notes）

• CollectionLayout.astro
  • 用途：笔记集合页布局与分页
  • 参数：
    • entryIndex
    • entries: NoteEntry[]
    • pageIndex: number
    • pageCount: number
    • allNotesCount?: number
    • basePath?: string
  • 参考：src/components/notes/CollectionLayout.astro:25–27
• HomeNotesPreview.astro
  • 用途：首页的笔记预览区块
  • 参数：
    • entries: NoteEntry[]
    • limit?: number = 3
  • 参考：src/components/notes/HomeNotesPreview.astro:12–14
• NotesListCard.astro
  • 用途：笔记列表卡片（心情/地点/图片等摘要）
  • 参数：
    • entry: NoteEntry
  • 参考：src/components/notes/NotesListCard.astro:15–17
• TaxaLayout.astro
  • 用途：标签或分类维度的笔记聚合视图
  • 参数：
    • taxonomy: string
    • taxa: string[]
    • allTaxa: string[]
  • 参考：src/components/notes/TaxaLayout.astro:11–13

search/

• 用途：站内搜索页面与交互，包括关键词匹配与结果列表渲染。
• 路径：src/components/search/
• 参考：src/components/search/Search.tsx:1–40

组件详解（search）

• Search.tsx
  • 用途：站内搜索页面（输入、URL 同步、Fuse.js 匹配）
  • 参数：
    • searchList: SearchableEntry[]
  • 参考：src/components/search/Search.tsx:8–15

terms/

• 用途：术语或条款页面的布局与呈现。
• 路径：src/components/terms/

组件详解（terms）

• EntryLayout.astro
  • 用途：条款内容页面布局
  • 参数：
    • entry
  • 参考：src/components/terms/EntryLayout.astro:12–15

ui/

• 用途：基础 UI 原子组件，用于在不同模块中复用，提升一致性。
• 路径：src/components/ui/

组件详解（ui）

• GlassButton.astro
  • 用途：玻璃态按钮（封装变体/尺寸/加载/图标等）
  • 参数：
    • variant?: 'primary' | 'secondary' | 'success' | 'warning' | 'danger' | 'info' | 'menu'
    • size?: 'sm' | 'md' | 'lg' | 'menu'
    • disabled?: boolean
    • loading?: boolean
    • icon?: string
    • iconPosition?: 'left' | 'right'
    • className?: string
    • id?: string
    • title?: string
    • type?: 'button' | 'submit' | 'reset'
    • onClick?: string
    • open?: boolean
  • 参考：src/components/ui/GlassButton.astro:2–49

---