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 action 非常有用。
更多資訊請閱讀 文件 > 4 X > 入門 > 狀態管理。
請注意，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 = {
  /**
   * Execution mode for the callOnce function
   * @default 'render'
   */
  mode?: 'navigation' | 'render'
}

引數

  • key：一個唯一的鍵，確保程式碼只執行一次。如果你不提供鍵，那麼將為你生成一個在檔案和 callOnce 例項的行號中唯一的鍵。
  • fn：要執行一次的函式。它可以是非同步的。
  • options：設定模式，要麼在導航時重新執行 (navigation)，要麼在應用程式的生命週期中只執行一次 (render)。預設為 render。
    • render：在初始渲染期間（SSR 或 CSR）執行一次 - 預設模式
    • navigation：在初始渲染期間執行一次，並在每次後續客戶端導航時執行一次