---
title: "composables"
description: "使用 composables/ 目录将 Vue 组合函数自动导入到您的应用程序中。"
canonical_url: "https://nuxt.zhcndoc.com/docs/3.x/directory-structure/composables"
---
# composables

> 使用 composables/ 目录将 Vue 组合函数自动导入到您的应用程序中。

## 用法

**方法 1：** 使用具名导出

```ts [composables/useFoo.ts]
export const useFoo = () => {
  return useState('foo', () => 'bar')
}
```

**方法 2：** 使用默认导出

```ts [composables/use-foo.ts or composables/useFoo.ts]
// 它将作为 useFoo() 使用（文件名去扩展名后的驼峰命名）
export default function () {
  return useState('foo', () => 'bar')
}
```

**用法：** 现在您可以在 `.js`、`.ts` 和 `.vue` 文件中使用自动导入的组合函数

```vue [app.vue]
<script setup lang="ts">
const foo = useFoo()
</script>

<template>
  <div>
    {{ foo }}
  </div>
</template>
```

::note
Nuxt 中的 `composables/` 目录并不会为您的代码提供任何额外的响应式能力。组合函数中的响应式特性是通过 Vue 的组合式 API 机制实现的，比如 ref 和 reactive。请注意，响应式代码也不限于 `composables/` 目录的范围。您可以在应用程序中任何需要的地方使用响应式特性。
::

::read-more{to="https://nuxt.zhcndoc.com/docs/3.x/guide/concepts/auto-imports"}
::

::link-example{to="https://nuxt.zhcndoc.com/docs/examples/features/auto-imports"}
::

## 类型

在底层，Nuxt 会自动生成文件 `.nuxt/imports.d.ts` 来声明类型。

请注意，您必须运行 [`nuxt prepare`](https://nuxt.zhcndoc.com/docs/3.x/api/commands/prepare)、[`nuxt dev`](https://nuxt.zhcndoc.com/docs/3.x/api/commands/dev) 或 [`nuxt build`](https://nuxt.zhcndoc.com/docs/3.x/api/commands/build)，才能让 Nuxt 生成类型。

请注意，您需要运行 [`nuxt prepare`](https://nuxt.zhcndoc.com/docs/3.x/api/commands/prepare)、[`nuxt dev`](https://nuxt.zhcndoc.com/docs/3.x/api/commands/dev) 或 [`nuxt build`](https://nuxt.zhcndoc.com/docs/3.x/api/commands/build) 以让 Nuxt 生成类型。

::note
如果您在未启动开发服务器的情况下创建组合函数，TypeScript 会抛出错误，例如 `Cannot find name 'useBar'.`
::

## 示例

### 嵌套组合函数

您可以在一个组合函数中通过自动导入使用另一个组合函数：

```ts [composables/test.ts]
export const useFoo = () => {
  const nuxtApp = useNuxtApp()
  const bar = useBar()
}
```

### 访问插件注入

您可以从组合函数中访问[插件注入](https://nuxt.zhcndoc.com/docs/3.x/directory-structure/plugins#providing-helpers)：

```ts [composables/test.ts]
export const useHello = () => {
  const nuxtApp = useNuxtApp()
  return nuxtApp.$hello
}
```

## 文件扫描规则

Nuxt 只扫描 [`composables/ 目录`](https://nuxt.zhcndoc.com/docs/3.x/directory-structure/composables)顶层的文件，例如：

```bash [目录结构]
-| composables/
---| index.ts     // 被扫描
---| useFoo.ts    // 被扫描
---| nested/
-----| utils.ts   // 不被扫描
```

只有 `composables/index.ts` 和 `composables/useFoo.ts` 会被用于搜索导入。

要使嵌套模块的自动导入生效，您可以选择重新导出它们（推荐）或者配置扫描器以包含嵌套目录：

**示例：** 从 `composables/index.ts` 文件中重新导出所需的组合函数：

```ts [composables/index.ts]
// 启用此导出的自动导入
export { utils } from './nested/utils.ts'
```

**示例：** 扫描 `composables/` 文件夹内的嵌套目录：

```ts twoslash [nuxt.config.ts]
export default defineNuxtConfig({
  imports: {
    dirs: [
      // 扫描顶级的 composables
      '~/composables',
      // ... 或扫描一层深的嵌套 composables 文件夹，指定名字和文件扩展名
      '~/composables/*/index.{ts,js,mjs,mts}',
      // ... 或扫描指定目录下所有的 composables
      '~/composables/**',
    ],
  },
})
```


## Sitemap

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