Skip to content

内置组件参考

Astro 包含多个内置组件供你在项目中使用。所有内置组件均可在 .astro 文件中使用，并且可能需要 import 语句。

¥Astro includes several built-in components for you to use in your projects. All built-in components are available in .astro files and may require an import statement.

你可以使用 ComponentProps 型 实用程序引用这些组件的 Props。

¥You can reference the Props of these components using the ComponentProps type utility.

<Code />

Section titled &lt;Code /&gt;
---
import { Code } from 'astro:components';
---
<!-- Syntax highlight some JavaScript code. -->
<Code code={`const foo = 'bar';`} lang="js" />
<!-- Optional: Customize your theme. -->
<Code code={`const foo = 'bar';`} lang="js" theme="dark-plus" />
<!-- Optional: Enable word wrapping. -->
<Code code={`const foo = 'bar';`} lang="js" wrap />
<!-- Optional: Output inline code. -->
<p>
  <Code code={`const foo = 'bar';`} lang="js" inline />
  will be rendered inline.
</p>
<!-- Optional: defaultColor -->
<Code code={`const foo = 'bar';`} lang="js" defaultColor={false} />

该组件在构建时提供代码块的语法高亮（不包括客户端 JavaScript）。该组件由 Shiki 内部供电，支持所有流行的 themes 和 languages。此外，你可以通过分别将自定义主题、语言、transformers 和 默认颜色 传递给 theme、lang、transformers 和 defaultColor 属性来添加它们。

¥This component provides syntax highlighting for code blocks at build time (no client-side JavaScript included). The component is powered internally by Shiki and it supports all popular themes and languages. Plus, you can add your custom themes, languages, transformers, and default colors by passing them to the theme, lang, transformers, and defaultColor attributes respectively.

Transformers

Section titled Transformers

Added in: astro@4.11.0

可以选择将 Shiki 变换器 应用于代码，方法是将它们作为数组通过 transformers 属性传入。自 Astro v4.14.0 起，你还可以为 Shiki 的 meta 属性 提供一个字符串，以将选项传递给转换器。

¥Shiki transformers can optionally be applied to code by passing them in through the transformers property as an array. Since Astro v4.14.0, you can also provide a string for Shiki’s meta attribute to pass options to transformers.

请注意，transformers 仅适用于类，你必须提供自己的 CSS 规则来定位代码块的元素。

¥Note that transformers only applies classes and you must provide your own CSS rules to target the elements of your code block.

src/pages/index.astro
---
import { transformerNotationFocus, transformerMetaHighlight } from '@shikijs/transformers'
import { Code } from 'astro:components'
const code = `const foo = 'hello'
const bar = ' world'
console.log(foo + bar) // [!code focus]
`
---
<Code
  code={code}
  lang="js"
  transformers={[transformerMetaHighlight()]}
  meta="{1,3}"
/>


<style is:global>
  pre.has-focused .line:not(.focused) {
    filter: blur(1px);
  }
</style>

<Fragment />

Section titled &lt;Fragment /&gt;

与 set:* 指令 一起使用的组件，无需任何额外的封装元素即可渲染 HTML 内容：

¥A component used with set:* directives to render HTML content without any additional wrapping elements:

src/components/SetHtml.astro
---
const htmlString = '<p>Raw HTML content</p>';
---
<Fragment set:html={htmlString} />

请参阅 Astro 语法中有关 使用片段 的更多信息。

¥See more about using fragments in Astro syntax.

<Prism />

Section titled &lt;Prism /&gt;

要使用 Prism 荧光笔组件，请先安装 @astrojs/prism 包：

¥To use the Prism highlighter component, first install the @astrojs/prism package:

Terminal window
npm install @astrojs/prism
 
---
import { Prism } from '@astrojs/prism';
---
<Prism lang="js" code={`const foo = 'bar';`} />

该组件通过应用 Prism 的 CSS 类为代码块提供特定于语言的语法高亮。请注意，你需要提供 Prism CSS 样式表（或自带）才能显示语法高亮！有关详细信息，请参阅 Prisma 配置部分。

¥This component provides language-specific syntax highlighting for code blocks by applying Prism’s CSS classes. Note that you need to provide a Prism CSS stylesheet (or bring your own) for syntax highlighting to appear! See the Prism configuration section for more details.

请参阅 Prism 支持的语言列表，你可以在其中找到语言对应的别名。而且，你还可以使用 lang="astro" 显示你的 Astro 代码块！

¥See the list of languages supported by Prism where you can find a language’s corresponding alias. And, you can also display your Astro code blocks with lang="astro"!

<Image />

Section titled &lt;Image /&gt;
src/components/MyComponent.astro
---
// import the Image component and the image
import { Image } from 'astro:assets';
import myImage from "../assets/my_image.png"; // Image is 1600x900
---


<!-- `alt` is mandatory on the Image component -->
<Image src={myImage} alt="A description of my image." />
<!-- Output -->
<!-- Image is optimized, proper attributes are enforced -->
<img
  src="/_astro/my_image.hash.webp"
  width="1600"
  height="900"
  decoding="async"
  loading="lazy"
  alt="A description of my image."
/>

属性

Section titled 属性

¥Properties

  • 源代码（必填）

  • 替代（必填）

  • 宽度和高度（public/ 和远程图片需要）

  • format

  • quality

  • densities

  • widths

除了上述属性之外，<Image /> 组件还接受 HTML <img> 标记接受的所有属性。

¥In addition to the properties above, the <Image /> component accepts all properties accepted by the HTML <img> tag.

更多内容请参见 图片指南。

¥See more in the Images Guide.

<Picture />

Section titled &lt;Picture /&gt;

Added in: astro@3.3.0

使用内置的 <Picture /> Astro 组件显示具有多种格式和/或尺寸的响应式图片。

¥Use the built-in <Picture /> Astro component to display a responsive image with multiple formats and/or sizes.

src/pages/index.astro
---
import { Picture } from 'astro:assets';
import myImage from "../assets/my_image.png"; // Image is 1600x900
---


<!-- `alt` is mandatory on the Picture component -->
<Picture src={myImage} formats={['avif', 'webp']} alt="A description of my image." />
<!-- Output -->
<picture>
  <source srcset="/_astro/my_image.hash.avif" type="image/avif" />
  <source srcset="/_astro/my_image.hash.webp" type="image/webp" />
  <img
    src="/_astro/my_image.hash.png"
    width="1600"
    height="900"
    decoding="async"
    loading="lazy"
    alt="A description of my image."
  />
</picture>

更多内容请参见 图片指南。

¥See more in the Images Guide.

属性

Section titled 属性

¥Properties

<Picture /> 接受 <Image /> 组件的所有属性，以及以下属性：

¥<Picture /> accepts all the properties of the <Image /> component, plus the following:

formats

Section titled formats

用于 <source> 标签的图片格式数组。默认情况下，该值设置为 ['webp']。

¥An array of image formats to use for the <source> tags. By default, this is set to ['webp'].

fallbackFormat

Section titled fallbackFormat

用作 <img> 标记后备值的格式。静态图片默认为 .png，动画图片默认为 .gif，SVG 文件默认为 .svg。

¥Format to use as a fallback value for the <img> tag. Defaults to .png for static images, .gif for animated images, and .svg for SVG files.

pictureAttributes

Section titled pictureAttributes

要添加到 <picture> 标记的属性对象。使用此属性将属性应用到外部 <picture> 元素本身。直接应用于 <Picture /> 组件的属性将应用于内部 <img> 元素，用于图片转换的属性除外。

¥An object of attributes to be added to the <picture> tag. Use this property to apply attributes to the outer <picture> element itself. Attributes applied to the <Picture /> component directly will apply to the inner <img> element, except for those used for image transformation.

<Content />

Section titled &lt;Content /&gt;

用于渲染 内容集合条目 内容的通用组件。

¥A generic component used to render the content of a content collection entry.

首先，使用 getCollection() 或 getEntry() 查询一个或多个条目。然后，entry.render() 函数可以返回 <Content /> 组件以在 .astro 文件模板中使用。

¥First, query one or more entries using getCollection() or getEntry(). Then, the entry.render() function can return the <Content /> component for use in a .astro file template.

src/pages/render-example.astro
---
import { getEntry } from 'astro:content';
const entry = await getEntry('blog', 'post-1');
const { Content } = await entry.render();
---
<p>Published on: {entry.data.published.toDateString()}</p>
<Content />

<ViewTransitions />

Section titled &lt;ViewTransitions /&gt;

Added in: astro@2.9.0

通过将 <ViewTransitions /> 路由组件导入并添加到每个所需页面上的 <head>，选择在各个页面上使用视图转换。

¥Opt in to using view transitions on individual pages by importing and adding the <ViewTransitions /> routing component to <head> on every desired page.

src/pages/index.astro
---
import { ViewTransitions } from 'astro:transitions';
---
<html lang="en">
  <head>
    <title>My Homepage</title>
    <ViewTransitions />
  </head>
  <body>
    <h1>Welcome to my website!</h1>
  </body>
</html>

详细了解如何通过 控制路由 和 添加转换指令 来页面元素和组件。

¥See more about how to control the router and add transition directives to page elements and components.

<Debug />

Section titled &lt;Debug /&gt;
---
import { Debug } from 'astro:components';
const serverObject = {
  a: 0,
  b: "string",
  c: {
    nested: "object"
  }
}
---
<Debug {serverObject} />

该组件提供了一种在客户端检查值的方法，无需任何 JavaScript。

¥This component provides a way to inspect values on the client-side, without any JavaScript.

Astro 中文网 - 粤ICP备13048890号