Skip to main content
我的博客

API 参考

Astro Modular • Version 1.1.0 •

本文档提供 Astro Modular 主题 API、工具和配置选项的完整参考。

内容集合

文章集合 (Posts)

interface PostData {
  title: string;          // 文章标题（必需）
  description: string;    // 文章描述（必需）
  date: Date;            // 发布日期（必需）
  tags?: string[];       // 标签数组
  draft?: boolean;       // 是否为草稿
  image?: string;        // 封面图片路径
  imageAlt?: string;     // 图片替代文本
  imageOG?: boolean;     // 使用作为 Open Graph 图片
  hideCoverImage?: boolean; // 隐藏封面图片
  hideTOC?: boolean;     // 隐藏目录
  targetKeyword?: string; // SEO 目标关键词
  noIndex?: boolean;     // SEO noindex 标记
}

页面集合 (Pages)

interface PageData {
  title: string;         // 页面标题（必需）
  description: string;   // 页面描述（必需）
  draft?: boolean;       // 是否为草稿
  lastModified?: Date;   // 最后修改日期
  image?: string;        // 封面图片
  imageAlt?: string;     // 图片替代文本
  hideCoverImage?: boolean; // 隐藏封面图片
  hideTOC?: boolean;     // 隐藏目录
  noIndex?: boolean;     // SEO noindex 标记
}

项目集合 (Projects)

interface ProjectData {
  title: string;         // 项目标题（必需）
  description: string;   // 项目描述（必需）
  date: Date;           // 项目日期（必需）
  categories?: string[]; // 分类数组
  projectUrl?: string;   // 项目 URL
  repositoryUrl?: string; // 仓库 URL
  status?: string;       // 项目状态
  featured?: boolean;    // 是否为特色项目
  image?: string;        // 封面图片
  imageAlt?: string;     // 图片替代文本
}

文档集合 (Docs)

interface DocData {
  title: string;         // 文档标题（必需）
  description: string;   // 文档描述（必需）
  category: string;      // 文档分类（必需）
  order: number;         // 排序顺序
  version?: string;      // 版本号
  lastModified?: Date;   // 最后修改日期
  featured?: boolean;    // 是否为特色文档
}

配置 API

网站配置

interface SiteConfig {
  site: string;          // 网站 URL
  title: string;         // 网站标题
  description: string;   // 网站描述
  author: string;        // 作者名称
  language: string;      // 语言代码（如 "zh-CN"）
  theme: string;         // 主题名称
  // ... 更多配置选项
}

主题设置

// 可用主题
type Theme = 
  | "minimal" 
  | "oxygen" 
  | "atom" 
  | "ayu" 
  | "catppuccin" 
  | "charcoal" 
  | "dracula" 
  | "everforest" 
  | "flexoki" 
  | "gruvbox" 
  | "macos" 
  | "nord" 
  | "obsidian" 
  | "rose-pine" 
  | "sky" 
  | "solarized" 
  | "things" 
  | "custom";

文章选项

interface PostOptions {
  postsPerPage: number;           // 每页文章数
  readingTime: boolean;           // 显示阅读时间
  wordCount: boolean;             // 显示字数
  tags: boolean;                  // 启用标签
  linkedMentions: {
    enabled: boolean;             // 启用反向链接
    linkedMentionsCompact: boolean;
  };
  graphView: {
    enabled: boolean;             // 启用图表视图
    showInSidebar: boolean;       // 在侧边栏显示
    maxNodes: number;             // 最大节点数
    showOrphanedPosts: boolean;   // 显示孤立文章
  };
  postNavigation: boolean;        // 文章导航
  showPostCardCoverImages: string; // 显示封面图片的位置
  postCardAspectRatio: string;    // 卡片图片比例
}

工具函数

Markdown 处理

// 处理 Markdown 内容
function processMarkdown(content: string): {
  excerpt: string;
  wordCount: number;
  hasMore: boolean;
}

// 计算阅读时间
function calculateReadingTime(content: string): ReadingTime

// 格式化日期
function formatDate(date: Date): string

// 格式化移动端日期
function formatDateMobile(date: Date): string

图片工具

// 优化图片路径
function optimizePostImagePath(
  imagePath: string, 
  folder?: string, 
  postId?: string
): string

// 优化项目图片路径
function optimizeProjectImagePath(
  imagePath: string, 
  projectId?: string
): string

SEO 工具

// 生成页面 SEO 数据
function generatePageSEO(config: SEOConfig): SEOData

// 生成 Open Graph 图片
function generateOGImage(
  title: string, 
  description?: string
): string

组件 API

BaseLayout

<BaseLayout seoData={seoData}>
  <!-- 页面内容 -->
</BaseLayout>

PostCard

<PostCard 
  post={post} 
  featured={false} 
  eager={false} 
  context="posts" 
/>

Pagination

<Pagination 
  pagination={paginationInfo} 
  baseUrl="/posts" 
/>

Tags

<Tags 
  tags={tagList} 
  currentTag={selectedTag} 
  showCount={false} 
/>

TableOfContents

<TableOfContents 
  headings={headings} 
/>

自定义主题

创建自定义主题

在 src/themes/custom/ 中创建主题文件：

// my-theme.ts
export default {
  name: "我的主题",
  colors: {
    primary: {
      50: "#...",
      100: "#...",
      // ... 更多颜色
    },
    highlight: {
      // 高亮颜色
    }
  }
}

使用自定义主题

在 src/config.ts 中：

export const siteConfig = {
  theme: "custom",
  customThemeFile: "my-theme"
}

钩子和生命周期

Astro 钩子

  • astro:config:setup - 配置设置
  • astro:config:done - 配置完成
  • astro:server:setup - 服务器设置
  • astro:build:start - 构建开始
  • astro:build:done - 构建完成

页面转换

使用 SWUP 库处理页面转换：

// 页面转换完成后执行
document.addEventListener('swup:pageView', () => {
  // 重新初始化组件
  initializeComponents();
});

脚本 API

开发脚本

pnpm dev          # 启动开发服务器
pnpm build        # 构建生产版本
pnpm preview      # 预览构建结果

工具脚本

# 同步图片
node scripts/sync-images.js

# 生成图表数据
node scripts/generate-graph-data.js

# 处理别名
node scripts/process-aliases.js

# 生成部署配置
node scripts/generate-deployment-config.js

最佳实践

性能优化

  • 使用 eager={true} 预加载首屏图片
  • 限制 maxNodes 以优化图表性能
  • 使用适当的图片比例

类型安全

  • 使用 TypeScript 类型
  • 导入 CollectionEntry 类型
  • 验证配置选项

可访问性

  • 为所有图片添加 alt 文本
  • 使用语义化 HTML
  • 确保键盘导航可用

故障排除

常见错误

类型错误

  • 确保所有必需字段都已提供
  • 检查数据类型匹配

构建错误

  • 验证前置元数据格式
  • 检查图片路径
  • 查看构建日志

运行时错误

  • 检查浏览器控制台
  • 验证客户端脚本
  • 确保依赖已安装

更多资源