插件参考

Starlight 插件可以自定义 Starlight 的配置、UI 和行为，同时也易于共享和重用。本参考页面记录了插件可以访问的 API。

要了解有关使用 Starlight 插件的更多信息，请参阅配置参考或访问插件展示以查看可用插件列表。

快速 API 参考

一个 Starlight 插件具有以下结构。有关不同属性和钩子（hook）参数的详细信息，请参见下文。

interface StarlightPlugin {
  name: string;
  hooks: {
    'i18n:setup'?: (options: {
      injectTranslations: (
        translations: Record<string, Record<string, string>>
      ) => void;
    }) => void | Promise<void>;
    'config:setup': (options: {
      config: StarlightUserConfig;
      updateConfig: (newConfig: StarlightUserConfig) => void;
      addIntegration: (integration: AstroIntegration) => void;
      addRouteMiddleware: (config: { entrypoint: string; order?: 'pre' | 'post' | 'default' }) => void;
      astroConfig: AstroConfig;
      command: 'dev' | 'build' | 'preview';
      isRestart: boolean;
      logger: AstroIntegrationLogger;
      useTranslations: (lang: string) => I18nT;
      absolutePathToLang: (path: string) => string;
    }) => void | Promise<void>;
  };
}

name

类型： string

插件必须提供一个描述其自身的唯一名称。该名称在记录与此插件相关的消息时使用，也可能被其他插件用来检测此插件的存在。

hooks

钩子（Hook）是 Starlight 在特定时间调用的函数，用于运行插件代码。

要获取钩子参数的类型，请使用 HookParameters 工具类型并传入钩子名称。在以下示例中，options 参数的类型与传递给 config:setup 钩子的参数相匹配。

import type { HookParameters } from '@astrojs/starlight/types';

function configSetup(options: HookParameters['config:setup']) {
  options.useTranslations('en');
}

i18n:setup

Starlight 初始化时调用的插件国际化设置函数。i18n:setup 钩子可用于注入翻译字符串，以便插件可以支持不同的区域设置（locale）。这些翻译将通过 config:setup 钩子中的 useTranslations() 以及 UI 组件中的 Astro.locals.t() 提供。

调用 i18n:setup 钩子时会传入以下选项：

injectTranslations

类型： (translations: Record<string, Record<string, string>>) => void

一个回调函数，用于添加或更新在 Starlight 的本地化 API 中使用的翻译字符串。

在以下示例中，一个插件为 en 和 fr 区域设置注入了一个名为 myPlugin.doThing 的自定义 UI 字符串的翻译：

plugin.ts

export default {
  name: 'plugin-with-translations',
  hooks: {
    'i18n:setup'({ injectTranslations }) {
      injectTranslations({
        en: {
          'myPlugin.doThing': 'Do the thing',
        },
        fr: {
          'myPlugin.doThing': 'Faire le truc',
        },
      });
    },
  },
};

要在你的插件 UI 中使用注入的翻译，请遵循“使用 UI 翻译”指南。如果你需要在插件的 config:setup 钩子上下文中使用 UI 字符串，可以使用 useTranslations() 回调。

插件注入的翻译字符串的类型会在用户项目中自动生成，但在你的插件代码库中工作时尚不可用。要在你的插件上下文中为 locals.t 对象提供类型，请在 TypeScript 声明文件中声明以下全局命名空间：

env.d.ts

declare namespace App {
  type StarlightLocals = import('@astrojs/starlight').StarlightLocals;
  // Define the `locals.t` object in the context of a plugin.
  interface Locals extends StarlightLocals {}
}

declare namespace StarlightApp {
  // Define the additional plugin translations in the `I18n` interface.
  interface I18n {
    'myPlugin.doThing': string;
  }
}

如果你有一个包含翻译的对象，也可以从源文件中推断 StarlightApp.I18n 接口的类型。

例如，给定以下源文件：

ui-strings.ts

export const UIStrings = {
  en: { 'myPlugin.doThing': 'Do the thing' },
  fr: { 'myPlugin.doThing': 'Faire le truc' },
};

以下声明将从源文件中的英文字符串键推断类型：

env.d.ts

declare namespace StarlightApp {
  type UIStrings = typeof import('./ui-strings').UIStrings.en;
  interface I18n extends UIStrings {}
}

config:setup

Starlight 初始化时调用的插件配置设置函数（在 astro:config:setup 集成钩子期间）。config:setup 钩子可用于更新 Starlight 配置或添加 Astro 集成。

调用此钩子时会传入以下选项：

config

类型： StarlightUserConfig

用户提供的 Starlight 配置的只读副本。此配置可能已被在当前插件之前配置的其他插件更新过。

updateConfig

类型： (newConfig: StarlightUserConfig) => void

一个回调函数，用于更新用户提供的 Starlight 配置。提供你想要覆盖的根级别配置键。要更新嵌套的配置值，你必须提供整个嵌套对象。

要在不覆盖现有配置选项的情况下扩展它，请将现有值展开到新值中。在以下示例中，通过将 config.social 展开到新的 social 数组中，将一个新的社交媒体帐户添加到现有配置中：

plugin.ts

export default {
  name: 'add-twitter-plugin',
  hooks: {
    'config:setup'({ config, updateConfig }) {
      updateConfig({
        social: [
          ...config.social,
          {
            icon: 'twitter',
            label: 'Twitter',
            href: 'https://twitter.com/astrodotbuild',
          },
        ],
      });
    },
  },
};

addIntegration

类型： (integration: AstroIntegration) => void

一个回调函数，用于添加插件所需的 Astro 集成。

在以下示例中，插件首先检查是否配置了 Astro 的 React 集成，如果未配置，则使用 addIntegration() 添加它：

plugin.ts

import react from '@astrojs/react';

export default {
  name: 'plugin-using-react',
  hooks: {
    'config:setup'({ addIntegration, astroConfig }) {
      const isReactLoaded = astroConfig.integrations.find(
        ({ name }) => name === '@astrojs/react'
      );

      // Only add the React integration if it's not already loaded.
      if (!isReactLoaded) {
        addIntegration(react());
      }
    },
  },
};

addRouteMiddleware

类型： (config: { entrypoint: string; order?: 'pre' | 'post' | 'default' }) => void

一个回调函数，用于向站点添加路由中间件处理器。

entrypoint 属性必须是你的插件中间件文件的模块说明符，该文件导出一个 onRequest 处理器。

在以下示例中，一个发布为 @example/starlight-plugin 的插件使用 npm 模块说明符添加了一个路由中间件：

plugin.ts

export default {
  name: '@example/starlight-plugin',
  hooks: {
    'config:setup'({ addRouteMiddleware }) {
      addRouteMiddleware({
        entrypoint: '@example/starlight-plugin/route-middleware',
      });
    },
  },
};

控制执行顺序

默认情况下，插件中间件按照插件添加的顺序运行。

如果你需要更多地控制中间件的运行时间，请使用可选的 order 属性。设置 order: "pre" 以在用户的中间件之前运行。设置 order: "post" 以在所有其他中间件之后运行。

如果两个插件添加的中间件具有相同的 order 值，则先添加的插件将先运行。

astroConfig

类型： AstroConfig

用户提供的 Astro 配置的只读副本。

command

类型： 'dev' | 'build' | 'preview'

用于运行 Starlight 的命令：

• dev - 项目使用 astro dev 执行
• build - 项目使用 astro build 执行
• preview - 项目使用 astro preview 执行

isRestart

类型： boolean

当开发服务器启动时为 false，当触发重新加载时为 true。重新启动的常见原因包括用户在开发服务器运行时编辑他们的 astro.config.mjs 文件。

logger

类型： AstroIntegrationLogger

一个 Astro 集成日志记录器的实例，你可以用它来写入日志。所有记录的消息都将以插件名称作为前缀。

plugin.ts

export default {
  name: 'long-process-plugin',
  hooks: {
    'config:setup'({ logger }) {
      logger.info('Starting long process…');
      // Some long process…
    },
  },
};

上面的示例将记录一条包含所提供信息的消息：

[long-process-plugin] Starting long process…

useTranslations

类型： (lang: string) => I18nT

使用 BCP-47 语言标签调用 useTranslations() 来生成一个工具函数，该函数提供对该语言的 UI 字符串的访问。useTranslations() 返回一个与 Astro 组件中可用的 Astro.locals.t() API 等效的函数。要了解有关可用 API 的更多信息，请参阅“使用 UI 翻译”指南。

plugin.ts

export default {
  name: 'plugin-use-translations',
  hooks: {
    'config:setup'({ useTranslations, logger }) {
      const t = useTranslations('zh-CN');
      logger.info(t('builtWithStarlight.label'));
    },
  },
};

上面的示例将记录一条包含简体中文内置 UI 字符串的消息：

[plugin-use-translations] 基于 Starlight 构建

absolutePathToLang

类型： (path: string) => string

使用文件的绝对路径调用 absolutePathToLang() 来获取该文件的语言。

这在添加 remark 或 rehype 插件来处理 Markdown 或 MDX 文件时特别有用。这些插件使用的虚拟文件格式包含了正在处理的文件的绝对路径，可以与 absolutePathToLang() 一起使用来确定文件的语言。返回的语言可以与 useTranslations() 辅助函数一起使用，以获取该语言的 UI 字符串。

例如，给定以下 Starlight 配置：

starlight({
  title: 'My Docs',
  defaultLocale: 'en',
  locales: {
    // English docs in `src/content/docs/en/`
    en: { label: 'English' },
    // French docs in `src/content/docs/fr/`
    fr: { label: 'Français', lang: 'fr' },
  },
});

插件可以使用文件的绝对路径来确定其语言：

plugin.ts

export default {
  name: 'plugin-use-translations',
  hooks: {
    'config:setup'({ absolutePathToLang, useTranslations, logger }) {
      const lang = absolutePathToLang(
        '/absolute/path/to/project/src/content/docs/fr/index.mdx'
      );
      const t = useTranslations(lang);
      logger.info(t('aside.tip'));
    },
  },
};

上面的示例将记录一条包含法语内置 UI 字符串的消息：

[plugin-use-translations] Astuce