callOnce
在 SSR 或 CSR 期间运行给定的函数或代码块一次。
此工具函数从 Nuxt v3.9 开始可用。
目的
callOnce 函数设计用于仅在以下情况下执行给定的函数或代码块一次：
- 服务端渲染但不在水合时
- 客户端导航
这对于应该只执行一次的代码很有用，例如记录事件或设置全局状态。
用法
callOnce 的默认模式是只运行一次代码。例如，如果代码在服务端运行，它不会在客户端再次运行。如果您在客户端多次 callOnce，例如通过导航回到此页面，它也不会再次运行。
app/app.vue
<script setup lang="ts">
const websiteConfig = useState('config')
await callOnce(async () => {
console.log('这只会记录一次')
websiteConfig.value = await $fetch('https://my-cms.com/api/website-config')
})
</script>
也可以在每次导航时运行，同时仍然避免初始的服务器/客户端双重加载。为此，可以使用 navigation 模式：
app/app.vue
<script setup lang="ts">
const websiteConfig = useState('config')
await callOnce(async () => {
console.log('这将只记录一次，然后在每次客户端导航时记录')
websiteConfig.value = await $fetch('https://my-cms.com/api/website-config')
}, { mode: 'navigation' })
</script>
navigation 模式从 Nuxt v3.15 开始可用。callOnce 与 Pinia 结合使用来调用 store 操作很有用。请注意，
callOnce 不返回任何内容。如果您想在 SSR 期间进行数据获取，应该使用 useAsyncData`` 或 useFetch``。callOnce 是一个旨在直接在 setup 函数、插件或路由中间件中调用的组合式函数，因为它需要将数据添加到 Nuxt payload 中，以避免在页面水合时在客户端重新调用函数。类型
签名
export function callOnce (key?: string, fn?: (() => any | Promise<any>), options?: CallOnceOptions): Promise<void>
export function callOnce (fn?: (() => any | Promise<any>), options?: CallOnceOptions): Promise<void>
type CallOnceOptions = {
/**
* callOnce 函数的执行模式
* @default 'render'
*/
mode?: 'navigation' | 'render'
}
参数
key: 确保代码只运行一次的唯一键。如果您不提供键，则会为您生成一个对于callOnce实例的文件和行号唯一的键。fn: 要运行一次的函数。它可以是异步的。options: 设置模式，是在导航时重新执行（navigation）还是仅在应用程序生命周期内执行一次（render）。默认为render。render: 在初始渲染期间执行一次（SSR 或 CSR）- 默认模式navigation: 在初始渲染期间执行一次，并在每次后续的客户端导航时执行一次