如何编写 Cloud9 JavaScript IDE 的功能扩展

时间 2019-11-05

标签如何编写 cloud9 cloud javascript ide 功能扩展栏目云服务繁體版

原文原文链接

上周末咱们在JSConf.eu发布了 Cloud9 IDE ，同时发布了对应的GitHub项目。在4天时间里该项目获得340我的的关注和将近50个fork。Cloud9的口号是由"由Javascripters 为Javascripters建立的IED"，这口号有点递归，它意味着你能够hack这个ide使它变得更强大。Cloud9项目开始之初就尤为注意考虑这点了；Cloud9中的每个功能点都是一个扩展(extension)。在IED启动的时候咱们用优秀的 requireJS 库加载全部的扩展。前端UI使用 ajax.org platform (apf)，apf 使咱们轻松地模块化Cloud9的用户界面。下面开始详细介绍怎样为Cloud9编写扩展。javascript

一个扩展的生命周期是从它做为requireJS的模块开始的。我将简述requireJS的基本语法，想深刻了解requireJS请参考这个文档。一个扩展会依赖其余的扩展和一些核心模块。咱们将编写一个给编辑器中选定的JSON代码进行格式化的扩展。该扩展依赖核心模块：core/ide, core/ext, core/util 和编辑器管理扩展：ext/editors/editors.让咱们称该扩展为formatjson，而后将其置于ext文件夹下。html

 
           01 
           require.def("ext/formatjson/formatjson", 
          
           02 
               ["core/ide",  
          
           03 
                "core/ext",  
          
           04 
                "core/util",  
          
           05 
                "ext/editors/editors",  
          
           06 
                "text!ext/formatjson/formatjson.xml"], 
          
           07 
               function(ide, ext, util, editors, markup) { 
          
           08 
             
           09 
           return ext.register("ext/formatjson/formatjson", { 
          
           10 
                   //Object definition 
          
           11 
           }); 
          
           12 
             
           13 
               } 
          
           14 
           );

jingxing05
翻译于昨天(12:55)

0人顶前端

顶翻译的不错哦! java

require.def第一个参数标识扩展的名字，第二参数中 ide，ext ，util和 editors 表明传入该扩展依赖的对象引用，formatjson扩展的第五个依赖是加载为一个文本的xml文件。 ‘text!’ 语法告诉 requireJS 不要将参数引入的文件解析为 javascript，仅将其中的内容做为文本返回便可。全部依赖加载完毕后将调用第三个参数表明的回调函数，在回调函数中将咱们的扩展注册到扩展管理器中，让咱们看看扩展文件的结构。

{
    name   : "JSON Formatter",
    dev    : "Your Name Here",
    alone  : true,
    type   : ext.GENERAL,
    markup : markup,

    hook    : function(){},
    init    : function(){},
    enable  : function(){},
    disable : function(){},
    destroy : function(){}
}

属性和方法详解:node

属性

属性名	是否必须	描述
name	必须	扩展的名字，供管理器中显示
dev	可选	开发者名字，供扩展管理器中显示，主要是表彰开发者的荣誉
alone	可选	Boolean值，标识该扩展是个独立的扩展仍是某个扩展的子扩展
type	可选	扩展类型，如今只支持 ext.GENERAL和ext.EDITOR，这个属性极有可能在将来版本中弃用
markup	可选	String，该扩展的UI定义的标记文本
visible	可选	Boolean值标识该扩展在加载时是否可见，该属性仅对 Panel 扩展有效

jingxing05
翻译于昨天(13:25)

0人顶git

顶翻译的不错哦! github

方法

方法名	必须	描述
hook	可选	在扩展注册时调用该方法，容许你延迟该扩展的初始化。例如你能够添加一个菜单项来初始化该扩展。初始化的时候， markup 参数的值被解析而后调用 init方法。若是没有定义hook方法，则扩展注册时会当即初始化。当你指定hook后，就要本身全权负责扩展的初始化。扩展的初始化是由调用 ext.initExtension(_self);完成的，其中 _self 是.Panel 扩展一个个引用。对于panel hook函数一般只有一单单的一个声明:panels.register(this);
init	必须	初始化时解析完UI markup标记字符串后调用该函数。使全部markup中引入的该扩展的元素可用，并能够对应到其正确的位置。在扩展管理器中启动该扩展时也会调用该函数。对editor 型扩展，第一个参数是tab page元素，指示该扩展能够用之填充到本身的UI.Panel 对panel ，第一个参数应该给this.panel传一个在Cloud9 UI的panel元素 (一般是window元素)。 ajax
enable	必须	前端启用该扩展时调用。这个函数是经过在前端菜单中点击某个panel扩展时被当即调用的(例如点击完某个菜单项后显现勾勾的这个动做)。不要与在扩展管理器中的启用和禁用扩展混淆，启禁扩展调用的是 destroy和init方法
disable	必须	前端停用扩展时调用。这个函数是经过在前端菜单中点击隐藏panel扩展时被当即调用的(例如点击完某个菜单项后勾勾不显示的这个动做)。不要与在扩展管理器中的启用和禁用扩展混淆，启禁扩展调用的是 destroy和init方法
destroy	必须	注销扩展时调用。注销时清除引入的UI元素，事件处理器，和其余状态等。在扩展管理器中禁用扩展时调用。

jingxing05
翻译于昨天(14:41)

0人顶json

顶翻译的不错哦! windows

实现 Format JSON扩展

好，如今咱们已经有了基本概念，让咱们开始真正来实现 format json扩展。首先完成咱们须要属性和方法。我将添加一nodes数组，其中包含该扩展所需的全部UI元素。咱们用hook方法来建立一个菜单来初始化 formatjson扩展，并显示一个格式化窗口接受用户输入的缩进值。代码以下：

{
    name   : "JSON Formatter",
    dev    : "Ajax.org",
    alone  : true,
    type   : ext.GENERAL,
    markup : markup,

    nodes : [],

    hook : function(){
        var _self = this;
        this.nodes.push(
            mnuEdit.appendChild(new apf.item({
                caption : "Format JSON",
                onclick : function(){
                    ext.initExtension(_self);
                    _self.winFormat.show();
                }
            }))
        );
    },

    init : function(amlNode){
        this.winFormat = winFormat;
    },

    enable : function(){
        this.nodes.each(function(item){
            item.enable();
        });
    },

    disable : function(){
        this.nodes.each(function(item){
            item.disable();
        });
    },

    destroy : function(){
        this.nodes.each(function(item){
            item.destroy(true, true);
        });
        this.nodes = [];
        this.winFormat.destroy(true, true);
    }
}

在hook方法中建立一个菜单依附到mnuEdit。mnuEdit是对编辑器菜单的全局引用。如今咱们的UI元素的名字挂靠在全局命名空间下(可能会在未来的版本中变动)。Cloud9中可用的UI元素表以下，并指定了哪些扩展添加了这个元素。

Name	Extension	Purpose
mnuFile		顶部菜单栏的 File 菜单
mnuEdit		顶部菜单栏的 Edit 菜单
mnuView		顶部菜单栏的 View菜单
mnuEditors		view菜单的 editors
mnuModes		Window菜单的布局菜单
mnuPanels	ext/panels/panels	顶部菜单栏的windows菜单
vbMain		布局的主vbox
tbMain		主菜单栏
barMenu		菜单
barTools		主菜单栏的第一栏
sbMain		底部的状态栏
mnuFile
mnuFile
winDbgConsole	ext/console/console	控制台面板
tabConsole	ext/console/console	控制台窗口的tab元素
winFilesViewer	ext/tree/tree	树面板
trFiles	ext/tree/tree	树面板中的树元素

jingxing05
翻译于昨天(15:07)

0人顶

顶翻译的不错哦!

还有更多建好的元素。能够在各自的扩展或经过DOM/XPath操做找到他们。例如在工具栏和状态栏之间有一个hbox包含3个vbox元素。

<a:hbox>
    <a:vbox />
    <a:vbox />
    <a:vbox />
</a:hbox>

能够用XPath选择器来访问元素:

vbMain.selectSingleNode("a:hbox/a:vbox[2]");

这条查询将定位到hbox中的第二个vbox。这个vbox含有了打开的文件tab和控制台面板。而后你能够像咱们在formatjson扩展中对菜单的处理方法同样将你想要的元素添加到该vbox。

jingxing05
翻译于昨天(15:15)

0人顶

顶翻译的不错哦!

MarkupUI 标记

而后format json 扩展会弹出个窗口给用户来设置缩进的空格数。咱们用aml标记语法来建立这个窗口。我将aml代码放到名为formatjson.xml的xml文件中，并在最外层添加了一个扩展所需的根元素：a:application，看起来像这样:

<a:application xmlns:a="http://ajax.org/2005/aml">
    <!-- Your UI markup here -->
</a:application>

UI标记能够包含html和 AML元素。咱们使用AML的一个下拉列表spinner和两个按钮来描述对json格式化的窗口。

<a:window
  id        = "winFormat"
  title     = "Format JSON"
  center    = "true"
  modal     = "false"
  buttons   = "close"
  kbclose   = "true"
  width     = "200">
    <a:vbox>
        <a:hbox padding="5" edge="10">
            <a:label width="100">Indentation</a:label>
            <a:spinner id="spIndent" flex="1" min="1" max="20" />
        </a:hbox>
        <a:divider />
        <a:hbox pack="end" padding="5" edge="10 10 5 10">
            <a:button default="2" caption="Format" 
              onclick = "
                require('ext/formatjson/formatjson').format(spIndent.value);
              "/>
            <a:button onclick="winFormat.hide()">Done</a:button>
        </a:hbox>
    </a:vbox>
</a:window>

格式化按钮绑定了onclick事件来调用咱们扩展的format方法，它传入了spinner的值。这就是咱们在扩展中须要实现的方法，让咱们动手吧。

jingxing05
翻译于昨天(15:34)

0人顶

顶翻译的不错哦!

自定义函数

格式化函数有一个参数，来指定json中缩进的空格数。首先获取当前选择的代码，若是选中的代码为有效的json，则对其格式化，更新到当前选中的代码，不然给用户一个错误提示。

咱们须要加载另外一个依赖来完成该功能，就是ace编辑器的Range模块。因而我在顶部将ace/Range添加到依赖列表中，而后调用参数"Range"。格式化函数看起来以下(我给每一个部分添加了注解)。

{
    ...

    format : function(indent){
        //获取当前编辑器
        var editor = editors.currentEditor;

        //从当前编辑器获取选中的对象
        var sel   = editor.getSelection();

        //获取当前的文档对象引用
        var doc   = editor.getDocument();

        //获取当前选中对象的range对象
        var range = sel.getRange();

        //从range对象获取选中的文本
        var value = doc.getTextRange(range);

        //尝试将选中的文本转换为JSON，并格式化 
        //而后再回转为文本字符串，若是出现错误则给用户显示错误.
        try{
            value = JSON.stringify(JSON.parse(value), null, indent);
        }
        catch(e){
            util.alert(
                "Invalid JSON", 
                "The selection contains an invalid or incomplete JSON string",
                "Please correct the JSON and try again");
            return;
        }

        //若是格式化成功则用格式化后值替换掉range对象
        var end = doc.replace(range, value);

        //用格式化的值更新当前选中的部分

sel.setSelectionRange(Range.fromPoints(range.start, end));

},

    ...
}

咱们的扩展示在可使用了，但让咱们再添加点东西。

jingxing05
翻译于昨天(17:27)

0人顶

顶翻译的不错哦!

Key快捷键绑定

我但愿使用快捷键来使用这个扩展，window使用: Ctrl-Shift-J，mac用Command-Shift-J。Cloud9中用户能够自行配置快捷键。要实现上述功能，还需几个步骤。首先在 ext/keybindings_default文件中为咱们的扩展新添windows和mac的默认键绑定部分。

...

"ext" : {
    ...
    "formatjson" : {
        "format" : "Ctrl-Shift-J" // Or "Command-Shift-J" for the mac file
    },
    ...
}

...

而后必需要让快捷键管理器知道该扩展对什么快捷键响应和显示什么UI元素。添加名为hotkeys和hotitems的hash表：

hotkeys  : {"format":1},
    hotitems : {},

如今你有两种途径为键绑定添加处理器了。直接的方式是在扩展中添加响应方法，方法的名称与hotkeys中指定的名称相同便可，此处就是“format”。由于咱们的json格式化扩展有一个菜单来显示快捷键，我更喜欢将响应方法链接到菜单的onclick事件上，这样当我按下快捷键时这个方法被执行。并且当我使用快捷键时这个菜单按钮应该点亮。能够在hotitems哈希表中添加菜单项来达到目的:

this.hotitems["format"] = [this.nodes[0]];

如今咱们能够在Tools菜单下的Extendtion Manage中来激活该扩展了，能够观看下面这段视频来看看，如何在3分钟内完成这个扩展。(视频下载)

jingxing05
翻译于昨天(18:04)

0人顶

顶翻译的不错哦!

其余资源

When you need help with creating an extension 在你开发扩展须要帮助的时候请到Cloud9的 Google Group 。能够向github的issue跟踪issue tracker of GitHub提交任何你发现的问题。Cloud9的全部开发者在Twitter上十分活跃。在扩展Cloud9的路上祝你好运。我都等不及要看你会扩展出什么了。咱们很是乐意将你酷毙了的扩展添加为Cloud9的子模块，或者在Github上提交pull request。

玩得开心!

如何编写 Cloud9 JavaScript IDE 的功能扩展

jingxing05翻译于 昨天(12:55)

属性

jingxing05翻译于 昨天(13:25)

方法

jingxing05翻译于 昨天(14:41)

实现 Format JSON扩展

jingxing05翻译于 昨天(15:07)

jingxing05翻译于 昨天(15:15)

MarkupUI 标记

jingxing05翻译于 昨天(15:34)

自定义函数

jingxing05翻译于 昨天(17:27)

Key快捷键绑定

jingxing05翻译于 昨天(18:04)

其余资源

jingxing05
翻译于昨天(12:55)

jingxing05
翻译于昨天(13:25)

jingxing05
翻译于昨天(14:41)

jingxing05
翻译于昨天(15:07)

jingxing05
翻译于昨天(15:15)

jingxing05
翻译于昨天(15:34)

jingxing05
翻译于昨天(17:27)

jingxing05
翻译于昨天(18:04)