v3.16
Nuxt on GitHub

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('这只会被记录一次')
  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('这只会被记录一次，之后在每次客户端导航时也会记录')
  websiteConfig.value = await $fetch('https://my-cms.com/api/website-config')
}, { mode: 'navigation' })
</script>
navigation 模式自 Nuxt v3.15 起可用。
callOnce 与 Pinia 模块 结合使用时非常有用，可用于调用 store 操作。
阅读更多 Docs > Getting Started > State Management.
请注意，callOnce 不返回任何值。如果您想在 SSR 期间进行数据获取，应使用 useAsyncData 或 useFetch。
callOnce 是一个组合函数，旨在直接在 setup 函数、插件或路由中间件中调用，因为它需要将数据添加到 Nuxt 负载中，以避免在页面 hydration 时重新调用该函数。

类型

callOnce (key?: string, fn?: (() => any | Promise<any>), options?: CallOnceOptions): Promise<void>
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：在初始渲染期间执行一次，并在后续的客户端导航中每次执行一次