composables

使用 composables/ 目录将你的 Vue 组合式函数自动导入到应用中。

用法

方法 1： 使用具名导出

app/composables/useFoo.ts

export const useFoo = () => {
  return useState('foo', () => 'bar')
}

方法 2： 使用默认导出

app/composables/use-foo.ts 或 composables/useFoo.ts

// 它将以 useFoo() 的形式可用（文件名去掉扩展名后的驼峰形式）
export default function () {
  return useState('foo', () => 'bar')
}

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

app/app.vue

<script setup lang="ts">
const foo = useFoo()
</script>

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

Nuxt 中的 app/composables/ 目录并不会为你的代码提供任何额外的响应式能力。相反，组合式函数中的任何响应式都是通过 Vue 的 Composition API 机制（如 ref 和 reactive）实现的。请注意，响应式代码也不局限于 app/composables/ 目录的边界。你可以在应用中任何需要的地方使用响应式特性。

类型

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

请注意，你必须运行 nuxt prepare、nuxt dev 或 nuxt build，以便让 Nuxt 生成这些类型。

如果你在开发服务器未运行时创建组合式函数，TypeScript 会抛出错误，例如 Cannot find name 'useBar'.

示例

嵌套组合式函数

你可以使用自动导入在一个组合式函数内使用另一个组合式函数：

app/composables/test.ts

export const useFoo = () => {
  const nuxtApp = useNuxtApp()
  const bar = useBar()
}

访问插件注入

你可以从组合式函数中访问插件注入：

app/composables/test.ts

export const useHello = () => {
  const nuxtApp = useNuxtApp()
  return nuxtApp.$hello
}

文件是如何被扫描的

Nuxt 只扫描 app/composables/ 目录的顶层文件，例如：

Directory Structure

-| composables/
---| index.ts     // 被扫描
---| useFoo.ts    // 被扫描
---| nested/
-----| utils.ts   // 不被扫描

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

要让嵌套模块也能自动导入，你可以重新导出它们（推荐），或者配置扫描器以包含嵌套目录：

示例： 从 app/composables/index.ts 文件重新导出你需要的组合式函数：

app/composables/index.ts

// 使此导出可被自动导入
export { utils } from './nested/utils.ts'

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

nuxt.config.ts

export default defineNuxtConfig({
  imports: {
    dirs: [
      // 扫描顶层 composables
      '~/composables',
      // ... 或扫描深一层嵌套、且具有特定名称和扩展名的 composables
      '~/composables/*/index.{ts,js,mjs,mts}',
      // ... 或扫描给定目录中的所有 composables
      '~/composables/**',
    ],
  },
})