某一天，业务开发部的小黑接到了新需求：要开发一个甘特图的功能。小黑一看懵了，心想：“苍穹开发平台上面可没有甘特图呀，这可咋整啊？”。带着这个疑问(和一杯奶茶)，小黑去请教了部门的资深开发白老师。

白老师推了推自己那厚厚的镜框，说：“平台不支持的控件？这可以使用自定义控件去实现啊！”

小黑听了很疑惑，回答道：“白老师，什么是自定义控件？”

善解人意的白老师开始给小黑详细讲解自定义控件......

1 使用场景

白老师：“苍穹平台目前在web端、移动端分别提供了众多标准控件，满足业务场景绝大部分通用场景开发。但面对特殊或者个性化需求时，平台支持二开通过开发自定义控件方式扩展平台控件。”

小黑听了恍然大悟：“我知道了，当平台提供的控件不能完全满足业务所需要的场景时，我们可以使用自定义控件重新去实现一个全新的控件。”

小黑：“白老师，那具体是怎么用呢？”

白老师：“小伙子，不要急，慢慢听我讲~”

2 入门使用

一切入门皆从“hello world”开始，我们也不例外。

下面将会通过一个最简单的例子：“hello world”的开发，来给大家介绍开发自定义控件的每一个步骤。跟着白老师进入自定义控件的开发吧！！

1. 新建

本地任意目录新建一个 `helloworld`目录，在该目录下新建index.js文件：

2. 开发

使用编辑器打开 `helloworld`文件夹，并将下面代码（可以先忽略代码逻辑，后面会描述）添加到 `index.js`文件中：

/**
 *  自定义控件书写模板
 */(function(KDApi, $){
    // 构造函数，变量名随意，与最后一句代码的KDApi.register的第二个参数一致即可
    function HelloWorld (model) {
        this._setModel(model)
    }
    // 原型中封装生命周期函数，固定格式
    HelloWorld.prototype = {
        _setModel: function(model) {
            this.model = model
        },
        init: function(props){
            // TO DO
            initFunc(this.model, props)
        },
        update: function(props){
            // TO DO
        },
        destoryed: function(){
            // TO DO
        }
    }
    // Other Code
    var initFunc = function(model, props) {
        model.dom.innerHTML = '<h1>init: Hello World!</h1>'
    }
    // 你只需知道第一个参数是你接下来要新增控件方案时填的方案id，第二个参数是上面声明的构造函数
    KDApi.register('helloworld', HelloWorld)})(window.KDApi, jQuery) // 这里的jQuery不是必须要传进去的，可移除，要用到的时候才传，PC端系统默认会有jQuery对象，版本是1.12.4

注：以上模板适用于`PC`端的自定义控件开发，如果是移动端的自定义控件开发，则需要将模板中使用的`jQuery`对象去除，移动端不提供`jQuery`对象。

3. 打包

将 `helloworld` 目录下的文件打成`zip`包，注意不要将`helloworld`文件夹也打包，只要其目录下的文件，且`zip`包下根目录必须要有`index.js`文件。

好了，到此`helloworld`控件前端编码部分已经完成，我们有一个`helloworld.zip`文件，我们该如何使用它呢？

4. 上传

接下来在设计器上找到`自定义控件` ，添加到你的页面中，并设置其标识为`helloworld`，点击控件方案，新增控件方案，方案`id`为`helloworld`，领域标识为`cq`，并且选择上传`helloworld.zip`。

注：该上传方案适用于客户伙伴。

左侧导航栏找`自定义控件`

上传`helloworld.zip`包

点击“保存”，选择这条方案，点击“返回数据”。

五. 预览

在设计器上点击保存，并预览：

点击保存

预览结果

Good！！我们的第一个例子`helloworld`就到此完成了！

回顾上面例子，完成一个自定义控件的步骤总结如下：

1.建一个包含`index.js`文件的目录，`index.js`是程序入口；

2.按照模版代码编辑前端`javascript`逻辑，完成后打包成`zip`；

3.设计器上新增控件方案，上传`zip`包，方案和`zip`关联；

4.设计器上新增自定义控件，自定义控件选择该方案，返回数据；

5.在页面上点击保存并且预览，就可以看到自定义控件的内容了。

小黑：“哇，原来开发自定义控件是这么简单的，我都想去试试了。但是，白老师我们目前逻辑只有 `model.dom.innerHTML = '<h1>init: Hello World!</h1>'`。假如控件很复杂的时候，还是通过`innerHTML`的方式拼接我们的页面吗？能否使用`html`和`css`写复杂交互的控件，同时让`javascript`、`html`和`css`分离？”

白老师：“哈哈哈，小伙子没想到你脑瓜子转得还挺快的呀，答案当然是可以的啦！”

3 HTML、CSS、JS分离

当开发复杂的自定义控件时，建议`css`、`html`、`javascript`分离处理，方便开发和维护。自定义控件默认集成了art-template 字符串模板，可以让开发者直接使用该语法编写`html`（非强制），并可通过`KDApi.getTemplateStringByFilePath` 接口解析为html字符串。

接下来就继续完善之前的例子。

1. 新建文件

在`helloworld`文件夹下，新建`html`目录并在该目录下，新建`helloworld.html`文件，并将以下代码复制粘贴到`helloworld.html` 中。

<h1>init: <%= text %>!</h1>

2. 修改代码

修改`index.js`里的`initFunc`函数的代码，使用以下代码，通过模版的方式分离`html`。

var initFunc = function(model, props) {
    // 通过路径去获取html字符串，第一个参数是模版文件路径，第二个参数是model，第三个参数是HTML模板中变量的值
    KDApi.getTemplateStringByFilePath('./html/helloworld.html', model, {
        text: 'Hello, World!'
    }).then(function(result) {
        model.dom.innerHTML = result
    })
}

3. 给控件添加`css`

<h1>init: <%= text %>!</h1>

4. 新建`css`目录

.helloworld{
    color: #C0C0C0; //修改字体颜色
    border: 1px solid #C0C0C0; //添加边框
}

注：建议`css`的`class`或者`id`的命名，遵循规范：使用`.领域_schemaId_`为前缀，防止与其他`class`或者`id`出现冲突。禁止直接使用标签选择器，例如：`a {...}：`禁止，`.hr_dellabel a{...}：`允许。

5. 修改函数，加载`css`

修改`index.js`里的`initFunc`函数，使用`KDApi.loadFile`把`css`加载进来，代码如下：

var initFunc = function(model, props) {
    // KDApi.loadFile可以通过路径加载js或css文件，并且在html文件头生成script或者link标签，第一个参数是路径，第二个参数是model，第三个参数是加载完成后执行的回调函数
    KDApi.loadFile('./css/helloworld.css', model, function() {
        // 通过路径去获取html字符串，第一个参数是路径，第二个参数是model，第三个参数是HTML模板中变量的值
        KDApi.getTemplateStringByFilePath('./html/helloworld.html', model, {
            text: 'Hello, World!'
        }).then(function(result) {
            model.dom.innerHTML = result
        })        
    })
}

6. 上传文件、预览效果

`helloworld` 目录下的文件重新打包成`helloworld.zip`并上传，保存预览后，效果如下：

至此，我们就完成简单的`html`、`css`、`javascript`分离啦！

回顾上面例子，我们完成了自定义控件的`html`、`css`、`javascript`的分离写法：

1. 通过`KDApi.getTemplateStringByFilePath`方法把`art-template`模版引入并解析；

2. 通过`KDApi.loadFile`方法把`css`文件引入；

小黑惊讶地说：“哇！还可以这样玩的呀，看来得多研究自定义控件这块了，感谢白老师！”

白老师得意地笑了笑：“小伙子，自定义控件的玩法多着呢！还有自定义控件前后端完整交互我还没说呢，下次找个时间给你讲讲！”

小黑：“好勒！”

#往期推荐#

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

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

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

# 帮助文本，不仅仅是简单的文本提示

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

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

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

恭喜您！