Skip to content

组件开发须知 & 规范

Jump to bottom
Jerome edited this page Jan 3, 2024 · 14 revisions

新增一个组件

项目脚手架自带新建组件模板功能，全局安装 @zarm-design/cli，进行以下四步即可快速创建一个组件模板。

第一步：进入 zarm 子工程，执行脚本新增一个 MyComponent 组件的模板

cd packages/zarm
zarm add MyComponent

第二步：在 packages/zarm/src/index.ts 中将组件导出

export { default as MyComponent } from './my-component';
export type { MyComponentCssVars, MyComponentProps } from './my-component';

第三步：在 packages/zarm/src/style/components/scss 中增加组件样式文件

@import "../my-component/style";

第四步：在 packages/site/site.config.js components 对象中增加组件示例配置

{
  key: 'my-component',
  name: '组件名',
  module: () => import('zarm/my-component/demo.md'),
  source: 'zarm/my-component/demo.md',
  style: false,
}

命名规范

  • ts 类型命名 特定属性需要按照大驼峰命名规范，并且带上组件名的前缀，如按钮组件的 size 大小：
export type ButtonSize = 'lg' | 'md' | 'sm' | 'xs';
  • 渲染节点命名 相关节点渲染的 render 函数命名，如果是 renderXXX 代表的是一个函数，如果是 xxxRender 代表的是一个表达式。
const iconRender = icon && <div className={`${prefixCls}__icon`}>{icon}</div>;

const renderIcon = (icon) => icon && <div className={`${prefixCls}__icon`}>{icon}</div>;

return (
  <>
    {iconRender}
    {renderIcon(icon)}
  </>
);

样式

  • 使用 bem 规范编写 scss 文件，项目已经写好了相关 mixins，详细规范可参考 https://github.com/ZhongAnTech/zarm/issues/234

  • 组件的状态用 @include m(xxx) 来定义，且尽量提升到组件的顶层节点。

<!-- good -->
<button className="za-button za-button--disabled za-button--lg">
  <span className="za-button__content">按钮文字</span>
</button>

<!-- bad -->
<button className="za-button">
  <span className="za-button__content za-button--disabled za-button--lg">按钮文字</span>
</button>
  • 样式文件中不能出现 .za-/.zw- 等写死的样式前缀。
  • 全局的 css variables 编译时会统一引入，组件的 scss 中无需额外引入
  • 希望后期能外部设置的 css variables 需要定义在 packages/zarm/src/style/themes/default.scss 文件中，且尽可能保证在变量修改的同时，显示的样式能够按比例适配
  • 复用其他组件以后，需要在 packages/zarm/src/当前组件/style/index.ts 文件中引入组件的样式文件。比如使用了 icon：
import '../../style';
import '../../icon/style';
import './index.scss';

CSS Variables 命名规范

规则：--前缀-组件名-(元素)-(状态)*n-属性

范例如下：

--前缀-组件名-属性
--za-button-height // 按钮组件的高度

--前缀-组件名-(元素)-属性
--za-button-icon-color // 按钮组件图标节点的颜色

--前缀-组件名-(状态)*1-属性
--za-button-primary-background // 主按钮的背景色

--前缀-组件名-(状态)*n-属性
--za-button-primary-active-background // 主按钮激活状态的背景色

--前缀-组件名-(元素)-(状态)*n-属性
--za-button-icon-primary-color // 按钮组件图标节点在主按钮状态下的颜色
--za-button-icon-primary-active-color // 按钮组件图标节点在主按钮激活状态下的颜色

TS 类型定义

  • 组件 props 需要导出相关 ts 类型，如
export type { RadioProps, RadioGroupProps } from './radio';
  • ReactNode 类型是联合类型，一般情况下不需要和其他类型同时使用，使用时请详细了解

接口文档

  • 表格列按顺序：属性、类型、默认值、说明
  • “类型”按照 TS 的定义来写
  • 可选参数填入“说明”中，并包含用法解释

示例

  • 按维度/场景列举展示
  • 尽可能覆盖到所有 props 的展示

单元测试

  • 代码覆盖率尽可能高，至少 80%。
  • 提交 PR 前执行 yarn test -u 命令，确保单元测试快照更新及无误，增加 -o 参数可以只运行已修改文件的单元测试。

持续集成

  • 提交 PR 后如 Github Actions 执行的 CI 报错，以及 netlify 的站点部署 CD 报错，请自行排查错误信息，修改并重新提交。

其他

  • 多参考已完成的组件，有利于代码风格的统一
  • 对设计稿、定义的 API 等问题有疑问，请及时沟通，应避免先做再提
  • 请充分自测后再提交 PR，避免不必要的沟通和反复审核
  • 组件自认领后，请尽快完成，避免影响项目进度，如有困难也应及时提出
Clone this wiki locally