构建组件库

开始之前

构建一个组件库需要考虑哪些问题

• 代码结构
• 样式解决方案
• 组件需求分析和编码
• 自建测试用例分析和编码
• 代码的打包和发布
• CI/CD，文档生成

创建组件库的色彩体系

色彩两大体系：

系统色板：

• 符合Vision的各种颜色
• 中性色板：黑白灰三色

产品色板：

• 一到两个主要色彩（品牌色/primary color）
• 一到两个次要颜色（secondary color）
• 一系列功能色

组件库样式变量分类

• 基础色彩系统
  • 基本色彩
  • 功能色彩
• 字体系统
  • Font Family
  • Font Size
  • Font Weight
  • Line Height
  • Header Size
  • Link
  • Body
• 表单
• 按钮
• 边框和阴影
• 可配置开关

如何编写组件测试

jest——JavaScript通用测试库

jest会自动将以下三类文件视为测试文件：

• __tests__ 文件夹中的.js后缀文件
• .test.js后缀的文件
• .spec.js后缀的文件

jest断言案例

test('test common matcher', ()=>{
  expect(2 + 2).toBe(4)
  expect(2 + 2).not.toBe(5)
})

test('test to be true or false', function () {
  expect(1).toBeTruthy()
  expect(0).toBeFalsy()
})

test('test object', function () {
  expect({name: 'llr'}).toEqual({name: 'llr'})
})

React目前推荐的测试框架——@testing-library/react

作为React组件测试框架的后起之秀，@testing-library/react已经被create-react-app内置在生成的项目中了

@testing-library/jest-dom同样被内置在CRA生成的项目中，不同于jest普通的断言，它提供了一系列方便的DOM断言，比如：toBeEmpty, toHaveClass, toContainHTML, toContainElement...

组件单元测试，测什么？

1. 测试能不能保持正常行为，比如Button组件能work as a button，可以添加onClick事件监听等
2. 测试渲染的结果是不是期望的HTML元素：tagName === BUTTON ？
3. 测试样式属性——根据属性值的不同，能不能得到相应的className（样式是否被正确添加）
4. 测试特殊属性的的作用：disable or 改变HTML类型的属性能否达成期望

Button组件的编写

Button类型：

• primary
• default
• danger
• link button & icon button

// 使用enum管理按钮的类型
export enum ButtonType {
    Primary = "primary",
    Default = "default",
    Danger = "danger",
    Link = "link",
}

Button大小：

• normal
• small
• large

// 使用enum管理按钮的大小
export enum ButtonSiz {
    Large = "lg",
    Small = "sm",
}

Button状态

• disable

// 不同的按钮类型，disable的表现是不一样的，button标签自带diabled属性，a标签没有disabled属性
    const classes = classNames('btn', className, {
        [`btn-${btnType}`]: btnType,
        [`btn-${size}`]: size,
        'disabled': (btnType === ButtonType.Link) && disable
    })
    if (btnType === ButtonType.Link && href) {
        return <a 
            className={classes}
            href={href}
            {...restProps}
        >{children}</a>
    } else {
        return <button 
            className={classes}
            disabled={disable}
            {...restProps}
        >{children}</button>
    }

Button组件的属性

自定义属性

interface BaseButtonProps {
    className?: string;
    disable?: boolean;
    href?: string;
    size?: ButtonSiz;
    btnType?: ButtonType;
    children: React.ReactNode;
}

内置的属性，如常见的onClick方法

button标签：React.ButtonHTMLAttributes<HTMLElement>
a标签：React.AnchorHTMLAttributes<HTMLElement>

使用ts类型别名定义交叉类型

// 最终Button标签的类型为ButtonProps，使用Partial interface包裹是将类型属性都设置为可选参数
type NativeButtonProps = BaseButtonProps & React.ButtonHTMLAttributes<HTMLElement>
type AnchorButtonProps = BaseButtonProps & React.AnchorHTMLAttributes<HTMLElement>
export type ButtonProps = Partial<NativeButtonProps & AnchorButtonProps>

Partial的作用

假设我们有一个定义 user 的接口：

interface IUser {
  name: string
  age: number
}

经过 Partial 类型转化后得到：

type optional = Partial<IUser>

// optional的结果如下
type optional = {
    name?: string | undefined;
    age?: number | undefined;
}

Button组件的测试

测试用例设计：

• should render the default button
• should render the correct HTML tag with correct className when render Button given btnType is Primary, size is Large, additional class is klass
• should render disabled button when render Button given disabled attribute true
• should render a link when render Button given btnType is link and href is provided
• should render a disabled link when render Button given btnType is link and href is provided and disabled attribute true

Menu组件

Menu组件语义分析（伪代码）：

<Menu defaultIndex={0} onSelect={} mode="vertical">
  <Menu.Item>
    title one
  </Menu.Item>
  <Menu.Item disabled>
    disabled menu item
  </Menu.Item>
  <Menu.Item>
    <a href="#">Link in menu</a>
  </Menu.Item>
</Menu>

Menu组件的属性分析

使用 string-literal-types来限制组件属性值的范围，比enum更好用

interface MenuProps {
  defaultIndex: number;
  mode: string;
  onSelect: (selectedIndex: number) => void;
  className: String
}

interface MenuItemProps {
  index: number;
  disabled: boolean;
  className: String
}

通过属性来生成Menu组件的className

Menu组件

const Menu: FC<MenuProps> = (props)=>{
    const {defaultIndex, className, mode, style, children, onSelect} = props
    
    const classes = classNames('tui-menu', className, {
        'menu-vertical': mode === 'vertical'
    })

    return <ul className={classes} style={style}>
        <MenuContext.Provider value={passedContext}>
            {children}
        </MenuContext.Provider>
    </ul>
}

MenuItem组件

const MenuItem: FC<MenuItemProps> = (props) => {
    const {index, disabled, className, style, children} = props

    const classes = classNames('tui-menu-item', className, {
        'is-disabled': disabled
    })

    return (
        <li className={classes} style={style}>
            {children}
        </li>
    )
}

useState记录Menu组件activeItem状态，通过useContext hook与子组件共享该状态

声明、构造MenuContext

// 定义MenuContext类型接口
interface IMenuContext {
    index: number;
    onSelect?: SelectCallback;
}
// 声明Context
export const MenuContext = createContext<IMenuContext>({index: 0})

const Menu: FC<MenuProps> = (props)=>{
    ...
    
    const [currentActive, setActive] = useState(defaultIndex)

    const handleClick = (index: number) => {
        setActive(index)
        if(onSelect){
            onSelect(index)
        }
    }

    // 将currentActive与onSelect方法绑定到Context中
    const passedContext: IMenuContext = {
        index: currentActive ? currentActive : 0,
        onSelect: handleClick
    }

    // 使用MenuContext.Provider包裹children
    return <ul className={classes} style={style} data-testid="test-menu">
        <MenuContext.Provider value={passedContext}>
            {children}
        </MenuContext.Provider>
    </ul>
}

MenuItem组件中获取MenuContext

import {MenuContext} from "./menu";

const MenuItem: FC<MenuItemProps> = (props) => {
    ...
    // 获取useContext
    const context = useContext(MenuContext)
    
    const classes = classNames('tui-menu-item', className, {
        'is-disabled': disabled,
        // 根据context中的index值判断当前MenuItem是否为active状态
        'is-active': context.index === index
    })
    
    // 调用context中的onSelect方法
    const handleClick = ()=>{
        if (context.onSelect && !disabled && (typeof index === "number")) {
            context.onSelect(index)
        }
    }

    return (
        <li className={classes} style={style} onClick={handleClick}>
            {children}
        </li>
    )
}

限制Menu组件的children只能为MenuItem，自动为MenuItem添加index值

使用React.Children.map遍历Menu组件下的子组件

使用React.cloneElement将数组index值注入到Menu子组件MenuItem中

const Menu: FC<MenuProps> = (props)=>{
    const {...} = props
    
    ...
    
    const renderChildren = ()=>{
        return React.Children.map(children, ((child, index) => {
            const childElement = child as React.FunctionComponentElement<MenuItemProps>
            const { displayName } = childElement.type
            if (displayName === 'MenuItem') {
                // ⚠️：将index作为自组件的props注入
                return React.cloneElement(childElement, {index})
            }else {
            // ⚠️：如果子组件的displayName不对，报警告
                console.error("Warning: Menu has a child which is not a MenuItem component")
            }
        }))
    }

    return <ul className={classes} style={style}>
        <MenuContext.Provider value={passedContext}>
            {renderChildren()}
        </MenuContext.Provider>
    </ul>
}

Menu组件的测试

测试用例设计：

• should render correct html tags when render Menu given default props
• should change active menu item and call the right callback when click Menu component item
• should render vertical mode when render Menu component given mode is vertical

Menu组件需求升级——Menu中支持下拉列表

期望得到的组件功能语以化表达：

<Menu mode="vertical" defaultIndex="0">
   <MenuItem>
        menu 1
    </MenuItem>
    <MenuItem disabled>
        menu 2
    </MenuItem>
    <SubMenu title="dropdown">
        <MenuItem>
            dropdown 1
        </MenuItem>
        <MenuItem>
            dropdown 2
        </MenuItem>
    </SubMenu>
    <MenuItem>
        menu 3
    </MenuItem>
</Menu>

Menu组件需要修改的部分：

• 子组件可以支持SubMenu
• MenuItem的index有多层结构，需要修改为数据类型为string，下拉菜单中的MenuItem index表现为类似"1-0"

封装subMenu：

• 根据menu的mode判断下拉列表的toggle形式
  • 横向menu通过鼠标的hover开关
  • 纵向的menu通过点击事件来开关下拉菜单

export interface SubMenuProps {
    index?: string;
    title?: string;
    className?: string;
}

const SubMenu: FC<SubMenuProps> = (props) => {
    const {index, title, className, children} = props
    const [open, setOpen] = useState(false)
    const context = useContext(MenuContext)
    const classes = classNames('tui-menu-item tui-submenu-item', className, {
        'is-active': context.index === index
    })

    const handleClick = (e: React.MouseEvent)=>{
        e.preventDefault()
        setOpen(!open)
    }

    let timer: any
    const handleMouse = (e: React.MouseEvent, toggle: boolean)=>{
        clearTimeout(timer)
        e.preventDefault()
        timer = setTimeout(()=>{
            setOpen(toggle)
        }, 300)
    }

    const clickEvents = context.mode === 'vertical'? {
        onClick: handleClick
    }:{}
    const hoverEvents = context.mode !== 'vertical'? {
        onMouseEnter: (e: React.MouseEvent)=>{handleMouse(e,true)},
        onMouseLeave: (e: React.MouseEvent)=>{handleMouse(e,false)}
    }:{}

    const renderChildren = () => {
        const subMenuClasses = classNames('tui-submenu', {
            'menu-opened': open
        })
        const childrenComponent = React.Children.map(children, ((child, i) => {
            const childElement = child as React.FunctionComponentElement<MenuItemProps>
            const {displayName} = childElement.type
            if (displayName === 'MenuItem') {
                return React.cloneElement(childElement, {
                    index: `${index}-${i}`
                })
            } else {
                console.error("Warning: SubMenu has a child which is not a MenuItem component")
            }
        }))
        return <ul className={subMenuClasses}>
            {childrenComponent}
        </ul>
    }

    return (
        <li key={index} className={classes} {...hoverEvents}>
            <div className="submenu-title" {...clickEvents}>{title}</div>
            {renderChildren()}
        </li>
    )
};

组件的调试与文档——StoryBook

安装storyBook

npx -p @storybook/cli sb init

配置读取ts

.storybook/main.js

module.exports = {
  stories: ['../src/**/*.stories.tsx', '../src/**/*.stories.js'],
  addons: [
    '@storybook/preset-create-react-app',
    '@storybook/addon-actions',
    '@storybook/addon-links',
  ],
};

配置全局样式

config.ts

import { configure } from "@storybook/react";
import '../src/styles/index.scss'

configure(require.context('../src', true, /\.stories\.tsx$/), module);

编写Button组件的story

当前storybook版本是5.3，5.2以上的版本已经推荐使用CSF语法编写story：
button.stories.tsx

import {action} from "@storybook/addon-actions";
import React from "react";
import Button from "./button";

const styles: React.CSSProperties = {
    textAlign: "center"
}
const CenterDecorator = (storyFn: any) => <div style={styles}>{storyFn()}</div>

export default {
    title: 'Button',
    component: Button,
    decorators: [CenterDecorator],
};

export const DefaultButton = () =>
    <Button onClick={action('clicked')}>Default Button</Button>;

DefaultButton.story = {
    name: '默认按钮',
};

export const buttonWithDifferentSize = () =>
    <>
        <Button size="lg">Large Button</Button>
        <Button>Default Button</Button>
        <Button size="sm">Small Button</Button>
    </>

export const buttonWithDifferentType = () =>
    <>
        <Button btnType="primary">Primary Button</Button>
        <Button btnType="default">Default Button</Button>
        <Button btnType="danger">Danger Button</Button>
        <Button btnType="link" href="https://www.baidu.com" target="_blank">Link Button</Button>
    </>

StoryBook的插件

配置addon-info插件，丰富组件的文档信息: .storybook/config.tsx

import {configure, addDecorator, addParameters} from "@storybook/react";
import '../src/styles/index.scss'
import React from "react";
import {withInfo} from "@storybook/addon-info";

const wrapperStyles: React.CSSProperties = {
    padding: '20px 40px'
}

const storyWrapper = (storyFn: any) => (
    <div style={wrapperStyles}>
        <h3>Component Demo</h3>
        {storyFn()}
    </div>
)

addDecorator(storyWrapper)
addDecorator(withInfo)
addParameters({info: {inline: true, header: false}})

configure(require.context('../src', true, /\.stories\.tsx$/), module);

配置react-docgen-typescript-loader webpack loader使react-docgen支持ts，同时配置过滤器，过滤掉html自带的props，只在文档中展示自定义的props.storybook/main.js：

module.exports = {
  stories: ['../src/**/*.stories.tsx'],
  addons: [
    '@storybook/addon-actions',
    '@storybook/addon-links',
  ],
  webpackFinal: async (config) => {
    config.module.rules.push({
      test: /\.tsx$/,
      use: [{
          loader: require.resolve("react-docgen-typescript-loader"),
          options: {
            shouldExtractLiteralValuesFromEnum: true,
            propFilter: (prop) => {
              if (prop.parent) {
                return !prop.parent.fileName.includes('node_modules')
              }
              return true
            }
          }
        }],
    });
    config.resolve.extensions.push('.ts', '.tsx');
    return config;
  },
};

在组件实现代码加上注释，可以完善react-gendoc的描述：

import React, {AnchorHTMLAttributes, ButtonHTMLAttributes, FC} from "react";
import classNames from 'classnames'

type ButtonSiz = 'lg' | 'sm'
type ButtonType = 'primary' | 'default' | 'danger' | 'link'

interface BaseButtonProps {
    className?: string;
    /** Setting Button's disable*/
    disable?: boolean;
    href?: string;
    /** Setting Button's size*/
    size?: ButtonSiz;
    /** Setting Button's type*/
    btnType?: ButtonType;
    children: React.ReactNode;
}

type NativeButtonProps = BaseButtonProps & ButtonHTMLAttributes<HTMLElement>
type AnchorButtonProps = BaseButtonProps & AnchorHTMLAttributes<HTMLElement>
export type ButtonProps = Partial<NativeButtonProps & AnchorButtonProps>

/**
 *
 The most commonly used button elements on the page, suitable for completing specific interactions
 * ### Reference method
 *
 * ~~~js
 * import { Button } from 'thought-ui'
 * ~~~
 */
export const Button: FC<ButtonProps> = (props) => {
    const {
        btnType,
        className,
        disable,
        size,
        children,
        href,
        ...restProps
    } = props

    const classes = classNames('btn', className, {
        [`btn-${btnType}`]: btnType,
        [`btn-${size}`]: size,
        'disabled': (btnType === 'link') && disable
    })
    if (btnType === 'link' && href) {
        return <a className={classes} href={href} {...restProps}>{children}</a>
    } else {
        return <button className={classes} disabled={disable} {...restProps}>{children}</button>
    }
}

Button.defaultProps = {
    disable: false,
    btnType: 'default'
}

export default Button

组件库打包

模块的历史

• 全局变量与命名空间、自执行函数：jQuery
  • 依赖全局变量
  • 污染全局变量、不安全
  • 手动管理依赖、控制执行顺序
  • 上线之前手动合并
• common.js规范：为服务器端诞生的，不符合前端规范
  • require & module.exports
• AMD：为前端模块化诞生的，解决了common.js规范的问题
  • define(function (){ const bar = require('../bar') })
  • 没办法使用直接使用，也需要模块打包工具require.js
• Es6 module
  • import & export
  • 也没办法直接在浏览器中使用，需要bundle为es5的代码

模块打包的流程

Typescript Files------tsc---->ES6 Modules Files----入口文件index.tsx----Bundler: webpack、rollup...----->浏览器可直接执行的文件

选择Javascript的模块格式

UMD(Universal Module Definition)是一种可以直接在浏览器中使用的模块格式，这种方式可以支持用户直接使用script标签引用模块。

ES模块：
ES模块是官方标准，可以进行代码静态分析，从而实现tree-shaking的优化，并提供诸如循环引用和动态绑定等高级功能。

所以：ES模块作为打包的输出结果

创建组件库模块的入口文件

components/Button/index.tsx:

import Button from "./button";

export default Button;

components/Menu/index.tsx:

import {FC} from 'react'

import Menu, {MenuProps} from "./menu";
import MenuItem, {MenuItemProps} from "./menuItem";
import SubMenu, {SubMenuProps} from "./subMenu";

export type IMenuComponent = FC<MenuProps> & {
    Item: FC<MenuItemProps>,
    SubMenu: FC<SubMenuProps>,
}

const FinalMenu = Menu as IMenuComponent;

FinalMenu.Item = MenuItem;
FinalMenu.SubMenu = SubMenu;

export default FinalMenu;

组件库模块的入口文件src/index.tsx:

export {default as Button} from './components/Button'
export {default as Menu} from './components/Menu'

使用tsc打包ts文件为ES文件

tsconfig.build.json

{
  "compilerOptions": {
    "outDir": "build",
    "module": "ESNext",
    "target": "ES5",
    "declaration": true,
    "jsx": "react",
    "moduleResolution": "Node",
    "allowSyntheticDefaultImports": true
  },
  "include": [
    "src"
  ],
  "exclude": [
    "src/**/*.test.tsx",
    "src/**/*.stories.tsx"
  ]
}

package.json

"scripts": {
    ...
    "build-ts": "tsc -p tsconfig.build.json"
  },

使用node-sass打包样式文件

package.json

"scripts": {
  "build": "npm run build-ts && npm run build-css",
  "build-ts": "tsc -p tsconfig.build.json",
  "build-css": "node-sass ./src/styles/index.scss ./build/index.css"
}

打包上传到npm

语义化版本号

自动化publish、commit之前的自动化测试与lint

// package.json scripts
{
    "lint": "eslint --ext js,ts,tsx src --max-warning 1",
    "test:nowatch": "cross-env CI=true react-scripts test",
    "build": "npm run clean && npm run build-ts && npm run build-css",
    "prepublishOnly": "npm run test:nowatch && npm run lint && npm run build"

}

配置husky的config:

{
  "husky": {
    "hooks": {
      "pre-commit": "npm run test:nowatch && npm run lint"
    }
  }
}

登录npm并执行npm run push

git addusr

npm run publish

配置circle ci自动化部署storybook到gh-pages

.circlecl/config.yml:

version: 2.1
orbs:
  node: circleci/node@1.1.6
  gh-pages: sugarshin/gh-pages@0.0.6
jobs:
  build-and-test:
    executor:
      name: node/default
    steps:
      - checkout
      - node/with-cache:
          steps:
            - run: yarn install
            - run: yarn run test:nowatch
  deploy-sb-ghpages:
    executor:
      name: node/default
    steps:
      - checkout
      - run: yarn install
      - run: yarn run build-storybook
      - gh-pages/deploy:
          build-dir: storybook-static
          ssh-fingerprints: xxx

workflows:
  version: 2
  build-and-deploy:
    jobs:
      - build-and-test
      - deploy-sb-ghpages:
          requires:
            - build-and-test