1 业务场景

在自定义控件开发中，开发者经常会碰到一些问题。例如，自定义控件没有注册（代码中没有注册控件id）、自定义控件在IE11上没显示（使用了不兼容IE11的语法）。而事实上，这些问题都可以在开发自定义控件过程中避免。

为提高自定义控件开发效率，便于后期开发者添加功能及维护、输出高质量的自定义控件，本文将针对开发者经常碰到的问题，从准备工作、代码编写到打包上传三个方面，为开发者定制一份自定义控件的开发规范（包括务必遵守和推荐执行两方面）。

2 规范分类

强制：这些规范能够帮助开发者规避自定义控件开发过程中的错误，所以开发者必须严格遵守该类规范，从而避免不必要的错误。

推荐：这些规范能够改善自定义控件代码中的可读性和开发体验。即使开发者不遵循，代码仍然可以照常运行，但是推荐遵循该类规范。

3 准备工作

注册控件id名称【强制】

注册自定义控件时，控件id组成规则应为 `开发商标识-领域标识-控件名称` 以确保控件id的唯一性。同时，命名需采用小写方式，可以用中划线分隔或者使用小写驼峰命名，避免出现大写的控件id。

正例【emoji】：

// 开发商标识：kingdee，领域标识：hr，控件名称：search-box
KDApi.register('kingdee-hr-search-box', MyFunction)

反例【emoji】：

// 这些都是不可取的
KDApi.register('SearchBox', MyFunction) // 控件id命名规则应为 `开发商标识-领域标识-控件名称`,且为小写
KDApi.register('kingdee_hr_search_box', MyFunction) // 控件id命名应该使用中划线分割

4 代码编写

（1） `model.dom.innerHTML` 挂载页面元素【强制】

当自定义控件需要渲染页面元素时，必须使用 `model.dom.innerHTML` 挂载页面元素。

正例【emoji】：

KDApi.getTemplateStringByFilePath('./html/entry.html', model).then(function (result) {
  model.dom.innerHTML = result
})

反例【emoji】：

KDApi.getTemplateStringByFilePath('./html/entry.html', model).then(function (result) {
  // 加载了html文件，并没有使用
})

（2）禁止在jquery中使用es6/es7语法【强制】

es6/es7语法在IE11上兼容性极差。如果自定义控件项目没有经过babel转译，应避免使用es6/es7语法 (vue、react项目可使用)。

正例【emoji】：

function getName () {}

反例【emoji】：

// es6语法在ie11上兼容性极差，如果项目没有经过babel转译，应尽量避免
const getName = () => {}

（3）禁止定义全局变量【强制】

所有的变量都应该定义在函数作用域。这样可以避免污染全局变量，并且全局变量是不会被垃圾回收的，容易引起内存泄漏等问题。

正例【emoji】：

function getName() {
   var name = '张三'
}

反例【emoji】：

window.name = '张三'

（4）禁止使用reset.css等样式文件【强制】

严禁使用该类样式文件，因为此样式会重置页面上对应标签的样式。

反例【emoji】：

html,body,div,span {
  margin:0;
  padding:0;
  border:0;
  font-size:100%;
  font:inherit;
  font-weight:normal;
  vertical-align:baseline;
}

（5）禁止定义全局标签选择器【强制】

禁止使用全局标签选择器，以防止全局样式被污染。

正例【emoji】：

.search-box-header {
  width: 100%;
}

反例【emoji】：

div {
  width: 100%;
}
span {
  color: #000000;
}

（6）禁止定义全局样式【强制】

样式命名应遵循以`开发商标识-领域标识-控件id-语义化名称`规则。

正例【emoji】：

// 开发商标识为kingdee，领域标识为hr，控件id为search-box，对应的语义化名称为header
.kingdee-hr-searchBox-header {
  width: 100%;
}

反例【emoji】：

// 这样写会有一个弊端，假如该样式没有经过混淆编译过，那么该样式将会影响页面上.header的所有样式
.header {
  width: 100%;
}

（7）自定义控件目录命名全部采用小写方式【推荐】

目录命名应采用小写方式。当有复数结构时，要采用复数命名法。

注：缩写无需使用复数形式。

正例【emoji】：

css / js / scripts / styles / components / images / utils

反例【emoji】：

script / style / demo_scripts / demoStyles / imgs / docs

5 打包上传

（1）上传/提交的代码必须是打包后的运行文件【强制】

react、vue打包后的dist目录文件、jquery等开发文件不应该包含源代码，源代码由项目组自行管理。

（2）上传自定义控件zip包，根目录下必须存在index.js文件【强制】

index.js为自定义控件的入口文件，加载自定义控件会从入口文件加载。

文件类型示例

（3）单个自定义控件大小控制在1M以内【推荐】

自定义控件体积大小和加载自定义控件速度有关。理论上来说，体积越小越好。当加载自定义控件比较缓慢的时候，应考虑想到优化自定义控件文件体积的大小。

（4）自定义控件文件格式要求【推荐】

只能上传如下格式文件：jpg、jpeg、png、gif、ico、xml、js、css、html、txt、json、svg、ttf、woff、ftl、less、scss、map、md、yml、tmpl、ts、bat、xlsm。

尽量避免上传后缀为rar、zip等压缩包和带有中文名称的文件，以避免上传控件包体积过大。

6 划重点

通过前期准备工作、代码编写、控件上传三个维度描述开发自定义控件全周期所要注意的规范，其中包括一些强制严格遵守的规范（必须注册控件id名称等），以及一些推荐的能优化控件的规范（文件大小等）。

希望大家能够严格遵守【强制】的规范，尽可能地根据【推荐】的规范编写高质量的自定义控件。

#往期推荐#

# 360°教你搞定“自定义控件”(高级技巧篇)

# 360°教你搞定“自定义控件开发”(进阶篇)

# 360°教你搞定“自定义控件开发”（入门篇）

# 360°教你搞定“自定义控件”（API手册篇）

更多精彩内容，“码”上了解！↓

360°教你搞定“自定义控件开发”（开发规范篇）

360°教你搞定“自定义控件开发”（开发规范篇）

恭喜您！