@zippybee/plugin-component-name

一个为 Vue3 组件自动注入组件名称的 Vite 插件。

功能特性

✨ 自动组件命名 - 根据文件路径自动生成组件名称 🎯 智能路由识别 - 只处理符合规则的路由组件 🔧 灵活配置 - 支持自定义命名规则和路径匹配 🚀 多框架支持 - 支持 Vue 3 (<script setup>) 和 React (JSX/TSX) 💾 缓存优化 - 内置命名转换缓存，提升性能

项目结构

zippybee-plugin-comname/
├── package.json          # 项目配置和依赖
├── tsconfig.json         # TypeScript 编译配置
├── src/
│   ├── index.ts         # 插件主入口，导出 Vite 插件
│   └── tool.ts          # 工具函数和类型定义
└── README.md            # 项目文档

安装

npm install @zippybee/plugin-component-name -D

快速开始

基础使用

在 vite.config.ts 中引入插件：

import { defineConfig } from "vite";
import vue from "@vitejs/plugin-vue";
import { zippyInjectComponetName } from "@zippybee/plugin-component-name";

export default defineConfig({
  plugins: [
    zippyInjectComponetName({
      VIEW_PATH_PATTERN: /src\/views\/(.+\.(vue|tsx|jsx))$/,
      PATH_SEPARATOR: "/",
      MIN_DEPTH: 2,
      MAX_DEPTH: 5,
    }),
    vue(),
  ],
});

自定义命名规则

如果需要自定义组件名称生成逻辑，可以传入 getName 函数：

zippyInjectComponetName({
  VIEW_PATH_PATTERN: /src\/views\/(.+\.(vue|tsx|jsx))$/,
  PATH_SEPARATOR: "/",
  MIN_DEPTH: 2,
  MAX_DEPTH: 5,
  getName: (match, id) => {
    // 自定义命名逻辑
    const fullPath = match[1];
    return customNameGenerator(fullPath);
  },
});

API 文档

zippyInjectComponetName(options: AutoNameOptions): Plugin

创建 Vite 插件实例。

参数：

• options - 插件配置选项

返回值： Vite Plugin 对象

配置选项

AutoNameOptions 接口

继承自 RouteOption，扩展字段：

interface AutoNameOptions extends RouteOption {
  getName?: (match: RegExpMatchArray, id: string) => string;
}

RouteOption 接口

interface RouteOption {
  // 用于匹配视图文件的正则表达式
  VIEW_PATH_PATTERN: RegExp;

  // 路径分隔符（通常为 '/' 或 '\\'）
  PATH_SEPARATOR: string;

  // 最小路径深度
  MIN_DEPTH: number;

  // 最大路径深度
  MAX_DEPTH: number;
}

核心原理

命名策略

插件通过以下逻辑生成组件名称：

1. 路径匹配 - 使用正则表达式匹配视图文件路径
2. 深度校验 - 检查路径深度是否在 MIN_DEPTH 和 MAX_DEPTH 范围内
3. 文件夹和文件名匹配 - 仅当文件夹名和文件名相同时生成名称
4. PascalCase 转换 - 将路由路径转换为 PascalCase 命名

示例：

/src/views/user/profile/profile.vue
→ 路由路径: /user/profile
→ 组件名称: UserProfile

支持的组件格式

Vue 3 (<script setup>)

如果组件中已存在 defineOptions，插件会在其中注入 name 属性：

<script setup>
defineOptions({
  name: "UserProfile",
});
</script>

如果不存在 defineOptions，插件会自动添加：

<script setup>
// ... 组件代码

defineOptions({ name: "UserProfile" });
</script>

Vue 3 (defineComponent)

插件会在 defineComponent 的配置对象中注入 name：

defineComponent({
  name: "UserProfile",
  // ... 其他配置
});

(JSX/TSX)

插件会在 defineComponent 中注入 name 属性：

const UserProfile = defineComponent({
  name: "UserProfile",
  // ... 其他配置
});

实现细节

注释处理

插件智能识别和跳过注释行，确保不会意外修改被注释的代码：

// 这一行会被跳过
// name: 'OldName'

name: "NewName"; // 这一行会被修改

性能优化

• 缓存机制 - PascalCase 转换结果被缓存，避免重复计算
• 预处理优先 - 设置 enforce: 'pre' 确保在其他插件之前运行

开发

构建

npm run build

编译后的文件输出到 dist/ 目录。

项目配置

• TypeScript 版本: 5.9.3
• Vite 版本: 7.2.2+
• Node 版本: 根据 TypeScript 和 Vite 的要求
• 模块格式: EsModule

许可证

ISC

相关资源

• Vite 插件文档
• Vue 3 defineOptions
• Vue 3 defineComponent