Skip to content

布局

布局用于提供可重复使用的 UI 结构，例如页面模板。

¥Layouts are Astro components used to provide a reusable UI structure, such as a page template.

我们通常使用术语 “layout” 来表示 Astro 组件，这些组件提供跨页面共享的通用 UI 元素，例如页眉、导航栏和页脚。典型的 Astro 布局组件为 Astro、Markdown 或 MDX 页面 提供：

¥We conventionally use the term “layout” for Astro components that provide common UI elements shared across pages such as headers, navigation bars, and footers. A typical Astro layout component provides Astro, Markdown or MDX pages with:

  • 页面外壳（<html>、<head> 和 <body> 标签）

  • <slot /> 指定应在何处注入各个页面内容。

但是，布局组件没有什么特别的！它们可以像任何其他 Astro 组件一样 accept props and import and use other components。它们可以包括 UI 框架组件 和 客户端脚本。它们甚至不必提供完整的页面 shell，而是可以用作部分 UI 模板。

¥But, there is nothing special about a layout component! They can accept props and import and use other components like any other Astro component. They can include UI frameworks components and client-side scripts. They do not even have to provide a full page shell, and can instead be used as partial UI templates.

但是，如果布局组件确实包含页面外壳，则其 <html> 元素必须是组件中所有其他元素的父元素。所有 <style> 或 <script> 元素都必须包含在 <html> 标签中。

¥However, if a layout component does contain a page shell, its <html> element must be the parent of all other elements in the component. All <style> or <script> elements must be enclosed by the <html> tags.

布局组件通常放置在项目中的 src/layouts 目录中以便组织，但这不是必需的；你可以选择将它们放置在项目中的任何位置。你甚至可以通过 在布局名称前添加 _ 前缀 将布局组件与页面并置。

¥Layout components are commonly placed in a src/layouts directory in your project for organization, but this is not a requirement; you can choose to place them anywhere in your project. You can even colocate layout components alongside your pages by prefixing the layout names with _.

布局示例

标题部分 布局示例

¥Sample Layout

src/layouts/MySiteLayout.astro
---
import BaseHead from '../components/BaseHead.astro';
import Footer from '../components/Footer.astro';
const { title } = Astro.props;
---
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <BaseHead title={title}/>
  </head>
  <body>
    <nav>
      <a href="#">Home</a>
      <a href="#">Posts</a>
      <a href="#">Contact</a>
    </nav>
    <h1>{title}</h1>
    <article>
      <slot /> <!-- your content is injected here -->
    </article>
    <Footer />
  </body>
  <style>
    h1 {
      font-size: 2rem;
    }
  </style>
</html>
src/pages/index.astro
---
import MySiteLayout from '../layouts/MySiteLayout.astro';
---
<MySiteLayout title="Home Page">
  <p>My page content, wrapped in a layout!</p>
</MySiteLayout>
Learn more about slots.

使用 TypeScript 和布局

标题部分 使用 TypeScript 和布局

¥Using TypeScript with layouts

可以通过为你的属性提供类型来修改任何 Astro 布局以引入类型安全和自动补齐：

¥Any Astro layout can be modified to introduce type safety & autocompletion by providing the types for your props:

src/components/MyLayout.astro
---
interface Props {
  title: string;
  description: string;
  publishDate: string;
  viewCount: number;
}
const { title, description, publishDate, viewCount } = Astro.props;
---
<html lang="en">
  <head>
    <meta charset="UTF-8">
    <meta name="description" content={description}>
    <title>{title}</title>
  </head>
  <body>
    <header>
      <p>Published on {publishDate}</p>
      <p>Viewed by {viewCount} folks</p>
    </header>
    <main>
      <slot />
    </main>
  </body>
</html>

Markdown 布局

标题部分 Markdown 布局

¥Markdown Layouts

页面布局对于单独的 Markdown 页面特别有用，否则这些页面将没有任何页面格式。

¥Page layouts are especially useful for individual Markdown pages which otherwise would not have any page formatting.

Astro 提供了一个特殊的 layout 前置属性，旨在供 使用 src/pages/ 中的单个 .md 文件基于文件的路由 指定要使用哪个 .astro 组件作为页面布局。此组件允许你提供 <head> 内容，如元标记（例如 <meta charset="utf-8">）和 Markdown 页面的样式。默认情况下，此指定组件可以自动访问 Markdown 文件中的数据。

¥Astro provides a special layout frontmatter property intended for individual .md files located within src/pages/ using file-based routing to specify which .astro component to use as the page layout. This component allows you to provide <head> content like meta tags (e.g. <meta charset="utf-8">) and styles for the Markdown page. By default, this specified component can automatically access data from the Markdown file.

当使用 内容集合 查询和渲染内容时，这不被视为特殊属性。

¥This is not recognized as a special property when using content collections to query and render your content.

src/pages/page.md
---
layout: ../layouts/BlogPostLayout.astro
title: "Hello, World!"
author: "Matthew Phillips"
date: "09 Aug 2022"
---
All frontmatter properties are available as props to an Astro layout component.


The `layout` property is the only special one provided by Astro.


You can use it in Markdown files located within `src/pages/`.

Markdown 页面的典型布局包括：

¥A typical layout for a Markdown page includes:

  1. frontmatter prop 用于访问 Markdown 页面的前置内容和其他数据。
  2. 默认 <slot /> 指示应在何处渲染页面的 Markdown 内容。
src/layouts/BlogPostLayout.astro
---
// 1. The frontmatter prop gives access to frontmatter and other data
const { frontmatter } = Astro.props;
---
<html>
  <head>
    <!-- Add other Head elements here, like styles and meta tags. -->
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <meta charset="utf-8">
    <title>{frontmatter.title}</title>
  </head>
  <body>
    <!-- Add other UI components here, like common headers and footers. -->
    <h1>{frontmatter.title} by {frontmatter.author}</h1>
    <!-- 2. Rendered HTML will be passed into the default slot. -->
    <slot />
    <p>Written on: {frontmatter.date}</p>
  </body>
</html>

你可以使用 MarkdownLayoutProps 助手设置布局的 Props 型：

¥You can set a layout’s Props type with the MarkdownLayoutProps helper:

src/layouts/BlogPostLayout.astro
---
import type { MarkdownLayoutProps } from 'astro';


type Props = MarkdownLayoutProps<{
  // Define frontmatter props here
  title: string;
  author: string;
  date: string;
}>;


// Now, `frontmatter`, `url`, and other Markdown layout properties
// are accessible with type safety
const { frontmatter, url } = Astro.props;
---
<html>
  <head>
    <meta charset="utf-8">
    <link rel="canonical" href={new URL(url, Astro.site).pathname}>
    <title>{frontmatter.title}</title>
  </head>
  <body>
    <h1>{frontmatter.title} by {frontmatter.author}</h1>
    <slot />
    <p>Written on: {frontmatter.date}</p>
  </body>
</html>

Markdown 布局属性

标题部分 Markdown 布局属性

¥Markdown Layout Props

Markdown 布局将能够通过 Astro.props 访问以下信息：

¥A Markdown layout will have access to the following information via Astro.props:

  • file - 此文件的绝对路径（例如 /home/user/projects/.../file.md）。

  • url - 页面的 URL（例如 /en/guides/markdown-content）。

  • frontmatter - Markdown 或 MDX 文档中的所有前言。

    • frontmatter.file - 与顶层 file 属性相同。

    • frontmatter.url - 与顶层 url 属性相同。

  • headings - Markdown 或 MDX 文档中的标题 (h1 -> h6) 列表以及相关元数据。该列表遵循以下类型：{ depth: number; slug: string; text: string }[]。

  • rawContent() - 以字符串形式返回原始 Markdown 文档的函数。

  • compiledContent() - 返回编译为 HTML 字符串的 Markdown 文档的异步函数。

手动导入布局 (MDX)

标题部分 手动导入布局 (MDX)

¥Importing Layouts Manually (MDX)

你还可以使用 MDX 文件前言中的特殊 Markdown 布局属性，以相同的方式将 frontmatter 和 headings 属性直接传递给指定的布局组件。

¥You can also use the special Markdown layout property in the frontmatter of MDX files to pass frontmatter and headings props directly to a specified layout component in the same way.

要将前置内容中不存在（或无法存在）的信息传递给 MDX 布局，你可以导入并使用 <Layout /> 组件。这像任何其他 Astro 组件一样工作，不会自动接收任何属性。直接向其传递任何必要的属性：

¥To pass information to your MDX layout that does not (or cannot) exist in your frontmatter, you can instead import and use a <Layout /> component. This works like any other Astro component, and will not receive any props automatically. Pass it any necessary props directly:

src/pages/posts/first-post.mdx
---
layout: ../../layouts/BaseLayout.astro
title: 'My first MDX post'
publishDate: '21 September 2022'
---
import BaseLayout from '../../layouts/BaseLayout.astro';


export function fancyJsHelper() {
  return "Try doing that with YAML!";
}


<BaseLayout title={frontmatter.title} fancyJsHelper={fancyJsHelper}>
  Welcome to my new Astro blog, using MDX!
</BaseLayout>

然后，你可以通过布局中的 Astro.props 使用你的值，并且你的 MDX 内容将被注入到写入 <slot /> 组件的页面中：

¥Then, your values are available to you through Astro.props in your layout, and your MDX content will be injected into the page where your <slot /> component is written:

src/layouts/BaseLayout.astro
---
const { title, fancyJsHelper } = Astro.props;
---
<html>
  <head>
    <!-- -->
    <meta charset="utf-8">
  </head>
  <body>
    <!-- -->
    <h1>{title}</h1>
    <slot /> <!-- your content is injected here -->
    <p>{fancyJsHelper()}</p>
    <!-- -->
  </body>
</html>

使用任何布局时（通过 frontmatter layout 属性或通过导入布局），你必须在布局中包含 <meta charset="utf-8"> 标签，因为 Astro 将不再自动将其添加到你的 MDX 页面。

¥When using any layout (either through the frontmatter layout property or by importing a layout), you must include the <meta charset="utf-8"> tag in your layout as Astro will no longer add it automatically to your MDX page.

Learn more about Astro’s Markdown and MDX support in our Markdown guide.

嵌套布局

标题部分 嵌套布局

¥Nesting Layouts

布局组件不需要包含整个页面的 HTML。你可以将布局分解为更小的组件，并组合布局组件以创建更灵活的页面模板。当你想要跨多个布局共享某些代码时，此模式非常有用。

¥Layout components do not need to contain an entire page worth of HTML. You can break your layouts into smaller components, and combine layout components to create even more flexible, page templates. This pattern is useful when you want to share some code across multiple layouts.

例如，BlogPostLayout.astro 布局组件可以设置帖子标题、日期和作者的样式。然后，站点范围的 BaseLayout.astro 可以处理页面模板的其余部分，例如导航、页脚、SEO 元标记、全局样式和字体。你还可以将从帖子收到的属性传递到另一个布局，就像任何其他嵌套组件一样。

¥For example, a BlogPostLayout.astro layout component could style a post’s title, date and author. Then, a site-wide BaseLayout.astro could handle the rest of your page template, like navigation, footers, SEO meta tags, global styles, and fonts. You can also pass props received from your post to another layout, just like any other nested component.

src/layouts/BlogPostLayout.astro
---
import BaseLayout from './BaseLayout.astro';
const { frontmatter } = Astro.props;
---
<BaseLayout url={frontmatter.url}>
  <h1>{frontmatter.title}</h1>
  <h2>Post author: {frontmatter.author}</h2>
  <slot />
</BaseLayout>
Astro 中文网 - 粤ICP备13048890号