内容页面操作流程
使用 Astro 内容集合(Content Layer API)配合动态路由,创建内容驱动页面的逐步流程。
前置条件
src/styles/global.css已存在且包含设计令牌(由 css-procedure 创建)docs/stitch/reference.md已存在(Stitch 屏幕中的字段信息)
输入 / 输出
[输入] [输出]
docs/stitch/reference.md ──┐
(屏幕字段信息) │
progress.md 笔记 ────────────┼──→ src/content/config.ts (schema)
(章节结构, │ src/content/<collection>/<slug>/index.mdx (数据)
设计决策) │ src/pages/<collection>/[...slug].astro (路由)
│ src/components/*.astro (章节组件)
步骤
步骤 1:Schema 定义 (src/content/config.ts)
Astro 5 Content Layer API 使用 glob 加载器。
1-1. 定义集合
import { defineCollection, z } from "astro:content";
import { glob } from "astro/loaders";
const myCollection = defineCollection({
loader: glob({ pattern: "**/index.mdx", base: "./src/content/my-collection" }),
schema: ({ image }) =>
z.object({
title: z.string(),
// ... 定义其他字段
heroImage: image(), // 图像使用 image() 辅助函数
}),
});
export const collections = { myCollection };
1-2. Schema 设计指南
- 从最小开始,逐步扩展。 仅定义当前页面渲染所需的字段;实现组件时再添加更多字段
- 对图像字段使用
image()辅助函数,以实现构建时路径验证和优化 - 对于非每个条目都必须的字段,使用
.optional() - 对于章节级别的数据,使用可选数组来控制每个页面的章节可见性:
// Schema moments: z.array(z.object({ title: z.string(), ... })).optional()<!-- 页面模板:条件渲染 --> {data.moments && <MomentsSection moments={data.moments} />}
1-3. YAML 前端数据陷阱
- 月份名称(March、May 等)和 Yes/No 会被 YAML 自动转换。 如果希望它们作为字符串,请加引号:
date: "March" - 图像路径相对于 MDX 文件:
heroImage: ./hero.jpg
步骤 2:创建内容数据
2-1. 目录结构
src/content/<collection>/<slug>/
├── index.mdx # frontmatter + MDX 正文
├── hero.jpg # 图像与内容位于同一目录
└── ...
2-2. MDX 文件结构
---
title: "页面标题"
heroImage: ./hero.jpg
description: "描述文本"
---
## MDX 正文
正文内容通过 `render()` 获取并以 `<Content />` 形式渲染。
2-3. 图像管理
- 将图像存放在
src/content/中,与其内容位于同一目录(不要放在public/中) - 提交前将大于 2560px 的图像缩小
- 在 schema 中使用
image()辅助函数时,前端数据中的图像路径会解析为ImageMetadata类型。在组件 Props 中也应使用ImageMetadata类型
步骤 3:动态路由页面
创建 src/pages/<collection>/[...slug].astro:
---
import type { GetStaticPaths } from "astro";
import { getCollection, render } from "astro:content";
export const getStaticPaths = (async () => {
const items = await getCollection("myCollection");
return items.map((item) => ({
params: { slug: item.id },
props: { item },
}));
}) satisfies GetStaticPaths;
const { item } = Astro.props;
const { Content } = await render(item);
---
关键点
getCollection()获取所有条目;getStaticPaths生成静态路径render()将 MDX 正文作为Content组件返回item.data提供类型安全的前端数据字段访问- 对于可选字段的条件渲染:
{data.field && <Component ... />}
步骤 4:页面数据文件 (src/data/<page>.md)
每个页面中用户可编辑的内容(文本、标签、URL)应定义在 src/data/ 目录下的 Markdown 文件中,使用 YAML 前端数据。这样既能保持与内容集合一致的格式,也便于用户查找和编辑内容。
注意:
src/data/目录不会被脚手架技能创建。请在此步骤中创建它。
4-1. 为每个页面创建一个数据文件
src/data/
├── index.md # 作品(Works)页面内容
├── about.md # 关于我页面内容
└── skills.md # 技能页面内容
4-2. 将可编辑内容定义为 YAML 前端数据
---
# ==============================
# 作品页面内容
# 编辑此文件以自定义你的页面。
# ==============================
hero:
headingPrefix: "你好,我是"
highlightedText: "Web 开发者。"
description: "我构建可扩展、以用户为中心的应用程序..."
badgeText: "可承接新项目"
cta:
heading: "准备好一起构建什么了吗?"
description: "我目前接受自由职业机会..."
buttons:
- label: "联系我"
href: "mailto:[email protected]"
variant: "primary"
- label: "下载简历"
href: "#"
variant: "secondary"
---
- 仅将用户可编辑的文本放入 YAML(字符串、标签、URL、文本数组)
- 将不可编辑的数据(SVG 图标路径等)作为 TypeScript 常量保留在
.astro页面文件中
4-3. 在页面中导入数据
使用 import.meta.glob() 加载前端数据:
---
const content = Object.values(
import.meta.glob("../data/index.md", { eager: true })
)[0] as { frontmatter: Record<string, unknown> };
const { hero, cta } = content.frontmatter;
---
步骤 5:章节组件实现
将每个章节(hero、moments 等)创建为 src/components/ 下的独立组件。
遵循 develop-guideline 中的组件结构和 CSS 规则。
图像显示:<Picture> vs <img>
| 方法 | 何时使用 | 示例 |
|---|---|---|
<Picture> | 构建时已知的静态图像 | Hero 背景、条目图像 |
<img> | 由客户端 JS 动态切换的图像 | 模态画廊幻灯片 |
<Picture> 在构建时渲染,因此当 src 由客户端 JS 切换时不能使用。
客户端 JavaScript
Astro 组件中的 <script> 标签会作为客户端 JS 运行。无需框架(React 等)即可构建交互功能。
数据传递模式: 使用 data-* 属性将前端数据传递给客户端 JS。<script> 不能直接引用前端数据变量。
可访问性:模态框 / 遮罩层
模态对话框实现的检查清单:
| 要求 | 实现 |
|---|---|
| 语义 | role="dialog" + aria-modal="true" + aria-label |
| 打开/关闭 | 切换 hidden 属性 + CSS opacity 过渡 |
| 滚动锁定 | 打开:document.body.style.overflow = "hidden" / 关闭:恢复为 "" |
| 键盘 | Escape 关闭,方向键导航 |
| 焦点捕获 | Tab/Shift+Tab 在模态框内的按钮间循环 |
| 焦点恢复 | 关闭时对触发元素执行 focus() |
| 背景关闭 | 当点击目标不是可交互元素时关闭 |
| z-index | 高于现有的固定元素(例如,header 50 → modal 60) |
步骤 6:构建验证
npm run build
内容集合 schema 验证错误会在构建时以清晰的提示信息显示。
常见错误
| 错误 | 原因 | 修复 |
|---|---|---|
Expected type "string", received "object" | YAML 自动转换了值(月份名称 → Date 等) | 给该值加引号 |
Could not find image | 图像路径不正确 | 验证从 MDX 文件开始的相对路径 |
does not match collection schema | 前端数据中缺少字段或类型不匹配 | 对照 config.ts schema 检查 |
步骤 7:开发服务器验证
npm run dev
- Schema 更改可能需要重启开发服务器(清空内容存储)
- 如果重启后错误仍然存在,删除
.astro/目录并重启
检查清单
-
src/content/config.ts已定义 schema - MDX 前端数据符合 schema
- 图像位于
src/content/内并已缩小至 ≤2560px -
[...slug].astro从getStaticPaths返回所有条目 - 可选字段章节使用了条件渲染
-
npm run build成功 - 在浏览器中目视确认所有章节(包括移动端宽度)