--- title: "组件" description: "Nuxt Kit 提供了一组实用工具来帮助您处理组件。您可以全局或局部注册组件，也可以添加要扫描组件的目录。" canonical_url: "https://nuxt.zhcndoc.com/docs/4.x/api/kit/components" --- # 组件 > Nuxt Kit 提供了一组实用工具来帮助您处理组件。您可以全局或局部注册组件，也可以添加要扫描组件的目录。 组件是 Nuxt 应用的构建块。它们是可重用的 Vue 实例，可用于创建用户界面。在 Nuxt 中，components 目录下的组件默认会被自动导入。但如果您需要从替代目录导入组件，或希望按需选择性地导入组件，`@nuxt/kit` 提供了 `addComponentsDir` 和 `addComponent` 方法。这些工具允许您自定义组件配置，以更好地满足您的需求。 ::tip{icon="i-lucide-video" to="https://vueschool.io/lessons/injecting-components-and-component-directories?friend=nuxt" target="_blank"} 观看关于注入组件的 Vue School 视频。 :: ## `addComponentsDir` 注册一个目录以扫描组件，并在仅使用时导入。请注意，除非您指定 `global: true` 选项，否则这不会将组件注册为全局组件。 ### 用法 ```ts export default defineNuxtModule({ meta: { name: '@nuxt/ui', configKey: 'ui', }, setup () { addComponentsDir({ path: resolve('./runtime/components'), prefix: 'U', pathPrefix: false, }) }, }) ``` ### 类型 ```ts function addComponentsDir (dir: ComponentsDir, opts: { prepend?: boolean } = {}): void ``` ### 参数 `dir` 一个包含以下属性的对象： | 属性 | 类型 | 必填 | 描述 | | ----------------- | ---------------------------------------------------------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | `path` | `string` | `true` | 包含组件的目录路径（绝对路径或相对路径）。您可以使用 Nuxt 别名（~ 或 @）引用项目中的目录，也可以直接使用类似于 require 的 npm 包路径。 | | `pattern` | `string \| string[]`{lang="ts"} | `false` | 将针对指定路径运行的匹配模式。 | | `ignore` | `string[]` | `false` | 将针对指定路径运行的忽略模式。 | | `prefix` | `string` | `false` | 为所有匹配的组件添加此前缀。 | | `pathPrefix` | `boolean` | `false` | 使用组件的路径作为组件名称前缀。 | | `prefetch` | `boolean` | `false` | 这些属性（prefetch/preload）用于在生产环境中通过 webpack 的魔法注释配置如何处理带有 Lazy 前缀的组件。了解更多信息，请参阅 [webpack 文档](https://webpack.js.org/api/module-methods/#magic-comments) | | `preload` | `boolean` | `false` | 这些属性（prefetch/preload）用于在生产环境中通过 webpack 的魔法注释配置如何处理带有 Lazy 前缀的组件。了解更多信息，请参阅 [webpack 文档](https://webpack.js.org/api/module-methods/#magic-comments) | | `isAsync` | `boolean` | `false` | 此标记表示组件应异步加载（使用单独的代码块），无论是否使用 Lazy 前缀。 | | `extendComponent` | `(component: Component) => Promise \| (Component \| void)`{lang="ts"} | `false` | 对目录中找到的每个组件调用的函数。它接受一个组件对象，并应返回一个组件对象或一个解析为组件对象的 Promise。 | | `global` | `boolean` | `false` | 启用后，将组件注册为全局可用。 | | `island` | `boolean` | `false` | 启用后，将组件注册为岛屿组件。您可以在 [``](https://nuxt.zhcndoc.com/docs/4.x/api/components/nuxt-island) 组件说明中了解有关岛屿组件的更多信息。 | | `watch` | `boolean` | `false` | 监视指定路径的更改，包括添加和删除文件。 | | `extensions` | `string[]` | `false` | Nuxt 构建器支持的扩展名。 | | `transpile` | `'auto' \| boolean`{lang="ts"} | `false` | 使用 build.transpile 转译指定路径。如果设置为 `'auto'`，且路径中包含 `node_modules/`，则会设置 `transpile: true`。 | `opts` | 属性 | 类型 | 必填 | 描述 | | --------- | --------- | ------- | ---------------------------------------------------------------- | | `prepend` | `boolean` | `false` | 如果设置为 `true`，则该目录将使用 `unshift()` 添加到数组前端，而不是使用 `push()` 添加到数组末尾。 | ## `addComponent` 注册一个组件以实现自动导入。 ### 用法 ```ts import { addComponent, createResolver, defineNuxtModule } from '@nuxt/kit' export default defineNuxtModule({ meta: { name: '@nuxt/image', configKey: 'image', }, setup () { const resolver = createResolver(import.meta.url) addComponent({ name: 'NuxtImg', filePath: resolver.resolve('./runtime/components/NuxtImg.vue'), }) addComponent({ name: 'NuxtPicture', filePath: resolver.resolve('./runtime/components/NuxtPicture.vue'), }) }, }) ``` ### 类型 ```ts function addComponent (options: AddComponentOptions): void ``` ### 参数 `options`：一个包含以下属性的对象： | 属性 | 类型 | 必填 | 描述 | | ----------------- | ------------------------------------------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | `name` | `string` | `true` | 组件名称。 | | `filePath` | `string` | `true` | 组件路径。 | | `declarationPath` | `string` | `false` | 组件声明文件的路径。用于生成组件的[类型模板](https://nuxt.zhcndoc.com/docs/4.x/api/kit/templates#addtypetemplate)；如果未提供，则使用 `filePath`。 | | `pascalName` | `string` | `false` | Pascal 命名格式的组件名称。如果未提供，将根据组件名称生成。 | | `kebabName` | `string` | `false` | kebab 命名格式的组件名称。如果未提供，将根据组件名称生成。 | | `export` | `string` | `false` | 指定命名导出或默认导出。如果未提供，则设置为 `'default'`。 | | `shortPath` | `string` | `false` | 组件的短路径。如果未提供，将根据组件路径生成。 | | `chunkName` | `string` | `false` | 组件的代码块名称。如果未提供，将根据组件名称生成。 | | `prefetch` | `boolean` | `false` | 这些属性（prefetch/preload）用于在生产环境中通过 webpack 的魔法注释配置如何处理带有 Lazy 前缀的组件。了解更多信息，请参阅 [webpack 文档](https://webpack.js.org/api/module-methods/#magic-comments) | | `preload` | `boolean` | `false` | 这些属性（prefetch/preload）用于在生产环境中通过 webpack 的魔法注释配置如何处理带有 Lazy 前缀的组件。了解更多信息，请参阅 [webpack 文档](https://webpack.js.org/api/module-methods/#magic-comments) | | `global` | `boolean` | `false` | 启用后，将组件注册为全局可用。 | | `island` | `boolean` | `false` | 启用后，将组件注册为岛屿组件。您可以在 [``](https://nuxt.zhcndoc.com/docs/4.x/api/components/nuxt-island) 组件说明中了解有关岛屿组件的更多信息。 | | `mode` | `'client' \| 'server' \| 'all'`{lang="ts"} | `false` | 此选项表示组件应在客户端、服务器端还是两端渲染。默认情况下，它会在客户端和服务器端渲染。 | | `priority` | `number` | `false` | 组件的优先级。如果多个组件具有相同的名称，则使用优先级最高的组件。 | ### 示例 如果您希望从 npm 包自动导入一个组件，并且该组件是命名导出（而不是默认导出），您可以使用 `export` 选项来指定它。 ```ts import { addComponent, defineNuxtModule } from '@nuxt/kit' export default defineNuxtModule({ setup () { // 从 'my-npm-package' 导入 { MyComponent as MyAutoImportedComponent } addComponent({ name: 'MyAutoImportedComponent', export: 'MyComponent', filePath: 'my-npm-package', }) }, }) ``` --- - [源码](https://github.com/nuxt/nuxt/blob/main/packages/kit/src/components.ts) ## Sitemap See the full [sitemap](https://nuxt.zhcndoc.com/sitemap.md) for all pages.