JSDuck 與 AngularJS 融合技巧

字數：1568

閱讀時間：10分鐘

<br/>

前言

  前面，咱們以一個實戰案例來詳細說明了如何在實際開發中使用JSDuck工具。可是，並非全部的時候，代碼的封裝方式都受咱們控制的。例如，若是咱們使用瞭如今的幾個主流框架AngularJS、React或者Vue的時候，代碼的封裝方式就必須按照框架定義的方式來構建。當咱們的代碼中出現了模塊、控制器、服務、指令等JSDuck徹底不認識的組成部分時，咱們該如何使用JSDuck來正確描述咱們的代碼呢？

  那麼，下面，筆者就以 AngularJS 爲例，來講一說筆者本身的解決方案。

<br/>

融合思路

  解決這個問題，有兩種思路。第一種，能夠將JSDuck不識別的代碼部分映射到工具識別的標籤來進行描述。第二種，既然沒有現成的標籤來描述這些新成員，那咱們能夠自定義一套標籤來描述它們。

  第一種方法更方便，不須要額外編碼；第二種方法更優雅，可是須要自定義一整套標籤。

  這裏，因爲筆者對文檔的要求主要是實用，不須要那麼完美，並且如今也沒有過多的精力來研發一整套標籤。因此，筆者選擇了第一種解決方案。

  第一種方案最核心的地方就是須要肯定AngularJS框架給咱們的代碼帶來了哪些新成員，然後如何將這些新成員映射到原有的標籤中去。

  AngularJS給咱們帶來了如下新成員：模塊、服務、指令、篩選器和控制器。而後映射關係以下：

新成員	映射的JSDuck標籤
模塊	模塊類（@class）
服務	服務類（@class）
指令	模塊類中的函數（@method）
篩選器	模塊類中的函數（@method）
控制器	控制器類（@class）

  其中，模塊是一個特殊的類，我叫它模塊類，它和其餘的類是經過命名空間和類名來區分的。例如，NgModule.layout ，就是個人一個模塊類，NgModule 這個命名空間就是專門存放模塊類的命名空間。

  服務是另外一種特殊的類，我叫它服務類，服務類和模塊類是經過命名空間來關聯的，而且服務類的名稱比較特殊，統一以 「$」 符號開頭。例如 , NgModule.layout.\$layoutTag 就是個人一個服務類，它的命名空間就是它所屬的模塊類。

  指令和篩選器就比較簡單了，他們都是所屬模塊類中的函數。

  控制器也是一個特殊的類，我叫他控制器類，它的命名空間是它所屬模塊類。與其餘類是經過類的名稱區分的，名稱統一以」Ctrl「結尾。例如：NgModule.frame3.frameCtrl 就是個人一個控制器類。這裏，父子控制器就直接經過父類子類來表示。

  總體的思路就是如此，那麼，下面咱仍是直接上代碼來講話吧！

<br/>

示例

  以下所示，就是咱們的一個模塊類的部分代碼（爲了方便查看，只留下了註釋，刪掉了具體實現）：

/**
     * 頁面通用小控件模塊
     * @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){
              
            }
        }
    });

  代碼上看已經很清晰了，這段代碼包含了模塊以及模塊中服務和指令的註釋方式。篩選器同指令，就不作贅述了。

<br/>

  下面，咱們再看看控制器的註釋方式：

/**
     * @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 。

<br/>

  至此，咱們就能夠按照這種方式來描述全部由於使用 AngularJS 框架而新增的代碼部分了。其餘的框架也能夠使用相同的辦法來處理。這種處理方式是一種折中方案，若是想要更加規範、優雅的話，建議使用自定義標籤來解決。

<br/>

<br/>

  歡迎大夥關注個人微信公衆號，和老司機一塊兒擼代碼：