vite-plugin-webcomponent-style-helper

一个用于在 Web Components 中自动导入 UI 组件样式的 Vite 插件，特别针对 Element Plus 等 UI 库进行了优化。

✨ 特性

• 自动检测：自动检测 .ce.vue 文件中使用的 UI 组件
• 灵活配置：支持自定义样式路径、组件前缀、文件后缀等
• 性能优化：预编译正则表达式，提高匹配性能
• 多格式支持：支持 SCSS 和 CSS 样式文件
• 🔍 智能匹配：支持 kebab-case 和 PascalCase 组件名匹配
• 📦 命令组件：支持 ElMessage、ElMessageBox 等命令式组件
• 🌟 UnoCSS 集成：支持 UnoCSS Shadow DOM 模式
• 调试模式：提供详细的调试信息

📦 安装

# 使用 npm
npm install vite-plugin-webcomponent-style-helper

# 使用 pnpm
pnpm add vite-plugin-webcomponent-style-helper

# 使用 yarn
yarn add vite-plugin-webcomponent-style-helper

🚀 快速开始

基本用法

*** 特别注意！！！！ webComponentStyleHelper 需要在所有插件之前运行配置（因为需要在插件解析 .vue 文件之前运行） ***

// vite.config.ts
import { defineConfig } from 'vite'
import { webComponentStyleHelper } from 'vite-plugin-webcomponent-style-helper'
// 或者 都可导入
// import webComponentStyleHelper from 'vite-plugin-webcomponent-style-helper'

export default defineConfig({
  plugins: [
    webComponentStyleHelper({
      stylePathPrefix: 'element-plus/theme-chalk/src',
      UITagPrefix: 'el',
      fileSuffix: 'scss'
    })
  ]
})

在 Web Component 中使用

<!-- MyComponent.ce.vue -->
<template>
  <div>
    <el-button type="primary">点击我</el-button>
    <el-dialog v-model="visible" title="对话框">
      <p>这是一个对话框</p>
    </el-dialog>
  </div>
</template>

<script setup>
import { ref } from 'vue'

const visible = ref(false)
</script>

插件会自动检测到使用的 el-button 和 el-dialog 组件，并自动导入对应的样式文件。

• 插件处理后输出如下

<!-- MyComponent.ce.vue -->
<style lang="scss">
  @use 'element-plus/theme-chalk/src/button.scss';
  @use 'element-plus/theme-chalk/src/dialog.scss';
</style>
<template>
  <div>
    <el-button type="primary">点击我</el-button>
    <el-dialog v-model="visible" title="对话框">
      <p>这是一个对话框</p>
    </el-dialog>
  </div>
</template>

<script setup>
import { ref } from 'vue'

const visible = ref(false)
</script>

⚙️ 配置选项

| 选项 | 类型 | 默认值 | 描述 | |------|------|--------|------| | stylePathPrefix | string | 'element-plus/theme-chalk/src' | 样式文件路径前缀 | | UITagPrefix | string | 'el' | 要匹配的组件标签前缀 | | fileSuffix | 'scss' \| 'css' | 'scss' | 样式文件后缀名 | | customStyleResolver | function | - | 自定义样式文件解析器 | | debug | boolean | false | 是否启用调试模式 | | useUnocss | boolean | false | 是否启用 UnoCSS Shadow DOM 支持 | | matchRules | string \| string[] | - | 需要处理的文件，为空时只处理 .ce.vue 文件 | | commonCss | string[] | - | 需要注入的公共样式文件 注意不要携带尾随分号 例：['@use element-plus/theme-chalk/src/base.scss'] |

高级配置示例

// vite.config.ts
import { webComponentStyleHelper } from 'vite-plugin-webcomponent-style-helper'

export default defineConfig({
  plugins: [
    webComponentStyleHelper({
      // 自定义样式路径
      stylePathPrefix: 'ant-design-vue/dist',
      UITagPrefix: 'a',
      fileSuffix: 'css',
      
      // 自定义样式解析器
      customStyleResolver: (componentName, options) => {
        // 返回自定义的样式导入路径
        return `@import 'ant-design-vue/dist/${componentName}.css';`
      },
      
      // 启用调试模式
      debug: true,
      
      // 启用 UnoCSS 支持
      useUnocss: true,

      // 需要处理的文件
      matchRules: ['**/*.ce.vue']
    })
  ]
})

🎯 支持的组件格式

模板中的组件

<template>
  <!-- kebab-case 格式 -->
  <el-button>按钮</el-button>
  <el-table-column prop="name" label="姓名" />
  
  <!-- PascalCase 格式 -->
  <ElDialog v-model="visible">对话框</ElDialog>
  <ElMessage>消息</ElMessage>
</template>

脚本中的组件

<script setup>
// 导入语句中的组件
import { ElButton, ElDialog } from 'element-plus'

// 命令式组件调用
ElMessage.success('操作成功')
ElMessageBox.confirm('确定要删除吗？')
ElNotification.info('通知消息')
ElLoading.service()
</script>

自定义样式解析器

当默认的样式解析逻辑不满足需求时，可以使用自定义解析器：

webComponentStyleHelper({
  customStyleResolver: (componentName, options) => {
    // componentName: 'el-button'
    // options: 完整的插件配置对象
    
    // 返回自定义的样式导入语句
    return `@use 'custom-ui-library/styles/${componentName}.scss';`
  }
})

🌟 UnoCSS 集成

插件支持 UnoCSS 的 Shadow DOM 模式，可以自动插入 UnoCSS 占位符：

webComponentStyleHelper({
  useUnocss: true
})

这会在组件中自动添加：

<style lang="scss">
  @unocss-placeholder
</style>

🐛 调试模式

启用调试模式可以查看详细的处理信息：

webComponentStyleHelper({
  debug: true
})

调试信息包括：

• 检测到的组件列表
• 生成的样式代码
• 文件处理状态

工作原理

1. 文件检测：只处理以 .ce.vue 结尾的文件
2. 组件解析：使用 Vue SFC 解析器解析模板和脚本
3. 组件匹配：通过正则表达式匹配使用的 UI 组件
4. 样式生成：根据配置生成对应的样式导入语句
5. 代码注入：将样式代码注入到原始文件中

*** 特别注意！！！！ webComponentStyleHelper 需要在所有插件之前运行配置（因为需要在插件解析 .vue 文件之前运行） ***