onPrehydrate

源文件
使用 onPrehydrate 在 Nuxt 对页面进行水合之前，立即在客户端上运行回调函数。
此组合式函数适用于 Nuxt v3.12 及以上版本。

onPrehydrate 是一个组合式生命周期钩子，允许你在 Nuxt 对页面进行水合之前，立即在客户端上运行回调函数。

这是一个高级实用工具，应谨慎使用。例如，nuxt-time 和 @nuxtjs/color-mode 会通过操作 DOM 来避免水合不匹配（hydration mismatches）。

使用

在 Vue 组件的 setup 函数中（例如在 <script setup> 中）或在插件中调用 onPrehydrate。该调用本身仅在服务器端执行时才有效，并且会从客户端构建中剥离。不过，你传递的回调函数会被序列化并内联到 HTML 中，因此它会在 Nuxt 进行水合之前的浏览器中立即运行。这意味着它可以访问诸如 window 和 DOM 之类的浏览器全局变量。

类型

签名
export function onPrehydrate (callback: (el: HTMLElement) => void): void
export function onPrehydrate (callback: string | ((el: HTMLElement) => void), key?: string): undefined | string

参数

参数类型必需描述
callback((el: HTMLElement) => void) | string是在 Nuxt 水合之前运行的函数（或序列化为字符串的函数）。它会被序列化并内联到 HTML 中。不应包含外部依赖项或引用回调函数外部的变量。由于它在 Nuxt 运行时初始化之前运行，因此不应依赖 Nuxt 或 Vue 上下文。
keystring否（高级）用于标识预水合脚本的唯一键，对于多根节点等高级场景非常有用。

返回值

  • 当仅使用回调函数调用时，返回 undefined。
  • 当使用回调函数和键进行调用时，返回一个字符串（预水合 ID），可用于在高阶用例中设置或访问 data-prehydrate-id 属性。

示例

app/app.vue
<script setup lang="ts">
declare const window: Window
// ---cut---
onPrehydrate(() => {
  // Runs in the browser, right before Nuxt hydrates
  console.log(window)
})

// Access the root element
onPrehydrate((el) => {
  console.log(el.outerHTML)
  // <div data-v-inspector="app.vue:15:3" data-prehydrate-id=":b3qlvSiBeH:"> Hi there </div>
})

// Advanced: access/set `data-prehydrate-id` yourself
const prehydrateId = onPrehydrate((el) => {})
</script>

<template>
  <div>
    Hi there
  </div>
</template>

底层原理是：回调函数在构建时会被序列化并进行代码压缩，然后作为 <script> 标签内联到服务器渲染的 HTML 中，紧挨在闭合的 </body> 标签之前。对于上面的示例，渲染出的 HTML 包含类似于以下内容

<div data-prehydrate-id=":b3qlvSiBeH:"> Hi there </div>
<script>(()=>{console.log(window)})()</script>
<script>document.querySelectorAll('[data-prehydrate-id*=":b3qlvSiBeH:"]').forEach(el=>{console.log(el.outerHTML)})</script>

当回调函数接受 el 参数时，组件的根元素会被标记一个 data-prehydrate-id 属性，以便内联脚本能够找到它。