@qingmingmu/components

青冥组件系统（Qingming Component System）

面向 Electron 桌面端管理型/工具型应用的 Vue3 组件库。核心定位：

• 自由度高：组件行为与样式解耦，支持无样式模式（unstyled）与全量定制
• 可定制化：ConfigProvider 全局配置 + 组件级覆盖 + 命名空间
• 主题系统：CSS Variables 运行时主题，支持亮/暗/跟随系统
• Electron 友好：CSP 合规样式方案、frameless 支持、系统主题桥接
• 按需引入：官方 resolver + 原生 tree-shaking

安装

# pnpm（推荐）
pnpm add @qingmingmu/components @qingmingmu/theme

# npm
npm install @qingmingmu/components @qingmingmu/theme

# yarn
yarn add @qingmingmu/components @qingmingmu/theme

@qingmingmu/theme 提供 CSS 变量主题产物，必须单独引入。vue >= 3.3.0 为 peerDependency。

使用

全量引入

import Qingming from '@qingmingmu/components'
// main.ts
import { createApp } from 'vue'
import App from './App.vue'
import '@qingmingmu/theme/theme/light.css' // 亮色主题
import '@qingmingmu/theme/theme/css-vars.css' // 组件 Token
import '@qingmingmu/theme/theme/dark.css' // 暗色主题（可选）

createApp(App).use(Qingming).mount('#app')

<template>
  <qm-button type="primary">
    主要按钮
  </qm-button>
</template>

按需引入（推荐）

pnpm add -D unplugin-vue-components unplugin-auto-import @qingmingmu/resolver

import { QingmingResolver } from '@qingmingmu/resolver'
import vue from '@vitejs/plugin-vue'
import AutoImport from 'unplugin-auto-import/vite'
import Components from 'unplugin-vue-components/vite'
// vite.config.ts
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [
    vue(),
    Components({
      resolvers: [QingmingResolver()],
    }),
    AutoImport({
      resolvers: [QingmingResolver()],
    }),
  ],
})

<template>
  <!-- 无需手动 import，自动按需注册 -->
  <qm-button type="primary">
    主要按钮
  </qm-button>
</template>

主题切换

import '@qingmingmu/theme/theme/light.css'
import '@qingmingmu/theme/theme/css-vars.css'
import '@qingmingmu/theme/theme/dark.css'

// 切换暗色
document.documentElement.dataset.theme = 'dark'
// 切换亮色
document.documentElement.dataset.theme = 'light'

开发（贡献者）

pnpm install
pnpm dev          # 启动 play 开发沙箱
pnpm typecheck    # 类型检查
pnpm lint         # ESLint + Stylelint
pnpm test         # 单元测试
pnpm build        # 全子包构建

文档

架构与任务文档见 docs/index.md（唯一入口）。

目录结构

packages/
  components/   组件库（Button/Dialog/Select...）
  theme/        主题系统（CSS 变量 Token + 亮/暗主题）
  hooks/        可复用组合式函数（useTheme/useSystemTheme...）
  utils/        纯函数工具集
  icons/        SVG 图标集
  resolver/     按需引入 resolver（unplugin-vue-components）
play/           开发沙箱（alias 直引源码）
internal/build  构建编排
scripts/        产物验证脚本
docs/           架构与任务文档

技术栈

pnpm workspace · TypeScript strict · unbuild · changesets · VitePress（文档站）· Vitest · Playwright · CSS Variables · SVG 图标