---
title: "新的 Composition API"
description: "Nuxt Bridge 实现了兼容 Nuxt 3 的组合式函数。"
canonical_url: "https://nuxt.zhcndoc.com/docs/3.x/bridge/nuxt3-compatible-api"
---
# 新的 Composition API

> Nuxt Bridge 实现了兼容 Nuxt 3 的组合式函数。

通过从 `@nuxtjs/composition-api` 迁移到兼容 Nuxt 3 的 API，迁移到 Nuxt 3 时需要重写的代码将更少。

## `ssrRef` 和 `shallowSsrRef`

这两个函数被一个新的组合式函数替换，底层工作方式非常相似：`useState`。

主要区别在于，你必须为此状态提供一个 *键*（Nuxt 会为 `ssrRef` 和 `shallowSsrRef` 自动生成键），并且只能在 Nuxt 3 插件（通过 `defineNuxtPlugin` 定义）或组件实例中调用它。换句话说，由于跨请求共享状态存在风险，你不能在全局／环境上下文中使用 [`useState`](https://nuxt.zhcndoc.com/docs/3.x/api/composables/use-state)。

```diff
- 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 文档](https://nuxt.zhcndoc.com/docs/3.x/api/composables/use-state)中进一步了解如何使用此组合式函数。

## `ssrPromise`

这个函数已被移除，如果你使用过它，需要寻找替代方案。如果你有 `ssrPromise` 的使用场景，请通过讨论告知我们。

## `onGlobalSetup`

此函数已被移除，但你可以在 `defineNuxtPlugin` 中使用 [`useNuxtApp`](https://nuxt.zhcndoc.com/docs/3.x/api/composables/use-nuxt-app) 或 [`useState`](https://nuxt.zhcndoc.com/docs/3.x/api/composables/use-state) 来满足相关使用场景。你也可以在布局的 `setup()` 函数中运行任意自定义代码。

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

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

## `useStore`

访问 Vuex store 实例时，可以使用 `useNuxtApp().$store`。

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

## `useContext` 和 `withContext`

你可以通过 `useNuxtApp` 访问注入的助手。

```diff
- import { useContext } from '@nuxtjs/composition-api`
+ const { $axios } = useNuxtApp()
```

::note
`useNuxtApp()` 还提供了一个名为 `nuxt2Context` 的键，包含你通常能从 Nuxt 2 上下文访问到的所有属性，但建议 *不要* 直接使用它，因为 Nuxt 3 中不会存在。你应当寻找其他方式访问所需内容。（如果没有，欢迎提出功能请求或讨论。）
::

## `wrapProperty`

此辅助函数不再提供，但你可以用以下代码替换它：

```ts
import { computed, getCurrentInstance } from 'vue'

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

## `useAsync` 和 `useFetch`

这两个组合式函数可以替换为 `useLazyAsyncData` 和 `useLazyFetch`，相关文档见 [Nuxt 3 文档](https://nuxt.zhcndoc.com/docs/3.x/getting-started/data-fetching)。与之前的 `@nuxtjs/composition-api` 组合式函数一样，这些组合式函数不会阻塞客户端的路由导航（因此名称中有“lazy”一词）。

::important
请注意，API 完全不同，尽管名称相似。特别是，你不应该尝试修改组合式函数外的其它变量值（之前 `useFetch` 可能允许这样做）。
::

::warning
必须为 [Nitro](https://nuxt.zhcndoc.com/docs/3.x/bridge/nitro) 配置 `useLazyFetch`。
::

从 `useAsync` 迁移到新的组合式函数：

```diff
<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` 迁移到新的组合式函数：

```diff
<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 标签。

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

你也可以传入计算属性或 refs，meta 值将响应式更新：

```vue
<script setup>
const title = ref('my title')
useNuxt2Meta({
  title,
})
title.value = 'new title'
</script>
```

::note
请避免在同一个组件中同时使用 `useNuxt2Meta()` 和 Options API 的 `head()`，否则行为不可预期。
::

Nuxt Bridge 还提供了兼容 Nuxt 3 的 meta 实现，你可以通过 [`useHead`](https://nuxt.zhcndoc.com/docs/3.x/api/composables/use-head) 组合式函数访问它。

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

你还需要在 `nuxt.config` 中显式启用它：

```js
import { defineNuxtConfig } from '@nuxt/bridge'

export default defineNuxtConfig({
  bridge: {
    meta: true,
  },
})
```

此 [`useHead`](https://nuxt.zhcndoc.com/docs/3.x/api/composables/use-head) 组合式函数在底层使用 `@unhead/vue`（而不是 `vue-meta`）来操作你的 `<head>`。因此，建议不要同时使用 Nuxt 2 原生的 `head()` 属性和 [`useHead`](https://nuxt.zhcndoc.com/docs/3.x/api/composables/use-head)，因为它们可能会发生冲突。

有关如何使用此组合式函数的更多信息，请参阅 [Nuxt 3 文档](https://nuxt.zhcndoc.com/docs/3.x/getting-started/seo-meta)。

### 显式导入

Nuxt 通过 `#imports` 别名导出所有自动导入的内容，如果需要，可以使用该别名进行显式导入：

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

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

### 禁用自动导入

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

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  imports: {
    autoImport: false,
  },
})
```

这将完全禁用自动导入，但仍可以从 `#imports` 进行[显式导入](https://nuxt.zhcndoc.com/docs/3.x/bridge/nuxt3-compatible-api#explicit-imports)。


## Sitemap

See the full [sitemap](https://nuxt.zhcndoc.com/sitemap.md) for all pages.