组件库的使用和自定义组件｜青训营笔记1. 组件库介绍软件组件封装好的可复用的程序“零部件” 前端 UI 组件 “按

1. 组件库介绍

软件组件

封装好的可复用的程序“零部件”

前端 UI 组件

“按钮”、“输入框”、“下拉选择”都是组件，组件和组件组合就变成了一个更复杂的组件。

组件库：一系列 UI 组件的合集。

一致性
效率
协同

ArcoDesign 是由字节跳动 GIP UED 团队和架构前端团队联合推出的企业级设计系统。

2023-05-06 (1).png

设计产出效率提升
协作效率提升
研发开发效率提升

主题平台

源力主题

物料平台

源力物料库
字节云物料库

图标平台

源力/业务图标库

2. 组件库的使用

2.1 快速上手

2.1.1 引入组件库

需要同时安装 react >= 16.8 和 react-dom >= 16.8

npm i arco-design/web-react

基础使用

import React from "react";
import ReactDOM from "react-dom";
import { Button } from "@arco-design/web-react";
import "@arco-design/web-react/dist/css/arco.css";

ReactDOM.render (
    <Button type="primary">Hello Arco</Button>,
    document.querySelector("#root")
);

安装按需加载插件 babel-plugin-import

yarn add babel-plugin-import -D

修改 Babel 配置，引入插件

plugins: [
    [
        ' babel-plugin-import ',
        {
            libraryName: '@arco-design/web-react',
            libraryDirectory: 'es',
            camel2DashComponentName: false,
            style: true, //样式按需加载
        },
    ],
    [
        'babel-plugin-import', //图标库按需加载
        {
            libraryName: '@arco-design/web-react/icon',
            libraryDirectory: 'react-icon',
            camel2DashComponentName: false,
        },
    ],
];

通过 CDN 使用

开发环境: unpkg.com/@arco-desig…

生产环境: unpkg.com/@arco-desig…

图标: unpkg.com/@arco-desig…

Arco Pro 技术栈

React
TypeScript
BizCharts
Arco Design
多架构
- Next.js
- Create React APP
- Vite

预装环境

npm i -g arco-cli

项目初始化 arco init hello-arco-pro 项目开发 cd hello-arco-pro

yarn dev

2.2 主题定制

通过 CSS 进行样式覆盖
修改 Less 变量
组件定制
DesignLab
- 通过 Arco 插件引入

2.3 暗黑模式

在不同模式下改变的只有颜色。尺寸，边距等没有改变。

写法一致，读取到的变量值不同。

核心思路

本质上是控制暗色颜色变量的挂载位置，提高我们所需要的颜色变量的优先级。

2.4 国际化

从全局配置上读取 Locale 语言文件。

// 分页条数选择器
function PageOption(props: PageOptionProps) {
    const { locale } = useContext(ConfigCOntext);
    return (
        <Select
            {
                // ...
            }
            >
            {props.sizeOptions.map((num) => {
                return (
                    <Option key={num} value={num}>
                        {'${num} ${locale.Pagination.countPerPage}'}
                    </Option>
                );
            })}
        </Select>
    );
}

直接通过 ConfigProvider 组件传入不同语言文件去修改 Locale。

想要的语言未支持

自定义语言包文件 custom-locale.ts
通过 ConfigProvider 组件消费

RTL 视图

如何开启：rtl={true}

元素方向 RTL
- CSS属性
- direction: rtl; (用来设置文本和其他元素的默认方向是从右到左)
布局 RTL
- margin-left => margin-right
- position: right => position: left
交互行为 RTL
- Slider 组件
- 向左拖动数值变小 => 向右拖动数值变小
其他处理
- 左还是左，右还是右
- Notification 设置为 right 弹出时，无论在 RTL 还是 LTR ，都是出现在右上角

修改组件默认的属性值，从而改变组件的默认表现

使用方式

通过 ConfigProvider 的 componentConfg 属性，传入定义好的配置文件，组件配置将会对 ConfigPorvider 组件所包裹的所有组件生效。

ConfigProvider: 利用 React Context，为所有组件提供统一的全局配置。

locale	语言配置
rtl	是否开启 rtl 视图
prefixCls	组件类名前缀
size	组件默认尺寸
componentConfig	组件默认属性

2.5 业务常见问题

旧项目迁移
如何获取 OnCall 支持
更新日志，发版周期
如何参与共建

Codemod 代码迁移工具

用户群

Github issue

官方文档站

3. 自定义组件

3.1 业务组件库搭建

通用业务组件库

保障规范性，稳定性，提高业务开发效率。

关键点

架构设计
- 单包架构
  
  一个代码仓库里所有组件打包成一个整体，发布出去一个 npm 包。
- 多包架构
  
  一个代码仓库包含多个组件代码，会发布出去多个 npm 包。
技术方案
- 开发环境
  - 打包速度
  - 实时预览，如 storybook
- 样式方案
  - 样式方案: Less / Sass，css in Js，css 等
  - 组件库换肤，样式定制等能力
- 产物构建
  - 构建工具 webpack，rollup，vite，gulp 等
  - 产物格式：cjs，umd，es
- 质量保障
  - 测试工具：jest，karma，mocha，enzyme，react-testing-library 等测试类型：单元测试，快照测试，截屏测试，e2e 测试等
- 组件开发
对外文档
- Demo 展示
  - Demo 展示：Storybook，umijs 等
  - 静态内容：markdown
- 组件 API 生成
  - 手写
  - 自动提取：ts-docuemnt 等
- 版本日志
  - 手写
  - 自动提取：从 PR 提交记录自动提取 @arco-design/changelog

单包架构：Arco Design

优点:

公共代码易复用
展示更聚合，便于维护
引入一个包即可使用全部组件

缺点:

修改一个组件需要更新整个库
需要考虑按需加载

多包架构：Arco 官方物料库

优点:

单独发包，升级灵活。
在同一仓库下，便于代码管理
使用者无需考虑按需加载

缺点∶

组件间相互依赖时,需要通过 npm 包引入
组合使用时需要安装每一个用到的 npm 包

3.2 组件开发规范

1.drawio.png

什么是好的组件

高内聚，低耦合

职责清晰，高可维护性 对外提供简单稳定的接口，对内关注内部逻辑的实现。

组件和组件之间能简单的配合实现定制的功能。

比如：Popver 直接嵌套 Input 即可实现：在输入框聚焦时显示气泡提示内容。
通用性，易扩展

基础组件适用广泛的业务场景

适用于不同行业的业务平台。

业务组件适用于针对性平台

具备显著的业务属性，一般基于基础组件开发。

比如：通过关键字调接口搜索 Lark 群聊

项目组织

语义化命名
包名和组件名最后一致
单独维护类型文件

组件设计

组件属性定义
类名前缀统一
避免行内样式
避免在 JS 中耦合 css
注意样式的按需加载

项目组织

语义化命名

组件的命名应当具有语义，并且避免与基础组件冲突。同一团队/仓库下的业务组件，也可采用相同的命名前缀。
包名和组件名一致

NPM 包名应当尽量与组件名保持一致，包含明确的使用场景信息。
单独维护类型文件

推荐将需要对外导出的 TS 类型维护在单独的 interface.ts 中，并将其在 index.ts 中导出。

组件设计

接口定义

在为组件定义接口类型时，应继承原生 DOM (或基础组件)属性，避免属性遗漏或重复声明。
类名前缀统一

组件使用特殊且统一的类名前缀，尽量降低与用户类名冲突的可能性。
避免行内样式和 css Modules

确保外部可通过类名进行样式覆盖。
避免在 JS 中直接引入样式文件

应尽量保证逻辑与样式的分离，确保用户可以分别引入 JS 和 CSS 文件，避免由于构建环境的不同导致的用户编译失败的问题。
注意组件样式的按需加载

在基于基础组件库如 Arco 进行业务组件的逻辑封装时，应注意按需引入所依赖的 Arco 基础组件的样式文件。

3.3 自定义组件 guide-tip

引导气泡功能要点

控制引导气泡的出现
点击下一步/上—步时切换气泡卡片的内容
气泡卡片的位置跟随变动
在最后一步时，显示完成按钮

2.drawio.png

API 定义

/**
 * @title GuideTip
 */
export interface GuideTipProps {
    /**
     * @zh 是否显示引导气泡
     */
    visible? : boolean;
    /**
     * @zh 引导步骤
     */
    steps?: {
        title? : ReactNode;
        content? : ReactNode;
        target: () => HTMLElement
    }[];
    /**
     * @zh 完成时的回调
     */
    onEnd? : () => void;
}

核心逻辑

显示弹出层：Arco Popover 组件
步骤切换：状态变量 current 记录当前处于哪一步骤
弹出层始终指向对应的 Button：实时获取目标节点的位置，更新弹出层指向

3.4 业务组件快速托管

Arco CLI + 物料平台

提供标准的业务模块开发方案的脚手架工具承载通用业务模块展示的在线平台。

高效生产通用业务模块
更友好的物料展示方式
提高流通率和复用率

组件库的使用和自定义组件｜ 青训营笔记