通过 100+ 技巧集合学习 Nuxt!

callOnce

在 SSR 或 CSR 期间,只运行给定的函数或代码块一次。
此实用工具自 Nuxt v3.9 版本起可用。

目的

callOnce 函数旨在在以下情况下仅执行给定的函数或代码块一次:

  • 服务器端渲染,但非水合(hydration)
  • 客户端导航

这对于只需执行一次的代码非常有用,例如记录事件或设置全局状态。

用法

callOnce 的默认模式是只运行代码一次。例如,如果代码在服务器上运行,则不会在客户端再次运行。如果您在客户端多次 callOnce,例如通过导航回到此页面,它也不会再次运行。

app.vue
<script setup lang="ts">
const websiteConfig = useState('config')

await callOnce(async () => {
  console.log('This will only be logged once')
  websiteConfig.value = await $fetch('https://my-cms.com/api/website-config')
})
</script>

也可以在每次导航时运行,同时避免初始服务器/客户端双重加载。为此,可以使用 navigation 模式

app.vue
<script setup lang="ts">
const websiteConfig = useState('config')

await callOnce(async () => {
  console.log('This will only be logged once and then on every client side navigation')
  websiteConfig.value = await $fetch('https://my-cms.com/api/website-config')
}, { mode: 'navigation' })
</script>
navigation 模式自 Nuxt v3.15 版本起可用。
callOncePinia 模块 结合使用,调用 store actions 非常有用。
文档 > 入门 > 状态管理 中阅读更多信息。
请注意,callOnce 不返回任何内容。如果您想在 SSR 期间进行数据获取,则应使用 useAsyncDatauseFetch
callOnce 是一个 composable,旨在直接在 setup 函数、插件或路由中间件中调用,因为它需要将数据添加到 Nuxt payload,以避免在页面水合时在客户端重新调用该函数。

类型

callOnce (key?: string, fn?: (() => any | Promise<any>), options?: CallOnceOptions): Promise<void>
callOnce(fn?: (() => any | Promise<any>), options?: CallOnceOptions): Promise<void>

type CallOnceOptions = {
  /**
   * Execution mode for the callOnce function
   * @default 'render'
   */
  mode?: 'navigation' | 'render'
}

参数

  • key:一个唯一的 key,确保代码只运行一次。如果您不提供 key,则会为您生成一个对于 callOnce 实例的文件和行号唯一的 key。
  • fn:要运行一次的函数。此函数也可以返回 Promise 和一个值。
  • options:设置模式,可以设置为在导航时重新执行 (navigation) 或仅在应用程序生命周期内执行一次 (render)。默认为 render
    • render:在初始渲染期间(SSR 或 CSR)执行一次 - 默认模式
    • navigation:在初始渲染期间执行一次,并在每次后续客户端导航时执行一次