Astro 集成 API
Astro 集成只需几行代码就能为你的项目添加新的功能和行为。
这个参考页是为任何想要编写集成的人准备的。要学习如何在项目中使用集成,请查看我们的使用集成指南。
示例
段落标题 示例当你创建自己的集成时,可以参考官方的 Astro 集成。
API 快速参考
段落标题 API 快速参考钩子
段落标题 钩子Astro 提供了集成可以实现的钩子,以便在 Astro 生命周期的某些部分执行。Astro 钩子被定义在 IntegrationHooks
接口中,该接口是全局 Astro
命名空间的一部分。
Astro 内置了以下钩子:
astro:config:setup
段落标题 astro:config:setup下一个钩子:astro:config:done
用途:扩展项目配置。包括更新 Astro 配置、应用 Vite 插件、添加组件渲染器,以及向页面注入脚本。
config
选项
段落标题 config 选项类型:AstroConfig
用户提供的 Astro 配置只读副本。这是在任何其他集成运行之前进行解析的。如果在所有集成完成配置更新后需要配置副本,见astro:config:done
钩子。
command
选项
段落标题 command 选项类型: 'dev' | 'build' | 'preview' | 'sync'
dev
- 项目执行astro dev
build
- 项目执行astro build
preview
- 项目执行astro preview
sync
- 项目执行astro sync
isRestart
选项
段落标题 isRestart 选项类型:boolean
开发服务器启动时为false
,触发重载时为true
。用于检测此函数何时被多次调用。
updateConfig
选项
段落标题 updateConfig 选项类型:(newConfig: DeepPartial<AstroConfig>) => AstroConfig;
用来更新用户提供的Astro 配置的回调函数。你提供的任何配置将与用户配置 + 其他集成配置的更新合并,所以你可以随意省略键名!
例如,假设你需要在项目使用 Vite 插件:
addRenderer
选项
段落标题 addRenderer 选项类型:(renderer:
AstroRenderer
) => void;
示例:lit
、svelte
、react
、preact
、vue
、solid
用于添加组件框架渲染器(即 React、Vue、Svelte 等)的回调函数。你可以浏览上面的例子和类型定义,了解更多的高级选项,但需要注意两个注意选项:
clientEntrypoint
- 当组件被使用时,在客户端执行的文件的路径。这主要是为了使用 JS 渲染或填充你的组件。serverEntrypoint
- 文件路径,在服务器端请求或静态构建时,只要使用组件就会执行。这些文件应该将组件渲染成静态标记,并在适当的时候使用钩子进行激活。React 的renderToString
回调函数是个典型例子。
addWatchFile
选项
段落标题 addWatchFile 选项类型: URL | string
如果你的集成依赖于一些 Vite 不监听或者需要完整的开发服务器重启才能生效的配置文件,请用addWatchFile
添加它。每当该文件发生变化,Astro 开发服务器将重新加载(你可以用isRestart
检查何时发生重新加载)。
使用示例:
addClientDirective
选项
段落标题 addClientDirective 选项
添加于:
astro@2.6.0
类型: (directive:
ClientDirectiveConfig
) => void;
添加一个 自定义客户端指令,用于在 .astro
文件中使用。
请注意,指令入口点仅通过 esbuild 进行打包,并且应保持较小,以避免减慢组件注水的速度。
示例用法:
你还可以在库的类型定义文件中为指令添加类型:
addDevToolbarApp
选项
段落标题 addDevToolbarApp 选项
添加于:
astro@3.4.0
类型: (pluginEntrypoint: string) => void;
添加一个自定义的开发工具栏应用。
使用示例:
addMiddleware
选项
段落标题 addMiddleware 选项
添加于:
astro@3.5.0
类型: (middleware:
AstroIntegrationMiddleware
) => void;
添加中间件以在每个请求上运行。接受包含中间件的 entrypoint
模块,以及一个 order
参数来指定它应该在其他中间件之前(pre
)运行还是之后(post
)运行。
中间件在一个包中定义,它有一个对应的 onRequest
函数,就像用户定义的中间件一样。
injectRoute
选项
段落标题 injectRoute 选项类型:({ pattern: string, entrypoint: string }) => void;
用于向 Astro 项目注入路由的回调函数。注入的路由可以是 .astro
页面 或 .js
和.ts
路由处理程序。
injectRoute
接收带有 pattern
和 entrypoint
的对象值。
pattern
- 应该在浏览器中使用的路由,例如/foo/bar
。pattern
可以使用 Astro 的文件路径语法来表示动态路由,例如/foo/[bar]
或/foo/[...bar]
。请注意,在pattern
中无需文件扩展名。entrypoint
— 裸模块指定器,指向.astro
页面或.js
/.ts
路由处理程序,处理pattern
中指定路由。
使用示例
段落标题 使用示例对于设计用于安装在其他项目中的集成,使用其包名来引用路由的入口点。
下面的示例展示了一个以 @fancy/dashboard
发布到 npm 上的包,在路由中注入一个仪表盘:
当你将你的包(在这个例子中是 @fancy/dashboard
)发布到 npm 上时,你必须在你的 package.json
中导出 dashboard.astro
:
injectScript
选项
段落标题 injectScript 选项类型:(stage: InjectedScriptStage, content: string) => void;
回调函数,在每个页面上注入 JavaScript 内容。
stage
表示这个脚本(content
)应该如何插入。有些阶段允许不加修改地插入脚本,而有些阶段允许在 Vite 的捆绑步骤中进行压缩:
-
head-inline
:注入每个页面的<head>
中的脚本标签。不由 Vite 压缩或解析。 -
before-hydration
:在激活脚本运行之前导入客户端。由 Vite 优化和解决。 -
page
:与head-inline
类似,只是注入片段由 Vite 进行处理,并与页面上 Astro 组件内定义的其他<script>
标签捆绑在一起。该脚本将在最终的页面输出中以<script type="module">
的形式加载,并由 Vite 压缩和解析。 -
page-ssr
:在每个 Astro 页面组件的 frontmatter 中作为单独的模块被导入。因为这个阶段导入你的脚本,无法使用全局Astro
,脚本只会在import
第一次 evaluate 时运行一次。page-ssr
阶段的主要是将 CSSimport
注入到每个页面,并由 Vite 进行优化和解析。
astro:config:done
段落标题 astro:config:done上一个钩子:astro:config:setup
下一个钩子:当在开发模式下运行时为 astro:server:setup
,在生产构建时为 astro:build:start
时机:在 Astro 配置解析后,其他集成已经运行 astro:config:setup
钩子后。
原因:检索最终的配置,以便在其他钩子中使用。
config
选项
段落标题 config 选项类型:AstroConfig
用户提供的 Astro 配置的只读副本。这在其他集成运行后进行解析。
setAdapter
选项
段落标题 setAdapter 选项类型:(adapter: AstroAdapter) => void;
使集成成为适配器。在适配器 API中阅读更多内容。
injectTypes
选项
段落标题 injectTypes 选项
添加于:
astro@4.14.0
类型:(injectedType: { filename: string; content: string }) => URL
允许你通过添加一个新的 *.d.ts
文件将类型注入到用户的项目中。
filename
属性将用于在 /.astro/integrations/<normalized_integration_name>/<normalized_filename>.d.ts
生成文件,必须以 ".d.ts"
结尾。
content
属性将用于在文件中生成内容,必须是有效的 TypeScript。
此外,injectTypes()
返回一个 URL,指向规范化路径,以便稍后覆盖其内容,或以任何你想要的方式操作它。
astro:server:setup
段落标题 astro:server:setup上一个钩子:astro:config:done
下一个钩子:astro:server:start
时机:在开发模式下创建 Vite 服务器后,但在 listen()
事件触发前。详见Vite 的 createServer API。
用途:更新 Vite 服务端选项和中间件。
server
选项
段落标题 server 选项在开发模式下使用的 Vite 服务器的可变实例。例如,在 Partytown 集成中使用,以注入 Partytown 服务器作为中间件。
astro:server:start
段落标题 astro:server:start上一个钩子:astro:server:setup
下一个钩子:astro:server:done
时机:在服务端 listen()
事件触发之后。
用途:拦截指定地址的网络请求。如果你打算将这个地址用于中间件,请考虑使用 astro:server:setup
来代替。
address
选项
段落标题 address 选项类型:AddressInfo
由 Node.js Net 模块提供的地址、协议族名和端口。
astro:server:done
段落标题 astro:server:done上一个钩子:astro:server:start
时机:在开发服务器关闭后。
用途:在运行 astro:server:setup
或 astro:server:start
钩子中可能触发的清理事件。
astro:build:start
段落标题 astro:build:start上一个钩子:astro:config:done
下一个钩子:astro:build:setup
时机:在 astro:config:done
事件之后,但在生产构建开始前。
用途:设置生产构建过程中需要的任何全局对象或客户端。这也可以扩展适配器 API中的构建配置选项。
astro:build:setup
段落标题 astro:build:setup上一个钩子:astro:build:start
下一个钩子:astro:build:ssr
时机:在 astro:build:start
钩子后,在构建之前立即运行。
用途:此时,用于构建的 Vite 配置已经完全建成,这是你修改它的最后机会。例如,这可以用来覆盖一些默认值。如果你不确定你应该使用这个钩子还是 astro:build:start
,请使用 astro:build:start
。
astro:build:generated
段落标题 astro:build:generated上一个钩子: astro:build:setup
时机:在静态生产构建完成生成路由和资源之后。
用途:在清理构建产物之前访问生成的路由和资源。这是一个非常不常见的用例。我们建议使用astro:build:done
,除非你真的需要在清理前访问生成的文件。
astro:build:ssr
段落标题 astro:build:ssr上一个钩子:astro:build:setup
时机:在生产 SSR 构建完成之后。
原因:获取 SSR manifest,这在插件或集成中创建自定义 SSR 构建时很有用。
entryPoints
将页面路由映射到构建后的物理文件;middlewareEntryPoint
是中间件文件的文件系统路径。
astro:build:done
段落标题 astro:build:done上一个钩子:astro:build:ssr
时机:在生产构建(SSG 或 SSR)完成后。
用途:访问生成的路由和资产进行扩展(例如,将内容复制到生成的 /assets
目录)。如果你打算转换生成的资源,我们建议探索 Vite 插件 API 和通过 astro:config:setup
进行配置来代替。
dir
option
段落标题 dir option类型:URL
指向构建输出目录的链接。注意,如果你需要有效的绝对路径字符串,你应该使用 Node 内置的 fileURLToPath
工具。
routes
选项
段落标题 routes 选项类型:RouteData[]
所有生成的路由及其相关元数据的列表。
你可以参考下面完整的 RouteData
类型,但最常见的属性是。
component
- 相对于项目根的输入文件路径pathname
- 输出文件的 URL(对于使用[dynamic]
和[...spread]
参数的路由未定义)。
RouteData
类型参考
段落标题 RouteData 类型参考pages
选项
段落标题 pages 选项类型: { pathname: string }[]
生成的所有页面的列表是一个包含一个属性的对象。
pathname
- 页面的最终路径。
astro:route:setup
段落标题 astro:route:setup
添加于:
astro@4.14.0
时机: 在 astro dev
中,每当请求一个路由时。在 astro build
中,当打包和转换路由文件时。
原因: 在构建或请求时为路由设置选项,例如启用按需服务器渲染 (EN)。
route
选项
段落标题 route 选项类型:RouteOptions
具有 component
属性的对象用于标识路由,以及以下附加值,以允许你配置生成的路由:prerender
。
component
属性是一个相对于项目根目录的只读字符串路径,例如 "src/pages/blog/[slug].astro"
。
route.prerender
段落标题 route.prerender类型:boolean
默认值:undefined
astro@4.14.0
prerender
属性用于配置按需服务器渲染 (EN)的路由。如果路由文件包含一个显式的 export const prerender
值,该值将被用作默认值,而不是 undefined
。
如果在运行所有钩子后的最终值是 undefined
,路由将根据 output
选项 回退到预渲染的默认值:hybrid
模式下预渲染,server
模式下按需渲染。
自定义钩子
段落标题 自定义钩子通过 全局增强 来扩展 IntegrationHooks
接口,可以将自定义钩子添加到集成中。
Astro 为未来的内置钩子保留了 astro:
前缀。请在命名时,为自定义钩子选择不同的前缀。
HookParameters
段落标题 HookParameters你可以通过将钩子的名称传递给 HookParameters
实用工具类型来获取钩子参数的类型。在以下示例中,输入了函数的 options
参数后,匹配到了 astro:config:setup
挂钩的参数:
使用 astro add
安装
段落标题 使用 astro add 安装用户可以使用 astro add
命令 轻松地在他们的项目中添加集成和适配器。如果你想让别人可以使用这个工具安装你的集成,在你的 package.json
中的 keywords
字段中添加 astro-integration
:
在你将集成发布到 npm后,即可运行 astro add example
安装包和 package.json
中指定的对等依赖。同时也会将你的集成应用到用户的 astro.config
中,就像这样:
这假定你的集成定义是:1)default
导出;2)函数。在添加 astro-integration
关键字前,请确保符合要求。
AstroIntegrationLogger
段落标题 AstroIntegrationLoggerAstro 日志记录器的实例,用于写日志。此日志记录器使用与 CLI 配置的相同的日志级别。
用于写入终端的可用方法:
logger.info("Message")
;logger.warn("Message")
;logger.error("Message")
;logger.debug("Message")
;
所有消息都前面带有一个具有集成名字的标签。
上面的示例将记录一个包含提供的 info
消息的日志:
要使用不同的标签记录一些日志,请使用 .fork
方法指定一个新的 name
:
上面的示例将默认生成带有 [astro-format]
的日志,并在指定名字时生成带有 [astro-format/build]
的日志:
集成排序
段落标题 集成排序所有的集成都是按照配置的顺序运行的。例如,在 astro.config.*
中的数组 [react(), svelte()]
,react
将在 svelte
之前运行。
你的集成最好能以任何顺序运行。如果不行我们建议在文档中注明你的集成需要排在 integrations
配置数组的第一位或最后一位。
合并预置集成
段落标题 合并预置集成一个集成也可以写成多个较小集成的集合。我们称这些集合为预设。预设不是创建返回单个集成对象的工厂函数,而是返回集成对象的数组。这对于从多个集成中构建复杂的功能非常有用。
社区资源
段落标题 社区资源- 构建你自己的 Astro 集成 - 由 FreeCodeCamp 的 Emmanuel Ohans 撰写
- Astro 集成模板 - 由 GitHub 上的 Florian Lefebvre 提供