adui

开始使用

---

使用 Package

adui 已经发布于 NPM。你可以通过你的包管理器安装（比如 Yarn）：

yarn add adui react react-dom

adui 目前依赖的 react 与 react-dom 版本为 16.13.1。adui 1.0 使用了 Hooks 书写组件，请保证你的 React 版本 ^16.8。

---

Import

引入你所需要的 React 组件。

import { Button } from "adui"

<Button intent="primary">开始使用<Button/>

你不需要独立地引入样式，因为每个组件都会 import 自己的 .css 文件。你只需要保证 webpack 的 css-loader 能够作用到 node_modules/adui 这个文件夹，就能保证样式的正确。

未来会加入不需要依赖 webpack 配置的编译版本，届时 CSS 文件会完全与 JS 文件分离。

---

主题色

adui 使用了 CSS Variables 实现变量配置。同时配合 css-vars-ponyfill 解决兼容性问题。
在引入之后，你的页面上就会有如下的样式：

:root {
  --primary-color: #07c160;
}

你可以用更高优先级的 CSS 规则覆盖：

html:root { --primary-color: #00bb9c; }

adui 还设置了许多其他变量比如 --gray-50 至 --gray-900，但请不要去修改这些变量。

---

兼容性

Browsers support

|
IE / Edge |
Firefox |
Chrome |
Safari |
Opera | | --------- | --------- | --------- | --------- | --------- | --------- | --------- | | Edge| last 2 versions| last 2 versions| last 2 versions| last 2 versions

---

关于组件类型

adui 1.0 一部分组件以 Function Component + Hooks 实现。 现在，组件一共有 类组件（Class Component），函数组件（Function Component），以及也属于函数组件的ForwardRef Component这三种。

关于内部驱动与外部控制

adui 所有包含状态的组件都有两种设计，即 内部驱动（uncontrolled） 与 外部控制（controlled）。

代表内部驱动的 Prop 是 defaultValue，代表外部控制的 Prop 是 value。比如 <Switch /> 组件的 defaultChecked 与 checked。

defaultChecked 只在第一次渲染（constructor）时生效，之后的状态变化都会完全交给组件自身完成；
而 checked 则代表如果不从外部改变，那么组件的状态就不会变化（代码上由生命周期 getDerivedStateFromProps 实现的）。

这样设计的原理来源于 React 对表单的 Controlled/Uncontrolled 的概念。请阅读学习，并且按照需求选择这两种模式使用。

如果你只是需要设置一个初始值，并且只想要关心这个值的改变情况，比如 <Switch defaultChecked onChange={xxx} />，这样你就不需要单独地设置一个 state 保证组件 UI 状态的完整； 如果你想要存储这个变化的值，并且之后会用这个值回传给 <Switch />，那么你需要自己存储这个 state <Switch checked={xxx} onChange={xxx} />。

---

*Git Submodule

Package 是推荐的使用方式。我们会在每 1 - 2 周进行日常的修订版本号更新。主版本与次版本号的发布不在发布周期内。你可以在 更新日志 中查看具体发布信息。

如果在需要更新时，你不想更新 Package 的版本，而是随时跟进 origin/master 分支的最新代码，你可以选择使用 Git Submodule。它允许你将 adui 添加到你的 Git 仓库子目录内。同时，adui 的提交与你的项目是独立的。因此，这也是解决项目间依赖的一种方法。

添加 Submodule

$ git submodule add http://git.code.oa.com/yijiejiang/adUI.git adui

这样，你的项目中就会新增 ".gitmodules" 文件与 "adui" 文件夹。

配置 Submodule

注意：

• Submodule 使用的路径是 adui/lib；
• 请确保针对 "adui" 文件夹配置了 webpack 的 css-loader。我们推荐的 loader 配置是：

  {
    test: /\.css$/,
    include: "path/to/adui/",
    loaders: ["style-loader", "css-loader"]
  }
  

• 你还需要安装 adui 自身的 dependencies，一种方法是使用 yarn workspace，yarn workspace 就是为了解决多项目依赖安装的问题，你只需要在主项目的 package.json 中：

  {
    "private": true,
    "workspaces": ["adui"]
  }
  

  这样在执行 yarn 时就会同时安装 adui 的依赖了。

使用 Submodule

推荐通过 webpack 的 resolve 配置 alias 存储相对路径：

resolve: {
  alias: {
    aduiPath: path.resolve(__dirname, 'adui/lib/'),
  }
}

这样，引入时也简便了很多：

// import { Button } from "path/to/adui/lib"
import { Button } from "aduiPath"

<Button intent="primary">开始使用<Button/>

另外，为了让你的 IDE 能够识别 alias，并且给出 TypeScript 自动提示，请在你的 tsconfig.json 中配置：

{
  "compilerOptions": {
    "paths": {
      "aduiPath": ["path/to/adui/lib/"]
    }
  },
}
 

综上所述，Git Submodule 除了敏捷开发的优点以外，非常麻烦。请尽量不要使用。

⌨️ 本地开发说明

adUI 的开发任务：

1. 建立 adUI 站点和组件文档；
2. 书写 components 代码；
3. 测试；
4. 编译与发布。

IDE 相关

Vscode 插件需要：ESlint + styleint。

建立 adUI 站点和组件文档

adUI 的文档生成工具是 bisheng。

文档发布命令 npm run site，现在没有将此 repo 与 github page 关联，采用手动复制到 github 项目中发布。

书写 components 代码

以 button 为例：

button
│   index.tsx                   组件出口    
│   Button.tsx                  组件文件
└───__tests__                   enzyme + jest 单元测试
│   │   ...
└───demo
│   │   basic.md                md 会被 bisheng 解析，可在 md 中定义 order/title，以及书写 jsx 代码
│   │   others.md               
└───style
    │   index.scss              scss 出口
    │   _button.scss            组件样式

组件的书写规范由以下方面限制

1. .tsx - eslint
2. .scss - stylelint
3. 为了方便组件文档的建立（如 API 表格），使用了 react-docgen 读取组件源代码。因此，组件必须有一句 title，以及每一个 prop 必须有文字说明。

export interface IButtonProps {
  /**
  * 类型
  */
  intent?: "normal" | "primary" | "success" | "warning" | "danger"
}
...
Button.propTypes = {
  /**
  * 类型
  */
  intent: PropTypes.oneOf([
    "normal",
    "primary",
    "success",
    "warning",
    "danger",
  ]),
}

react-docgen 实际读取 tsType，所以可以说 prop-types 也并没有实际的用处了。保留 prop-types 库是为了保留这种偏原生的实现。在组件的不断更新迭代下，这让我更有安全感。

内部驱动与外部控制

Class Component 会使用 getDerivedStatesFromProp 生命周期实现，在 FC 中，我们直接在 render 中判断：

  // 相当于生命周期 getDerivedStateFromProps
  if (checkedProp !== null && checked !== checkedProp) {
    setChecked(!!checkedProp)
  }

测试

enzyme + jest 书写测试用例。正在学习。 关于测试：

1. 必须包含：最基本的快照 expect(<Button />).toMatchSnapshot()；
2. 必须包含：对内部驱动（defaultValue）和外部控制（value）的功能测试；
3. npm run test 是跑全部测试，并生成 coverage，本地查看：adUI/coverage/lcov-report/index.html，请尽力提高 statements 的覆盖率；
4. 跑单一组件测试，如jest components/button，请确保全局安装了 jest。

编译与发布

npm run compile 编译版本，每次修改提交到 master，因为 mpweb 的使用方式是 submodule

发布与 Changelog 使用 standard-version。

多人维护

1. 透明的开发：前期的开发模式仍待规范，我自己都重复 refactor 过几次；
2. Pull Request Review：为了更好地进行 review，需要将 jest snapshot 一并 request。

分支名称规范

待规范

提交规范

提交规范现在使用了 commitlint + husky 自动在 git pre-commit hook 时检测。同样在这时候会执行 stylelint 和 eslint。

未来会使用 commitlint 做自动化 changelog。此处感谢 charlieyin 推荐此工具。

现在推荐的 commit 示例：

新组件、功能（feature）

feat(Button): 添加 focus prop。

修复（bugfix）

fix(Button): 修复 focus 问题。

重构，无 feature & bugfix

refactor(Button): 调整 scss 结构。

文档相关

docs(Button): 添加 demo。

测试相关

test(Button): 添加快照。