Skip to main content

组件开发指南

⽬的​

本开发规范，分别在⼯程规约、编程规约、设计规约等多个维度，根据 KDesign 项⽬的实际情况， 对组件的开发进⾏约束和建议，最终形成《KDesign 开发规范》。

根据约束⼒强弱及故障敏感性，规约依次分为强制、推荐、参考三⼤类。

对于规约条⽬的延伸信息中，

“说明” 对规约做了适当扩展和解释；

“推荐” 提倡什么样的编码和实现⽅式；

“慎用” 说明需要提防的雷区，以及真实的错误案例。

本开发规范旨在码出⾼效，码出质量。做到尽可能少踩坑，杜绝踩重复的坑，切实提升系统稳定性，码出质量。

适⽤范围​

本规范适⽤ KDesign 所有开发者。

⼯程规约​

开发集成环境​

  • IDE ⼯具：Visual Studio Code 1.60 及以上版本
  • typescript 版本：4.7 及以上
  • react 版本：18.2 及以上
  • 包管理⼯具：yarn
  • UI 框架：antd 4.21 及以上
  • css 预处理语⾳：Less 4.1.3 及以上

项⽬规约​

  • 【强制】组件名称格式统⼀以：K ⼤写字⺟开头 进⾏命名，切勿出现拼⾳式英⽂。

KButton, KInput

正确

kInput, k-input, Kinput, K-input, K-Input

错误

  • 【强制】组件对应⽂件夹命名：跟规约 1 相同。

  • 【强制】新增组件存放位置：根⽬录/components 。

  • 【强制】新增图⽚资源存放位置：

    • svg 格式：根⽬录/components/assets/svgs
    • png, jpg 格式：根⽬录/components/assets/images

  • 【强制】新增图⽚资源统⼀以⼩写英⽂命名，可带-分割：

search.png, close.svg, delete-all.svg

正确

Search.png, delete-All.svg

错误
  • 【强制】组件独特的样式名统⼀以⼩写英⽂命名，格式为 k-组件名称；在样式⽂件⾥⽤变量替换该组件特有的样式名，格式为 @组件名称-prefix-cls。

样式名称: k-btn, 对应变量: @btn-prefix-cls;

样式名称: k-input, 对应变量: @input-prefix-cls

正确

k-Btn, Kbtn

--

错误
  • 【强制】 样式⽂件⾊值、字体⾏⾼⽤统⼀的变量，命名变量⽂件位置： 根⽬录/components/style/variables.less。
  • 【强制】组件⼊参类型名称，统⼀以 K + 组件名称 + Props 驼峰命名

KButtonProps, KInputProps

正确

kButtonProps, Kbuttonprops

错误
  • 【强制】组件⼊参类型名称中，⾃定义的字段，需要添加注释说明，格式为
export type KComponentProps = {
  /** 添加对自定义字段的描述 */
  myApi: any;
}
  • 【强制】每个组件下设置⼀⽂件夹 style，存放该组件的样式⽂件；样式⽂件命名统⼀⽤组件名称，英⽂⼩写字⺟。

button.less, input.less

正确

Button.less, KInput.less

错误
  • 【强制】codesign 下载 svg 资源，统⼀选择压缩版。

项目结构​

.
├── commitlint.config.js
├── components  ———— 存放组件代码
│   ├── KButton
│   ├── KCard
│   ├── KColorsPecification
│   ├── KDatePicker
│   ├── KDrawer
│   ├── KDropdown
│   ├── KIcon
│   ├── KInput
│   ├── KMessage
│   ├── KModal
│   ├── KPagination
│   ├── KSelect
│   ├── KSpace
│   ├── KSteps
│   ├── KTooltip
│   ├── KTransfer
│   ├── assets  ———— 图⽚资源
│   ├── button_primary.tsx
│   ├── style   ———— 公共样式⽂件
│   └── utils   ———— 公共⽅法
├── config      ———— storybook 配置⽂件
│   ├── antd.themes.ts
│   └── common.config.ts
├── index.html
├── package.json
├── scripts     ———— 打包配置⽂件
│   ├── compileStyle.ts
│   ├── compileTypescript.ts
│   ├── component.ts
│   ├── full-component.ts
│   ├── gulp-other-file.ts
│   ├── gulpfile.ts
│   └── utils
├── src
│   ├── index.less
│   ├── main.tsx
│   └── typings.d.ts
├── tsconfig.json
└── vite.config.ts