新的 Composition API
通过从 @nuxtjs/composition-api
迁移到兼容 Nuxt 3 的 API,迁移到 Nuxt 3 时需要重写的代码将更少。
ssrRef
和 shallowSsrRef
这两个函数被一个新的组合式函数替换,底层工作方式非常相似:useState
。
关键区别是你必须为这个状态提供一个 key(Nuxt 之前会自动为 ssrRef
和 shallowSsrRef
生成 key),而且它只能在 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
内使用 useNuxtApp
或 useState
来满足。你也可以在布局的 setup()
函数中运行任何自定义代码。
- import { onGlobalSetup } from '@nuxtjs/composition-api'
- export default () => {
- onGlobalSetup(() => {
+ export default defineNuxtPlugin((nuxtApp) => {
+ nuxtApp.hook('vue:setup', () => {
// ...
})
- }
+ })
useStore
访问 Vuex store 实例时,可以使用 useNuxtApp().$store
。
- import { useStore } from '@nuxtjs/composition-api`
+ const { $store } = useNuxtApp()
useContext
和 withContext
你可以通过 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]
}
useAsync
和 useFetch
这两个组合式函数可以用 useLazyAsyncData
和 useLazyFetch
替代,相关文档见 Nuxt 3 文档。就像之前的 @nuxtjs/composition-api
组合式函数一样,这些新的组合式函数在客户端不会阻塞路由导航(因此名称中的 ‘lazy’)。
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
的方式操作 meta 标签。
<script setup>
- import { useMeta } from '@nuxtjs/composition-api'
useNuxt2Meta({
title: 'My Nuxt App',
})
</script>
你也可以传入计算属性或 refs,meta 值将响应式更新:
<script setup>
const title = ref('my title')
useNuxt2Meta({
title,
})
title.value = 'new title'
</script>
useNuxt2Meta()
和 Options API 的 head()
,否则行为不可预期。Nuxt Bridge 还提供了兼容 Nuxt 3 的 meta 实现,可以通过 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
。
export default defineNuxtConfig({
imports: {
autoImport: false
}
})
这将完全禁用自动导入,但你仍然可以从 #imports
使用 显式导入。