composables

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

用法

方法 1: 使用具名导出

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

方法 2: 使用默认导出

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

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

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

<template>
  <div>
    {{ foo }}
  </div>
</template>
Nuxt 中的 composables/ 目录并不会为您的代码提供任何额外的响应式能力。组合函数中的响应式特性是通过 Vue 的组合式 API 机制实现的,比如 ref 和 reactive。请注意,响应式代码也不限于 composables/ 目录的范围。您可以在应用程序中任何需要的地方使用响应式特性。
Read more in Docs > Guide > Concepts > Auto Imports.
Read and edit a live example in Docs > Examples > Features > Auto Imports.

类型

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

请注意,您需要运行 nuxt preparenuxt devnuxt build 以让 Nuxt 生成类型。

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

示例

嵌套组合函数

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

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

访问插件注入

您可以在组合函数中访问插件注入

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

文件扫描规则

Nuxt 仅扫描 composables/ 目录 顶层的文件,例如:

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

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

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

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

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

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

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