ng-ui-router 官方示例的解读

angular.module('uiRouterSample.contacts', [
  'ui.router'
])
  
.config(
  [          '$stateProvider', '$urlRouterProvider',
    function ($stateProvider,   $urlRouterProvider) {
      $stateProvider
        //////////////
        // Contacts //
        //////////////
        .state('contacts', {

          // With abstract set to true, that means this state can not be explicitly activated.
          // It can only be implicitly activated by activating one of its children.
            /**
             *
             * 抽象路由模板，该状态永远不会被激活
             * 只会被其子状态隐式激活
             * 在本例子中  就是被导航中的ui-sref=contacts.list激活的
             * */
          abstract: true,

          // This abstract state will prepend '/contacts' onto the urls of all its children.
            /**
             * 这个抽象状态会预置/contacts到其所有的子状态中
             *
             * */
          url: '/contacts',

          // Example of loading a template from a file. This is also a top level state,
          // so this template file will be loaded and then inserted into the ui-view
          // within index.html.
          templateUrl: 'app/contacts/contacts.html',

          // Use `resolve` to resolve any asynchronous controller dependencies
          // *before* the controller is instantiated. In this case, since contacts
          // returns a promise, the controller will wait until contacts.all() is
          // resolved before instantiation. Non-promise return values are considered
          // to be resolved immediately.
            /**
             * resolve处理异步数据调用，在控制器实例化之前
             *在这个例子中，contacts返回一个promise，控制器会等到promise处理完之后再进行初始化
             *non-promise会立即resolve
             */
          resolve: {
            contacts: ['contacts',
              function( contacts){
                return contacts.all();
              }]
          },

          // You can pair a controller to your template. There *must* be a template to pair with.
            /***
             * 为template添加控制器。
             * 必须与template配对
             *
             */
          controller: ['$scope', '$state', 'contacts', 'utils',
            function (  $scope,   $state,   contacts,   utils) {

              // Add a 'contacts' field in this abstract parent's scope, so that all
              // child state views can access it in their scopes. Please note: scope
              // inheritance is not due to nesting of states, but rather choosing to
              // nest the templates of those states. It's normal scope inheritance.
              $scope.contacts = contacts;

              $scope.goToRandom = function () {
               var randId = utils.newRandomKey($scope.contacts, "id", $state.params.contactId);


                // $state.go() can be used as a high level convenience method
                // for activating a state programmatically.
                /**
                 * go()方法是一个高级又便利的方法
                 *用于激活一个动态的状态
                 */
                $state.go('contacts.detail', { contactId: randId });
              };
            }]
        })

        /////////////////////
        // Contacts > List //
        /////////////////////

        // Using a '.' within a state name declares a child within a parent.
        // So you have a new state 'list' within the parent 'contacts' state.
      /**
       * 在状态中用一个'.'才分割父状态和子状态，
       * 所有现在创建了一个新的'list'状态位于父状态'contacts'中
       */
        .state('contacts.list', {

          // Using an empty url means that this child state will become active
          // when its parent's url is navigated to. Urls of child states are
          // automatically appended to the urls of their parent. So this state's
          // url is '/contacts' (because '/contacts' + '').
            /**
             * 用空的url表示这个子状态会在其父状态导航到时被激活
             * 子状态会自动添加
             * 所以这个状态的url='/contacts'+''
             */
          url: '',

          // IMPORTANT: Now we have a state that is not a top level state. Its
          // template will be inserted into the ui-view within this state's
          // parent's template; so the ui-view within contacts.html. This is the
          // most important thing to remember about templates.
            /**
             * 现在我们有一个非顶级的状态
             *这个模板会出入到其父状态的ui-view中：也就是contact.html中的ui-view
             *这是模板中很重要的性质
             */
          templateUrl: 'app/contacts/contacts.list.html'
        })

        ///////////////////////
        // Contacts > Detail //
        ///////////////////////

        // You can have unlimited children within a state. Here is a second child
        // state within the 'contacts' parent state.
      /**
       * 一个状态的子状态是无限的，这是contacts的第二个子状态
       */
        .state('contacts.detail', {

          // Urls can have parameters. They can be specified like :param or {param}.
          // If {} is used, then you can also specify a regex pattern that the param
          // must match. The regex is written after a colon (:). Note: Don't use capture
          // groups in your regex patterns, because the whole regex is wrapped again
          // behind the scenes. Our pattern below will only match numbers with a length
          // between 1 and 4.
            /**
             * url上可以有参数，定义形式：param 或者 {param}
             * 如果使用{}，也可以定义成一个正则表达式，参数必须匹配正则
             *
             */

          // Since this state is also a child of 'contacts' its url is appended as well.
          // So its url will end up being '/contacts/{contactId:[0-9]{1,4}}'. When the
          // url becomes something like '/contacts/42' then this state becomes active
          // and the $stateParams object becomes { contactId: 42 }.
            /**
             * /contacts/42
             * 这样的url就能访问该状态
             * 而且$stateParams对象就变成了{contactId:42}
             *
             */
          url: '/{contactId:[0-9]{1,4}}',

          // If there is more than a single ui-view in the parent template, or you would
          // like to target a ui-view from even higher up the state tree, you can use the
          // views object to configure multiple views. Each view can get its own template,
          // controller, and resolve data.
            /**
             * 如果父template不止一个ui-view
             * 或者想访问更往上的状态（—from state tree)
             * 可以使用views对象来配置多views，每个view都可以从他自己的template,controller,resolve data中获取
             */

          // View names can be relative or absolute. Relative view names do not use an '@'
          // symbol. They always refer to views within this state's parent template.
          // Absolute view names use a '@' symbol to distinguish the view and the state.
          // So 'foo@bar' means the ui-view named 'foo' within the 'bar' state's template.
            /**
             * view的名字有相对和绝对两种
             * 相对的视图名字不需要用@标志
             * 这些view总会在当前状态的父template中展示
             *
             * 绝对名称的view使用@标志来区分状态和视图view
             * foo@bar   bar状态的foo  view
             */
          views: {

            // So this one is targeting the unnamed view within the parent state's template.
              /**
               * ''指向父template中未命名的view
               */
            '': {
              templateUrl: 'app/contacts/contacts.detail.html',
              controller: ['$scope', '$stateParams', 'utils',
                function (  $scope,   $stateParams,   utils) {
                  $scope.contact = utils.findById($scope.contacts, $stateParams.contactId);
                }]
            },

            // This one is targeting the ui-view="hint" within the unnamed root, aka index.html.
            // This shows off how you could populate *any* view within *any* ancestor state.
              /**
               * ui-view=hint  操作的是root 也就是index.html
               *
               */
            'hint@': {
              template: 'This is contacts.detail populating the "hint" ui-view'
            },

            // This one is targeting the ui-view="menuTip" within the parent state's template.
              /**
               * 这个指向父状态template中的menuTip
               */
            'menuTip': {
              // templateProvider is the final method for supplying a template.
              // There is: template, templateUrl, and templateProvider.
                /**
                 * templateProvider是提供模板的底层方法
                 *
                 */
              templateProvider: ['$stateParams',
                function (        $stateParams) {
                  // This is just to demonstrate that $stateParams injection works for templateProvider.
                  // $stateParams are the parameters for the new state we're transitioning to, even
                  // though the global '$stateParams' has not been updated yet.
                  /**
                   *这里仅仅只是展示$stateParams怎么注入templateProvider的
                   */
                  return '<hr><small class="muted">Contact ID: ' + $stateParams.contactId + '</small>';
                }]
            }
          }
        })

        //////////////////////////////
        // Contacts > Detail > Item //
        //////////////////////////////

        .state('contacts.detail.item', {

          // So following what we've learned, this state's full url will end up being
          // '/contacts/{contactId}/item/:itemId'. We are using both types of parameters
          // in the same url, but they behave identically.
          url: '/item/:itemId',
          views: {

            // This is targeting the unnamed ui-view within the parent state 'contact.detail'
            // We wouldn't have to do it this way if we didn't also want to set the 'hint' view below.
            // We could instead just set templateUrl and controller outside of the view obj.
            '': {
              templateUrl: 'app/contacts/contacts.detail.item.html',
              controller: ['$scope', '$stateParams', '$state', 'utils',
                function (  $scope,   $stateParams,   $state,   utils) {
                  $scope.item = utils.findById($scope.contact.items, $stateParams.itemId);

                  $scope.edit = function () {
                    // Here we show off go's ability to navigate to a relative state. Using '^' to go upwards
                    // and '.' to go down, you can navigate to any relative state (ancestor or descendant).
                    // Here we are going down to the child state 'edit' (full name of 'contacts.detail.item.edit')
                    $state.go('.edit', $stateParams);
                  };
                }]
            },

            // Here we see we are overriding the template that was set by 'contacts.detail'
            'hint@': {
              template: ' This is contacts.detail.item overriding the "hint" ui-view'
            }
          }
        })

        /////////////////////////////////////
        // Contacts > Detail > Item > Edit //
        /////////////////////////////////////

        // Notice that this state has no 'url'. States do not require a url. You can use them
        // simply to organize your application into "places" where each "place" can configure
        // only what it needs. The only way to get to this state is via $state.go (or transitionTo)
      /**
       * 当一个状态并不一定非要有url  可以通过$scope.go  或者ui-sref   指向
       */
        .state('contacts.detail.item.edit', {
          views: {

            // This is targeting the unnamed view within the 'contacts.detail' state
            // essentially swapping out the template that 'contacts.detail.item' had
            // inserted with this state's template.
            '@contacts.detail': {
              templateUrl: 'app/contacts/contacts.detail.item.edit.html',
              controller: ['$scope', '$stateParams', '$state', 'utils',
                function (  $scope,   $stateParams,   $state,   utils) {
                  $scope.item = utils.findById($scope.contact.items, $stateParams.itemId);
                  $scope.done = function () {
                    // Go back up. '^' means up one. '^.^' would be up twice, to the grandparent.
                    /**
                     * 退回父状态 
                     * ^.^表示退回两次  即是grandparent
                     */
                    $state.go('^', $stateParams);
                  };
                }]
            }
          }
        });
    }
  ]
);

 

angular.module('uiRouterSample.contacts', [
  'ui.router'
])
  
.config(
  [          '$stateProvider', '$urlRouterProvider',
function ($stateProvider,   $urlRouterProvider) {
      $stateProvider
        //////////////
        // Contacts //
        //////////////
.state('contacts', {

          // With abstract set to true, that means this state can not be explicitly activated.
          // It can only be implicitly activated by activating one of its children.
/**
             *
             * 抽象路由模板，该状态永远不会被激活
* 只会被其子状态隐式激活
* 在本例子中  就是被导航中的ui-sref=contacts.list激活的
* */
abstract: true,

// This abstract state will prepend '/contacts' onto the urls of all its children.
/**
             * 这个抽象状态会预置/contacts到其所有的子状态中
*
             * */
url: '/contacts',

// Example of loading a template from a file. This is also a top level state,
          // so this template file will be loaded and then inserted into the ui-view
          // within index.html.
templateUrl: 'app/contacts/contacts.html',

// Use `resolve` to resolve any asynchronous controller dependencies
          // *before* the controller is instantiated. In this case, since contacts
          // returns a promise, the controller will wait until contacts.all() is
          // resolved before instantiation. Non-promise return values are considered
          // to be resolved immediately.
/**
             * resolve处理异步数据调用，在控制器实例化之前
*在这个例子中，contacts返回一个promise，控制器会等到promise处理完之后再进行初始化
*non-promise会立即resolve
             */
resolve: {
            contacts: ['contacts',
function( contacts){
                return contacts.all();
}]
          },

// You can pair a controller to your template. There *must* be a template to pair with.
/***
             * 为template添加控制器。
* 必须与template配对
*
             */
controller: ['$scope', '$state', 'contacts', 'utils',
function (  $scope,   $state,   contacts,   utils) {

              // Add a 'contacts' field in this abstract parent's scope, so that all
              // child state views can access it in their scopes. Please note: scope
              // inheritance is not due to nesting of states, but rather choosing to
              // nest the templates of those states. It's normal scope inheritance.
$scope.contacts = contacts;

$scope.goToRandom = function () {
               var randId = utils.newRandomKey($scope.contacts, "id", $state.params.contactId);


// $state.go() can be used as a high level convenience method
                // for activating a state programmatically.
/**
                 * go()方法是一个高级又便利的方法
*用于激活一个动态的状态
*/
$state.go('contacts.detail', { contactId: randId });
};
}]
        })

        /////////////////////
        // Contacts > List //
        /////////////////////

        // Using a '.' within a state name declares a child within a parent.
        // So you have a new state 'list' within the parent 'contacts' state.
/**
       * 在状态中用一个'.'才分割父状态和子状态，
* 所有现在创建了一个新的'list'状态位于父状态'contacts'中
*/
.state('contacts.list', {

          // Using an empty url means that this child state will become active
          // when its parent's url is navigated to. Urls of child states are
          // automatically appended to the urls of their parent. So this state's
          // url is '/contacts' (because '/contacts' + '').
/**
             * 用空的url表示这个子状态会在其父状态导航到时被激活
* 子状态会自动添加
* 所以这个状态的url='/contacts'+''
             */
url: '',

// IMPORTANT: Now we have a state that is not a top level state. Its
          // template will be inserted into the ui-view within this state's
          // parent's template; so the ui-view within contacts.html. This is the
          // most important thing to remember about templates.
/**
             * 现在我们有一个非顶级的状态
*这个模板会出入到其父状态的ui-view中：也就是contact.html中的ui-view
             *这是模板中很重要的性质
*/
templateUrl: 'app/contacts/contacts.list.html'
})

        ///////////////////////
        // Contacts > Detail //
        ///////////////////////

        // You can have unlimited children within a state. Here is a second child
        // state within the 'contacts' parent state.
/**
       * 一个状态的子状态是无限的，这是contacts的第二个子状态
*/
.state('contacts.detail', {

          // Urls can have parameters. They can be specified like :param or {param}.
          // If {} is used, then you can also specify a regex pattern that the param
          // must match. The regex is written after a colon (:). Note: Don't use capture
          // groups in your regex patterns, because the whole regex is wrapped again
          // behind the scenes. Our pattern below will only match numbers with a length
          // between 1 and 4.
/**
             * url上可以有参数，定义形式：param 或者 {param}
             * 如果使用{}，也可以定义成一个正则表达式，参数必须匹配正则
*
             */

// Since this state is also a child of 'contacts' its url is appended as well.
          // So its url will end up being '/contacts/{contactId:[0-9]{1,4}}'. When the
          // url becomes something like '/contacts/42' then this state becomes active
          // and the $stateParams object becomes { contactId: 42 }.
/**
             * /contacts/42
             * 这样的url就能访问该状态
* 而且$stateParams对象就变成了{contactId:42}
             *
             */
url: '/{contactId:[0-9]{1,4}}',

// If there is more than a single ui-view in the parent template, or you would
          // like to target a ui-view from even higher up the state tree, you can use the
          // views object to configure multiple views. Each view can get its own template,
          // controller, and resolve data.
/**
             * 如果父template不止一个ui-view
             * 或者想访问更往上的状态（—from state tree)
             * 可以使用views对象来配置多views，每个view都可以从他自己的template,controller,resolve data中获取
*/

// View names can be relative or absolute. Relative view names do not use an '@'
          // symbol. They always refer to views within this state's parent template.
          // Absolute view names use a '@' symbol to distinguish the view and the state.
          // So 'foo@bar' means the ui-view named 'foo' within the 'bar' state's template.
/**
             * view的名字有相对和绝对两种
* 相对的视图名字不需要用@标志
* 这些view总会在当前状态的父template中展示
*
             * 绝对名称的view使用@标志来区分状态和视图view
             * foo@bar   bar状态的foo  view
             */
views: {

            // So this one is targeting the unnamed view within the parent state's template.
/**
               * ''指向父template中未命名的view
               */
'': {
              templateUrl: 'app/contacts/contacts.detail.html',
controller: ['$scope', '$stateParams', 'utils',
function (  $scope,   $stateParams,   utils) {
                  $scope.contact = utils.findById($scope.contacts, $stateParams.contactId);
}]
            },

// This one is targeting the ui-view="hint" within the unnamed root, aka index.html.
            // This shows off how you could populate *any* view within *any* ancestor state.
/**
               * ui-view=hint  操作的是root 也就是index.html
               *
               */
'hint@': {
              template: 'This is contacts.detail populating the "hint" ui-view'
},

// This one is targeting the ui-view="menuTip" within the parent state's template.
/**
               * 这个指向父状态template中的menuTip
               */
'menuTip': {
              // templateProvider is the final method for supplying a template.
              // There is: template, templateUrl, and templateProvider.
/**
                 * templateProvider是提供模板的底层方法
*
                 */
templateProvider: ['$stateParams',
function (        $stateParams) {
                  // This is just to demonstrate that $stateParams injection works for templateProvider.
                  // $stateParams are the parameters for the new state we're transitioning to, even
                  // though the global '$stateParams' has not been updated yet.
/**
                   *这里仅仅只是展示$stateParams怎么注入templateProvider的
*/
return '<hr><small class="muted">Contact ID: ' + $stateParams.contactId + '</small>';
}]
            }
          }
        })

        //////////////////////////////
        // Contacts > Detail > Item //
        //////////////////////////////

.state('contacts.detail.item', {

          // So following what we've learned, this state's full url will end up being
          // '/contacts/{contactId}/item/:itemId'. We are using both types of parameters
          // in the same url, but they behave identically.
url: '/item/:itemId',
views: {

            // This is targeting the unnamed ui-view within the parent state 'contact.detail'
            // We wouldn't have to do it this way if we didn't also want to set the 'hint' view below.
            // We could instead just set templateUrl and controller outside of the view obj.
'': {
              templateUrl: 'app/contacts/contacts.detail.item.html',
controller: ['$scope', '$stateParams', '$state', 'utils',
function (  $scope,   $stateParams,   $state,   utils) {
                  $scope.item = utils.findById($scope.contact.items, $stateParams.itemId);

$scope.edit = function () {
                    // Here we show off go's ability to navigate to a relative state. Using '^' to go upwards
                    // and '.' to go down, you can navigate to any relative state (ancestor or descendant).
                    // Here we are going down to the child state 'edit' (full name of 'contacts.detail.item.edit')
$state.go('.edit', $stateParams);
};
}]
            },

// Here we see we are overriding the template that was set by 'contacts.detail'
'hint@': {
              template: ' This is contacts.detail.item overriding the "hint" ui-view'
}
          }
        })

        /////////////////////////////////////
        // Contacts > Detail > Item > Edit //
        /////////////////////////////////////

        // Notice that this state has no 'url'. States do not require a url. You can use them
        // simply to organize your application into "places" where each "place" can configure
        // only what it needs. The only way to get to this state is via $state.go (or transitionTo)
/**
       * 当一个状态并不一定非要有url  可以通过$scope.go  或者ui-sref   指向
*/
.state('contacts.detail.item.edit', {
          views: {

            // This is targeting the unnamed view within the 'contacts.detail' state
            // essentially swapping out the template that 'contacts.detail.item' had
            // inserted with this state's template.
'@contacts.detail': {
              templateUrl: 'app/contacts/contacts.detail.item.edit.html',
controller: ['$scope', '$stateParams', '$state', 'utils',
function (  $scope,   $stateParams,   $state,   utils) {
                  $scope.item = utils.findById($scope.contact.items, $stateParams.itemId);
$scope.done = function () {
                    // Go back up. '^' means up one. '^.^' would be up twice, to the grandparent.
/**
                     * 退回父状态 
* ^.^表示退回两次  即是grandparent
                     */
$state.go('^', $stateParams);
};
}]
            }
          }
        });
}
  ]
);