@littlekai/x-template-ui v1.1.5

开始

安装依赖
npm i

新建一个组件，只需控制台输入相关组件信息， 会根据该信息自动创建组件相关文件
npm run gen

进行开发组件，packages 下编写代码， 并实时预览
npm run dev

进行组件库打包
npm run build:lib

组件文档打包 可部署到静态网站
npm run build:doc

更新组件信息, 自动生成组件配置文件、重新生成路由、配置等信息
npm run cfg

组件开发：

如何进行一个新的组件开发？

1 安装依赖后运行 npm run gen; 会生成组件相关文件; 以 qz-button 为例

2 在packages/QzButton/src/index.vue 编写组件代码进行开发

/* setup 写法 */
<script setup>
// index.vue
import { ElButton } from 'element-plus' // 引入的element-plus包 ElButton
</script>
<template>
    <el-button class="qz-button qz-ui-custom-component" type="primary"><slot>默认插槽</slot></el-button>
</template>

/* jsx 写法  !!! 需要修改文件名 index.vue 为 index.jsx*/
// index.jsx
import { ElInput } from 'element-plus'
export default defineComponent({
    components: {
        ElInput
    },
    setup(props, { attrs, slots, emit, expose }) {
        return () => {
            return (<ElInput />)
        }
    }
})

/* 不采用 setup */
<script>
// index.vue
import { ElDatePicker } from 'element-plus';
export default defineComponent({
    components: {
        ElDatePicker
    },
    setup(props, { attrs, slots, emit, expose }) {
        const value = ref('')
        return {
            value
        }
    }
})
</script>
<template>
    <div class="qz-date-picker qz-ui-custom-component">
        <el-date-picker  v-model="value" type="date"></el-date-picker>
    </div>
</template>

3 为了将组件样式与组件分隔开， 以及后续自定义主题样式， 需要手动导入相关样式

.qz-button.qz-ui-custom-component {
    // 在这里编写你的样式代码 直接使用在 variables.scss 文件中定义的scss变量 
}

4 实时查看效果？ 在packages/QzButton/doc 目录编写 demo.vue组件， 可编写多个demo 组件， 推荐命名以 base.demo.vue、xxx.demo.vue命名;

在 packages/QzButton/doc/README.md 引入你的 xxx.demo.vue 组件 Preview 组件包裹

<script setup>
// 在这里导入你的组件demo
import demo from './demo.vue'
import demo from './base.demo.vue'
</script>


<Preview comp-name="QzButton" demo-name="demo">
  <xxx-demo />
</Preview>

组件介绍：

目录介绍：

build
├──base.config.js         // 基础打包配置
├──doc.config.js         // 文档打包配置
├──lib.config.js         // 库打包配置
├──lib.css.js         // 样式打包配置
├──lib.disperse.js    // 组件块打包配置
dist                  // 组件打包输出目录
docs                  // 组件文档目录
packages              // 组件包目录
├── locale            // 国际化
├── shared            // 公共模块
├── utils             // 工具函数等
├── styles            // 主题样式
├── Button            // 组件
│   ├── docs
│   │   ├── README.md  // 组件文档
│   │   └── demo.vue   // 交互式预览实例
│   ├── index.js       // 模块导出文件
│   └── src
│       └── index.vue  // 组件本体
├── index.js           // 组件库导出文件
└── list.json          // 组件列表信息
play                   // 项目测试目录play
script                 // 脚本

packages/QzButton/src/index.vue

该文件是组件的本体，代码如下：

<template>
  <button class="qz-button" @click="$emit('click', $event)">
    <slot></slot>
  </button>
</template>

<script setup>
defineEmits(['click']);
</script>

packages/QzButton/index.js

为了让组件库既允许全局调用：

import { createApp } from 'vue'
import App from './app.vue'

import QzUI from 'qz-ui'

createApp(App).use(QzUI)

也允许局部调用：

import { QzButtonPlugin } from 'qz-ui'

app.use(QzButtonPlugin)

因此需要为每一个组件定义一个 VuePlugin 的引用方式。package/Button/index.js 的内容如下：

import Button from './src/index.vue';

export const ButtonPlugin = {
  install(app) {
    app.component('q-button', Button);
  },
};

export { Button };

packages/index.js

组件库本身的导出文件，它默认导出了一个 VuePlugin：

import { ButtonPlugin } from './Button';
//...其他组件

const QzUIPlugin = {
  install(app) {
    ButtonPlugin.install?.(app);
    //...其他组件
  },
};

export default QzUIPlugin;

export * from './Button';
//...其他组件

/packages/list.json

组件库的一个记述文件，用来记录里面组件的各种说明：

[
  {
    "compName": "QzButton",
    "compType": "{ \"type\": \"Basic\", \"desc\": \"基础\" }",
    "compZhName": "按钮",
    "compDesc": "这是按钮描述",
    "compAuthor": "xks",
    "compClassName": "qz-button"
  }
]

使用

全局使用

import { createApp } from 'vue'
import App from './App.vue'

import QzUI from 'qz-ui';
import 'qz-ui/dist/style.css';

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

在项目中按需使用

import { QzButton } from 'qz-ui/dist/packages/es/QzButton'; // 或者 import { QzButton } from 'qz-ui';
import 'qz-ui/dist/packages/QzButton/index.scss';

主题定制

qz-ui 使用 scss 定义了一套默认样式变量 default.scss, 定制主题就是编辑这个变量列表配置文件 variables.scss;

第一步：

import 'element-plus/theme-chalk/src/index.scss'; // 依赖element-plus包组件样式 mian.js
// 全局使用时 需要引入themes/index.scss 的scss文件 而不能使用已编译的style.css文件
import QzUI from 'qz-ui';
import 'qz-ui/dist/packages/styles/themes/index.scss' // import 'QzUI/dist/style.css';

// 局部使用时 需要引入themes/index.scss 的scss文件 而不能使用已编译的style.css文件
import { QzButton } from 'qz-ui/dist/packages/es/QzButton';
// 或者 import { QzButton } from 'qz-ui';
import 'qz-ui/dist/packages/QzButton/index.scss';
// import 'qz-ui/dist/styles/themes/index.scss' // 所有样式

第二步：

项目中新建 vars.scss 文件, vite.config.js中配置该用户自定义的scss变量文件

// 项目中主题自定义样式 修改主题 可覆盖 qi-ui 样式变量
$bg: #fff;
$c: blue;
$base: #130909;

// 在此修改element-plus 主题
@forward 'element-plus/theme-chalk/src/common/var.scss' with (
  $colors: (
    'primary': (
      'base': $base,
    ),
  ),
);

// vite.config.js
export default defineConfig({
    // 其他配置
    css: {
        preprocessorOptions: {
            scss: {
                additionalData: `@use "xxxxxx/vars.scss" as *;`
            }
        }
    }
})

// webpack 配置
{
    test: /\.(sa|sc)ss$/,
    use: [
        {
            loader: 'sass-loader',
            options: {
                data:  `@import "xxxxxx/vars.scss";`,
            }
        }
    ]
}

使用css变量

在variables.scss 中编写css 变量，在组件的index.scss中直接var(--qz-color-xxx)使用

具体方法查看头部(src/App.vue中useVarCss)

国际化

组件中使用国际化参考 QzButton/doc/demo.vue

按照Element Plus 提供的即可

<template>
  <el-config-provider :locale="locale">
    <app />
  </el-config-provider>
</template>

<script>
  import { defineComponent } from 'vue'
  import { ElConfigProvider } from 'element-plus'

  import zhCn from 'element-plus/lib/locale/lang/zh-cn'

  export default defineComponent({
    components: {
      ElConfigProvider,
    },
    setup() {
      return {
        locale: zhCn,
      }
    },
  })
</script>