跳转到内容

组件

组件让你可以轻松地重用 UI 或样式。 例如,链接卡片或 YouTube 嵌入。 Starlight 支持在 MDX 文件中使用组件,并提供了一些常用组件供你使用。

在 Astro 文档中了解更多关于构建组件的内容

使用组件

你可以通过在 MDX 文件中导入组件,然后像渲染 JSX 标签一样来使用组件。 这些看起来像 HTML 标签,但是以大写字母开头,与你的 import 语句中的名称匹配:

src/content/docs/example.mdx
---
title: 欢迎来到我的文档
---
import SomeComponent from '~/components/SomeComponent.astro';
import AnotherComponent from '~/components/AnotherComponent.astro';
<SomeComponent prop="something" />
<AnotherComponent>组件也可以包含**嵌套内容**</AnotherComponent>

因为 Starlight 是由 Astro 提供支持的,所以你可以在 MDX 文件中添加对任何 支持的 UI 框架(React、Preact、Svelte、Vue、Solid、Lit 和 Alpine) 构建的组件的支持。 在 Astro 文档中了解更多关于 在 MDX 中使用组件 的内容。

与 Starlight 样式的兼容

Starlight 为你的 Markdown 内容应用了默认样式,例如在元素之间添加边距。

如果这些样式与你的组件的外观冲突,请在组件上设置 not-content 类来禁用它们。

src/components/Example.astro
<div class="not-content">
<p>不受 Starlight 默认内容样式的影响。</p>
</div>

内置组件

Starlight 为常见的文档用例提供了一些内置组件。 这些组件可以从 @astrojs/starlight/components 包中获取。

选项卡

你可以使用 <Tabs><TabItem> 组件显示一个选项卡界面。 每个 <TabItem> 必须有一个 label 来显示给用户。 使用可选的icon属性在标签旁包含一个Starlight内置图标

src/content/docs/example.mdx
import { Tabs, TabItem } from '@astrojs/starlight/components';
<Tabs>
<TabItem label="恒星" icon="star">
天狼星、织女星、参宿四
</TabItem>
<TabItem label="卫星" icon="moon">
木卫一、木卫二、木卫三
</TabItem>
</Tabs>

以上代码在页面上生成了以下选项卡:

天狼星、织女星、参宿四

卡片

你可以使用 <Card> 组件在与 Starlight 样式匹配的盒子中显示内容。 当有足够的空间时,可以使用 <CardGrid> 组件将多个卡片封装在一起,以便并排显示卡片。

<Card> 需要一个 title,并且可以选择包含一个 icon 属性,该属性设置为 Starlight 内置图标 之一的名称。

src/content/docs/example.mdx
import { Card, CardGrid } from '@astrojs/starlight/components';
<Card title="看看这个">你想要突出显示的有趣内容。</Card>
<CardGrid>
<Card title="恒星" icon="star">
天狼星、织女星、参宿四
</Card>
<Card title="卫星" icon="moon">
木卫一、木卫二、木卫三
</Card>
</CardGrid>

以上代码在页面上生成了以下内容:

看看这个

你想要突出显示的有趣内容。

恒星

天狼星、织女星、参宿四

卫星

木卫一、木卫二、木卫三

链接卡片

使用 <LinkCard> 组件来突出显示链接到不同页面的内容。

<LinkCard> 需要一个 title 和一个 href 属性。你可以选择包含一个简短的 description 或其他链接属性,例如 target

当有足够的空间时,将多个 <LinkCard> 组件组合在 <CardGrid> 中,以便并排显示卡片。

src/content/docs/example.mdx
import { LinkCard, CardGrid } from '@astrojs/starlight/components';
<LinkCard
title="自定义 Starlight"
description="了解如何使用自定义样式、字体等打造你自己的 Starlight 网站。"
href="/zh-cn/guides/customization/"
/>
<CardGrid>
<LinkCard title="创作 Markdown" href="/zh-cn/guides/authoring-content/" />
<LinkCard title="组件" href="/zh-cn/guides/components/" />
</CardGrid>

以上代码在页面上生成了以下内容:

旁白

旁白(也称为“警告”或“提醒”)对于在页面的主要内容旁边显示次要信息非常有用。

<Aside> 可以有一个可选的 type 属性,可以是 note(默认值)、tipcautiondanger。设置 title 属性会覆盖默认的旁白标题。

src/content/docs/example.mdx
import { Aside } from '@astrojs/starlight/components';
<Aside>没有自定义标题的默认旁白</Aside>
<Aside type="caution" title="当心!">
*带有* 自定义标题的警告旁白。
</Aside>
<Aside type="tip">
旁白中也支持其他内容。
```js
// 比如代码片段。
```
</Aside>
<Aside type="danger">不要把你的密码告诉任何人。</Aside>

以上代码在页面上生成了以下内容:

Starlight 还提供了一种在 Markdown 和 MDX 中渲染旁白的自定义语法,作为 <Aside> 组件的替代方案。 有关自定义语法的详细信息,请参阅 “在 Markdown 中创作内容” 指南。

代码块

当使用 Markdown 代码块 行不通时,可以使用 <Code> 组件来渲染语法高亮的代码。例如,渲染来自文件、数据库或 API 等外部来源的数据。

有关 <Code> 支持的完整属性的详细信息,请参阅 Expressive Code 的 “Code Component” 文档

src/content/docs/example.mdx
import { Code } from '@astrojs/starlight/components';
export const exampleCode = `console.log('这可能来自一个文件或CMS!');`;
export const fileName = 'example.js';
export const highlights = ['文件', 'CMS'];
<Code code={exampleCode} lang="js" title={fileName} mark={highlights} />

以上代码在页面上生成了以下内容:

example.js
console.log('这可能来自一个文件CMS!');

导入代码字符串

使用 Vite 的 ?raw 导入后缀 来将任何代码文件导入为字符串。 然后,你可以将此导入的字符串传递给 <Code> 组件,以便将其包含在页面上。

src/content/docs/example.mdx
import { Code } from '@astrojs/starlight/components';
import importedCode from '/src/env.d.ts?raw';
<Code code={importedCode} lang="ts" title="src/env.d.ts" />

以上代码在页面上生成了以下内容:

src/env.d.ts
/// <reference path="../.astro/types.d.ts" />
/// <reference types="astro/client" />

文件树

使用<FileTree>组件来显示带有文件图标和可折叠子目录的目录结构。

使用 <FileTree> 组件内置的 Markdown 无序列表语法指定文件和目录的组织结构。使用嵌套的列表项创建子目录;若希望某个目录不显示具体内容,只需在列表项末尾添加斜杠/即可。

以下语法可用于自定义文件树的外观:

  • 通过加粗文件名或目录名来突出显示,例如 **README.md**
  • 通过在名称后添加更多文本来为文件或目录添加注释
  • 使用 ... 作为名称来添加占位符文件和目录。
src/content/docs/example.mdx
import { FileTree } from '@astrojs/starlight/components';
<FileTree>
- astro.config.mjs 一个 **重要** 的文件
- package.json
- README.md
- src
- components
- **Header.astro**
-
- pages/
</FileTree>

以上代码在页面上生成了以下内容:

  • astro.config.mjs 一个 重要 的文件
  • package.json
  • README.md
  • 文件夹src
    • 文件夹components
      • Header.astro
  • 文件夹pages/

步骤

使用 <Steps> 组件为任务的编号列表设置样式。这对于需要清晰突出地显示每个步骤的分布指南很有用。

<Steps> 包裹在标准 Markdown 有序列表中。通常所有 Markdown 语法都适用于 <Steps> 内部。

src/content/docs/example.mdx
import { Steps } from '@astrojs/starlight/components';
<Steps>
1.在 MDX 文件中导入该组件
```js
import { Steps } from '@astrojs/starlight/components';
```
2. 将有序列表放入该组件中
</Steps>

以上代码在页面上生成了以下内容:

  1. 在 MDX 文件中导入该组件

    import { Steps } from '@astrojs/starlight/components';
  2. 将有序列表放入该组件中

图标

Starlight 提供了一组常用的图标,你可以使用 <Icon> 组件在你的内容中显示。

每个 <Icon> 都需要一个 name,并且可以选择包含 labelsizecolor 属性。

src/content/docs/example.mdx
import { Icon } from '@astrojs/starlight/components';
<Icon name="star" color="goldenrod" size="2rem" />

以上代码在页面上生成了以下内容:

所有图标

下面显示了所有可用图标的列表及其关联的名称。点击图标以复制其组件代码。