# vite-plugin-vue-comp-name-route

**Repository Path**: li-hanming/vite-plugin-vue-comp-name-route

## Basic Information

- **Project Name**: vite-plugin-vue-comp-name-route
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-23
- **Last Updated**: 2025-11-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# vite-plugin-vue-comp-name-route

一个 Vite 插件，用于根据 Vue 组件的目录结构动态生成 Vue Router 路由。

## 作用

本插件通过扫描指定目录（默认为 `src/views`）下的 Vue 组件，自动生成对应的 Vue Router 路由数组。它从 Nuxt.js 的路由系统获得灵感，旨在简化路由配置。插件支持在开发和生产环境中使用，并允许通过 Vue 文件中的自定义块为路由添加元数据。

## 安装

```bash
# 使用 pnpm
pnpm add vite-plugin-vue-comp-name-route -D 

# 或使用 npm
npm i vite-plugin-vue-comp-name-route -D
```

## 使用方法

### 1. 配置 Vite 插件

在您的 `vite.config.js` 或 `vite.config.ts` 中引入并配置插件：

```javascript
// vite.config.js
import componentFilterPlugin from 'vite-plugin-vue-comp-name-route'

// 示例配置，您可以根据需要调整参数
export default defineConfig({
  plugins: [
    componentFilterPlugin({
      // 配置选项（详见下方配置说明）
      include: "./src/views/**/*.vue",
      exclude: ["**/components/**", "**/component/**", "**/*component*/**"],
      showConsole: false, // 可选：开启控制台日志
      // ... 其他配置
    })
  ]
})
```

### 2. 在路由文件中使用

在您的 Vue Router 设置文件（例如 `src/router/index.js`）中，从插件生成的虚拟模块导入自动生成的路由：

```javascript
// src/router/index.js
import { createRouter, createWebHistory } from 'vue-router'
// 从插件生成的虚拟模块导入路由
import { routeComponents } from 'virtual:filtered-route-components'

const router = createRouter({
  history: createWebHistory(),
  routes: [
    // 将自动生成的路由展开到您的路由数组中
    ...routeComponents,
    // 您也可以在此处继续添加静态路由
  ]
})

export default router
```

### 3. 标记需要生成路由的组件

在您的 Vue 单文件组件中，通过在 `<script>` 标签内添加 `isRoute` 属性来标记该组件需要被插件处理并生成对应的路由。

```vue
<!-- src/views/about.vue -->
<script setup isRoute>
// 您的组件逻辑
</script>

<template>
  <div>About Page</div>
</template>
```

## 配置选项

插件接受一个配置对象 `ComponentFilterConfig`，以下是所有可用选项：

| 选项 | 类型 | 默认值 | 描述 |
|------|------|--------|------|
| **`include`** | `string` 或 `Array<string>` | `"./src/views/**/*.vue"` | 定义插件要扫描的文件路径模式（Glob Pattern）。 |
| **`exclude`** | `string` 或 `Array<string>` | `["**/components/**", "**/component/**", "**/*component*/**"]` | 定义扫描中要排除的文件或文件夹路径模式。 |
| **`filterFn`** | `Function` | `(config) => config && config.isRoute` | 自定义的组件过滤函数。默认识别 `<script setup isRoute>` 中的 `isRoute` 属性。 |
| **`loadCompPathFn`** | `Function` | `null` | 自定义的组件路径解析函数。如果您的组件路径结构特殊，可能需要配置此项。 |
| **`customExtViewPathRegexFn`** | `Function` | `null` | 自定义路由路径（path）生成规则函数。默认根据文件目录结构生成。 |
| **`showConsole`** | `boolean` | `false` | 是否在控制台输出详细的处理日志，用于调试。 |
| **`checkKey`** | `string` | `"isRoute"` | 用于识别组件的属性键名。如果您不想用 `isRoute`，可以更改为其他字符串。 |
| **`useCache`** | `boolean` | `true` | *（预留功能）* 是否启用缓存。 |

### 配置示例

```javascript
// 详细的配置示例
componentFilterPlugin({
  include: "./src/features/**/*.vue", // 扫描 features 目录
  exclude: ["**/test/**"], // 排除 test 目录
  showConsole: true, // 开发时查看日志
  checkKey: 'isAutoRoute', // 使用自定义的标记属性
  // 高级功能：自定义路由路径生成
  customExtViewPathRegexFn: (filePath) => {
    // 您的自定义逻辑，例如将 _id 转换为动态段
    const path = filePath.replace('./src/features/', '').replace('.vue', '');
    return path.includes('_id') ? path.replace('_id', ':id') : path;
  }
})
```

## 工作原理

1.  **扫描阶段**：在 Vite 开发服务器启动或生产构建时，插件会根据 `include` 和 `exclude` 配置扫描项目目录。
2.  **过滤阶段**：对扫描到的每个 Vue 文件，使用 `filterFn`（默认检查 `isRoute` 属性）判断是否需要为其生成路由。
3.  **生成阶段**：为过滤后的组件生成导入语句和路由配置对象。
4.  **虚拟模块**：插件创建一个名为 `virtual:filtered-route-components` 的虚拟模块，导出生成的路由数组。
5.  **集成**：在您的应用代码中导入该虚拟模块，即可获得自动生成的的路由配置。

## 注意事项

*   确保您的项目已正确安装和配置 `vue-router`。
*   插件生成的路径默认基于文件结构。例如，文件 `src/views/user/profile.vue` 会生成路径 `/user/profile`。
*   使用自定义块或 `checkKey` 时，请确保语法正确。
*   如果遇到缓存问题，在开发期间可以尝试重启 Vite 开发服务器。

## 故障排查

*   **路由未生成**：检查组件是否已被正确标记（例如，设置了 `<script setup isRoute>`），并且文件路径符合 `include` 模式。
*   **控制台报错**：开启 `showConsole: true` 查看详细日志，确认插件的扫描和生成过程。
*   **路径不正确**：使用 `customExtViewPathRegexFn` 自定义路径生成逻辑。

对于更复杂的需求，请参考 https://vitejs.dev/guide/api-plugin.html 和 https://router.vuejs.org/。
```