ArticleHeader 组件使用说明

建站
0 字 / 约 0 分钟

ArticleHeader 组件使用说明 ​

概述 ​

ArticleHeader 是一个自动为Markdown文档添加文章头部信息的Vue组件，包含路径导航、发布时间、字数统计、阅读时间等信息。

功能特性 ​

1. 路径导航（面包屑） ​

  • 自动根据当前页面路径生成面包屑导航
  • 支持多级目录结构
  • 自动处理数字前缀（如 "10.版图" → "版图"）
  • 响应式设计，移动端友好

2. 文章元信息 ​

  • 发布时间：从frontmatter的 createTime 字段读取
  • 字数统计：自动计算文章字数（中文字符 + 英文单词）
  • 阅读时间：按每分钟200字计算
  • 分类信息：从frontmatter的 categories 字段读取
  • 标签信息：从frontmatter的 tags 字段读取

3. 视觉设计 ​

  • 使用SVG图标，支持深色模式
  • 响应式布局，适配不同屏幕尺寸
  • 与VitePress主题风格一致

自动插入机制 ​

组件通过Vite插件自动在Markdown文件中插入，无需手动添加：

  1. 插入位置：在H1标题前插入
  2. 跳过文件：自动跳过 index.md 和 AllArticles.md
  3. 避免重复：如果文件中已存在ArticleHeader组件，不会重复插入

自定义配置 ​

修改组件样式 ​

编辑 docs/.vitepress/theme/components/ArticleHeader.vue 文件：

vue
<style scoped>
/* 自定义样式 */
.article-header {
  /* 修改头部容器样式 */
}

.article-title {
  /* 修改标题样式 */
}

.article-meta {
  /* 修改元信息样式 */
}
</style>

修改阅读速度 ​

在组件中修改阅读速度计算：

javascript
// 计算阅读时间（按每分钟200字计算）
readTime.value = Math.max(1, Math.ceil(totalWords / 200))

修改字数统计规则 ​

在 calculateStats 函数中自定义字数统计逻辑：

javascript
const calculateStats = () => {
  // 自定义字数统计逻辑
  const chineseChars = (cleanText.match(/[\u4e00-\u9fa5]/g) || []).length
  const englishWords = (cleanText.match(/[a-zA-Z]+/g) || []).length
  const totalWords = chineseChars + englishWords
  // ...
}

手动使用 ​

如果需要在特定文件中手动使用组件：

vue
<ArticleHeader
  title="文章标题"
  create-time="2025-01-21T10:00:00.000Z"
  :categories="['分类1', '分类2']"
  :tags="['标签1', '标签2']"
/>

技术实现 ​

文件结构 ​

docs/.vitepress/
├── theme/
│   ├── components/
│   │   ├── ArticleHeader.vue    # 主组件
│   │   └── README.md           # 使用说明
│   └── index.ts                # 主题配置
└── plugins/
    └── vite-article-header.js  # Vite插件

核心功能 ​

  1. 路径解析：使用VitePress的 useRoute 获取当前路径
  2. 字数统计：通过DOM操作获取页面内容并计算字数
  3. 响应式数据：使用Vue 3的响应式API
  4. 自动插入：通过Vite插件在构建时处理Markdown文件

故障排除 ​

组件未显示 ​

  1. 检查组件是否正确注册在 theme/index.ts 中
  2. 确认Vite插件已添加到 config.ts 中
  3. 检查文件是否被跳过（如 index.md）

字数统计不准确 ​

  1. 确认页面内容已完全加载
  2. 检查 calculateStats 函数的执行时机
  3. 验证DOM选择器是否正确

样式问题 ​

  1. 检查CSS变量是否正确定义
  2. 确认深色模式适配
  3. 验证响应式断点设置

更新日志 ​

  • v1.0.0 - 初始版本，包含基础功能
  • 路径导航、字数统计、阅读时间计算
  • 自动插入机制
  • 响应式设计和深色模式支持

Frontmatter 与 SEO（合并自《文章元信息与 SEO》） ​

Frontmatter 规范 ​

  • title：显示标题
  • permalink：访问路径（优先级最高）
  • createTime：创建时间
  • tags / categories：标签与分类

提取与展示 ​

  • 工具：.vitepress/utils/articleMeta.ts
  • 组件：列表卡片展示摘要、标签、时间

代码片段：文章元信息 HTML 生成 ​

ts
// docs/.vitepress/utils/articleMeta.ts（节选）
export interface ArticleMeta {
  createTime?: string
  categories?: string[]
  tags?: string[]
}

export function generateArticleMeta(frontmatter: ArticleMeta): string {
  const metaItems: string[] = []
  if (frontmatter.createTime) {
    const date = new Date(frontmatter.createTime)
    const formattedDate = date.toLocaleDateString('zh-CN', {
      year: 'numeric', month: 'long', day: 'numeric'
    })
    metaItems.push(`<div class="mt-2 flex items-center text-sm text-gray-500">
      <Icon name="CalendarIcon" class="mr-1.5 size-5 shrink-0 text-gray-400" aria-hidden="true" /> ${formattedDate}</div>`)
  }
  if (frontmatter.categories?.length) {
    metaItems.push(`<div class="mt-2 flex items-center text-sm text-gray-500">
      <Icon name="CatIcon" class="mr-1.5 size-5 shrink-0 text-gray-400" aria-hidden="true" /> ${frontmatter.categories.join(' / ')}</div>`)
  }
  if (frontmatter.tags?.length) {
    metaItems.push(`<div class="mt-2 flex items-center text-sm text-gray-500">
      <Icon name="TagIcon" class="mr-1.5 size-5 shrink-0 text-gray-400" aria-hidden="true" /> ${frontmatter.tags.join(', ')}</div>`)
  }
  return metaItems.length ? `<div class="mt-1 flex flex-col sm:mt-0 sm:flex-row sm:flex-wrap sm:space-x-6">${metaItems.join('')}</div>` : ''
}

实践 ​

  • 文件名可与 title 不一致，统一由 permalink 负责路由