指令详解
一个指令的定义应当是如下这个样子:
code:
angular.module('myApp', [])
.directive('myDirective', function (UserDefinedService) {
// 指令定义放在这里
});
其中,fun中的注入参数为angular自带或用户定义的服务,需要在指令内部中调用。分析其结构:
angular.module('myApp', [])
:是声明整个应用对象的。.directive('myDirective', fun(){})
:directive方法接受两个参数:字符串和函数。
字符串myDirective
是用以在视图中引用特定的指令。而函数则返回一个对象,这个对象中定义了指令的全部行为,$compile服务利用这个方法返回的对象,在DOM调用指令时来构造指令的行为。即:
angular.module('myApp', [])
.directive('myDirective', function (UserDefinedService) {
return {
}
});
当然除了返回一个对象,其实也可以返回一个函数:
angular.module('myApp', [])
.directive('myDirective', function (UserDefinedService) {
return function() { //此时这个函数叫做“链接传递函数”
}
});
但是一般地,都采用返回对象的形式,这样指令的定义可以更丰富。返回函数的情况只有在定义非常简单的指令时才可能会使用。
下面看指令中第二个参数——函数——返回对象的详细配置!!!
code:
angular.module('myApp', [])
.directive('myDirective', function() {
return {
restrict: String,
priority: Number,
terminal: Boolean,
template: String or Template Function:
function(tElement, tAttrs){...},
templateUrl: String,
replace: Boolean or String,
scope: Boolean or Object,
transclude: Boolean,
controller: String or
function(scope, element, attrs, transclude, otherInjectables){...},
controllerAs: String,
require: String,
link: function(scope, iElement, iAttrs){...},
compile: //该属性值返回的是一个对象或函数,如下所示:
function(tElement, tAttrs, transclude) {
return {
pre: function(scope, iElement, iAttrs, controller){...},
post: function(scope, iElement, iAttrs, controller){...}
}
//或者
return function postLink(...){...}
}
}
});
下面分别对各个配置项进行详细说明:
1. restrict
- 非必须
- 可选值:’EACM’
EACM指的是指令在DOM视图中的应用形式,如下:
E: (元素)
<my-directive></my-directive>
A: (属性,默认值)
<div my-directive="expression"></div>
C: (类名)
<div class="my-directive:expression;"></div>
M: (注释)
<--directive:my-directive expression-->
这些值可以单独使用,也可以混合使用。其中A是推荐的方式,因为它的兼容性更好,也更容易扩充。
2. priority
优先级。它的作用是声明指令的优先级,当多个指令用在同一个DOM元素上时,哪个会先执行呢?就取决于这个参数。如果两个指令的优先级一样,那么声明在前的会先被调用并执行。
例如 ng-repeat
的优先级就是1000,因此,它总是比其他指令更优先执行。
3. terminal
Boolean值,它的作用是告诉angularJS是否停止运行当前元素上比本指令优先级更低的指令,但与当前指令优先级同级的指令仍然会被执行的。如下面的例子:
<div>
<p my-terminal-test1 my-terminal-test2></p>
</div>
angular.module('angularLearningApp')
.directive('myTerminalTest1', function() {
return {
restrict: 'A',
priority: 1,
template: '百度',
link: function (scope, element, attrs) {
console.log("myTerminalTest1");
}
}
})
.directive('myTerminalTest2', function() {
return {
restrict: 'A',
priority: 2,
terminal: false, //现将terminal设置为false
link: function(scope, element, attrs) {
console.log("myTerminalTest2");
element[0].textContent += '谷歌';
}
}
});
显然div中的内容是 百度谷歌
,如果将terminal设置为true,则显示的结果为 谷歌
,这是因为 myTerminalTest1
指令的优先级低于 myTerminalTest2
,而terminal为true因此,低于它的指令将不被执行。
4. template
template有两种形式:
- String //模板字符串
- function(tElement, tAttrs){ …; return templateStr;//返回模板字符串}
需要注意的是: template返回的模板中,DOM结构中必须存在一个根节点。在实际的开发中,更常使用的是templateUrl,因为可以避免字符串拼接,那是可读性、维护性很差的方式。另外,template中最为重要的东西是controller与本指令中template变量的数据传递。
5. templateUrl
同样有两种形式:
- String // 模板html文件路径
- function(tElement, tAttrs){…; return templatePath;//返回模板html路径}
默认情况下,调用指令会在后台通过ajax请求html模板文件,有两个特别需要注意的:
- 在本地开发时,需要在后台运行一个本地服务器,用以从文件系统加载HTML模板,否则会导致Cross Origin Request Script(CORS)错误。
- 模板加载是异步的,意味着编译和链接要暂停,等待模板加载完成。
通过Ajax异步加载大量的模板将严重拖慢一个客户端应用的速度。为了避免延迟,可以在部
署应用之前对HTML模板进行缓存。在大多数场景下缓存都是一个非常好的选择,因为AngularJS
通过减少请求数量提升了性能。更多关于缓存的内容请查看第28章。
模板加载后, AngularJS会将它默认缓存到$templateCache服务中。在实际生产中,可以提
前将模板缓存到一个定义模板的JavaScript文件中,这样就不需要通过XHR来加载模板了。更多内容请查看第34章。
6. replace
默认值是false,表示模板的内容将会被插入到视图中应用指令元素的内部。如果设置为true,则表示替代,即插入到视图中时,应用指令的html元素将被删除,取而代之的是html模板。
7. scope
可选参数
- boolean 默认是false,即该指令并不会创建新的作用域,改指令内部或外部的作用域是一样的。当为true时,会从父作用域继承并创建一个新的作用域对象,即该指令内部和外部并不是在一个作用域内。
- Object :设置此属性也被称为“隔离作用域”。
scope为Boolean时
code:
<div ng-init="someProperty = 'some data'"></div>
<div ng-init="siblingProperty='moredata'">
Inside Div Two: { { aThirdProperty } }
<div ng-init="aThirdProperty = 'data for 3rd property'"
ng-controller="SomeController">
Inside Div Three: { { aThirdProperty } }
<div ng-controller="SecondController">
Inside Div Four: { { aThirdProperty } }
<br>
Outside myDirective: { { myProperty } }
<div my-directive ng-init="myProperty = 'wow, this is cool'">
Inside myDirective: { { myProperty } }
<div>
</div>
</div>
</div>
angular.module('myApp', [])
.controller('SomeController', function($scope) {
// 可以留空,但需要被定义
})
.controller('SecondController', function($scope) {
// 同样可以留空
});
angular.module('myApp', [])
.directive('myDirective', function() {
return {
restrict: 'A',
//scope: true
};
});
首先,将把 scope:true
注释掉即设置scope为默认的false。此时的结果是:
view:
<div ng-init="someProperty = 'some data'"></div>
<div ng-init="siblingProperty='moredata'">
Inside Div Two: {{ aThirdProperty }}
<div ng-init="aThirdProperty = 'data for 3rd property'"
ng-controller="SomeController">
Inside Div Three:{{ aThirdProperty }}
<div ng-controller="SecondController">
Inside Div Four:{{ aThirdProperty }}<br>
Outside myDirective: {{ myProperty }}
<div my-directive-scope-test ng-init="myProperty = 'wow, this is cool'">
Inside myDirective: {{ myProperty }}<div>
</div>
</div>
</div>
显而易见,Outside myDirective和Inside myDirecitve都将是有值的,即使myProperty的值是在指令标签中定义的,但因为指令中的配置项scope为false,该指令并没有产生一个新的作用域,因此,在这个指令标签内部和外部都是在一个作用域下,即:SecondController对应的作用域下,所以值都是有的。
但如果将 scope:true
释放掉,那么该指令就会产生一个独立作用域,此作用域继承父作用域,但是在该作用域中定义的变量myProperty,就无法在该指令外部调用了,因此,结果就是:
Outside myDirective:
Inside myDirective: wow, this is cool
这就是scope为boolean值时的作用。
scope为Object时————隔离作用域
设置scope配置属性值为Object时,指令的模板就无法访问外部作用域了。也因此,不受外部作用域变量的影响,因此,隔离作用域常用来创建可复用的指令组件。
code:
<div ng-controller='SomeController2'>
Outside myDirective: { { myProperty2 } }
<div my-directive-scope-test2 ng-init="myProperty2 = 'wow, this is cool!'">
Inside myDirective: { { myProperty2 } }
</div>
</div>
angular.module('myApp', [])
.controller('SomeController2', function($scope) {
})
.directive('myDirectiveScopeTest2', function() {
return {
restrict: 'A',
scope: {}, //对象
priority: 100,
template: '<div>Inside myDirective: { { myProperty2 } }</div>'
};
});
view:
<div ng-controller='SomeController2'>
Outside myDirective: {{ myProperty2 }}
<div my-directive-scope-obj-test ng-init="myProperty2 = 'wow, this is cool!'">
Inside myDirective: {{ myProperty2 }}
</div>
</div>
Inside myDirective
中将不会出现值,没错,因为scope隔离了模板与外界作用域。
但是Outside myDirective
中将存在值,为什么呢?难道隔离作用域只是隔离了模板与外界作用域,而当前指令应用的DOM元素中用其他指令定义的变量仍然可以在外面被访问?
为此,在此进行对比演示:
code:
<div ng-controller="ScopeValueCompareController"
ng-init="myProperty='wow,this is so cool'">
Surrounding scope: {{ myProperty }}
<div my-inherit-scope-directive></div>
<div my-directive></div>
</div>
angular.module('myApp', [])
.controller('ScopeValueCompareController', function($scope) {
})
.directive('myDirective3', function() {
return {
restrict: 'A',
template: 'Inside myDirective, isolate scope: {{ myProperty }}',
scope: {}
};
})
.directive('myInheritScopeDirective', function() {
return {
restrict: 'A',
template: 'Inside myDirective, isolate scope: {{ myProperty }}',
scope: true
};
});
view:
<div ng-controller="ScopeValueCompareController"
ng-init="myProperty3='wow,this is so cool'">
Surrounding scope: {{ myProperty3 }}
<div my-directive3></div>
<div my-inherit-scope-directive></div>
</div>
scope为{}时,指令内模板作用域被隔离开,所以是没有值得。scope为true时,指令内新建了一个作用域,但他继承父级作用域(这里是ScopeValueCompareController对应的作用域),因此可以访问外部变量。
scope为对象时的绑定策略
scope为Object时,像上面的空对象的情况肯定是不适用的。angularJS提供了几种方法,可以将指令内部的隔离作用域和指令外部的作用域进行数据绑定。
@
(or@attr
) : 本地作用域属性。使用@
符号将本地作用域与DOM属性的值进行绑定,指令内部作用域可以访问并使用外部作用域的变量,常用于DOM中属性值为固定参数。=
(or=attr
) : 双向绑定。使用=
符号将本地作用域中的属性和DOM属性的值进行双向绑定,那么当DOM属性值随时改变时,指令中的值也会改变,同时反过来也是一样的。常用于DOM中对应属性值是动态的,如ng-model。&
(or&attr
) : 父级作用域绑定。主要用于运行其中的函数,也就是说这个值在指令中设置后,会生成一个指向父级作用域的包装函数。如果要调用带有参数的父方法,则需要在DOM指令属性值的函数形参中传入一个对象,对象的键是参数名,值是参数值。
如下面的例子:
code:
<input type="text" ng-model="to"/>
<!-- 调用指令 -->
<div scope-example ng-model="to" on-send="sendMail(email)"
from-name="ari@fullstack.io">
</div>
自定义指令 scope-example
中如果要访问此处的数据(模型to
、 函数方法sendMail(email)
以及字符串"ari@fullstack.io"
)的话,就必须配置scope为对象,如下:
scope: {
ngModel: '=', // 将ngModel同指定对象绑定
onSend: '&', // 将引用传递给这个方法
fromName: '@' // 储存与fromName相关联的字符串
}
注意指令中本地变量的命名规则(驼峰法)。如果不想用驼峰法,想自定义随便取名,也可以指定要绑定的外部DOM变量,如下:
scope: {
a: '=ngModel', // 将ngModel同指定对象绑定
b: '&onSend', // 将引用传递给这个方法
c: '@fromName' // 储存与fromName相关联的字符串
}
那么a
的值就是 to
的值, b
的值就是 sendMail(email)
方法的引用,c
的值就是ari@fullstack.io
。
这就是三种绑定策略的不同以及各自的适用场景!
8. transclude
可选参数。Boolean值,默认值为false。定义为true时,它会将整个DOM嵌入到指令内部定义的模板中,包括DOM中的其他指令。
只有当你希望创建一个可以包含任意内容的指令时, 才使用transclude: true。
为了将作用域传递进去, scope参数的值必须通过{}或true设置成隔离作用域。如果没有设
置scope参数,那么指令内部的作用域将被设置为传入模板的作用域。嵌入允许指令的使用者方便地提供自己的HTML模板,其中可以包含独特的状态和行为,并对指令的各方面进行自定义。看一个简单的例子,一个包括标题和少量html内容的侧边栏。
code:
<div sidebox title="Links">
<ul>
<li>First link</li>
<li>Second link</li>
</ul>
</div>
为这个侧边栏创建一个简单的指令,设置transclude为true:
angular.module('myApp', [])
.directive('sidebox', function() {
return {
restrict: 'EA',
scope: {
title: '@'
},
transclude: true,
template: '<div class="sidebox">\
<div class="content">\
<h2 class="header">{ { title } }</h2>\
<span class="content" ng-transclude>\
</span>\
</div>\
</div>'
};
});
view:
<div sidebox title="Links">
<ul>
<li>First link</li>
<li>Second link</li>
</ul>
</div>
此时,在浏览器中生成的DOM结构为:
<div sidebox title="Links"> <!-- a:原来DOM中应用sidebox指令的标签 -->
<div class="sidebox"> <!-- c:sidebox指令中定义的模板 -->
<div class="content"> <!-- c -->
<h2 class="header">{ { title } }</h2> <!-- c -->
<span class="content" ng-transclude> <!-- c -->
<ul> <!-- b 的子标签内容 -->
<li>First link</li> <!-- b -->
<li>Second link</li> <!-- b -->
</ul>
</span> <!-- c -->
</div> <!-- c -->
</div> <!-- c -->
</div> <!-- a -->
显然,transclude设为true后,angularJS将该指令应用的DOM元素(a)的内部所有元素(b)都嵌入到了指令模板中声明ng-transclude的元素(c)内,并全部套入到a中,再被渲染出来。
transclude和ng-transclude是联合使用的。
9.controller
controller可以是字符串或函数:
- String : 以该字符串为值去整个项目中查找同名注册的controller
- function: 匿名构造函数定义的内联controller
code:
angular.module('myApp',[])
.directive('myDirective', function() {
restrict: 'A',
controller:
function($scope, $element, $attrs, $transclude) {
// 控制器逻辑放在这里
}
});
我们可以将任意可以被注入的AngularJS服务传递给控制器。例如,如果我们想要将$log服
务传入控制器,只需简单地将它注入到控制器中,便可以在指令中使用它了。上面的例子,有:
- $scope :与指令元素相关联的当前作用域
- $element: 指令元素,即当前指令应用的DOM元素
- attrs:由指令元素的属性和属性值所组成的对象。如:‘<divid="aDiv"class="box"></div>‘的attrs值为:
{id: "aDiv", class: "box"}
- $transclude: transclude链接函数是实际被执行用来克隆元素和操作DOM的函数。
指令的控制器和link函数可以进行互换。控制器主要是用来提供可在指令间复用的行为,但
链接函数只能在当前内部指令中定义行为,且无法在指令间复用。由于指令可以require其他指令所使用的控制器,因此控制器常被用来放置在多个指令间共享的动作。
10.controllerAs
字符串。这个参数用以设置控制器的别名,以此名发布控制器,并且作用域可以访问controllerAs。
code:
angular.module('myApp')
.directive('myDirective', function() {
return {
restrict: 'A',
template: '<h4>{{ myController.msg }}</h4>',
controllerAs: 'myController',
controller: function() {
this.msg = "Hello World"
}
}
});
11. require
字符串或数组。可选值。当值为字符串时,它应当是另一个指令的名字。require是将其值所指定的指令中的控制器注入到当前指令中,并作为当前指令的link函数的第四个参数。而这个被注入进来的控制器(位于指令链接的父指令中)会首先被当前指令查找,查找当然是根据require的值决定的,不过给这个值予以不同的前缀,会影响它的查找行为:
- ? 寻找require值对应的指令中的控制器,如果在指令链的父指令(即require的值所对应的指令)中没有找到需要的控制器,则当前指令中的link函数的第四个参数将会是null。
- ^ 如果在指令链的父指令中没有找到需要的控制器,则会进一步往指令链上游寻找需要的控制器。
- ?^ 教程的解释是:我们可选择地加载需要的指令并在父指令链中进行查找。
- 没有前缀的情况: 如果没有前缀,则指令就会在自身所提供的控制器中进行查找,如果没有找到控制器(或者没有找到require的值所对应的指令),就会抛出一个错误。
code:
<hello>
<div>hello</div>
<beautiful good>
beautiful
</beautiful>
</hello>
angular.module("myApp", [])
.directive("hello",function(){
return {
restrict : "E",
controller : function($scope){
$scope.name = "张三";
this.information = {
name : $scope.name,
age : 25,
job : "程序员"
}
},
link : function(scope){
}
}
})
.directive("beautiful",function(){
return {
restrict : "E",
require : "?good",
controller : function(){
this.name = "beautiful";
},
link : function (scope,element,attrs,good) {
console.log(good.name)
}
}
}).
directive("good",function(){
return {
restrict : "A",
require : "?^hello",
controller : function(){
this.name = "good";
},
link : function (scope,element,attrs,hello) {
console.log(hello.information)
}
}
});
12.compile
该属性的属性值是一个函数内部返回一个对象,或者函数。理解compile和link函数是angularJS需要讨论的高级话题之一,对于了解angularJS是如何工作的是至关重要的。
本质上,当我们设置了link选项,实际上是创建了一个postLink()链接函数,以便compile()函数可以定义函数。
通常情况下,如果我们设置了complie()函数,说明我们希望在指令和实时数据被放到DOM中之前对DOM进行操作,在这个函数中进行诸如,添加和删除节点等DOM操作是安全的。
特别注意:compile函数和link函数是互斥的。即,如果同时设置了这两个配置项,那么angularJS会选择compile函数的返回函数作为link函数,而本身link函数的配置会被完全忽略。
- 编译函数compile内部通常用来转换可以被安全操作的DOM节点,不要对DOM进行事件监听注册。
- 链接函数link负责将DOM和作用域进行链接。
如下一个例子:
compile: function(tEle, tAttrs, transcludeFn) {
var tplEl = angular.element('<div>' +
'<h2></h2>' +
'</div>');
var h2 = tplEl.find('h2');
h2.attr('type', tAttrs.type);
h2.attr('ng-model', tAttrs.ngModel);
h2.val("hello");
tEle.replaceWith(tplEl);
return function(scope, ele, attrs) {
// 连接函数
};
}
13 link函数
link函数用来创建可以操作DOM的属性。当定义了编译函数来取代链接函数时,链接函数是我们能提供给返回对象的第二个方法,也就是postLink函数。本质上讲,这个事实正说明了链接函数的作用。它会在模板编译并同作用域进行链接后被调用,因此它负责设置事件监听器,监视数据变化和实时的操作DOM。
链接函数一共有四个参数:
- scope : 指令用来在其内部注册监听器的作用域
- iElement: 代表实例元素,即使用此指令的元素。在postLink函数中,我们应该只操作这个元素和其子元素,因为这些元素已经被链接过了。
- iAttrs: 代表实例属性,一个由定义在元素上的属性组成的标准化列表,可以在所有指令的链接函数间共享。会以javascript对象的形式进行传递。
- controller: 这个参数只有在当前指令存在
require
选项时才会有,否则就是undefined。如果require的值是另一个指令A,那么controller的值就是这个指令A中的controller;如果require的值是另一个单独的controller,那么当前controller的值就是这个controller;如果require指向多个控制器,那么当前controller就是一个由这些多个控制器组成的数组。
link函数是指令中最为常用的一个配置项。它和controller函数最大的区别就是功能性区分,前者是用以操作DOM,后者用以指令间传递。
自定义指令的配置项中complie、link、controller等还有很深的水,需要进一步去探究。关于指令的link中如何访问到视图中的ng-model的值,其中也存在很多问题。