callOnce

源文件
在 SSR（服务端渲染）或 CSR（客户端渲染）期间运行指定的函数或代码块一次。
此工具自 Nuxt v3.9 起提供。

目的

callOnce 函数旨在确保指定的函数或代码块仅在以下情况下执行一次：

  • 服务端渲染（而非客户端水合/hydration）
  • 客户端导航

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

使用

callOnce 的默认模式是只运行代码一次。例如，如果代码在服务端运行，它就不会在客户端再次运行。此外，如果你在客户端多次调用 callOnce（例如通过导航回到此页面），它也不会再次运行。

app/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/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 起提供。
callOnce 可与 Pinia 模块结合使用，以调用 store 的 actions。
更多信息请阅读 文档 > 4 X > 入门指南 > 状态管理。
注意，callOnce 不返回任何内容。如果你需要在 SSR 期间进行数据获取，请使用 useAsyncData 或 useFetch。
callOnce 是一个组合式函数（composable），旨在直接在 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 = {
  /**
   * Execution mode for the callOnce function
   * @default 'render'
   */
  mode?: 'navigation' | 'render'
}

参数

  • key: 一个唯一键，确保代码只运行一次。如果你不提供键，系统会自动根据 callOnce 所在的文件和行号生成一个唯一键。
  • fn: 需要运行一次的函数。它可以是异步的。
  • options: 设置模式，可选择在导航时重新执行 (navigation) 或仅在应用生命周期内执行一次 (render)。默认为 render。
    • render: 在初始渲染（SSR 或 CSR）期间执行一次 - 默认模式
    • navigation: 在初始渲染期间执行一次，并在随后的每次客户端导航中执行一次