JSDuck 与 AngularJS 融合技巧

摘要：融合思路解决这个问题，有两种思路。给我们带来了以下新成员模块服务指令筛选器和控制器。与其他类是通过类的名称区分的，名称统一以结尾。这种处理方式是一种折中方案，如果想要更加规范优雅的话，建议使用自定义标签来解决。

字数：1568

阅读时间：10分钟

  前面，我们以一个实战案例来详细说明了如何在实际开发中使用JSDuck工具。但是，并不是所有的时候，代码的封装方式都受我们控制的。例如，如果我们使用了现在的几个主流框架AngularJS、React或者Vue的时候，代码的封装方式就必须按照框架定义的方式来构建。当我们的代码中出现了模块、控制器、服务、指令等JSDuck完全不认识的组成部分时，我们该如何使用JSDuck来正确描述我们的代码呢？

  那么，下面，笔者就以 AngularJS 为例，来说一说笔者自己的解决方案。

  解决这个问题，有两种思路。第一种，可以将JSDuck不识别的代码部分映射到工具识别的标签来进行描述。第二种，既然没有现成的标签来描述这些新成员，那我们可以自定义一套标签来描述它们。

  第一种方法更方便，不需要额外编码；第二种方法更优雅，但是需要自定义一整套标签。

  这里，由于笔者对文档的要求主要是实用，不需要那么完美，而且现在也没有过多的精力来研发一整套标签。所以，笔者选择了第一种解决方案。

  第一种方案最核心的地方就是需要确定AngularJS框架给我们的代码带来了哪些新成员，而后如何将这些新成员映射到原有的标签中去。

  AngularJS给我们带来了以下新成员：模块、服务、指令、筛选器和控制器。然后映射关系如下：

  其中，模块是一个特殊的类，我叫它模块类，它和其他的类是通过命名空间和类名来区分的。例如，NgModule.layout ，就是我的一个模块类，NgModule 这个命名空间就是专门存放模块类的命名空间。

  服务是另一种特殊的类，我叫它服务类，服务类和模块类是通过命名空间来关联的，并且服务类的名称比较特殊，统一以 “$” 符号开头。例如 , NgModule.layout.$layoutTag 就是我的一个服务类，它的命名空间就是它所属的模块类。

  指令和筛选器就比较简单了，他们都是所属模块类中的函数。

  控制器也是一个特殊的类，我叫他控制器类，它的命名空间是它所属模块类。与其他类是通过类的名称区分的，名称统一以”Ctrl“结尾。例如：NgModule.frame3.frameCtrl 就是我的一个控制器类。这里，父子控制器就直接通过父类子类来表示。

  整体的思路就是如此，那么，下面咱还是直接上代码来说话吧！

  如下所示，就是我们的一个模块类的部分代码（为了方便查看，只留下了注释，删掉了具体实现）：

    /**
     * 页面通用小控件模块
     * @class NgModule.layout
     * @alias gm.ngCustom.layout
     * @author lsjcoder
     */
    angular.module("gm.ngCustom.layout",[]).provider("$layoutTag",
    /**
     * 表示查询项的标签的服务
     * @class NgModule.layout.$layoutTag
     * @alias $layoutTag
     * @author lsjcoder
     */
    function() {
        this.$get = [function () {
            function factory() {
                var $layout = {};

                /**
                 * @member NgModule.layout.$layoutTag
                 * @method  getCheckedTags 获取选中的标签
                 * @param {Array} tags 标签集合
                 * @returns {Array} 选中的标签集合
                 */
                $layout.getCheckedTags = function(tags){
                };

                /**
                 * @member NgModule.layout.$layoutTag
                 * @method clearCheck 清空选择
                 * @param {Array} tags 标签集合
                 */
                $layout.clearCheck = function(tags){
                };
                return $layout;
            }
            return factory;
        }];
    }).directive("gmTags",["$layoutTag",
    /**
     * @member NgModule.layout
     * @method gmTags 标签指令，EAC模式
     * @param {Number} [max-tag-num] DOM属性传值，外部显示出来的标签最大个数，默认会自动根据页面宽度计算
     * @param {Boolean} [multi = true] DOM属性传值，是否开启多选模式
     * @param {Object} tagdata 作用于传值，指令配置项
     * @param {String} tagdata.checkTag 选中标签后调用函数的名称
     * @param {Array} tagdata.tags 标签数据
     */
    function($layoutTag){
        //查询表单中标签指令
        return {
            restrict: "ECA",
            templateUrl: "tag.tpl.html",
            replace: true,
            scope: {
                tagdata: "="
            },
            link: function (scope, element, attr, transclution) {
            }
        }
    }]).directive("dateChoose",
    /**
     * @member NgModule.layout
     * @method dateChoose 日期指令，EAC模式
     */
    function(){
        return {
            restrict:"EAC",
            link :function(scope,element,attr,transclution){
            }
        }
    }).directive("timeChoose",
    /**
     * @member NgModule.layout
     * @method timeChoose 时间指令，EAC模式
     */
    function(){
        return {
            restrict:"EAC",
            link :function(scope,element,attr,transclution){
              
            }
        }
    });

  代码上看已经很清晰了，这段代码包含了模块以及模块中服务和指令的注释方式。筛选器同指令，就不做赘述了。

  下面，我们再看看控制器的注释方式：

    /**
     * @class NgModule.frame3 frame3模块
     * @alias frame3
     * @author lsjcoder
     */
    var frameApp = angular.module("frameApp",[]);

    /**
     * @class NgModule.frame3.frameCtrl 框架控制器
     * @extends NgModule.frame.frameCtrl
     * @author lsjcoder
     */
    frameApp.controller("frameCtrl",["$scope",function($scope){
       /**
         * @member NgModule.frame3.frameCtrl
         * @method refreshPage 刷新路由页面
         * @param  {String} strPath 路由地址
         * @author lsjcoder
         */
        $scope.refreshPage = function(strPath){
           
        };
    }]);

  如上代码所示，我声明了一个控制器 NgModule.frame3.frameCtrl ，它属于模块 NgModule.frame3 ，父控制器是 NgModule.frame.frameCtrl ，内部有一个函数成员 refreshPage 。

  至此，我们就可以按照这种方式来描述所有因为使用 AngularJS 框架而新增的代码部分了。其他的框架也可以使用相同的办法来处理。这种处理方式是一种折中方案，如果想要更加规范、优雅的话，建议使用自定义标签来解决。

  欢迎大伙关注我的微信公众号，和老司机一起撸代码：