跳转到内容

组件

组件让你可以轻松地重用 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 来显示给用户。

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

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

图标

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

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

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

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

所有图标

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

代码块

当使用 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" />