# @hd-front-end 组件体系 🚀

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

![Node](https://img.shields.io/badge/node-%3E%3D20-brightgreen)
![pnpm](https://img.shields.io/badge/pnpm-9.5.0-orange)
![Vue](https://img.shields.io/badge/Vue-%5E3.2.37-4FC08D)
![TypeScript](https://img.shields.io/badge/TypeScript-~5.5.4-3178C6)
![ESLint](https://img.shields.io/badge/ESLint-%5E8.57.1-4B32C3)

## 特性 ✨

- 组件聚合与按需引入，覆盖常用企业级场景
- 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`

## 安装 📦

```bash
pnpm install
```

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

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

## 快速开始 🏁

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

```ts
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` 上设置变量。切换方式：

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

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

```ts
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 变量以支持运行时切换：

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

## 使用 Design Token（Sass 变量） 🎨

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

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

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

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

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

## 按需自动引入（Vite） ⚡️

推荐使用 `unplugin-vue-components`：

```ts
// 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 变量）。

## 开发与预览 🧪

```bash
pnpm run dev
```

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

## 许可证 📄

MIT