Devil May Code...

Vergil's Blog

前言

一般来说,AJAX请求与普通HTTP请求没有任何的区别。但jQuery框架会在Request header加上X-Requested-With:XMLHttpRequest

但这并不是一个标准,所以并非所有AJAX请求都会发送这个request header。原生的XMLHttpRequest对象就没有这个东西。

AngularJS的$http服务也不会发送这个header。

由于jQuery的流行,很多PHP框架会以此来判断这个请求是否AJAX。

例如:

LaravelIlluminate\Http\Request::ajax()方法。该类继承自Symfony框架的Symfony\Component\HttpFoundation\Request并使用了它的isXmlHttpRequest()来判断是否AJAX请求。

国内著名的ThinkPHP框架,IS_AJAX常量也是以此来判断是否AJAX。

define('IS_AJAX', ((isset($_SERVER['HTTP_X_REQUESTED_WITH']) && strtolower($_SERVER['HTTP_X_REQUESTED_WITH']) == 'xmlhttprequest') 

阅读剩余部分...


上一篇博文提到,是由于jQuery.val()方法设置DOM元素的值的时候,并没有触发AngularJS的$digest循环。然后我写了一个directive来解决这个问题。

那是否可以有一个更加通用的方法,让AngularJS适应其他使用val()方法设置值的jQuery插件呢?如何让val()自动触发DOM事件??

jQuery Hooks

豆浆油条求助,得知jQuery有一个API,称为“hook(钩子)”(怪自己不去看官方文档)。

Hooks可以使用在val()css()attr()prop()这些getter/setter方法上。如果你设置了hook,当你调用这些函数的时候,jQuery会触发你hook定义的方法。

Hooks签名如下:

var someHook = {
    get: function(elem) {
        // obtain and return a value
        return "something";
    },
    set: function(elem, value) {
        // do something with value
    }
}

.val() Hooks

valHooks允许我们拦截.val()的功能

HTML:

<input type="text" id="t" />

JavaScript:

$.valHooks.text = {
    set: function(elem, val) {
        elem.value = 'hello  ' + val;
        return true;
    },
    get: function(elem) {
        return 'fuck';
    }
}

$('#t').val('world!');      //设置值为:hello world!
$('#t').val();              //返回:fuck

.css() Hooks

以后补充

.prop()和.attr() Hooks

以后补充

使用valHooks让jQuery.val()与AngularJS模型数据同步

知道Hooks之后,我们就可以拦截.val()的功能,在设置好值之后,触发一个让AngularJS进入$degist的情况。比如,触发input事件

Example:

<!doctype html>
<html ng-app="app">
    <head>
        <script src="http://cdn.bootcss.com/jquery/2.2.0/jquery.min.js"></script>
        <script src="http://cdn.bootcss.com/angular.js/1.4.8/angular.min.js"></script>
        <script>
            $(function(){
                $('#setvalue').on('click', function() {
                    $('#input').val('hello world!');
                });

                $.valHooks.text = {
                    set: function(elem, val) {
                        elem.value = val;   //把DOM元素设置为传进来的val值
                        $(elem).trigger('input');  //触发input事件
                        return true;
                    }
                };
            });
        </script>
    </head>
    <body>
        <div>
            <input type="text" ng-model="value" id="input" />
            <button type="button" id="setvalue">jQuery set value</button>
            <p>ng model value is:{{value}}</p>
        </div>
    </body>
</html>

OK,那么现在,使用val()方法设置元素的值之后,也可能让AngularJS的模型同步了。

一般情况下,这样子确实可以解决问题,但如果你不想让它触发input事件呢?比如说,你的input事件有另外的功能。

我的思路就是,触发一个自定义事件,写一个directive监听该事件。

Example:

<!doctype html>
<html ng-app="app">
    <head>
        <script src="http://cdn.bootcss.com/jquery/2.2.0/jquery.min.js"></script>
        <script src="http://cdn.bootcss.com/angular.js/1.4.8/angular.min.js"></script>
        <script>
            $(function(){
                $('#setvalue').on('click', function() {
                    $('#input').val('hello world!');
                });

                $.valHooks.text = {
                    set: function(elem, val) {
                        elem.value = val;
                        $(elem).trigger('jquery.set.value');    //触发自定义事件
                        return true;
                    }
                };
            });
        </script>
    </head>
    <body>
        <div>
            <!-- 注意这个input标签使用了jqSetValue组件 -->
            <input type="text" ng-model="value" id="input" jq-set-value />
            <button type="button" id="setvalue">jQuery set value</button>
            <p>ng model value is:{{value}}</p>
        </div>
        <script>
            angular.module('app', []).directive('jqSetValue', function() {
                return {
                    restrict: 'AC',
                    require: '?ngModel',
                    link: function(scope, element, attrs, ngModel) {
                         //设置自定义事件的回调函数
                        element.on('jquery.set.value', function(event) {
                            if(!ngModel) return;
                            scope.$apply(function(){
                                ngModel.$setViewValue($(element).val());
                            });
                        });
                    }
                };
            });
        </script>
    </body>
</html>

今天在AngularJS下使用Fuel UXspinbox时出现了问题:

如果手动输入input的值,一切正常。但如果使用spinbox的增加/减少按钮时,DOM已经被改变,$scope却无法同步修改后的值。

示例代码如下:

<div class="spinbox" data-initialize="spinbox" id="mySpinbox">
  <input type="text" class="form-control input-mini spinbox-input" ng-model="number">
  <div class="spinbox-buttons btn-group btn-group-vertical">
    <button type="button" class="btn btn-default spinbox-up btn-xs">
      <span class="glyphicon glyphicon-chevron-up"></span><span class="sr-only">Increase</span>
    </button>
    <button type="button" class="btn btn-default spinbox-down btn-xs">
      <span class="glyphicon glyphicon-chevron-down"></span><span class="sr-only">Decrease</span>
    </button>
  </div>
</div>

Why?

查看FuelUX源码可以发现它是使用jQuery的val()方法去修改DOM的值的(猜也猜到-_-||)。所以并没有启动$digest循环,详细看这篇文章

解决办法

最简单的方法就是直接改FuelUX的源码,找到它调用render()方法之后,触发一下input事件:

this.$element.trigger('input');     

不过这种修改别人源码的做法非常不好

那么,我写了一个directive来更新模型:

angular.module('your-app').directive('spinbox', ['$parse', function($parse) {
    return {
        restrict: 'C',      //以ClassName的形式被声明
        link: function(scope, element, attrs) {
            element.on('changed.fu.spinbox', function() {
                var $spinbox = angular.element(this);
                var $input = $spinbox.find('.spinbox-input');
                var model = $input.attr('ng-model');

                if (!model) return;

                var setter = $parse(model).assign;
                scope.$apply(function(){
                    setter(scope, $spinbox.spinbox('value'));
                });
            });

        }
    }
}]);

使用jQuery钩子与AngularJS模型数据同步

OK,如果有更好的方法,欢迎讨论:)


Angular Team Endorsed

非常感谢领导Angular团队的Igor Minar对本指南做出的审查和贡献,并且委托我继续打理本指南。

目的

Angular规范@john_papa

如果你正在寻找一些关于语法、约定和结构化的Angular应用的一个有建设性的规范,那么你来对地方了。这里所包含的内容是基于我在团队中使用Angular的一些经验、一些演讲和Pluralsight培训课程

这个规范的目的是为构建Angular应用提供指导,当然更加重要的是让大家知道我为什么要选择它们。

如果你喜欢这个规范,请在Pluralsight看看Angular Patterns: Clean Code

Angular Patterns: Clean Code

Community Awesomeness and Credit

Angular社区是一个热衷于分享经验的令人难以置信的社区,尽管Todd Motto(他是我的一个朋友,也是Angular专家)和我合作了多种规范和惯例,但是我们也存在着一些分歧。我鼓励你去看看Todd的指南,在那里你能看到我们之间的区别。

我的许多规范都是从大量的程序会话Ward Bell和我所拥有的而来的,我的好友Ward也影响了本规范的最终演变。

在示例App中了解这些规范

看示例代码有助于你更好地理解,你可以在modular文件夹下找到命名为modular的示例应用程序,随便克隆。

##翻译
Angular规范翻译版本

##目录

  1. 单一职责
  2. IIFE
  3. Modules
  4. Controllers
  5. Services
  6. Factories
  7. Data Services
  8. Directives
  9. 解决Controller的Promises
  10. 手动依赖注入
  11. 压缩和注释
  12. 异常处理
  13. 命名
  14. 应用程序结构LIFT原则
  15. 应用程序结构
  16. 模块化
  17. 启动逻辑
  18. Angular $包装服务
  19. 测试
  20. 动画
  21. 注释
  22. JSHint
  23. JSCS
  24. 常量
  25. 文件模板和片段
  26. Yeoman Generator
  27. 路由
  28. 任务自动化
  29. Filters
  30. Angular文档
  31. 贡献
  32. 许可

单一职责

###规则一

[Style Y001]
  • 一个文件只定义一个组件。

    下面的例子在同一个文件中定义了一个app的module和它的一些依赖、一个controller和一个factory。

/* avoid */
angular
  .module('app', ['ngRoute'])
  .controller('SomeController', SomeController)
  .factory('someFactory', someFactory);

function SomeController() { }

function someFactory() { }

推荐以下面的方式来做,把上面相同的组件分割成单独的文件。

/* recommended */

// app.module.js
angular
    .module('app', ['ngRoute']);
/* recommended */

// someController.js
angular
      .module('app')
      .controller('SomeController', SomeController);

function SomeController() { }
/* recommended */
// someFactory.js
angular
      .module('app')
      .factory('someFactory', someFactory);

function someFactory() { }

返回顶部

IIFE

JavaScript闭包

[Style Y010]
  • 把Angular组件包装到一个立即调用函数表达式中(IIFE)。

为什么?:把变量从全局作用域中删除了,这有助于防止变量和函数声明比预期在全局作用域中有更长的生命周期,也有助于避免变量冲突。

为什么?:当你的代码为了发布而压缩了并且被合并到同一个文件中时,可能会有很多变量发生冲突,使用了IIFE(给每个文件提供了一个独立的作用域),你就不用担心这个了。

/* avoid */
// logger.js
angular
    .module('app')
    .factory('logger', logger);

// logger function会被当作一个全局变量
function logger() { }

// storage.js
angular
    .module('app')
    .factory('storage', storage);

// storage function会被当作一个全局变量
function storage() { }
/**
 * recommended
 *
 * 再也不存在全局变量了
 */

// logger.js
(function() {
    'use strict';

    angular
        .module('app')
        .factory('logger', logger);

    function logger() { }
})();

// storage.js
(function() {
    'use strict';

    angular
        .module('app')
        .factory('storage', storage);

    function storage() { }
})();
  • 注:为了简洁起见,本规范余下的示例中将会省略IIFE语法。

  • 注:IIFE阻止了测试代码访问私有成员(正则表达式、helper函数等),这对于自身测试是非常友好的。然而你可以把这些私有成员暴露到可访问成员中进行测试,例如把私有成员(正则表达式、helper函数等)放到factory或是constant中。

返回顶部

Modules

###避免命名冲突

[Style Y020]
  • 每一个独立子模块使用唯一的命名约定。

为什么:避免冲突,每个模块也可以方便定义子模块。

###定义(aka Setters)

[Style Y021]
  • 不使用任何一个使用了setter语法的变量来定义modules。

    为什么?:在一个文件只有一个组件的条件下,完全不需要为一个模块引入一个变量。

/* avoid */
var app = angular.module('app', [
    'ngAnimate',
    'ngRoute',
    'app.shared',
    'app.dashboard'
]);
你只需要用简单的setter语法来代替。
/* recommended */
angular
      .module('app', [
      'ngAnimate',
      'ngRoute',
      'app.shared',
      'app.dashboard'
  ]);

###Getters

[Style Y022]
  • 使用module的时候,避免直接用一个变量,而是使用getter的链式语法。

    为什么?:这将产生更加易读的代码,并且可以避免变量冲突和泄漏。

/* avoid */
var app = angular.module('app');
app.controller('SomeController', SomeController);

function SomeController() { }
/* recommended */
angular
    .module('app')
    .controller('SomeController', SomeController);

function SomeController() { }

###Setting vs Getting

[Style Y023]
  • 只能设置一次。

为什么?:一个module只能被创建一次,创建之后才能被检索到。

- 设置module,`angular.module('app', []);`。
- 获取module,`angular.module('app');`。

###命名函数 vs 匿名函数

[Style Y024]
  • 回调函数使用命名函数,不要用匿名函数。

    为什么?:易读,方便调试,减少嵌套回调函数的数量。

/* avoid */
angular
    .module('app')
    .controller('Dashboard', function() { })
    .factory('logger', function() { });
/* recommended */

// dashboard.js
angular
    .module('app')
    .controller('Dashboard', Dashboard);

function Dashboard () { }
// logger.js
angular
    .module('app')
    .factory('logger', logger);

function logger () { }

回到顶部

Controllers

###controllerAs在View中的语法

[Style Y030]
  • 使用controllerAs 语法代替直接用经典的$scope定义的controller的方式。

    为什么?:controller被构建的时候,就会有一个新的实例,controllerAs 的语法比经典的$scope语法更接近JavaScript构造函数。

    为什么?:这促进在View中对绑定到“有修饰”的对象的使用(例如用customer.name 代替name),这将更有语境、更容易阅读,也避免了任何没有“修饰”而产生的引用问题。

    为什么?:有助于避免在有嵌套的controllers的Views中调用 $parent

<!-- avoid -->
<div ng-controller="Customer">
  {{ name }}
</div>
<!-- recommended -->
<div ng-controller="Customer as customer">
  {{ customer.name }}
</div>

###controllerAs在controller中的语法

[Style Y031]
  • 使用 controllerAs 语法代替 经典的$scope语法 语法。

  • 使用controllerAs 时,controller中的$scope被绑定到了this上。

    为什么?controllerAs$scope的语法修饰,你仍然可以绑定到View上并且访问 $scope的方法。

    为什么?:避免在controller中使用 $scope,最好不用它们或是把它们移到一个factory中。factory中可以考虑使用$scope,controller中只在需要时候才使用$scope,例如当使用$emit$broadcast,或者 $on

/* avoid */
function Customer ($scope) {
    $scope.name = {};
    $scope.sendMessage = function() { };
}
/* recommended - but see next section */
function Customer () {
    this.name = {};
    this.sendMessage = function() { };
}

###controllerAs with vm

[Style Y032]
  • 使用controllerAs语法时把this 赋值给一个可捕获的变量,选择一个有代表性的名称,例如vm代表ViewModel。

为什么?this在不同的地方有不同的语义(就是作用域不同),在controller中的一个函数内部使用this时可能会改变它的上下文。用一个变量来捕获this的上下文从而可以避免遇到这样的坑。

/* avoid */
function Customer() {
    this.name = {};
    this.sendMessage = function() { };
}
/* recommended */
function Customer () {
    var vm = this;
    vm.name = {};
    vm.sendMessage = function() { };
}
  • 注:你可以参照下面的做法来避免 jshint的警告。但是构造函数(函数名首字母大写)是不需要这个的.
/* jshint validthis: true */
var vm = this;
  • 注:在controller中用controller as创建了一个watch时,可以用下面的语法监测vm.*的成员。(创建watch时要谨慎,因为它会增加更多的负载)
<input ng-model="vm.title"/>
function SomeController($scope, $log) {
    var vm = this;
    vm.title = 'Some Title';

    $scope.$watch('vm.title', function(current, original) {
        $log.info('vm.title was %s', original);
        $log.info('vm.title is now %s', current);
    });
}

###置顶绑定成员

[Style Y033]
  • 把可绑定的成员放到controller的顶部,按字母排序,并且不要通过controller的代码传播。

为什么?:虽然设置单行匿名函数很容易,但是当这些函数的代码超过一行时,这将极大降低代码的可读性。在可绑定成员下面定义函数(这些函数被提出来),把具体的实现细节放到下面,可绑定成员置顶,这会提高代码的可读性。

/* avoid */
function Sessions() {
    var vm = this;

    vm.gotoSession = function() {
      /* ... */
    };
    vm.refresh = function() {
      /* ... */
    };
    vm.search = function() {
      /* ... */
    };
    vm.sessions = [];
    vm.title = 'Sessions';
/* recommended */
function Sessions() {
    var vm = this;

    vm.gotoSession = gotoSession;
    vm.refresh = refresh;
    vm.search = search;
    vm.sessions = [];
    vm.title = 'Sessions';

    ////////////

    function gotoSession() {
      /* */
    }

    function refresh() {
      /* */
    }

    function search() {
      /* */
    }

Controller Using &quot;Above the Fold&quot;

注:如果一个函数就是一行,那么只要不影响可读性就把它放到顶部。

/* avoid */
function Sessions(data) {
    var vm = this;

    vm.gotoSession = gotoSession;
    vm.refresh = function() {
        /**
         * lines
         * of
         * code
         * affects
         * readability
         */
    };
    vm.search = search;
    vm.sessions = [];
    vm.title = 'Sessions';
/* recommended */
function Sessions(dataservice) {
    var vm = this;

    vm.gotoSession = gotoSession;
    vm.refresh = dataservice.refresh; // 1 liner is OK
    vm.search = search;
    vm.sessions = [];
    vm.title = 'Sessions';

###函数声明隐藏实现细节

[Style Y034]
  • 使用函数声明来隐藏实现细节,置顶绑定成员,当你需要在controller中绑定一个函数时,把它指向一个在文件的后面会出现函数声明。更多详情请看这里

为什么?:易读,易识别哪些成员可以在View中绑定和使用。

为什么?:把函数的实现细节放到后面,你可以更清楚地看到重要的东西。

为什么?:由于函数声明会被置顶,所以没有必要担心在声明它之前就使用函数的问题。

为什么?:你再也不用担心当 a依赖于 b时,把var a放到var b之前会中断你的代码的函数声明问题。

为什么?:函数表达式中顺序是至关重要的。

/**
 * avoid
 * Using function expressions.
 */
function Avengers(dataservice, logger) {
    var vm = this;
    vm.avengers = [];
    vm.title = 'Avengers';

    var activate = function() {
        return getAvengers().then(function() {
            logger.info('Activated Avengers View');
        });
    }

    var getAvengers = function() {
        return dataservice.getAvengers().then(function(data) {
            vm.avengers = data;
            return vm.avengers;
        });
    }

    vm.getAvengers = getAvengers;

    activate();
}

注意这里重要的代码分散在前面的例子中。
下面的示例中,可以看到重要的代码都放到了顶部。实现的详细细节都在下方,显然这样的代码更易读。

/*
 * recommend
 * Using function declarations
 * and bindable members up top.
 */
function Avengers(dataservice, logger) {
    var vm = this;
    vm.avengers = [];
    vm.getAvengers = getAvengers;
    vm.title = 'Avengers';

    activate();

    function activate() {
        return getAvengers().then(function() {
            logger.info('Activated Avengers View');
        });
    }

    function getAvengers() {
        return dataservice.getAvengers().then(function(data) {
            vm.avengers = data;
            return vm.avengers;
        });
    }
}

###把Controller中的逻辑延迟到Service中

[Style Y035]
  • 通过委派到service和factory中来延迟controller中的逻辑。

为什么?:把逻辑放到service中,并通过一个function暴露,就可以被多个controller重用。

为什么?:把逻辑放到service中将会使单元测试的时候更加容易地把它们分离,相反,如果在controller中调用逻辑就显得很二了。

为什么?:保持controller的简洁。

为什么?:从controller中删除依赖关系并且隐藏实现细节。

/* avoid */
function Order($http, $q, config, userInfo) {
    var vm = this;
    vm.checkCredit = checkCredit;
    vm.isCreditOk;
    vm.total = 0;

    function checkCredit () {
        var settings = {};
        // Get the credit service base URL from config
        // Set credit service required headers
        // Prepare URL query string or data object with request data
        // Add user-identifying info so service gets the right credit limit for this user.
        // Use JSONP for this browser if it doesn't support CORS
        return $http.get(settings)
            .then(function(data) {
               // Unpack JSON data in the response object
               // to find maxRemainingAmount
               vm.isCreditOk = vm.total <= maxRemainingAmount
            })
            .catch(function(error) {
               // Interpret error
               // Cope w/ timeout? retry? try alternate service?
               // Re-reject with appropriate error for a user to see
            });
    };
}
/* recommended */
function Order (creditService) {
    var vm = this;
    vm.checkCredit = checkCredit;
    vm.isCreditOk;
    vm.total = 0;

    function checkCredit () {
        return creditService.isOrderTotalOk(vm.total)
          .then(function(isOk) { vm.isCreditOk = isOk; })
          .catch(showServiceError);
    };
}

###保持Controller的专一性

[Style Y037]
  • 一个view定义一个controller,尽量不要在其它view中使用这个controller。把可重用的逻辑放到factory中,保证controller只服务于当前视图。

    为什么?:不同的view用同一个controller是非常不科学的,良好的端对端测试覆盖率对于保证大型应用稳定性是必需的。

###分配Controller

[Style Y038]
  • 当一个controller必须匹配一个view时或者任何一个组件可能被其它controller或是view重用时,连同controller的route一起定义。

    注:如果一个view是通过route外的其它形式加载的,那么就用ng-controller="Avengers as vm"语法。

    为什么?:在route中匹配controller允许不同的路由调用不同的相匹配的controller和view,当在view中通过ng-controller分配controller时,这个view总是和相同的controller相关联。

 /* avoid - when using with a route and dynamic pairing is desired */

 // route-config.js
 angular
     .module('app')
     .config(config);

 function config ($routeProvider) {
     $routeProvider
         .when('/avengers', {
             templateUrl: 'avengers.html'
         });
 }
<!-- avengers.html -->
<div ng-controller="Avengers as vm">
</div>
/* recommended */

// route-config.js
angular
    .module('app')
    .config(config);

function config ($routeProvider) {
    $routeProvider
        .when('/avengers', {
            templateUrl: 'avengers.html',
            controller: 'Avengers',
            controllerAs: 'vm'
        });
}
<!-- avengers.html -->
<div>
</div>

返回顶部

Services

###单例

[Style Y040]
  • new实例化service,用this实例化公共方法和变量,由于这和factory是类似的,所以为了保持统一,推荐用facotry来代替。

注意:所有的Angular services都是单例,这意味着每个injector都只有一个实例化的service。

// service
angular
    .module('app')
    .service('logger', logger);

function logger () {
    this.logError = function(msg) {
      /* */
    };
}
// factory
angular
    .module('app')
    .factory('logger', logger);

function logger () {
    return {
        logError: function(msg) {
          /* */
        }
    };
}

返回顶部

Factories

###单一职责

[Style Y051]
  • factory应该是单一职责,这是由其上下文进行封装的。一旦一个factory将要处理超过单一的目的时,就应该创建一个新的factory。

###单例

[Style Y051]

###可访问的成员置顶###

[Style Y052]
  • 使用从显露模块模式派生出来的技术把service(它的接口)中可调用的成员暴露到顶部,

    为什么?:易读,并且让你可以立即识别service中的哪些成员可以被调用,哪些成员必须进行单元测试(或者被别人嘲笑)。

    为什么?:当文件内容很长时,这可以避免需要滚动才能看到暴露了哪些东西。

    为什么?:虽然你可以随意写一个函数,但当函数代码超过一行时就会降低可读性并造成滚动。通过把实现细节放下面、把可调用接口置顶的形式返回service的方式来定义可调用的接口,从而使代码更加易读。

/* avoid */
function dataService () {
    var someValue = '';
    function save () {
      /* */
    };
    function validate () {
      /* */
    };

    return {
        save: save,
        someValue: someValue,
        validate: validate
    };
}
/* recommended */
function dataService () {
    var someValue = '';
    var service = {
        save: save,
        someValue: someValue,
        validate: validate
    };
    return service;

    ////////////

    function save () {
      /* */
    };

    function validate () {
      /* */
    };
}

这种绑定方式复制了宿主对象,原始值不会随着暴露模块模式的使用而更新。

Factories Using &quot;Above the Fold&quot;

###函数声明隐藏实现细节

[Style Y053]
  • 函数声明隐藏实现细节,置顶绑定成员,当你需要在controller中绑定一个函数时,把它指向一个函数声明,这个函数声明在文件的后面会出现。

    为什么?:易读,易识别哪些成员可以在View中绑定和使用。

    为什么?:把函数的实现细节放到后面,你可以更清楚地看到重要的东西。

    为什么?:由于函数声明会被置顶,所以没有必要担心在声明它之前就使用函数的问题。

    为什么?:你再也不用担心当 a依赖于 b时,把var a放到var b之前会中断你的代码的函数声明问题。

    为什么?:函数表达式中顺序是至关重要的。

/**
 * avoid
 * Using function expressions
 */
 function dataservice($http, $location, $q, exception, logger) {
    var isPrimed = false;
    var primePromise;

    var getAvengers = function() {
      // implementation details go here
    };

    var getAvengerCount = function() {
      // implementation details go here
    };

    var getAvengersCast = function() {
      // implementation details go here
    };

    var prime = function() {
      // implementation details go here
    };

    var ready = function(nextPromises) {
      // implementation details go here
    };

    var service = {
        getAvengersCast: getAvengersCast,
        getAvengerCount: getAvengerCount,
        getAvengers: getAvengers,
        ready: ready
    };

    return service;
}
/**
 * recommended
 * Using function declarations
 * and accessible members up top.
 */
function dataservice($http, $location, $q, exception, logger) {
    var isPrimed = false;
    var primePromise;

    var service = {
        getAvengersCast: getAvengersCast,
        getAvengerCount: getAvengerCount,
        getAvengers: getAvengers,
        ready: ready
    };

    return service;

    ////////////

    function getAvengers() {
      // implementation details go here
    }

    function getAvengerCount() {
      // implementation details go here
    }

    function getAvengersCast() {
      // implementation details go here
    }

    function prime() {
      // implementation details go here
    }

    function ready(nextPromises) {
      // implementation details go here
    }
}

返回顶部

Data Services

###独立的数据调用

[Style Y060]
  • 把进行数据操作和数据交互的逻辑放到factory中,数据服务负责XHR请求、本地存储、内存存储和其它任何数据操作。

    为什么?:controller的作用是查看视图和收集视图的信息,它不应该关心如何取得数据,只需要知道哪里需要用到数据。把取数据的逻辑放到数据服务中能够让controller更简单、更专注于对view的控制。

    为什么?:方便测试。

    为什么?:数据服务的实现可能有非常明确的代码来处理数据仓库,这可能包含headers、如何与数据交互或是其它service,例如$http。把逻辑封装到单独的数据服务中,这隐藏了外部调用者(例如controller)对数据的直接操作,这样更加容易执行变更。

/* recommended */

// dataservice factory
angular
    .module('app.core')
    .factory('dataservice', dataservice);

dataservice.$inject = ['$http', 'logger'];

function dataservice($http, logger) {
    return {
        getAvengers: getAvengers
    };

    function getAvengers() {
        return $http.get('/api/maa')
            .then(getAvengersComplete)
            .catch(getAvengersFailed);

        function getAvengersComplete(response) {
            return response.data.results;
        }

        function getAvengersFailed(error) {
            logger.error('XHR Failed for getAvengers.' + error.data);
        }
    }
}
注意:数据服务被调用时(例如controller),隐藏调用的直接行为,如下所示。
/* recommended */

// controller calling the dataservice factory
angular
    .module('app.avengers')
    .controller('Avengers', Avengers);

Avengers.$inject = ['dataservice', 'logger'];

function Avengers(dataservice, logger) {
    var vm = this;
    vm.avengers = [];

    activate();

    function activate() {
        return getAvengers().then(function() {
            logger.info('Activated Avengers View');
        });
    }

    function getAvengers() {
        return dataservice.getAvengers()
          .then(function(data) {
              vm.avengers = data;
              return vm.avengers;
          });
    }
}

###数据调用返回一个Promise

[Style Y061]
  • 就像$http一样,调用数据时返回一个promise,在你的调用函数中也返回一个promise。

    为什么?:你可以把promise链接到一起,在数据调用完成并且resolve或是reject这个promise后采取进一步的行为。

/* recommended */

activate();

function activate() {
    /**
     * Step 1
     * Ask the getAvengers function for the
     * avenger data and wait for the promise
     */
    return getAvengers().then(function() {
      /**
       * Step 4
       * Perform an action on resolve of final promise
       */
      logger.info('Activated Avengers View');
    });
}

function getAvengers() {
    /**
     * Step 2
     * Ask the data service for the data and wait
     * for the promise
     */
    return dataservice.getAvengers()
      .then(function(data) {
          /**
           * Step 3
           * set the data and resolve the promise
           */
          vm.avengers = data;
          return vm.avengers;
      });
}

返回顶部

Directives

###一个directive一个文件

[Style Y070]
  • 一个文件中只创建一个directive,并依照directive来命名文件。

    为什么?:虽然把所有directive放到一个文件中很简单,但是当一些directive是跨应用的,一些是跨模块的,一些仅仅在一个模块中使用时,想把它们独立出来就非常困难了。

    为什么?:一个文件一个directive也更加容易维护。

    注: "最佳实践:Angular文档中有提过,directive应该自动回收,当directive被移除后,你可以使用element.on('$destroy', ...)或者scope.$on('$destroy', ...)来执行一个clearn-up函数。"

/* avoid */
/* directives.js */

angular
    .module('app.widgets')

    /* order directive仅仅会被order module用到 */
    .directive('orderCalendarRange', orderCalendarRange)

    /* sales directive可以在sales app的任意地方使用 */
    .directive('salesCustomerInfo', salesCustomerInfo)

    /* spinner directive可以在任意apps中使用 */
    .directive('sharedSpinner', sharedSpinner);

function orderCalendarRange() {
    /* implementation details */
}

function salesCustomerInfo() {
    /* implementation details */
}

function sharedSpinner() {
    /* implementation details */
}
/* recommended */
/* calendarRange.directive.js */

/**
 * @desc order directive that is specific to the order module at a company named Acme
 * @example <div acme-order-calendar-range></div>
 */
angular
    .module('sales.order')
    .directive('acmeOrderCalendarRange', orderCalendarRange);

function orderCalendarRange() {
    /* implementation details */
}
/* recommended */
/* customerInfo.directive.js */

/**
 * @desc sales directive that can be used anywhere across the sales app at a company named Acme
 * @example <div acme-sales-customer-info></div>
 */
angular
    .module('sales.widgets')
    .directive('acmeSalesCustomerInfo', salesCustomerInfo);

function salesCustomerInfo() {
    /* implementation details */
}
/* recommended */
/* spinner.directive.js */

/**
 * @desc spinner directive that can be used anywhere across apps at a company named Acme
 * @example <div acme-shared-spinner></div>
 */
angular
    .module('shared.widgets')
    .directive('acmeSharedSpinner', sharedSpinner);

function sharedSpinner() {
    /* implementation details */
}
注:由于directive使用条件比较广,所以命名就存在很多的选项。选择一个让directive和它的文件名都清楚分明的名字。下面有一些例子,不过更多的建议去看[命名](#命名)章节。

###在directive中操作DOM

[Style Y072]
  • 当需要直接操作DOM的时候,使用directive。如果有替代方法可以使用,例如:使用CSS来设置样式、animation services、Angular模板、ngShow或者ngHide,那么就直接用这些即可。例如,如果一个directive只是想控制显示和隐藏,用ngHide/ngShow即可。

    为什么?:DOM操作的测试和调试是很困难的,通常会有更好的方法(CSS、animations、templates)。

###提供一个唯一的Directive前缀

[Style Y073]
  • 提供一个短小、唯一、具有描述性的directive前缀,例如acmeSalesCustomerInfo在HTML中声明为acme-sales-customer-info

    为什么?:方便快速识别directive的内容和起源,例如acme-可能预示着这个directive是服务于Acme company。

    注:避免使用ng-为前缀,研究一下其它广泛使用的directive避免命名冲突,例如Ionic Frameworkion-

###限制元素和属性

[Style Y074]
  • 当创建一个directive需要作为一个独立元素时,restrict值设置为E(自定义元素),也可以设置可选值A(自定义属性)。一般来说,如果它就是为了独立存在,用E是合适的做法。一般原则是允许EA,但是当它是独立的时候这更倾向于作为一个元素来实施,当它是为了增强已存在的DOM元素时则更倾向于作为一个属性来实施。

    为什么?:这很有意义!

    为什么?:虽然我们允许directive被当作一个class来使用,但如果这个directive的行为确实像一个元素的话,那么把directive当作元素或者属性是更有意义的。

    注:Angular 1.3 +默认使用EA。

<!-- avoid -->
<div class="my-calendar-range"></div>
/* avoid */
angular
    .module('app.widgets')
    .directive('myCalendarRange', myCalendarRange);

function myCalendarRange () {
    var directive = {
        link: link,
        templateUrl: '/template/is/located/here.html',
        restrict: 'C'
    };
    return directive;

    function link(scope, element, attrs) {
      /* */
    }
}
<!-- recommended -->
<my-calendar-range></my-calendar-range>
<div my-calendar-range></div>
/* recommended */
angular
    .module('app.widgets')
    .directive('myCalendarRange', myCalendarRange);

function myCalendarRange () {
    var directive = {
        link: link,
        templateUrl: '/template/is/located/here.html',
        restrict: 'EA'
    };
    return directive;

    function link(scope, element, attrs) {
      /* */
    }
}

###Directives和ControllerAs

[Style Y075]
  • directive使用controller as语法,和view使用controller as保持一致。

    为什么?:因为不难且有必要这样做。

    注意:下面的directive演示了一些你可以在link和directive控制器中使用scope的方法,用controllerAs。这里把template放在行内是为了在一个地方写出这些代码。

    注意:关于依赖注入的内容,请看手动依赖注入

    注意:directive的控制器是在directive外部的,这种风格避免了由于注入造成的return之后的代码无法访问的情况。

<div my-example max="77"></div>
angular
    .module('app')
    .directive('myExample', myExample);

function myExample() {
    var directive = {
        restrict: 'EA',
        templateUrl: 'app/feature/example.directive.html',
        scope: {
            max: '='
        },
        link: linkFunc,
        controller : ExampleController,
        controllerAs: 'vm',
        bindToController: true // because the scope is isolated
    };

    return directive;

    function linkFunc(scope, el, attr, ctrl) {
        console.log('LINK: scope.min = %s *** should be undefined', scope.min);
        console.log('LINK: scope.max = %s *** should be undefined', scope.max);
        console.log('LINK: scope.vm.min = %s', scope.vm.min);
        console.log('LINK: scope.vm.max = %s', scope.vm.max);
    }
}

ExampleController.$inject = ['$scope'];

function ExampleController($scope) {
    // Injecting $scope just for comparison
    var vm = this;

    vm.min = 3;

    console.log('CTRL: $scope.vm.min = %s', $scope.vm.min);
    console.log('CTRL: $scope.vm.max = %s', $scope.vm.max);
    console.log('CTRL: vm.min = %s', vm.min);
    console.log('CTRL: vm.max = %s', vm.max);
}
<!-- example.directive.html -->
<div>hello world</div>
<div>max={{vm.max}}<input ng-model="{{vm.max}}"/></div>
<div>min={{vm.min}}<input ng-model="{{vm.min}}"/></div>
注意:当你把controller注入到link的函数或可访问的directive的attributes时,你可以把它命名为控制器的属性。
// Alternative to above example
function linkFunc(scope, el, attr, vm) { // 和上面例子的区别在于把vm直接传递进来
  console.log('LINK: scope.min = %s *** should be undefined', scope.min);
  console.log('LINK: scope.max = %s *** should be undefined', scope.max);
  console.log('LINK: vm.min = %s', vm.min);
  console.log('LINK: vm.max = %s', vm.max);
}
[Style Y076]
  • 当directive中使用了controller as语法时,如果你想把父级作用域绑定到directive的controller作用域时,使用bindToController = true

    为什么?:这使得把外部作用域绑定到directive controller中变得更加简单。

    注意:Angular 1.3.0才介绍了bindToController

<div my-example max="77"></div>
angular
    .module('app')
    .directive('myExample', myExample);

function myExample() {
    var directive = {
        restrict: 'EA',
        templateUrl: 'app/feature/example.directive.html',
        scope: {
            max: '='
        },
        controller: ExampleController,
        controllerAs: 'vm',
        bindToController: true
      };

    return directive;
}

function ExampleController() {
    var vm = this;
    vm.min = 3;
    console.log('CTRL: vm.min = %s', vm.min);
    console.log('CTRL: vm.max = %s', vm.max);
}
<!-- example.directive.html -->
<div>hello world</div>
<div>max={{vm.max}}<input ng-model="vm.max"/></div>
<div>min={{vm.min}}<input ng-model="vm.min"/></div>

返回顶部

解决Controller的Promises

###Controller Activation Promises

[Style Y080]
  • activate函数中解决controller的启动逻辑。

    为什么?:把启动逻辑放在一个controller中固定的位置可以方便定位、有利于保持测试的一致性,并能够避免controller中到处都是激活逻辑。

    为什么?activate这个controller使得重用刷新视图的逻辑变得很方便,把所有的逻辑都放到了一起,可以让用户更快地看到视图,可以很轻松地对ng-viewui-view使用动画,用户体验更好。

    注意:如果你需要在开始使用controller之前有条件地取消路由,那么就用route resolve来代替。

/* avoid */
function Avengers(dataservice) {
    var vm = this;
    vm.avengers = [];
    vm.title = 'Avengers';

    dataservice.getAvengers().then(function(data) {
        vm.avengers = data;
        return vm.avengers;
    });
}
/* recommended */
function Avengers(dataservice) {
    var vm = this;
    vm.avengers = [];
    vm.title = 'Avengers';

    activate();

    ////////////

    function activate() {
        return dataservice.getAvengers().then(function(data) {
            vm.avengers = data;
            return vm.avengers;
        });
    }
}

###Route Resolve Promises

[Style Y081]
  • 当一个controller在激活之前,需要依赖一个promise的完成时,那么就在controller的逻辑执行之前在$routeProvider中解决这些依赖。如果你需要在controller被激活之前有条件地取消一个路由,那么就用route resolver。

  • 当你决定在过渡到视图之前取消路由时,使用route resolve。

    为什么?:controller在加载前可能需要一些数据,这些数据可能是从一个通过自定义factory或是$http的promise而来的。route resolve允许promise在controller的逻辑执行之前解决,因此它可能对从promise中来的数据做一些处理。

    为什么?:这段代码将在路由后的controller的激活函数中执行,视图立即加载,promise resolve的时候将会开始进行数据绑定,可以(通过ng-viewui-view)在视图的过渡之间加个loading状态的动画。

    注意:这段代码将在路由之前通过一个promise来执行,拒绝了承诺就会取消路由,接受了就会等待路由跳转到新视图。如果你想更快地进入视图,并且无需验证是否可以进入视图,你可以考虑用控制器 activate 技术

/* avoid */
angular
    .module('app')
    .controller('Avengers', Avengers);

function Avengers (movieService) {
    var vm = this;
    // unresolved
    vm.movies;
    // resolved asynchronously
    movieService.getMovies().then(function(response) {
        vm.movies = response.movies;
    });
}
/* better */

// route-config.js
angular
    .module('app')
    .config(config);

function config ($routeProvider) {
    $routeProvider
        .when('/avengers', {
            templateUrl: 'avengers.html',
            controller: 'Avengers',
            controllerAs: 'vm',
            resolve: {
                moviesPrepService: function(movieService) {
                    return movieService.getMovies();
                }
            }
        });
}

// avengers.js
angular
    .module('app')
    .controller('Avengers', Avengers);

Avengers.$inject = ['moviesPrepService'];
function Avengers (moviesPrepService) {
    var vm = this;
    vm.movies = moviesPrepService.movies;
}
注意:下面这个例子展示了命名函数的路由解决,这种方式对于调试和处理依赖注入更加方便。
/* even better */

// route-config.js
angular
    .module('app')
    .config(config);

function config($routeProvider) {
    $routeProvider
        .when('/avengers', {
            templateUrl: 'avengers.html',
            controller: 'Avengers',
            controllerAs: 'vm',
            resolve: {
                moviesPrepService: moviesPrepService
            }
        });
}

function moviesPrepService(movieService) {
    return movieService.getMovies();
}

// avengers.js
angular
    .module('app')
    .controller('Avengers', Avengers);

Avengers.$inject = ['moviesPrepService'];
function Avengers(moviesPrepService) {
      var vm = this;
      vm.movies = moviesPrepService.movies;
}

注意:示例代码中的movieService不符合安全压缩的做法,可以到手动依赖注入压缩和注释部分学习如何安全压缩。

返回顶部

手动依赖注入

压缩的不安全性

[Style Y090]
  • 声明依赖时避免使用缩写语法。

    为什么?:组件的参数(例如controller、factory等等)将会被转换成各种乱七八糟错误的变量。例如,commondataservice可能会变成a或者b,但是这些转换后的变量在Angular中是找不到的。

/* avoid - not minification-safe*/
angular
    .module('app')
    .controller('Dashboard', Dashboard);

function Dashboard(common, dataservice) {
}

这一段代码在压缩时会产生错误的变量,因此在运行时就会报错。

/* avoid - not minification-safe*/
angular.module('app').controller('Dashboard', d);function d(a, b) { }

###手动添加依赖

[Style Y091]
  • $inject手动添加Angular组件所需的依赖。

    为什么?:这种技术反映了使用ng-annotate的技术,这就是我推荐的对依赖关系进行自动化创建安全压缩的方式,如果ng-annotate检测到已经有了注入,那么它就不会再次重复执行。

    为什么?:可以避免依赖变成其它Angular找不到的变量,例如,commondataservice可能会变成a或者b

    为什么?:避免创建内嵌的依赖,因为一个数组太长不利于阅读,此外,内嵌的方式也会让人感到困惑,比如数组是一系列的字符串,但是最后一个却是组件的function。

/* avoid */
angular
    .module('app')
    .controller('Dashboard',
        ['$location', '$routeParams', 'common', 'dataservice',
            function Dashboard($location, $routeParams, common, dataservice) {}
        ]);
/* avoid */
angular
    .module('app')
    .controller('Dashboard',
      ['$location', '$routeParams', 'common', 'dataservice', Dashboard]);

function Dashboard($location, $routeParams, common, dataservice) {
}
/* recommended */
angular
    .module('app')
    .controller('Dashboard', Dashboard);

Dashboard.$inject = ['$location', '$routeParams', 'common', 'dataservice'];

function Dashboard($location, $routeParams, common, dataservice) {
}
注意:当你的函数处于return语句后面,那么`$inject`是无法访问的(这会在directive中发生),你可以通过把Controller移到directive外面来解决这个问题。
/* avoid */
// inside a directive definition
function outer() {
    var ddo = {
        controller: DashboardPanelController,
        controllerAs: 'vm'
    };
    return ddo;

    DashboardPanelController.$inject = ['logger']; // Unreachable
    function DashboardPanelController(logger) {
    }
}
/* recommended */
// outside a directive definition
function outer() {
    var ddo = {
        controller: DashboardPanelController,
        controllerAs: 'vm'
    };
    return ddo;
}

DashboardPanelController.$inject = ['logger'];
function DashboardPanelController(logger) {
}

###手动确定路由解析器依赖

[Style Y092]
  • $inject手动给Angular组件添加路由解析器依赖。

    为什么?:这种技术打破了路由解析的匿名函数的形式,易读。

    为什么?$inject语句可以让任何依赖都可以安全压缩。

/* recommended */
function config ($routeProvider) {
    $routeProvider
        .when('/avengers', {
            templateUrl: 'avengers.html',
            controller: 'AvengersController',
            controllerAs: 'vm',
            resolve: {
                moviesPrepService: moviesPrepService
            }
        });
}

moviesPrepService.$inject =  ['movieService'];
function moviesPrepService(movieService) {
    return movieService.getMovies();
}

返回顶部

压缩和注释

###ng-annotate

[Style Y100]
  • GulpGrunt中使用ng-annotate,用/** @ngInject */对需要自动依赖注入的function进行注释。

    为什么?:可以避免代码中的依赖使用到任何不安全的写法。

    为什么?:不推荐用ng-min

    我更喜欢Gulp,因为我觉得它是易写易读易调试的。

    下面的代码没有注入依赖,显然压缩是不安全的。

    angular
        .module('app')
        .controller('Avengers', Avengers);
    
    /* @ngInject */
    function Avengers (storageService, avengerService) {
        var vm = this;
        vm.heroSearch = '';
        vm.storeHero = storeHero;
    
        function storeHero(){
          var hero = avengerService.find(vm.heroSearch);
          storageService.save(hero.name, hero);
        }
    }
    

    当上面的代码通过ng-annotate运行时,就会产生如下的带有$inject注释的输出结果,这样的话压缩就会安全了。

    angular
        .module('app')
        .controller('Avengers', Avengers);
    
    /* @ngInject */
    function Avengers (storageService, avengerService) {
        var vm = this;
        vm.heroSearch = '';
        vm.storeHero = storeHero;
    
        function storeHero(){
          var hero = avengerService.find(vm.heroSearch);
          storageService.save(hero.name, hero);
        }
    }
    
    Avengers.$inject = ['storageService', 'avengerService'];
    

    注意:如果ng-annotate检测到已经有注入了(例如发现了@ngInject),就不会重复生成$inject代码了。

    注意:路由的函数前面也可以用/* @ngInject */

    // Using @ngInject annotations
    function config($routeProvider) {
        $routeProvider
            .when('/avengers', {
                templateUrl: 'avengers.html',
                controller: 'Avengers',
                controllerAs: 'vm',
                resolve: { /* @ngInject */
                    moviesPrepService: function(movieService) {
                        return movieService.getMovies();
                    }
                }
            });
    }
    

    注意:从Angular 1.3开始,你就可以用ngApp指令的 ngStrictDi参数来检测任何可能失去依赖的地方,当以“strict-di”模式创建injector时,会导致应用程序无法调用不使用显示函数注释的函数(这也许无法安全压缩)。记录在控制台的调试信息可以帮助追踪出问题的代码。我只在需要调试的时候才会用到ng-strict-di
    <body ng-app="APP" ng-strict-di>

###使用Gulp或Grunt结合ng-annotate

[Style Y101]
  • 在自动化任务中使用gulp-ng-annotategrunt-ng-annotate,把/* @ngInject */注入到任何有依赖关系函数的前面。

    为什么?:ng-annotate会捕获大部分的依赖关系,但是有时候需要借助于/* @ngInject */语法提示。

    下面的代码是gulp任务使用ngAnnotate的例子。

    gulp.task('js', ['jshint'], function() {
        var source = pkg.paths.js;
    
        return gulp.src(source)
            .pipe(sourcemaps.init())
            .pipe(concat('all.min.js', {newLine: ';'}))
            // Annotate before uglify so the code get's min'd properly.
            .pipe(ngAnnotate({
                // true helps add where @ngInject is not used. It infers.
                // Doesn't work with resolve, so we must be explicit there
                add: true
            }))
            .pipe(bytediff.start())
            .pipe(uglify({mangle: true}))
            .pipe(bytediff.stop())
            .pipe(sourcemaps.write('./'))
            .pipe(gulp.dest(pkg.paths.dev));
    });
    
    

**[返回顶部](#目录)**

## 异常处理

###修饰符
###### [Style [Y110](#style-y110)]

- 使用一个[decorator](https://docs.angularjs.org/api/auto/service/$provide#decorator),在配置的时候用[`$provide`](https://docs.angularjs.org/api/auto/service/$provide)服务,当发生异常时,在[`$exceptionHandler`](https://docs.angularjs.org/api/ng/service/$exceptionHandler)服务中执行自定义的处理方法。

  *为什么?*:在开发时和运行时提供了一种统一的方式来处理未被捕获的Angular异常。

  注:另一个选项是用来覆盖service的,这个可以代替decorator,这是一个非常nice的选项,但是如果你想保持默认行为,那么推荐你扩展一个decorator。

  ```javascript
  /* recommended */
  angular
      .module('blocks.exception')
      .config(exceptionConfig);

  exceptionConfig.$inject = ['$provide'];

  function exceptionConfig($provide) {
      $provide.decorator('$exceptionHandler', extendExceptionHandler);
  }

  extendExceptionHandler.$inject = ['$delegate', 'toastr'];

  function extendExceptionHandler($delegate, toastr) {
      return function(exception, cause) {
          $delegate(exception, cause);
          var errorData = {
            exception: exception,
            cause: cause
          };
          /**
           * Could add the error to a service's collection,
           * add errors to $rootScope, log errors to remote web server,
           * or log locally. Or throw hard. It is entirely up to you.
           * throw exception;
           */
          toastr.error(exception.msg, errorData);
      };
  }

###异常捕获器

[Style Y111]
  • 创建一个暴露了一个接口的factory来捕获异常并以合适方式处理异常。

    为什么?:提供了一个统一的方法来捕获代码中抛出的异常。

    注:异常捕获器对特殊异常的捕获和反应是非常友好的,例如,使用XHR从远程服务获取数据时,你想要捕获所有异常并做出不同的反应。

    /* recommended */
    angular
        .module('blocks.exception')
        .factory('exception', exception);
    
    exception.$inject = ['logger'];
    
    function exception(logger) {
        var service = {
            catcher: catcher
        };
        return service;
    
        function catcher(message) {
            return function(reason) {
                logger.error(message, reason);
            };
        }
    }
    

###路由错误

[Style Y112]
  • $routeChangeError来处理并打印出所有的路由错误信息。

    为什么?:提供一个统一的方式来处理所有的路由错误。

    为什么?:当一个路由发生错误的时候,可以给展示一个提示信息,提高用户体验。

    /* recommended */
    var handlingRouteChangeError = false;
    
    function handleRoutingErrors() {
        /**
         * Route cancellation:
         * On routing error, go to the dashboard.
         * Provide an exit clause if it tries to do it twice.
         */
        $rootScope.$on('$routeChangeError',
            function(event, current, previous, rejection) {
                if (handlingRouteChangeError) { return; }
                handlingRouteChangeError = true;
                var destination = (current && (current.title ||
                    current.name || current.loadedTemplateUrl)) ||
                    'unknown target';
                var msg = 'Error routing to ' + destination + '. ' +
                    (rejection.msg || '');
    
                /**
                 * Optionally log using a custom service or $log.
                 * (Don't forget to inject custom service)
                 */
                logger.warning(msg, [current]);
    
                /**
                 * On routing error, go to another route/state.
                 */
                $location.path('/');
    
            }
        );
    }
    

返回顶部

命名

###命名原则

[Style Y120]
  • 遵循以描述组件功能,然后是类型(可选)的方式来给所有的组件提供统一的命名,我推荐的做法是feature.type.js。大多数文件都有2个名字。

    • 文件名 (avengers.controller.js)
    • 带有Angular的注册组件名 (AvengersController)

    为什么?:命名约定有助于为一目了然地找到内容提供一个统一的方式,在项目中和团队中保持统一性是非常重要的,保持统一性对于跨公司来说提供了巨大的效率。

    为什么?:命名约定应该只为代码的检索和沟通提供方便。

###功能文件命名

[Style Y121]
  • 遵循以“描述组件功能.类型(可选)”的方式来给所有的组件提供统一的命名,我推荐的做法是feature.type.js

    为什么?:为快速识别组件提供了统一的方式。

    为什么?:为任何自动化的任务提供模式匹配。

    /**
     * common options
     */
    
    // Controllers
    avengers.js
    avengers.controller.js
    avengersController.js
    
    // Services/Factories
    logger.js
    logger.service.js
    loggerService.js
    
    /**
     * recommended
     */
    
    // controllers
    avengers.controller.js
    avengers.controller.spec.js
    
    // services/factories
    logger.service.js
    logger.service.spec.js
    
    // constants
    constants.js
    
    // module definition
    avengers.module.js
    
    // routes
    avengers.routes.js
    avengers.routes.spec.js
    
    // configuration
    avengers.config.js
    
    // directives
    avenger-profile.directive.js
    avenger-profile.directive.spec.js
    

注意:另外一种常见的约定就是不要用controller这个词来给controller文件命名,例如不要用avengers.controller.js,而是用avengers.js。所有其它的约定都坚持使用类型作为后缀,但是controller是组件中最为常用的类型,因此这种做法的好处貌似仅仅是节省了打字,但是仍然很容易识别。我建议你为你的团队选择一种约定,并且要保持统一性。我喜欢的命名方式是avengers.controller.js

```javascript
/**
 * recommended
 */
// Controllers
avengers.js
avengers.spec.js
```

###测试文件命名

[Style Y122]
  • 和组件命名差不多,带上一个spec后缀。

    为什么?:为快速识别组件提供统一的方式。

    为什么?:为karma或是其它测试运行器提供模式匹配。

    /**
     * recommended
     */
    avengers.controller.spec.js
    logger.service.spec.js
    avengers.routes.spec.js
    avenger-profile.directive.spec.js
    

###Controller命名

[Style Y123]
  • 为所有controller提供统一的名称,先特征后名字,鉴于controller是构造函数,所以要采用UpperCamelCase(每个单词首字母大写)的方式。

    为什么?:为快速识别和引用controller提供统一的方式。

    为什么?:UpperCamelCase是常规的识别一个可以用构造函数来实例化的对象的方式。

    /**
     * recommended
     */
    
    // avengers.controller.js
    angular
        .module
        .controller('HeroAvengersController', HeroAvengersController);
    
    function HeroAvengers(){ }
    

###Controller命名后缀

[Style Y124]
  • 使用Controller

    为什么?Controller使用更广泛、更明确、更具有描述性。

    /**
     * recommended
     */
    
    // avengers.controller.js
    angular
        .module
        .controller('AvengersController', AvengersController);
    
    function AvengersController(){ }
    

###Factory命名

[Style Y125]
  • 一样要统一,对service和factory使用camel-casing(驼峰式,第一个单词首字母小写,后面单词首字母大写)方式。避免使用$前缀。

    为什么?:可以快速识别和引用factory。

    为什么?:避免与内部使用$前缀的服务发生冲突。

    /**
     * recommended
     */
    
    // logger.service.js
    angular
        .module
        .factory('logger', logger);
    
    function logger(){ }
    

###Directive组件命名

[Style Y126]
  • 使用camel-case方式,用一个短的前缀来描述directive在哪个区域使用(一些例子中是使用公司前缀或是项目前缀)。

    为什么?:可以快速识别和引用controller。

    /**
     * recommended
     */
    
    // avenger-profile.directive.js
    angular
        .module
        .directive('xxAvengerProfile', xxAvengerProfile);
    
    // usage is <xx-avenger-profile> </xx-avenger-profile>
    
    function xxAvengerProfile(){ }
    

###模块

[Style Y127]
  • 当有很多的模块时,主模块文件命名成app.module.js,其它依赖模块以它们代表的内容来命名。例如,一个管理员模块命名成admin.module.js,它们各自的注册模块名字就是appadmin

    为什么?:给多模块的应用提供统一的方式,这也是为了扩展大型应用。

    为什么?:对使用任务来自动化加载所有模块的定义(先)和其它所有的angular文件(后)提供了一种简单的方式。

###配置

[Style Y128]
  • 把一个模块的配置独立到它自己的文件中,以这个模块为基础命名。app模块的配置文件命名成app.config.js(或是config.js),admin.module.js的配置文件命名成admin.config.js

    为什么?:把配置从模块定义、组件和活跃代码中分离出来。

    为什么?:为设置模块的配置提供了一个可识别的地方。

###路由

[Style Y129]
  • 把路由的配置独立到单独的文件。主模块的路由可能是app.route.jsadmin模块的路由可能是admin.route.js。即使是在很小的应用中,我也喜欢把路由的配置从其余的配置中分离出来。

返回顶部

应用程序结构的LIFT准则

###LIFT

[Style Y140]
  • 构建一个可以快速定位(Locate)代码、一目了然地识别(Identify)代码、拥有一个平直(Flattest)的结构、尽量(Try)坚持DRY(Don’t Repeat Yourself)的应用程序,其结构应该遵循这4项基本准则。

    为什么是LIFT?: 提供一个有良好扩展的结构,并且是模块化的,更快的找到代码能够帮助开发者提高效率。另一种检查你的app结构的方法就是问你自己:你能多块地打开涉及到一个功能的所有相关文件并开始工


       在AngularJS的术语中,把检测模型变化的过程称为$digest循环。这个名字来源于Scope实例上的$digest方法。这种方法被作为$apply中的重要一步来调用,它会检测注册在所有作用域上的所有监视对象。

       为什么AngularJS中要有$digest循环呢?它又是如何判断模型发生变化的?$digest循环的存在是为了解决下面的两个问题。

  • 判定模型的哪些部分发生变化,以及DOM中的哪些属性应该被更新。这一步的目的是让检测模型变化的过程对开发者保持尽可能的简单。在开发时,我们只需要修改属性值,之后AngularJS指令会自动找出网页中哪些部分应该被重绘。
  • 减少不必要的重绘以提升应用性能,避免UI界面闪烁。为了实现这点,AngularJS会将DOM重绘尽可能推迟到最后一刻,此时模型趋于稳定(所有模型值都已完成运算,时刻准备驱动UI重绘)。

       要理解AngularJS如何实现这种效果,首先要明白web浏览器只有一个UI线程。浏览器中当然还有其他线程(如负责网络相关操作的线程),但只有一个线程用于渲染DOM元素、监视DOM事件,以及执行JavaScript代码。浏览器不停地在JavaScript执行环境和DOM渲染环境之间切换。

       AngularJS确保在将控制权交还给DOM渲染环境之前,所有的模型值都已完成运算且已“稳定”。这种方法保证了UI一次性完成重绘,而不会为了响应某个单独的模型变化而不停重绘。这保证了更快的执行速度(因为运行环境的切换很少)和更好的视觉效果(所有重绘一次完成)。每个单独的模型属性变化都出发一次UI重绘会让界面变得很慢,而且会出现明显的闪烁。

解剖$watch

       AngularJS使用脏检查(dirty checking)机制来判定某个模型值是否真正发生了变化。脏检查的工作机制是将之前保存的模型值和能导致模型发生变化的事件(DOM事件、XHR事件等)发生后计算的新模型值做对比。

       再来看一下,注册一个新的模型监视基本语法如下:

$scope.$watch(watchExpression, modelChangeCallback);

       当作用域添加一个新的$watch时,AngularJS会运算watchExpression表达式,然后在内部将运算所得的值存储起来。紧接着进入$digest循环,watchExpression会被再次运算,运算所得的新值会和之前保存的值进行对比。modelChangeCallback只会在新值与旧值不同时才会执行。这个新值也会被保存起来以备下一次对比使用,整个过程可以一直这样持续下去。

       作为开发者,我们对自己手动注册的监视(watches)很清楚。但我们还要明白任何指令(AngularJS的内置核心指令和任何第三方指令)都可以设置自己的监视。任何插值表达式({{wapression}})也会在作用域上注册一个新的监视。

模型的稳定性

       如果模型上的任何一个监视器都检测不到任何变化,AngularJS就认为该模型是稳定的(此时就可以进行UI渲染工作了)。只要一个监视器的一个变化,就足以使整个$digest循环变“脏”(dirty),迫使AngularJS进入下一轮循环。此时使用了“一颗老鼠屎坏了一锅汤”的原则,当然这么做是有充足的理由的。

       AngularJS会持续执行$digest循环,反复运算所有作用域上的所有监视,知道没有发现任何变化为止。连续几轮$digest循环是必要的,因为模型监视回调会有一些副作用。如果只是简单地设置一个回调,当见识的模型值变化时执行,那就可能改变我们已经运算过且认为是稳定的那些模型。

       我们来考虑一个简单的表单例子,该表单有两个字段Start和End。在这个表单中结束时间(End)应该永远晚于开始时间(Start)。

<div>
    <form>
        Start date: <input ng-model="startDate">
        End date: <input ng-model="endDate">
    </form>
</div>

       为了保证在模型中endDate永远晚于StartDate,可以注册一个监视,代码如下:

function oneDayAhead(dateToIncrement){
    return dateToIncrement.setDate(dateToIncrement.getDate() + 1);
}

$scope.$watch('startDate', function(newValue){
    if(newValue <= $scope.startDate) {
        $scope.endDate = oneDayAhead($scope.startDate);
    }
});

       在上面的监视中,我们让两个模型值之间产生一个依赖关系,其中一个模型的变化(startDate)可以触发另一个变化。这个例子就能说明模型变化回调的副作用,一个模型变化时可能会让另一个已被认为“稳定”的模型值也发生变化。

       对脏检查算法的深入理解,会让你明白一个watchExpression在每次$digest循环中都会被至少运算两次。可以通过创建下面代码来验证这一点:

<input ng-model="name">
{{getName()}}

       getName()是在作用域上的一个函数

$scope.getName = function(){
    console.log('dirty-checking');
    return $scope.name;
}

       如果运行上面的代码,注意观察控制台的输出,就会发现<input>的每次变化都会输出两条日志。

任何一个$digest循环至少都会运行一次,一般情况下会运行两次。这意味着每一个被监视的表达式在每个$digest循环中都会被运算两次(在浏览器离开JavaScript环境转向UI渲染之前)

不稳定的模型

有些情况下,$digest执行两次循环也不足以确定模型的稳定性。更糟糕的是,有可能会出现永远无法确定模型稳定性的模型的情况!我们来看下面的例子:

<span>Random Value: {{random()}}</span>

       random()函数定义如下:

$scope.random = Math.random;

       监视表达式等于Math.random(),这样会(极大可能)导致每次$digest循环运算所得的值都不一样。这表示每次检查的结果都是“脏”的,需要启动新一轮检查。这会导致一遍又一遍地循环,直到AngularJS认为这个模型是“不稳定”的,然后强制跳出$digest循环。

AngularJS默认最多会执行10次循环,之后就会声明该模型是不稳定的,然后中断$digest循环。

       在中断$digest之后,AngularJS会抛出一个错误(使用$exceptionHandler服务来处理,该服务用来在控制台记录错误)。抛出的错误中会包含5个最新的不稳定的监视信息(其中含有这些表达式的新值和旧值)。大多数情况下只会有一个不稳定的监视模型,所以很容易找出罪魁祸首。

       在$digest循环被中止之后,JavaScript线程就会离开“AngularJS世界”。此时,没有什么能够阻挡浏览器对渲染的向往。之后,用户就会看到使用$digest循环最后一次运行所得到的模型值渲染的页面。

即使$digest循环运行超过10次上限,页面还是会被渲染。在你观察控制台日志之前,这种错误很难定位,所以它可能会被忽略一段时间。即便如此,还是应该追踪并解决与不稳定模型有关的问题

$digest循环和作用域的层级

        每次$digest循环都会从$rootScope开始,重新计算所有作用域上的所有监视表达式。这一眼看上去有点违反直觉,有些人可能会说只要重新计算指定作用域及其子作用域上的表达式足矣。不幸的是,这样做会导致UI和模型不同步。原因就是子作用域上的变化可能会影响父作用域上的变。请看下面的例子,含有两个作用域(一个是$rootScope,另一个是ng-controller指令创建的):

<body ng-app ng-init="user = {name: 'Superhero'}">
    Name in parent: {{user.name}}
    <div ng-controller="ChildCtrl">
        Name in child; {{user.name}}
        <input ng-model="user.name">
    </div>
</body>

       模型(user.name)的变化是被子作用域(ng-controller)触发的,但是这个变化也改变了$rootScopr上对应的属性。

       这种情况迫使AngularJS次那个$rootScope开始逐级往下(使用深度优先遍历)运算所有的监视表达式。如果AngularJS只是运算某个作用域上(加上它的子作用域)的监视表达式,那么,一旦模型有变化,应用中就存在模型和实际显示不同步的风险,比如我们讨论的这个例子, Name in Parent:{{user.name}}中的插值表达式就不会被运算,显示结果也就不同步。

在每次$digest循环中,AngularJS都需要运算所有作用域上的所有监视表达式。这种过程从$rootScope开始,然后以深度优先便利所有子作用域。


摘自《精通AngularJS》 11.2理解AngularJS的内部运作机制


       当AngularJS首次向公众发布之后,就有许多关于它的模型变化监控算法的“阴谋论”。其中最被津津乐道的一种是,怀疑AngularJS使用了某种轮询机制。这种机制可能每隔一小段时间就去检查模型值的变化,如果发现变化,就重绘DOM。所有这些猜测都是错误的。

AngularJS没有使用任何的轮询算法来定期检查模型变化

       AngularJS的模型变化监控机制背后的思路其实是“善后”(Observeat the end of the day),因为引发模型变化的情况是有限的。这些情况包括:

  • DOM事件(例如,用户修改了input的值,然后点击一个按钮,调用了一个JavaScript函数或执行其他操作);
  • XHR相应触发回调;
  • 浏览器的地址变化;
  • 计时器(setTimeout, setInterval)触发回调。

       的确,如果上面的任何一种情况都未发生(用户与页面没有发生任何交互,没有任何XHR响应,没有计时器结束),那么监控模型的变化是没有意义的。此时页面上什么事情也没发生,模型也没有变化,重绘DOM也就毫无必要了。

       AngularJS只会在被明确告知的情况下才会启动它的模型监控机制。为了让这种复杂的机制运作起来,需要在scope对象上执行$apply方法。

       回到之前的simple-model执行,可以在input值每次发生变化后执行$apply方法(这样每次按键的变化都会传播给模型。这也是ng-model执行的模型行为)。

.directive('simpleModel', function($parse){
    return function(scope, element, attrs){
        var modelGetter = $parse(attrs.simpleModel);
        var modelSetter = modelGetter.assign;

        //从model更新DOM
        scope.$watch(modelGetter, function(newVal, oldVal){
            element.val(newVal);
        });

        //从DOM更新model
        element.bind('input', function(){
            scope.$apply(function(){
                modelSetter(scope, element.val());
            });
        });
    }
});

       使用AngularJS的内置指令时,我们完全无需调用$apply方法,就可以看到很多“奇迹”,这一点很让人惊讶。但实际上,内置指令的实现代码中调用了$apply方法。也就是说,标准的指令和服务已经帮我们处理好了模型变化的监控工作($http、$timeout、$location等)。

当在一个作用域上调用$apply方法后,AngularJS就会启动模型变化监控机制。在网络通信、DOM事件、JavaScript计时或浏览器地址发生变化之后,AngularJS标准的服务和指令就会调用$apply方法。


摘自《精通AngularJS》 11.2理解AngularJS的内部运作机制


AngularJS 默认将会使用一个 # 号来对URL进行路由.
例如:
http://example.com/
http://example.com/#/about
http://example.com/#/contact
要获得干净的URL并将井号从URL中移除是很容易的.
完成两件事情就行了.
配置 $locationProvider
设置我们的相对连接的起点路径
$location 服务

在Angular中, $location服务会解析地址栏中的URL,并对你的应用程序作出改变,反之亦然.
我强烈推荐通读官方的 Angular $location 文档 以对$location 服务及其所提供的特性有一个了解.

$location 服务

在Angular中, $location服务会解析地址栏中的URL,并对你的应用程序作出改变,反之亦然.
我强烈推荐通读官方的 Angular $location 文档 以对$location 服务及其所提供的特性有一个了解.

$locationProvider 和 html5 模式(html5Mode)

我们会使用 $locationProvider 模块,并将html5Mode设置为true.
我们会在你定义Angular应用程序并配置你的路由时做这些.

angular.module('scotchy', [])

    .config(function($routeProvider, $locationProvider) {
 
        $routeProvider
            .when('/', {
                templateUrl : 'partials/home.html',
                controller : mainController
            })
            .when('/about', {
                templateUrl : 'partials/about.html',
                controller : mainController
            })
            .when('/contact', {
                templateUrl : 'partials/contact.html',
                controller : mainController
            });
 
    // use the HTML5 History API
    $locationProvider.html5Mode(true);
});

什么是 HTML5 History API? 它是使用一个脚本来操作浏览器历史的标准方法. 有了它就能在不刷新页面的前提下让 Angular 改变路由和页面的URL. 更多的信息,这里有一篇蛮好的 HTML5 History API 文章.

为相对链接设置

为了在应用程序各处使用相对链接,你将需要在你文档的里面设置一个.

<!doctype html>
<html>
<head>
    <meta charset="utf-8">
 
    <base href="/">
</head>

有大量的方法可以用来配置这个东西,而将HTML5Mode设置为true就会自动的解析相对链接了. 在我这儿这种方式总是能起效. 如果你应用程序的根同url相比有所不同,例如 /my-base, 那就用那个作为你的起点路径.

老浏览器的回调

$location服务对不支持HTML5浏览历史API的浏览器将自动回调hashbang方法。
一切的发生对你是透明的,你不需为此做任何配置。从Angular $location文档中,你可以看到回调的方法已经它是如何工作的。

总结

这是一个在Angular应用中获得漂亮URL并删除哈希标记的简单方法。享受超洁净、超快速的Angular应用吧!


英文原文:Pretty URLs in AngularJS: Removing the #
转自:http://www.oschina.net/translate/pretty-urls-in-angularjs-removing-the-hashtag


Powered by Typecho.