跳到主要内容

组件开发指南


⽬的

本开发规范,分别在⼯程规约、编程规约、设计规约等多个维度,根据 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