# 开发指南

# 克隆项目

# 克隆项目
git clone http://172.16.98.176/common/ykc-ui.git
# 切换到dev分支
cd ykc-ui && git checkout dev

# 项目介绍

项目基于 vue cli 构建目标 (opens new window)，所以其本来就是一个 vue 项目。

# 目录规范

├── README.md
├── babel.config.js
├── docs
├── package.json
├── packages
├── public
├── scripts
├── src
├── tests
├── types
├── vue.config.js
└── yarn.lock

主要目录介绍

docs
该目录是基于 vuepress (opens new window)创建的，主要用来书写组件文档。
packages
该目录主要存放组件代码、共享样式、工具函数等，开发的组件应该存放于此。
public 和 src
这两个目录主要是构建应用时使用，构建库时不需要。
但在开发组件过程中，可以通过 yarn serve 启动开发服务器并在 src 目录下引用组件，即可实时调测组件，实用且方便！
scripts
主要存放了构建库的脚本、验证 git 提交信息的脚本、检测包管理工具的脚本。
tests
主要存放测试文件。
types
组件类型声明文件，在项目中开发过程中使用该组件库时，会有字段、方法等智能提示。
vue.config.js
vue 项目配置文件。
yarn.lock
包管理器 yarn 的 lock 文件，用于锁定依赖版本，减少依赖冲突等问题。

# 安装依赖

温馨提示

项目强制使用 yarn 作为包管理工具！了解详情 (opens new window)

yarn install

# 开发组件

温馨提示

如果需要在项目中联调组件，该组件库已支持。

全局安装 yalc

npm install yalc -g

发布组件库到本地

yalc publish

在业务项目中引用刚才发布的组件库

yalc add @ykc/ykc-ui

组件库启动开发服务，会自动将代码同步到业务项目中！

以开发 ykc-foo-bar 组件为例！

复制 packages/template 整个目录到 packages 目录下，并重命名为 foo-bar
编辑 package/foo-bar/src/main.vue，按照实际组件逻辑编写即可，但须注意以下几点：
- 应该把该组件配置的 name 字段写成 YkcFooBar，因为这是推荐写法 (opens new window)，更是兜底的写法！了解详情 (opens new window)
- 需要引入项目中其他文件、组件或公共代码时，推荐以下方式引入
  比如
```
// 需要引入 `packages/utils/a.js`，应该这么写
import utilA from '@ykc/ykc-ui/packages/utils/a'
// 需要引入 `Button` 组件，应该这么写，并局部注册
import YkcButton from '@ykc/ykc-ui/packages/button'
```
  打包配置做了优化。这里会被当做 externals 处理，并会自动转换到打包后的 lib 目录中的对应文件！
- 样式文件可以单独引用，也可以在 style 标签中写
如果需要使用主题颜色，有两种方式
- 主色使用 css 变量 var(--theme-color-primary)，悬停/点击效果使用 css 变量 var(--theme-color-active)
- 引入 packages/styles/var.scss 文件
```
// 在 vue.config.js 中定义了 @ykc/ykc-ui 别名，或者使用相对路径
@import '~@ykc/ykc-ui/packages/styles/var.scss'
```
  主色使用 scss 变量 $theme_primary，悬停/点击效果使用 scss 变量 $theme_active
如果需要新增字体图标，则在 iconfont (opens new window) 所在项目中上传 svg 文件后，需要更新其在线链接，并将该链接重写到 packages/icon/src/dev.css 文件中！
```
/* 修改下面的链接地址即可 */
@import 'https://at.alicdn.com/t/font_2842460_83dk7wzxw7g.css?spm=a313x.7781069.1998910419.43&file=font_2842460_83dk7wzxw7g.css';
```

特别注意

调用 DOM API 时（比如：window.addEventListener, document.createElement 等函数时），务必将这些逻辑写在 beforeMount 或者 mounted 钩子函数中！主要应对 SSR (opens new window) 场景，而组件文档使用的 vuepress 就是 SSR 的应用。

# 调试组件

执行 yarn serve 启动开发服务器后，即可在 http://localhost:9090/ (opens new window)访问页面。
在 src/demos 目录下创建 foo-bar.vue 文件，并在该文件中使用 ykc-foo-bar 组件进行调测即可。

Why

这得益于在 src/App.vue 中自动加载 src/demos 中的全部 vue 组件，并动态渲染到页面上！

# 书写组件声明

仿照项目 types 目录声明或者 element ui types 声明 (opens new window)等开源项目。

# 书写组件使用说明文档

仍然以 foo-bar 组件为例子！

添加 sidebar
编辑 docs/.vuepress/config.js，给 sidebar 字段下的 /components 字段中 title 为组件的对象的 children 字段添加一条数据 ['components/foo-bar', 'foo-bar']
添加组件说明文档
在 docs/components 目录下新建 foo-bar.md 文件，并书写组件使用说明文档
如何书写组件使用demo

参考 vuepress-plugin-demo-container (opens new window)
文档开发预览，项目根目录执行
```
yarn docs:dev
```
即可在 http://localhost:7070/ (opens new window)访问文档页面。

# 组件打包

在项目根目录执行

yarn lib

即可，打包文件将输出至 lib 目录下。

# 打包说明

打包前，会先删除 lib 目录，若要备份，可集成 jenkins 或 NPM私服 (opens new window)用版本管理实现
打包时，会自动过滤 package/styles 和 package/utils 和 package/template 目录
使用了 webpack 的 require.context 和正则表达式实现
打包后，会将 packages/styles 和 package/utils 目录复制到 lib 目录，以供外部项目使用

实现按需加载特性，需要把每个组件单独打包，并对生成的 css 和 js 文件进行了不存在则创建和重命名的操作
在项目中以按需加载的方式使用

安装 babel-plugin-import
```
yarn add babel-plugin-import -D
```
配置 babel 插件

module.exports = {
  presets: [
    [
      '@vue/cli-plugin-babel/preset',
    ]
  ],
  plugins: [
    [
      'import',
      {
        'libraryName': '@ykc/ykc-ui',
        'style': (name) => `${name}/style.css`
      }
    ]
  ]
}

引入组件

import Vue from 'vue'
import { Header } from '@ykc/ykc-ui'
Vue.use(Header)

依赖其他库，尽量把这些库作为外部依赖，即在 vue.config.js 中配置 externals 字段
由于使用了 require.context，如果按需加载不映射源码，则不需要考虑 tree shaking 问题，除非是映射源码（iview 是映射源码的实现方式）！

# 发布

注意

请勿单独自己发布包，因为会涉及版本管理
发包权限由 NPM私服 (opens new window)管理