title | description | i18nReady |
---|---|---|
预获取 |
预获取链接以在页面间实现更快的导航。 |
true |
import { Steps } from '@astrojs/starlight/components'
页面加载时间在网站的可用性和整体体验中扮演着重要角色。当你的访问者与网站进行交互时,Astro 的可选预获取功能能在你的多页面应用(MPA)中带来几乎瞬时的页面导航的好处。
你可以使用 prefetch
配置来启用预获取:
import { defineConfig } from 'astro/config';
export default defineConfig({
prefetch: true
});
一个预获取脚本将被添加到你网站的所有页面。然后你可以在你网站的任何 <a />
链接上添加 data-astro-prefetch
属性来选择预获取。当你将鼠标悬停在链接上时,脚本将在后台获取页面。
<a href="/about" data-astro-prefetch>
注意,预获取只适用于你的网站内的链接,不适用于外部链接。
prefetch
配置也接受一个选项对象,以进一步自定义预获取。
Astro 支持 4 种预获取策略,以适应各种用例:
hover
(默认):当你将鼠标悬停在链接上或聚焦在链接上时预获取。tap
:在你点击链接之前预获取。viewport
:当链接进入视口时预获取。load
:当页面加载后预获取当前页面的所有链接。
你可以通过将其传递给 data-astro-prefetch
属性来为单个链接指定策略:
<a href="/about" data-astro-prefetch="tap">About</a>
每种策略都经过了微调,只有在需要时才预获取,以节省用户的带宽。例如:
添加 data-astro-prefetch
属性时的默认预获取策略是 hover
。要更改它,你可以在你的 astro.config.mjs
文件中配置 prefetch.defaultStrategy
:
import { defineConfig } from 'astro/config';
export default defineConfig({
prefetch: {
defaultStrategy: 'viewport'
}
});
如果你想预获取所有链接,包括那些没有 data-astro-prefetch
属性的链接,你可以将 prefetch.prefetchAll
设置为 true
:
import { defineConfig } from 'astro/config';
export default defineConfig({
prefetch: {
prefetchAll: true
}
});
然后你可以通过设置 data-astro-prefetch="false"
来为单个链接选择不进行预获取:
<a href="/about" data-astro-prefetch="false">About</a>
所有链接的默认预获取策略可以通过 prefetch.defaultStrategy
更改,如 默认预获取策略部分 所示。
由于一些导航可能不总是以 <a />
链接的形式出现,你也可以使用 astro:prefetch
模块中的 prefetch()
API 进行程序化预获取:
<button id="btn">Click me</button>
<script>
import { prefetch } from 'astro:prefetch';
const btn = document.getElementById('btn');
btn.addEventListener('click', () => {
prefetch('/about');
});
</script>
prefetch()
API 包括相同的流量节省模式和慢速连接检测,因此只有在需要时才预获取。
要忽略慢速连接检测,你可以使用 ignoreSlowConnection
选项:
// 即使在数据保护模式或慢速连接下也能预获取
prefetch('/about', { ignoreSlowConnection: true });
确保只在客户端脚本中导入 prefetch()
,因为它依赖于浏览器 API。
当你在页面上使用 视图过渡动画 时,预获取也将默认启用。它设置了一个默认配置 { prefetchAll: true }
,在页面上启用 所有链接的预获取。
你可以在 astro.config.mjs
中自定义预获取配置以覆盖默认设置。例如:
import { defineConfig } from 'astro/config';
export default defineConfig({
// 完全禁用预获取
prefetch: false
});
import { defineConfig } from 'astro/config';
export default defineConfig({
// 保留预获取,但只对带有 `data-astro-prefetch` 的链接进行预获取
prefetch: {
prefetchAll: false
}
});
如果浏览器支持,Astro 的预获取将使用 <link rel="prefetch">
,否则将回退到 fetch()
API。
常见的浏览器对 Astro 的预获取支持存在细微差别:
Chrome 支持 <link rel="prefetch">
。预获取按预期工作。
Firefox 支持 <link rel="prefetch">
,但可能会显示错误或完全失败:
- 如果没有明确的缓存头(例如
Cache-Control
或Expires
),预获取将会因NS_BINDING_ABORTED
错误而失败。 - 即使出现错误,如果响应中有正确的
ETag
头,它将在导航时被重用。 - 否则,如果没有其他缓存头的错误,预获取将不会工作。
Safari 不支持 <link rel="prefetch">
,将回退到 fetch()
API,这需要设置缓存头(例如 Cache-Control
、Expires
和 ETag
)。否则,预获取将不会工作。
特殊情况: 在隐私窗口中,ETag
头不起作用。
为了更好地支持所有浏览器,请确保你的页面设置了正确的缓存头。
对于静态或预渲染的页面,ETag
头通常由部署平台自动设置,并且预期可以直接使用。
对于动态和服务端渲染的页面,根据页面内容自行设置适当的缓存头。更多信息请访问 MDN 关于 HTTP 缓存的文档。
@astrojs/prefetch
集成在 v3.5.0 中被弃用,最终将被完全移除。使用以下说明将 @astrojs/prefetch
迁移到 Astro 的内置预获取,这将替代这个集成。
```js title="astro.config.mjs" ins={6} del={2,5}
import { defineConfig } from 'astro/config';
import prefetch from '@astrojs/prefetch';
export default defineConfig({
integrations: [prefetch()],
prefetch: true
});
```
-
从
@astrojs/prefetch
的配置选项转换:-
已弃用的集成使用
selector
配置选项来指定哪些链接应在进入视口时被预获取。而现在,你需要在这些单独的链接上添加
data-astro-prefetch="viewport"
。<a href="/about" data-astro-prefetch="viewport">
-
已弃用的集成使用
intentSelector
配置选项来指定哪些链接在被悬停或聚焦时应被预获取。现在,你需要在这些单独的链接上添加
data-astro-prefetch
或data-astro-prefetch="hover"
:<!-- 如果 `defaultStrategy` 设置为 `hover`(默认),你可以省略值 --> <a href="/about" data-astro-prefetch> <!-- 否则,你可以明确定义预获取策略 --> <a href="/about" data-astro-prefetch="hover">
-
@astrojs/prefetch
的throttles
选项不再需要,因为新的预获取特性将自动调度和优化预获取。
-