平时我除了业务需求，偶尔会投入到UI组件的开发中，大多数时候只会负责自己业务场景相关或者一小部分公共组件，极少有从创建项目、集成可视化、测试到发布的整个过程的操作，这篇文章就是记录组件开发全流程，UI组件在此仅作为调试用，重点在于集成项目环境。
组件
我们使用 React + TypeScript 来开发UI组件库，为了简化 webpack 环境和 Typescript 环境配置，这里直接使用 create-react-app 通过如下命令来创建一个新项目。
npx create-react-app 项目名称 --template typescript
创建项目后先将无用文件删除，在 scr/components/Button/index.tsx 下定义一个简单的 Button 组件。
import React, { FC, ReactNode } from "react";
import cn from "classnames";
import "./index.scss";
interface BaseButtonProps {
className?: string;
size?: "small" | "middle" | "large";
disabled?: boolean;
children?: ReactNode;
}
type ButtonProps = BaseButtonProps & React.ButtonHTMLAttributes<HTMLElement>;
const Index: FC<ButtonProps> = (props) => {
const {
size = "middle",
children = "按钮",
className,
disabled,
...restProps
} = props;
return (
<button
className={cn("btn", `btn-${size}`, className, { disabled })}
{...restProps}
>
{children}
</button>
);
};
export default Index;
使用 scss 对其进行样式编写，这里需要注意，create-react-app 中没有自动支持 scss 文件，如果需要使用需要手动安装 sass 资源来处理。
.btn {
background-color: #fff;
border: 1px solid #d9d9d9;
color: rgba(0, 0, 0, 0.88);
line-height: 1.5;
&.disabled {
cursor: not-allowed;
color: rgba(0, 0, 0, 0.25);
background-color: rgba(0, 0, 0, 0.04);
}
}
.btn-large {
font-size: 16px;
height: 40px;
padding: 7px 15px;
border-radius: 8px;
}
.btn-middle {
font-size: 14px;
height: 32px;
padding: 4px 15px;
border-radius: 6px
}
.btn-small {
font-size: 14px;
height: 24px;
padding: 0 7px;
border-radius: 4px
}
在 App.tsx 文件中引入组件并测试，验证其功能是否可用。
import React from "react";
import Button from "./components/Button";
import "./app.scss";
function App() {
return (
<div className="container">
<Button
size="large"
onClick={() => {
console.log("我是一个大按钮");
}}
>
大按钮
</Button>
<Button disabled>中等按钮</Button>
<Button size="small">小按钮</Button>
</div>
);
}
export default App;
在浏览器中可以看到组件效果，以及点击【大按钮】会触发对应的事件
Jest测试
功能简单自测后，我们需要编写测试用例来对组件进行测试，一方面是为了提高代码质量减少bug，另一方面在后期的维护升级或者重构中，只需要执行自动化脚本，便可以确认是否兼容历史版本。
这里选用 jest 和 testing-library ，我们通过 create-react-app 创建的 react 脚手架已经集成了单元测试的能力。
首先查看项目中的 setupTests.ts 有如下 Jest 断言增强的导入语句
import '@testing-library/jest-dom/extend-expect';
然后在 Button 文件夹下增加 index.test.tsx 文件编写测试用例，先判断是否成功渲染一个 Button 组件。
import React from 'react';
import { render, screen } from "@testing-library/react";
import Button from ".";
describe("Button组件", () => {
it("默认Button", () => {
render(<Button>查询</Button>); // 渲染一个名为查询的按钮
const element = screen.getByText("查询");
expect(element).toBeInTheDocument(); // 判断按钮是否在页面上
});
});
脚手架 package.json 中已经添加了 test 指令的配置，我们在执行单元测试的时候只需要执行 npm run test，等待几秒便可以看到单元测试的执行结果
当我们将 const element = screen.getByText("查询"); 中的字符串 查询 改为 上传 时，会立马给出错误信息。
另外，还可以进一步的对渲染的组件进行测试，如判断 tagName、判断类名、是否是 disabled 状态、点击事件是否执行。
import React from 'react';
import { fireEvent, render, screen } from "@testing-library/react";
import Button from ".";
const defaultProps = {
onClick: jest.fn()
}
describe("Button组件", () => {
it("默认Button", () => {
render(<Button {...defaultProps}>查询</Button>);
const element = screen.getByText("查询");
expect(element).toBeInTheDocument();
expect(element.tagName).toEqual('BUTTON');
expect(element.disabled).toBeFalsy();
expect(element).toHaveClass('btn btn-middle');
fireEvent.click(element)
expect(defaultProps.onClick).toHaveBeenCalled()
});
});
为组件增加新属性或者新特性时，记得为其在原来测试用例的基础上新增用例并执行，这样能在保证兼容历史功能的基础上验证新功能。
Storybook
通过项目入口文件 app.tsx 引入 Button 组件可以在本地服务运行的页面中预览效果，但随着组件的开发，我们需要不断 import 新的组件注释旧的引用来调试。
这样开发起来非常的繁琐，我们期望能有一个地方可以根据对组件进行分类，并且随时预览组件的效果，最好还能展示所有的组件配置，能根据选择配置展示组件效果。
针对以上的诉求，Storybook 就是一个非常好的解决方案。
使用 npm install storybook -d 安装，并通过 npx sb init 初始化，此时 storybook 会开启个一本地端口来展示默认生成的 stories 文件夹内案例。
我们在开发组件的 Button 文件夹下新增 index.stories.tsx 文件，来编写我们自己组件描述，一开始如果不知道如何定义，可以直接在案例组件的基础上进行修改。
import type { Meta, StoryObj } from "@storybook/react";
import { fn } from "@storybook/test";
import Button from ".";
const meta = {
title: "Example/iceButton", // 用于展示组件的目录
component: Button,
tags: ["autodocs"], // 是否存在 Docs 页面
args: { onClick: fn() },
} satisfies Meta<typeof Button>;
export default meta;
type Story = StoryObj<typeof meta>;
export const Primary: Story = {
args: {
children: "按钮", // 配置自己组件的属性
},
};
这样我们自己编写的组件就加入到了页面中，右下方 Control 中是我们为组件添加的
interface BaseButtonProps，storybook 会自动将这部分填充进来，并且部分属性还可以直接在页面上修改并预览效果。
每新增一个组件，我们为其添加一个对应的 stories 文件，不仅便于预览功能，同时还能为提供详细的配置说明，直接省去编写文档的时间。
编译
在进行发布之前，我们还需要做一些配置，首先是修改入口文件，原本在 React 项目中，index.jsx 文件是找到页面中 id 为 root 的根元素并渲染组件的，现在要修改成将所有定义的组件导出，开发者者通过 import 就能导入使用。
export { default as Button} from "./components/Button";
然后我们使用 typecript 工具来对项目进行编译，react 项目初始化了 tsconfig.json，这个文件和开发相关，编译的配置需要我们自定义 tsconfig.build.json 文件。
{
"compilerOptions": {
// 输出文件夹
"outDir": "dist",
// 是 esmodule 的形式，还可以选 amd、cmd
"module": "esnext",
// 输出的ES版本，ES3-ESNext
"target": "ES5",
// typescript 使用库的时候，可以获取类型提示，在 .d.ts 文件，所以这个文件也要导出
"declaration": true,
// jsx 是 React.createElement 的语法糖，可选 preserve | react | react-native，编译出来的文件使用 React.createElement 代替 jsx 语法
"jsx": "react",
// 加载资源的方案，有classic 和 node 两种，classic 对应的是相对路径的方案，从当前路径一直往上找到 root。但是 node 是去 node_modules 中查找
"moduleResolution": "node",
// 支持默认导出的方式，不定义时只支持 import * as React from 'react'
"allowSyntheticDefaultImports": true
},
// 编译src下的文件
"include": ["src"],
// 排除 src 无需编译的文件
"exclude": ["src/**/*.test.tsx", "src/**/*.stories.tsx", "src/setupTests.ts"]
}
可以看到常用的组件库，样式资源都是单独加载的，比如 antd 👉 import 'antd/dist/antd.css'，element 👉 npm install element-theme-default，我们项目也按照这种方式来做一些调整。
去除各组件 scss 文件的引入，统一收口在 src 下的 index.scss 文件中，如 @import './components/Button/index.scss';，然后为以上修改在 package.json 中添加指令。
"scripts": {
"build-ts": "tsc -p tsconfig.build.json",
"build-css": "sass ./src/index.scss ./dist/index.css --no-source-map",
"build": "npm run build-css && npm run build-ts"
}
执行 npm run build 后生成如下文件
发布npm
在发布 npm 之前，我们需要确保用户通过 npm 下载的组件资源是可用的，在本地通过 npm link 先验证一下功能。
我的UI组件项目名称为 ice-ts-app，对它执行 npm link，测试项目执行 npm link ice-ts-app，并引入测试代码。
import { Button } from 'ice-ts-app';
import 'ice-ts-app/dist/index.css';
运行测试项目，如果组件及其功能生效则代表验证成功。
验证完成后，还需要对 package.json 的配置做一些调整，包含项目的入口文件 dist/inde.js，TypeScript 类型定义文件 dist/index.d.ts，发布到 npm 的文件夹 dist ，调整 dependencies 和 devDependencies 的依赖，将 react 和 react-dom 迁移至 peerDependencies 中。
{
"main": "dist/index.js",
"module": "dist/index.js",
"types": "dist/index.d.ts",
"files": ["dist"],
"peerDependencies": {
"react": ">=16.8.0",
"react-dom": ">=16.8.0"
},
}
还有一些通用的属性，包括 description、license、author、homepage 等等，开发者按需配置。
另外每次执行 npm run build 都需要手动删除 dist 文件夹，这里可以安装并使用 rimraf 自动删除，同时再增加一条 script 指令，用于发布前执行。安装： npm install rimraf --save
"script": {
"clean": "rimraf ./dist",
"build": "npm run clean && npm run build-css && npm run build-ts",
"prepublishOnly": "npm run build"
}
发布之前先在 npm 仓库 上登录，然后执行 npm publish ，可以看到发布日志中有我们提交的文件名称、文件大小，版本号等信息。
接着我们将用于测试的项目执行 npm unlink ice-ts-app 来解除本地的绑定，并通过 npm install app-ts-app 安装并验证刚刚发布到 npm 仓库的资源，如果组件能够正常使用就代表成功啦~
完整代码
以上便是 React + TypeScript 组件开发、测试、可视化及发布解析，完整代码我放在了 github 上，戳 ice-ts-app 可查看，欢迎大家点个 star~
