npm package: @littlekai/x-template-ui
Description: ```bash 安装依赖 npm i
Latest version: 1.1.5

## 开始
```bash
安装依赖
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 编写组件代码进行开发  

```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
/* 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 />)
        }
    }
})

```


```vue
/* 不采用 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 为了将组件样式与组件分隔开， 以及后续自定义主题样式， 需要手动导入相关样式

```scss
.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 组件包裹

```html
<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>

```

## 组件介绍：

#### 目录介绍：

```bash
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`

该文件是组件的本体，代码如下：

```html
<template>
  <button class="qz-button" @click="$emit('click', $event)">
    <slot></slot>
  </button>
</template>

<script setup>
defineEmits(['click']);
</script>

```

---

`packages/QzButton/index.js`

为了让组件库既允许全局调用：
```js
import { createApp } from 'vue'
import App from './app.vue'

import QzUI from 'qz-ui'

createApp(App).use(QzUI)

```

也允许局部调用：

```js
import { QzButtonPlugin } from 'qz-ui'

app.use(QzButtonPlugin)
```

因此需要为每一个组件定义一个 `VuePlugin` 的引用方式。`package/Button/index.js` 的内容如下：

```js
import Button from './src/index.vue';

export const ButtonPlugin = {
  install(app) {
    app.component('q-button', Button);
  },
};

export { Button };
```

---

 `packages/index.js`

组件库本身的导出文件，它默认导出了一个 `VuePlugin`：

```js
import { ButtonPlugin } from './Button';
//...其他组件

const QzUIPlugin = {
  install(app) {
    ButtonPlugin.install?.(app);
    //...其他组件
  },
};

export default QzUIPlugin;

export * from './Button';
//...其他组件
```

---

`/packages/list.json`

组件库的一个记述文件，用来记录里面组件的各种说明：

```json
[
  {
    "compName": "QzButton",
    "compType": "{ \"type\": \"Basic\", \"desc\": \"基础\" }",
    "compZhName": "按钮",
    "compDesc": "这是按钮描述",
    "compAuthor": "xks",
    "compClassName": "qz-button"
  }
]
```

---
## 使用
全局使用
```js
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')

```

在项目中按需使用
```js
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; 

##### 第一步：
```js
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';
``` 
```js
// 局部使用时 需要引入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变量文件

```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,
    ),
  ),
);

```


```js
// vite.config.js
export default defineConfig({
    // 其他配置
    css: {
        preprocessorOptions: {
            scss: {
                additionalData: `@use "xxxxxx/vars.scss" as *;`
            }
        }
    }
})
```

```js
// 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 提供的即可
```js
<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>

```