hlxb-ui

智慧运营管控平台

• 参考 vue 规范 (Angular)

  • feat 增加新功能
  • fix 修复问题/BUG
  • style 代码风格相关无影响运行结果的
  • perf 优化/性能提升
  • refactor 重构
  • revert 撤销修改
  • test 测试相关
  • docs 文档/注释
  • chore 依赖更新/脚手架配置修改等
  • workflow 工作流改进
  • ci 持续集成
  • types 类型定义文件更改
  • wip 开发中

调试模式切换

# 显示当前模式并进入交互选择
pnpm switch-mode

# 直接切换到调试模式
pnpm mode:debug

# 直接切换到生产模式
pnpm mode:prod

# 显示帮助信息
pnpm mode:help

组件名称

• 组件命名和导出统一前缀为 Hlxb

• 示例 button 组件：

  <script lang="ts" setup>
    // 组件命名
    defineOptions({ name: 'HlxbButton' });
  </script>
  

  // button/index.ts
  import hlxbButton from './button.vue';
  import { withInstall } from '../utils';
  const HlxbButton = withInstall(hlxbButton);
  // 组件导出
  export default HlxbButton;
  // 或
  export { HlxbButton };
  

样式文件位置

• 自动样式导入插件支持以下样式文件位置（按优先级排序）：
  • components/[组件名]/index.less - 单文件样式
  • components/[组件名]/style/index.less - 标准样式目录
  • components/[组件名]/src/index.less - src 目录样式
  • components/[组件名]/src/style/index.less - src 样式目录
  • components/[组件名]/src/[子组件]/style/index.less - 多层嵌套组件样式

支持的组件结构

插件支持多层嵌套的组件结构：

components/
├── button/                    # 单层组件
│   └── style/index.less
├── card/                      # 单层组件
│   └── style/index.less
└── card-component/            # 多层组件
    └── src/
        ├── basicComponents/   # 子组件层
        │   └── style/index.less
        └── combinationCards/  # 子组件层
            └── style/index.less

完整引入

import { createApp } from 'vue';
import HlxbUI from 'hlxb-ui';
import 'hlxb-ui/style.css';
import App from './App.vue';

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

🎨 样式自动导入 (推荐)

使用 HlxbUIStyleImport 插件自动导入组件样式，无需手动引入 CSS 文件。

✨ 核心功能

• 智能依赖分析：自动分析组件间依赖关系，确保样式完整
• 按需导入：只导入实际使用的组件样式
• 多层嵌套支持：支持复杂的组件结构
• 自动维护：新增组件时自动更新映射

在 Vite 中使用

// vite.config.ts
import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';
import { HlxbUIStyleImport } from 'hlxb-ui/resolver';

export default defineConfig({
  plugins: [
    vue(),
    HlxbUIStyleImport({
      importStyle: true, // 默认为 true
    }),
  ],
});

插件配置选项

interface HlxbUIStyleImportOptions {
  /**
   * 是否启用样式自动导入
   * @default true
   */
  importStyle?: boolean;
  /**
   * 自定义样式路径解析函数
   */
  resolveStyle?: (name: string) => string | string[] | undefined;
}

自定义样式路径

HlxbUIStyleImport({
  importStyle: true,
  resolveStyle: (name) => {
    // 自定义样式路径
    if (name === 'HlxbButton') {
      return 'path/to/custom/button.css';
    }
    // 返回 undefined 使用默认路径
    return undefined;
  },
});

按需引入（手动方式）

import { HlxbButton, HlxbInput } from 'hlxb-ui';

// 手动引入样式（不推荐，建议使用自动导入插件）
import 'hlxb-ui/es/button/style/index.css';
import 'hlxb-ui/es/input/style/index.css';

📖 组件使用示例

复杂组件深层依赖

以 HlxbTabsTableCard 为例，展示插件如何处理复杂的深层依赖：

<template>
  <HlxbTabsTableCard title="数据表格" :dataSource="tableData" :loading="loading" />
</template>

<script setup lang="ts">
  import { ref } from 'vue';
  import { HlxbTabsTableCard } from 'hlxb-ui';

  /*
   * 插件会自动导入所有依赖的样式文件：
   * - hlxb-ui/card-component/combinationCards/style/index.css (主组件)
   * - hlxb-ui/card/style/index.css (HlxbTabsCard 依赖)
   * - hlxb-ui/card-component/basicComponents/style/index.css (HlxbCardLoading 依赖)
   * - hlxb-ui/table/style/index.css (HlxbTable 依赖)
   * - hlxb-ui/empty/style/index.css (HlxbEmpty 依赖)
   * 以及这些组件的递归依赖样式
   */

  const tableData = ref([]);
  const loading = ref(false);
</script>

工作原理

插件通过静态分析组件文件中的 import 语句，自动识别依赖关系并导入对应样式。支持相对路径导入、具名导入等多种方式，使用递归算法确保深层依赖样式的完整导入。

维护说明

当添加新组件时，系统会在 Git 提交时自动检查组件映射。

手动更新命令：

# 检查映射状态
pnpm run check:resolver

# 更新组件映射
pnpm run sync:resolver