angular ui-router
翻译：深入 AngularUI Router
原文地址：http://www.ng-newsletter.com/posts/angular-ui-router.html
ui-router: https://angular-ui.github.io/ui-router/site/#/api/ui.router
ui-router 是 AngularUI 库提供的特别有用的一个部分，是一个通过提供状态机机制，而不是简单的 URL 来组织我们的界面的路由框架。
这个库提供了针对视图的众多的额外控制，我们可以创建嵌套的视图，在单个页面使用多个视图，多个视图来控制单个视图，还有更多特性。对于更加精细的控制和更为复杂的应用，ui-router 是非常棒的工具。
ui-router 从状态着手来管理路由，它将应用视为多个状态的组合，通过状态的切换进行路由。
- 一个状态可以对应一个页面地址，通过特定的地址到达应用的特定状态。
- 通过状态的 controller、template 和 views 来管理特定状态的 UI 和行为
- 通过嵌套视图来解决页面中重复出现的内容。
Installation
安装 ui-router，既可以直接下载发布版本，也可以通过 bower 来获取。
$ bower install angular-ui-router --save
然后，需要在页面中进入这个库，当然要先加载 angular 库。
<script type="text/javascript" src="angular-ui-router.js"></script>
在 angular 中注入 ui.router.
angular.module('myApp', ['ui.router'])
不像 angular 内置的 ngRoute, ui-router 可以嵌套视图，它是基于状态，而不 URL 的。
也不像 ngRoute 使用 ng-view 指令，在 ui-router 中，我们使用 ui-view 指令。
当在 ui-router 中考虑路由和状态的关系时，我们主要关注应用的什么状态对应应用的什么路由。
<div ng-controller="DemoController"> <div ui-view></div> </div>
类似 ngRoute, 对于给定的状态，模板中的内容将会填充到 <div ui-view></div> 元素，每个模板还可以包含自己的 ui-view ，这就是我们可以支持嵌套路径的原因。
定义路径的时候，我们使用 .config 方法，像通常一样，但是使用 $stateProvider 来替换 $routeProvider。
.config(function($stateProvider, $urlRouterProvider) {
$stateProvider
.state('start', {
url: '/start',
templateUrl: 'partials/start.html'
})
});
这样，我们；定义了名为 start 的状态，传递的对象定义了状态配置信息，或者称为 stateConfig，类似于路由配置对象，我们通过它配置状态信息。
template, templateUrl, templateProvider
可以使用下面三种之一的方式来定义视图使用的模板：
- template, 字符串方式的模板内容，或者是一个返回 HTML 的函数
- templateUrl, 模板的路径，或者返回模板路径的函数
- templateProvider, 返回 HTML 内容的函数
例如
$stateProvider.state('home', {
template: '<h1>Hello {{ name }}</h1>'
});
Controller
类似于 ngRoute，我们既可以通过控制器的名字来关联一个预定义的控制器，也可以直接创建一个控制器函数来处理。
如果没有对应的模板定义，控制器对象就不会被创建。
Resolve
使用 resolve 功能，我们可以准备一组用来注入到控制器中的依赖对象。在 ngRoute 中，resolve 可以在路由实际渲染之前解决掉 promise
resolve 选项提供一个对象，对象中的 key 就是准备注入 controller 的依赖名称，值则是创建对象的工厂。
如果是一个串，就试图用这个串来匹配当前已经注册的服务名称，如果是一个函数，执行这个函数，返回的值就是依赖。如果函数返回一个 promise，在控制器被实例化之前，将会被 resolved，返回的值被注入到 controller 中。
$stateProvider.state('home', {
resolve: {
// This will return immediately as the
// result is not a promise
person: function() {
return {
name: "Ari",
email: "ari@fullstack.io"
}
},
// This function returns a promise, therefore
// it will be resolved before the controller
// is instantiated
currentDetails: function($http) {
return $http({
method: 'JSONP',
url: '/current_details'
});
},
// We can use the resulting promise in another
// resolution
facebookId: function($http, currentDetails) {
$http({
method: 'GET',
url: 'http://facebook.com/api/current_user',
params: {
email: currentDetails.data.emails[0]
}
})
}
},
controller: function($scope, person,
currentDetails, facebookId) {
$scope.person = person;
}
})
URL
url 用来设置应用对应的一个特定状态. 也就是说，我们可以通过 url 来到达某个特定的状态，所以这里的 url 不是简单的 url 地址，而是某个可到达状态的标志。
这个特性类似于 ngRoute 中的 URL, 但是，可以被看作一个重大的升级，后面我们就会看到。
简单的路由类似下面所示。
$stateProvider
.state('inbox', {
url: '/inbox',
template: '<h1>Welcome to your inbox</h1>'
});
当我们导航到 /index 的时候，应用将会过渡到 inbox 状态，使用这里提供的内容模板填充 ui-view 的内容。
URL 中可以包含多种内容，令人难以置信的强大，可以像在 ngRoute 中设置简单的参数。
$stateProvider
.state('inbox', {
url: '/inbox/:inboxId',
template: '<h1>Welcome to your inbox</h1>',
controller: function($scope, $stateParams) {
$scope.inboxId = $stateParams.inboxId;
}
});
这里，我们创建了 :inboxId 参数来捕获 url 中的第二部分，例如，如果应用访问 /inbox/1，那么，$stateParameter.inboxId 就成为 1, 实际上， $stateParams 的值将为 { inboxId: 1 }
也可以使用另外一种语法。
url: '/inbox/{inboxId}'
路径必须完全匹配，不像 ngRoute, 如果用户访问 /inbox/，这个路径配置将会工作，但是，如果访问 /inbox，这个状态就不会被激活。
还可以使用正则表达式来表示参数，这样可以通过正则表达式来设置匹配规则，例如。
// Match only inbox ids that contain
// 6 hexidecimal digits
url: '/inbox/{inboxId:[0-9a-fA-F]{6}}',
// Or
// match every url at the end of `/inbox`
// to `inboxId` (a catch-all)
url: '/inbox/{inboxId:.*}'
注意，不能在路由中使用捕获组
甚至可以在路径中使用查询参数。
// will match a route such as // /inbox?sort=ascending url: '/inbox?sort'
绝对路由
如果你使用绝对 url 方式，需要在 url 字符串的开发加上特殊字符 ^
$stateProvider
.state('contacts', {
url: '/contacts',
...
})
.state('contacts.list', {
url: '^/list',
...
});
'contacts'状态将匹配"/contacts"'contacts.list'状态将匹配"/list"。子状态的url没有附在父状态的url之后的，因为使用了^。
嵌套路由
我们可以使用 url 参数添加到路由中来实现嵌套路由。这样可以提供多个 ui-views 在我们的页面中，例如，我们可以在 /inbox 之上，提供嵌套的独立路由。这里使用了子状态。
$stateProvider
.state('inbox', {
url: '/inbox/:inboxId',
template: '<div><h1>Welcome to your inbox</h1>\
<a ui-sref="inbox.priority">Show priority</a>\
<div ui-view></div>\
</div>',
controller: function($scope, $stateParams) {
$scope.inboxId = $stateParams.inboxId;
}
})
.state('inbox.priority', {
url: '/priority',
template: '<h2>Your priority inbox</h2>'
});
第一个路由与前面一样，现在还有第二个路由，一个匹配 inbox 之下的子路由，语法 (.) 表示这是一个子路由。
/inbox/1 匹配第一个状态，/inbox/1/priority 则匹配第二个状态。使用这种语法，我们可以在父路由中支持嵌套的 url。在父视图中的 ui-view 指令将会处理 priority。
Params
params 选项是参数名称或者正则的数组。它不能合并 url 选项，当状态激活的时候，应用会使用这些参数填充 $stateParams 服务。
Views
我们可以在 state 中提供命名的视图。这是强大的特性，在单个视图中，我们可以定义多个视图，甚至使用单个模板。
如果我们使用了 views 参数，那么，templateUrl, template 和 templateProvider 就会忽略。如果我们希望包含父模板，我们需要创建一个抽象模板。
假如我们有如下模板。
<div> <div ui-view="filters"></div> <div ui-view="mailbox"></div> <div ui-view="priority"></div> </div>
主要注意的是，顶级的状态自然对应母版页中的视图，一般这个视图是 noname 的，所以，需要一个 noname 的视图来匹配这个 placeholder。其它的视图需要匹配父状态中的视图 placeholder，这些 placeholder 可以是命名的，也可以是 naname的，自然，noname 的只能有一个，否则无法进行区分，我们在 provider 中进行配置的时候，就需要描述清楚这些 view 和 placeholder 之间的对应关系。
使用 @ 可以定义绝对命名的视图名称，@ 的前面是 placeholder 的名称，后面是状态的名称。@ 前面为空表示未命名的 ui-view，@ 后面为空表示相对于根模板，通常是 index.html
我们可以创建命名的视图，然后填充对应的模板。每个子视图都可以有特有的模板，控制器和数据。
$stateProvider
.state('inbox', {
views: {
'filters': {
template: '<h4>Filter inbox</h4>',
controller: function($scope) {}
},
'mailbox': {
templateUrl: 'partials/mailbox.html'
},
'priority': {
template: '<h4>Priority inbox</h4>',
resolve: {
facebook: function() {
return FB.messages();
}
}
}
}
});
在这个例子中，我们有两个命名的视图嵌套在抽象视图中。
Abstract
我们永远不能直接激活抽象模板，但是，可以通过派生模板来激活。
抽象模板提供封装命名视图的模板，可以传递 $scope 对象给派生子模板。可以通过它解决依赖问题，或者特定数据处理，或者简单地同样的 url 来嵌套多个路由，例如，所有路由都在 /admin 下面。
$stateProvider
.state('admin', {
abstract: true,
url: '/admin',
template: '<div ui-view></div>'
})
.state('admin.index', {
url: '/index',
template: '<h3>Admin index</h3>'
})
.state('admin.users', {
url: '/users',
template: '<ul>...</ul>'
});
onEnter, onExit
在应用进入或者退出视图的时候，会调用这些回调函数。它们都可以设置回调函数；函数可以访问获取的数据。
这些回调函数可以提供我们一些能力，在访问新视图，或者改变当前状态的时候。这里是很好的执行 "Are you sure?" 对话框，或者请求用户在进入之前登陆的地方。
两个函数都不提供参数，需要的信息需要自己提供。
Data
我们可以附加任意的数到我们的状态配置对象 configObject 上，data 属性类似于 resolve 属性，除了不会注入到控制器，也不会 resolve promise。
当需要从父状态向子状态传递数据的时候，附加数据是方便的途径。
Evnets
类似 ngRoute 服务，angular-route 服务在状态生命周期的不同时间点会触发多种事件。我们可以通过在 $scope 中监听来处理这些事件。
所有的下面的事件都会在 $rootScope 中触发，所以，我们可以在任何 $scope 对象中监听这些事件。
State change events
可以如下监听
$scope.$on('$stateChangeStart',
function(evt, toState, toParams, fromState, fromParams), {
// We can prevent this state from completing
evt.preventDefault();
});
$stateChangeStart
当从一个状态开始向另外一个状态过度的时候触发。
$stateChangeSuccess
当状态过渡完成之后触发。
$stateChangeError
在状态过渡中出现错误。常见的错误例如，不能获取模板，或者 promise 不能成功 resolve 等等
视图加载事件
ui-router 也提供了视图加载阶段的事件。
$viewContentLoading
视图开始加载，但是，在 DOM 渲染之前。
可以如下监听。
$scope.$on('$viewContentLoading',
function(event, viewConfig){
// Access to all the view config properties.
// and one special property 'targetView'
// viewConfig.targetView
});
$viewContentLoad
视图已经加载，渲染完成。
$stateParams
在前面的内容中，我们使用 $stateParams 来从 url 参数中获取 params ，这个服务，与 url 不同。
例如，如果我们 inbox 状态的 url 如下。
url: '/inbox/:inboxId/messages/{sorted}?from&to'
用户使用下面的 url 访问
/inbox/123/messages/ascending?from=10&to=20
我们的 $stateParams 对象将获取如下数据。
{inboxId: '123', sorted: 'ascending', from: 10, to: 20}
$urlRouterProvider
类似 ngRoute, 可以创建当特定的 url 访问时处理的规则。
可以通过不同的 url 激活不同的状态，所以在管理激活和加载状态的时候， $urlRouterProvider 并不是必须的。在状态管理之外的时候才会需要，比如重定向，或者验证的时候。
when()
when 函数需要两个参数，我们希望匹配的路径，另外就是我们希望重新定向的目标。也可以是一个函数。
例如，如果希望任何空的路由到我们的 /inbox 路由中。
.config(function($urlRouterProvider) {
$urlRouterProvider.when('', '/inbox');
});
如果提供一个函数处理，路由匹配的时候，这个函数就会被调用，它可以返回下列三种之一的结果。
- false，这个回应告诉 $urlRouter 规则并不匹配，应该查找其它匹配的状态，在我们希望验证用户是否访问正确地址的时候很有用。
- 字符串，$urlRouter 将其作为重定向目标。
- true 或者 undefined，函数已经处理了这个 url
otherwise()
与 ngRoute 中的 oterwise() 方法类似，oterwiese() 在没有其它路由匹配的情况下重定向。这是创建默认 url 的好方法。
otherwise() 函数只需要一个参数，一个字符串或者一个函数。
如果提供了一个字符串，就会被看做一个默认地址，在任何错误的或者不能匹配任何路由的时候，就会被重定向到这个地址。
如果是一个函数，在没有其它路由匹配的时候，就会被执行
.config(function($urlRouterProvider) {
$urlRouterProvider.otherwise('/');
// or
$urlRouterProvider.otherwise(
function($injector, $location) {
$location.path('/');
});
});
rule()
如果我们希望处理任何路由，或者在其它路由之前进行一些处理，可以使用 rule() 函数。
我们必须返回一个验证的路径串
app.config(function($urlRouterProvider){
$urlRouterProvider.rule(
function($injector, $location) {
return '/index';
});
})
激活状态
有三种方式来激活特定的状态
- 使用 $state.go() 方法
- 使用 ui-sref 绑定的连接
- 直接导航到与状态关联的 url
创建报名向导
为什么不使用一下它呢？
我们创建一个报名的向导来演练一下 ui-router 的使用。
使用 ui-router ，我们创建一个简单的报名服务，使用一个控制器来处理报名。
首先，我们创建应用的视图。
<div ng-controller="WizardSignupController"> <h2>Signup wizard</h2> <div ui-view></div> </div>
在这个视图中，我们定义了报名视图。下一步，在报名向导中，需要三步
- start，在这一步，我们获取用户名称，提供欢迎信息
- email, 这里，我们获取用户的 email 信息
- finish, 这里，用户完成报名，我们简单地显示完成页面
报名处理依赖 wizardapp.controllers 模块，
angular.module('wizardApp', [
'ui.router',
'wizardapp.controllers'
]);
我们的 wizardSignupController 控制器，使用 $scope.user 对象在整个过程中收集信息。
angular.module('wizardapp.controllers', [])
.controller('WizardSignupController',
['$scope', '$state', function($scope, $state) {
$scope.user = {};
$scope.signup = function() {}
}]);
现在，向导处理逻辑处理主要工作，配置 config()
angular.module('wizardApp', [
'ui.router', 'wizardapp.controllers'
])
.config(['$stateProvider', '$urlRouterProvider',
function($stateProvider, $urlRouterProvider) {
$stateProvider
.state('start', {
url: '/step_1',
templateUrl: 'partials/wizard/step_1.html'
})
.state('email', {
url: '/step_2',
templateUrl: 'partials/wizard/step_2.html'
})
.state('finish', {
url: '/finish',
templateUrl: 'partials/wizard/step_3.html'
});
}]);
这样，我们基本的流程就已经有了。现在，如果用户导航到 /step_1，就会看到开始页面，尽管现在地址是 /step_1, 而我们希望是 /wizard/step_1
为了这个效果，我们创建 abstract 状态来寄宿各个步骤。
.config(['$stateProvider', '$urlRouterProvider',
function($stateProvider, $urlRouterProvider) {
$stateProvider
.state('wizard', {
abstract: true,
url: '/wizard',
template: '<div><div ui-view></div></div>'
})
.state('wizard.start', {
url: '/step_1',
templateUrl: 'partials/wizard/step_1.html'
})
.state('wizard.email', {
url: '/step_2',
templateUrl: 'partials/wizard/step_2.html'
})
.state('wizard.finish', {
url: '/finish',
templateUrl: 'partials/wizard/step_3.html'
});
}]);
这样，它们都安全地嵌套到 /wizard 之下了。
在状态之间进行导航，我们使用 ui-router 提供的指令 ui-sref 来生成链接，这个指令用来生成导航链接。
例如，step_1.html 如下。
<!-- step_1.html --> <h3>Step 1</h3> <form ng-submit=""> <input type="text" ng-model="user.name" placeholder="Your name" /> <input type="submit" class="button" value="Next" ui-sref="wizard.email"/> </form>
我们还希望在报名流程完成之后，执行特定的动作，来调用定义在父控制器上的 signup 函数，我们可以在最后的步骤中添加一个控制器来调用 $scope.signup() 函数。由于整个向导封装在 WizardSignupControoler 中，我们可以像通常一样访问嵌套的 scope 对象。
.state('wizard.finish', {
url: '/finish',
templateUrl: 'partials/wizard/step_3.html',
controller: function($scope) {
$scope.signup();
}
});
总结
在这里，我们深入讨论了 ui-router 几乎全部的特性，我们发现这个库非常有用，希望也能帮到你。
