新 Composition API

Nuxt Bridge 实现了与 Nuxt 3 兼容的可组合函数。

通过从 @nuxtjs/composition-api 迁移到与 Nuxt 3 兼容的 API,您在迁移到 Nuxt 3 时需要重写的代码会更少。

ssrRefshallowSsrRef

这两个函数已被一个新的可组合函数替换,底层工作方式非常相似:useState

主要区别在于,您必须为此状态提供一个_键_(Nuxt 之前会为 ssrRefshallowSsrRef 自动生成键),并且它只能在 Nuxt 3 插件(通过 defineNuxtPlugin 定义)或组件实例中调用。换句话说,您不能在全局/环境上下文中使用 useState,因为这可能会导致跨请求共享状态的危险。

- import { ssrRef } from '@nuxtjs/composition-api'

- const ref1 = ssrRef('initialData')
- const ref2 = ssrRef(() => 'factory function')
+ const ref1 = useState('ref1-key', () => 'initialData')
+ const ref2 = useState('ref2-key', () => 'factory function')
  // 访问状态
  console.log(ref1.value)

由于状态是有键的,您可以从多个位置访问相同的状态,只要使用相同的键即可。

您可以在 Nuxt 3 文档 中了解更多关于如何使用此可组合函数的信息。

ssrPromise

此函数已被移除,如果您在使用它,则需要寻找替代实现。如果您有 ssrPromise 的用例,请通过讨论告知我们。

onGlobalSetup

此函数已被移除,但其用例可以通过在 defineNuxtPlugin 中使用 useNuxtAppuseState 来满足。您还可以在布局的 setup() 函数中运行任何自定义代码。

- import { onGlobalSetup } from '@nuxtjs/composition-api'

- export default () => {
-   onGlobalSetup(() => {
+ export default defineNuxtPlugin((nuxtApp) => {
+   nuxtApp.hook('vue:setup', () => {
      // ...
    })
- }
+ })

useStore

为了访问 Vuex 存储实例,您可以使用 useNuxtApp().$store

- import { useStore } from '@nuxtjs/composition-api`
+ const { $store } = useNuxtApp()

useContextwithContext

您可以使用 useNuxtApp 访问注入的辅助函数。

- import { useContext } from '@nuxtjs/composition-api`
+ const { $axios } = useNuxtApp()
useNuxtApp() 还提供了一个名为 nuxt2Context 的键,包含您通常从 Nuxt 2 上下文中访问的所有属性,但建议_不要_直接使用它,因为它在 Nuxt 3 中将不存在。相反,请查看是否有其他方法访问您所需的内容。(如果没有,请提出功能请求或讨论。)

wrapProperty

此辅助函数不再提供,但您可以使用以下代码替换它:

const wrapProperty = (property, makeComputed = true) => () => {
  const vm = getCurrentInstance().proxy
  return makeComputed ? computed(() => vm[property]) : vm[property]
}

useAsyncuseFetch

这两个可组合函数可以替换为 useLazyAsyncDatauseLazyFetch,相关文档在 Nuxt 3 文档 中。与之前的 @nuxtjs/composition-api 可组合函数一样,这些可组合函数不会在客户端阻塞路由导航(因此名称中包含“lazy”)。

请注意,尽管名称听起来相似,但 API 完全不同。重要的是,您不应尝试在可组合函数外部更改其他变量的值(就像您可能在使用之前的 useFetch 时所做的那样)。
useLazyFetch 必须为 Nitro 配置。

useAsync 迁移到新可组合函数:

<script setup>
- import { useAsync } from '@nuxtjs/composition-api'
- const posts = useAsync(() => $fetch('/api/posts'))
+ const { data: posts } = useLazyAsyncData('posts', () => $fetch('/api/posts'))
+ // 或者更简单!
+ const { data: posts } = useLazyFetch('/api/posts')
</script>

useFetch 迁移到新可组合函数:

<script setup>
- import { useFetch } from '@nuxtjs/composition-api'
- const posts = ref([])
- const { fetch } = useFetch(() => { posts.value = await $fetch('/api/posts') })
+ const { data: posts, refresh } = useLazyAsyncData('posts', () => $fetch('/api/posts'))
+ // 或者更简单!
+ const { data: posts, refresh } = useLazyFetch('/api/posts')
  function updatePosts() {
-   return fetch()
+   return refresh()
  }
</script>

useMeta

为了与 vue-meta 交互,您可以使用 useNuxt2Meta,它在 Nuxt Bridge 中有效(但在 Nuxt 3 中无效),并允许您以与 vue-meta 兼容的方式操作元标签。

<script setup>
- import { useMeta } from '@nuxtjs/composition-api'
  useNuxt2Meta({
    title: 'My Nuxt App',
  })
</script>

您还可以传入计算属性或 ref,元标签值会响应式更新:

<script setup>
const title = ref('my title')
useNuxt2Meta({
  title,
})
title.value = 'new title'
</script>
注意不要在同一组件中同时使用 useNuxt2Meta() 和 Options API 的 head(),因为行为可能不可预测。

Nuxt Bridge 还提供了与 Nuxt 3 兼容的元标签实现,可通过 useHead 可组合函数访问。

<script setup>
- import { useMeta } from '@nuxtjs/composition-api'
  useHead({
    title: 'My Nuxt App',
  })
</script>

您还需要在 nuxt.config 中显式启用它:

import { defineNuxtConfig } from '@nuxt/bridge'
export default defineNuxtConfig({
  bridge: {
    meta: true
  }
})

useHead 可组合函数在底层使用 @unhead/vue(而不是 vue-meta)来操作您的 <head>。因此,建议不要同时使用原生的 Nuxt 2 head() 属性和 useHead,因为它们可能会冲突。

有关如何使用此可组合函数的更多信息,请参阅 Nuxt 3 文档

显式导入

Nuxt 通过 #imports 别名暴露了所有自动导入的项,如果需要,可以使用它来进行显式导入:

<script setup lang="ts">
import { ref, computed } from '#imports'

const count = ref(1)
const double = computed(() => count.value * 2)
</script>

禁用自动导入

如果您想禁用可组合函数和工具的自动导入,可以在 nuxt.config 文件中将 imports.autoImport 设置为 false

nuxt.config.ts
export default defineNuxtConfig({
  imports: {
    autoImport: false
  }
})

这将完全禁用自动导入,但仍可以通过 #imports 进行显式导入。