跳转到内容
Starlight

路由数据参考

Starlight 的路由数据对象包含有关当前页面的信息。请在 “路由数据”指南 中了解更多关于 Starlight 的数据模型如何工作的信息。

在 Astro 组件中，从 Astro.locals.starlightRoute 访问路由数据：

src/components/Custom.astro
---
const { hasSidebar } = Astro.locals.starlightRoute;
---

在 路由中间件 中，从传递给你的中间件函数的上下文对象中访问路由数据：

src/routeData.ts
import { defineRouteMiddleware } from '@astrojs/starlight/route-data';


export const onRequest = defineRouteMiddleware((context) => {
  const { hasSidebar } = context.locals.starlightRoute;
});

starlightRoute

Section titled “starlightRoute”

starlightRoute 对象具有以下属性:

dir

Section titled “dir”

类型： 'ltr' | 'rtl'

页面书写方向。

lang

Section titled “lang”

类型： string

此页面区域设置的 BCP-47 语言标记，例如 en、zh-CN 或 pt-BR。

locale

Section titled “locale”

类型： string | undefined

提供语言的基本路径。对于根语言环境的 slug，返回 undefined。

siteTitle

Section titled “siteTitle”

类型： string

该页面区域设置的站点标题。

siteTitleHref

Section titled “siteTitleHref”

类型： string

网站标题的 href 属性值，链接回主页，例如 /。对于多语言站点，这将包括当前区域设置，例如 /en/ 或 /zh-cn/。

slug

Section titled “slug”

类型： string

该页面的 slug 由内容文件名生成。

此属性已弃用，并将在 Starlight 的未来版本中删除。通过使用 Starlight 的 docsLoader 迁移到新的内容层 API，并使用 id 属性代替。

id

Section titled “id”

类型： string

此页面的 slug，或者如果使用 legacy.collections 标志，则基于内容文件名的此页面的唯一 ID。

isFallback

Section titled “isFallback”

类型： boolean | undefined

如果此页面在当前语言中未翻译，并且正在使用来自默认语言环境的回退内容，则为 true。 仅在多语言站点中使用。

entryMeta

Section titled “entryMeta”

类型： { dir: 'ltr' | 'rtl'; lang: string }

页面内容的区域设置元数据。当页面使用回退内容时，可以与顶级区域设置值不同。

entry

Section titled “entry”

当前页面的 Astro 内容集合条目。 包括当前页面在 entry.data 中的 frontmatter 值。

entry: {
  data: {
    title: string;
    description: string | undefined;
    // 等等
  }
}

在 Astro的集合条目类型参考 中了解更多关于此对象结构的信息。

Section titled “sidebar”

类型： SidebarEntry[]

此页面的网站导航侧边栏条目。

hasSidebar

Section titled “hasSidebar”

类型： boolean

是否在此页面上显示侧边栏。

pagination

Section titled “pagination”

类型： { prev?: Link; next?: Link }

如果启用了侧边栏，则链接到侧边栏中的上一页和下一页。

toc

Section titled “toc”

类型： { minHeadingLevel: number; maxHeadingLevel: number; items: TocItem[] } | undefined

如果启用，则为此页面的目录。

headings

Section titled “headings”

类型： { depth: number; slug: string; text: string }[]

从当前页面提取的所有 Markdown 标题的数组。如果要构建一个遵循 Starlight 配置选项的目录组件，请使用 toc

lastUpdated

Section titled “lastUpdated”

类型： Date | undefined

JavaScript Date 对象，表示启用时此页面上次更新的时间。

editUrl

Section titled “editUrl”

类型： URL | undefined

如果启用，则用于编辑此页面的地址的 URL 对象。

Section titled “head”

类型： HeadConfig[]

包含在当前页面 <head> 中的所有标签的数组。包括重要的标签，如 <title> 和 <meta charset="utf-8">。

工具函数

Section titled “工具函数”

defineRouteMiddleware()

Section titled “defineRouteMiddleware()”

使用 defineRouteMiddleware() 工具函数来帮助定义你的路由中间件模块：

src/routeData.ts
import { defineRouteMiddleware } from '@astrojs/starlight/route-data';


export const onRequest = defineRouteMiddleware((context) => {
  // ...
});

StarlightRouteData 类型

Section titled “StarlightRouteData 类型”

如果您正在编写需要使用 Starlight 路由数据的代码，您可以导入 StarlightRouteData 类型来匹配 Astro.locals.starlightRoute 的结构。

在下面的例子中，usePageTitleInTOC() 函数更新路由数据，以使用当前页面的标题作为目录中第一个项目的标签，替换默认的 “Overview” 标签。 StarlightRouteData 类型允许你检查路由数据更改是否有效。

src/route-utils.ts
import type { StarlightRouteData } from '@astrojs/starlight/route-data';


export function usePageTitleInTOC(starlightRoute: StarlightRouteData) {
  const overviewLink = starlightRoute.toc?.items[0];
  if (overviewLink) {
    overviewLink.text = starlightRoute.entry.data.title;
  }
}

然后可以从路由中间件调用此函数：

src/route-middleware.ts
import { defineRouteMiddleware } from '@astrojs/starlight/route-data';
import { usePageTitleInTOC } from './route-utils';


export const onRequest = defineRouteMiddleware((context) => {
  usePageTitleInTOC(context.locals.starlightRoute);
});