@hd-front-end/element-plus

@hd-front-end 组件体系 🚀

一个基于 Vue 3 的企业级组件与主题系统，提供组件聚合包 @hd-front-end/element-plus 与主题包 @hd-front-end/theme-chalk，支持 Design Token 驱动的主题定制与明暗模式切换。

特性 ✨

• 组件聚合与按需引入，覆盖常用企业级场景
• Token 驱动主题：统一色盘、字号、圆角等设计刻度
• CSS 变量映射 Element Plus，运行时可切换 Light/Dark
• 完整的工程化规范：TypeScript 严格模式、ESLint/Prettier

环境要求 🔧

• Node.js >= 20（建议 nvm use 20）
• pnpm 9.5.0
• Vue ^3.2.37、TypeScript ~5.5.4

安装 📦

pnpm install

在独立项目中使用聚合安装包：

pnpm add @hd-front-end/element-plus

快速开始 🏁

入口文件示例（全量安装 + 全局样式）：

import { createApp } from 'vue'
import App from './App.vue'
import HD from '@hd-front-end/element-plus'

// 组件样式
import '@hd-front-end/element-plus/theme-chalk/index.css'

// 主题 CSS 变量（Light/Dark）覆盖
// 推荐使用新包路径：
import '@hd-front-end/element-plus/theme-chalk/src/hd.scss'

const app = createApp(App)
app.use(HD)
app.mount('#app')

明暗模式切换 🌗

主题文件已在 :root/html.dark 上设置变量。切换方式：

// 切换暗色
document.documentElement.classList.add('dark')
// 切换回浅色
document.documentElement.classList.remove('dark')

示例（在组件中维护开关）：

import { ref, watch, onMounted } from 'vue'

const isDark = ref(false)

const applyDark = (v: boolean) => {
  const el = document.documentElement
  v ? el.classList.add('dark') : el.classList.remove('dark')
}

onMounted(() => {
  const m = window.matchMedia('(prefers-color-scheme: dark)')
  isDark.value = m.matches || document.documentElement.classList.contains('dark')
  applyDark(isDark.value)
})

watch(isDark, (v) => applyDark(v))

样式层建议使用 CSS 变量以支持运行时切换：

.container {
  background-color: var(--el-bg-color);
  color: var(--el-text-color-primary);
}

使用 Design Token（Sass 变量） 🎨

Sass 变量在编译期生效，需要在样式中显式引入：

// 推荐使用新包路径：
@use '@hd-front-end/theme-chalk/src/token.scss' as *;

.btn {
  background-color: $primary-1;
}

若希望所有 .vue 的 <style lang="scss"> 自动具备 Token，可在构建工具中全局预置：

// vite.config.ts
export default {
  css: {
    preprocessorOptions: {
      scss: {
        additionalData: `
          @use '@hd-front-end/theme-chalk/src/token.scss' as *;
        `
      }
    }
  }
}

按需自动引入（Vite） ⚡️

推荐使用 unplugin-vue-components：

// vite.config.ts
import Components from 'unplugin-vue-components/vite'

export default {
  plugins: [
    Components({
      dts: resolve(__dirname, 'src/components.d.ts'),
      resolvers: [
        (name: string) => {
          if (name.startsWith('El')) {
            return { name, from: '@hd-front-end/element-plus' }
          }
        }
      ]
    })
  ]
}

常见问题 ❓

• 为什么在样式里直接用 $primary-1 报错？
  • 需要在样式块中 @use '@hd-front-end/theme-chalk/src/token.scss' 引入，或使用上面的 additionalData 全局预置。
• 我应该用 CSS 变量还是 Sass 变量？
  • 运行时会切换/响应暗色：用 var(--el-*)（CSS 变量）。
  • 编译期常量（色盘、间距、字号）：用 $...（Sass 变量）。

开发与预览 🧪

pnpm run dev

本地示例位于 packages/hd-front-end/play，启动后可在浏览器中预览主题与组件效果。

许可证 📄

MIT