跳转到内容
Starlight
Filters

    路由数据参考

    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);
    });