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

> Nuxt Bridge 实现了与 Nuxt 3 兼容的 composables。

通过将来自 `@nuxtjs/composition-api` 的用法迁移到与 Nuxt 3 兼容的 API，当迁移到 Nuxt 3 时需要重写的内容会更少。

## `ssrRef` 和 `shallowSsrRef`

这两个函数已被一个在底层工作方式非常相似的新 composable 所替代：`useState`。

主要区别在于，你必须为此状态提供一个 *key*（Nuxt 会为 `ssrRef` 和 `shallowSsrRef` 自动生成 key），并且它只能在 Nuxt 3 插件（通过 `defineNuxtPlugin` 定义）或组件实例中调用。（换句话说，由于存在请求间共享状态的风险，你不能在全局／环境上下文中使用 [`useState`](https://nuxt.zhcndoc.com/docs/4.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')
  // accessing the state
  console.log(ref1.value)
```

由于状态是有键的，只要使用相同的键，就可以在多个位置访问相同的状态。

你可以在 [Nuxt 3 文档](https://nuxt.zhcndoc.com/docs/4.x/api/composables/use-state)中阅读有关如何使用此 composable 的更多信息。

## `ssrPromise`

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

## `onGlobalSetup`

此函数已被移除，但你可以在 `defineNuxtPlugin` 中使用 [`useNuxtApp`](https://nuxt.zhcndoc.com/docs/4.x/api/composables/use-nuxt-app) 或 [`useState`](https://nuxt.zhcndoc.com/docs/4.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` 来访问注入的 helpers。

```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`

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

::important
请注意，尽管名称相似，但 API 完全不同。重要的是，你不应该尝试去修改 composable 之外的其他变量的值（这可能是你在以前的 `useFetch` 中所做的）。
::

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

从 `useAsync` 迁移到新 composable：

```diff
<script setup>
- import { useAsync } from '@nuxtjs/composition-api'
- const posts = useAsync(() => $fetch('/api/posts'))
+ const { data: posts } = useLazyAsyncData('posts', () => $fetch('/api/posts'))
+ // or, more simply!
+ const { data: posts } = useLazyFetch('/api/posts')
</script>
```

从 `useFetch` 迁移到新 composable：

```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'))
+ // or, more simply!
+ const { data: posts, refresh } = useLazyFetch('/api/posts')
  function updatePosts() {
-   return fetch()
+   return refresh()
  }
</script>
```

### `useMeta`

为了与 `vue-meta` 交互，你可以使用 `useNuxt2Meta`，它可在 Nuxt Bridge 中使用（但在 Nuxt 3 中不可用），并允许你以 `vue-meta` 兼容的方式操纵元标签。

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

你也可以传入计算值或 ref，元数据将以响应式方式更新：

```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/4.x/api/composables/use-head) composable 访问。

```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/4.x/api/composables/use-head) composable 在底层使用 `@unhead/vue`（而非 `vue-meta`）来操纵你的 `<head>`。因此，建议不要同时使用原生 Nuxt 2 的 `head()` 属性和 [`useHead`](https://nuxt.zhcndoc.com/docs/4.x/api/composables/use-head)，因为它们可能会发生冲突。

有关如何使用此 composable 的更多信息，请参阅 [Nuxt 3 文档](https://nuxt.zhcndoc.com/docs/4.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>
```

### 禁用自动导入

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

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

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


## Sitemap

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