本文實例講述了AngularJS創(chuàng)建自定義指令的方法。分享給大家供大家參考，具體如下：
這是一篇譯文，來自angular開發(fā)者說明的指令。主要面向已經(jīng)熟悉angular開發(fā)基礎的開發(fā)者。這篇文檔解釋了什么情況下需要創(chuàng)建自己的指令，和如何去創(chuàng)建指令。
什么是指令
從一個高的層面來講，指令是angular $compile服務的說明，當特定的標簽(屬性，元素名，或者注釋) 出現(xiàn)在DOM中的時候，它讓編譯器附加指定的行為到DOM上。
這個過程是很簡單的。angular內(nèi)部有很用這樣自帶的指令，比如說ngBind, ngView,就像你創(chuàng)建控制器和服務一樣，你也可以創(chuàng)建自己的指令。當angular啟動的時候，Angular的編譯器分析html去匹配指令，這允許指令注冊行為或者改變DOM。
匹配指令
在寫指令之前，我們首先需要知道的是angular是如何匹配到一個指令的，在以下的例子我們說input元素匹配到ngModel指令.
<input ng-model="foo">
下面這種方法同樣也會匹配到ngModel：
<input data-ng:model="foo">
Angular會規(guī)范化一個元素的標簽名和屬性名，以便確定哪一個元素匹配到哪一個指令。我們在js中是通過使用規(guī)范化后的駝峰式的名字來引用指令(比如ngModel)。在HTML中常常使用'-'劃定的屬性名字來調(diào)用指令(比如說ng-model).
規(guī)范化的處理過程：
-去掉元素或屬性上面的x-和data-的前綴
-轉化':','-'和‘_-'形式的命名為駝峰式拼寫
以下例子展示了用不同的方式匹配到ngBind指令
<span ng-bind="name"></span> <br/><span ng:bind="name"></span> <br/><span ng_bind="name"></span> <br/><span data-ng-bind="name"></span> <br/><span x-ng-bind="name"></span> <br/>
Best Practice: 優(yōu)先使用'-'格式的命名(比如說ng-bind匹配ngBind)。如果你想在HTML驗證工具中通過，你可以用'data-'前綴的方式(比如data-ng-bind)。其他格式的命名是因為歷史遺留的原因存在，避免使用它們。
$compile服務可以基于元素的名字，屬性名，類名，和注釋來匹配指令
所有Angular內(nèi)部提供的指令都匹配屬性名，標簽名，注釋，或者類名。以下不同的方式都可以被解析到
<my-dir></my-dir><span my-dir="exp"></span><!-- directive: my-dir exp --><span class="my-dir: exp;"></span>
Best Practice: 優(yōu)先利用標簽名和屬性名的方式使用指令。這樣子更容易理解指定的元素匹配到了哪個元素。
Best Practice: 注釋的方式通常被用在DOM API限制創(chuàng)建跨越多個元素的指令，比如說table元素，限制重復嵌套，這樣就要用注釋的方式。在AngularJS 1.2版本中，通過使用ng-repeat-start 和 ng-repeat-end 作為一個更好的方案來解決這個問題。在可能的情況下，推薦使用這種方式。
文本和屬性的綁定
在編譯過程中，編譯器會使用$interpolate服務來檢測匹配到的文本和屬性值是否包含內(nèi)嵌表達式。這些表達式被注冊為watches，可以在digest循環(huán)時被更新。
<a ng-href="img/{{username}}.jpg">Hello {{username}}!</a>ngAttr屬性的綁定
瀏覽器有些時候會對它認為合法的屬性值非常的挑剔(就是某些元素的屬性是不可以任意賦值的，否則會報錯)。
比如：
<svg> <circle cx="{{cx}}"></circle></svg>使用這樣的寫法時，我們會發(fā)現(xiàn)控制臺中報錯Error: Invalid value for attribute cx="{{cx}}". .這是由于SVG DOM API的限制，你不能簡單的寫為cx="{{cx}}".
使用ng-attr-cx 可以解決這個問題
如果一個綁定的屬性使用ngAttr前綴(或者ng-attr), 那么在綁定的時候將會被應用到相應的未前綴化的屬性，這種方式允許你綁定到需要馬上被瀏覽器處理的屬性上面(比如SVG元素的circle[cx]屬性)。
所以，我們可以這樣寫來修復以上的問題:
<svg> <circle ng-attr-cx="{{cx}}"></circle></svg>創(chuàng)建指令
首先我們來談論下注冊指令的API，跟controller一樣，指令是注冊在module上，不同的是，指令是通過module.directive API來注冊的。module.directive接受的是一個規(guī)范化的名字和工廠函數(shù)，這個工廠函數(shù)返回一個包含不同配置的對象，這個對象用來告訴$compile服務如何進行下一步處理。
工廠函數(shù)僅在編譯器第一次匹配到指令的時候調(diào)用一次。通常在工廠函數(shù)中執(zhí)行初始化的工作。該函數(shù)使用$injector.invoke調(diào)用，所以它可以像controller一樣進行依賴注入。
Best Practice: 優(yōu)先返回一個定義好的對象，而不是返回一個函數(shù)。
接下來，我們先會了解一些常見的例子，然后再深入了解不同的配置項的原理和編譯過程。
Best Practice: 為了避免與某些未來的標準命名沖突，最好前綴化你自己的指令，比如你創(chuàng)建一個<carousel>指令，它可能會產(chǎn)生沖突，加入HTML7引入相同的元素。推薦使用兩三個單詞的前綴(比如btfCarousel)，同樣不能使用ng或者其他可能與angular未來版本起沖突的前綴。
以下的例子中，我們統(tǒng)一使用my前綴。
模板擴展的指令
當你有大量代表客戶信息的模板。這個模板在你的代碼中重復了很多次，當你改變一個地方的時候，你不得不在其他地方同時改動，這時候，你就要使用指令來簡化你的模板。
我們來創(chuàng)建一個指令，簡單的時候靜態(tài)模板來替換它的內(nèi)容。
<div ng-controller="Ctrl"> <div my-customer></div> </div>
JS
angular.module('docsSimpleDirective', []) .controller('Ctrl', function($scope) { $scope.customer = { name: 'Naomi', address: '1600 Amphitheatre' }; }) .directive('myCustomer', function() { return { template: 'Name: {{customer.name}} Address: {{customer.address}}' }; });注意我們這里做了一些綁定，$compile編譯鏈接<div my-customer> </div>之后，它將會匹配子元素的指令。這意味著你可以組合一些指令。以下例子中你會看到如何做到這一點。
這個例子中，我們直接在template配置項里寫上模板，但是隨著模板大小的增加，這樣非常不優(yōu)雅。
Best Practice: 除非你的模板非常小，否則更好的是分割成單獨的hmtl文件，然后使用templateUrl選項來加載。
假如你熟悉ngInclude，templateUrl跟它非常類似。現(xiàn)在我們使用templateUrl方式重寫上面的例子:
<div ng-controller="Ctrl"> <div my-customer></div> </div>
JS：
angular.module('docsTemplateUrlDirective', []) .controller('Ctrl', function($scope) { $scope.customer = { name: 'Naomi', address: '1600 Amphitheatre' }; }) .directive('myCustomer', function() { return { templateUrl: 'my-customer.html' }; });my-customer.html
Name: {{customer.name}} Address: {{customer.address}}非常好，但是如果我們想讓我們的指令匹配標簽名<my-customer>？ 如果我們只是簡單的把<my-customer>元素放在hmtl上面，會發(fā)現(xiàn)沒有效果。
Note: 創(chuàng)建指令的時候，默認僅使用屬性的方式。為了創(chuàng)建一個能由元素名字觸發(fā)的指令，你需要用到restrict配置。
restrict配置可以按如下方式設置:
-'A' 僅匹配屬性名字
-'E' 僅匹配元素名字
-'AE' 可以匹配到屬性名字或者元素名
所以，我們可以使用 restrict: 'E'配置我們指令。
<div ng-controller="Ctrl"> <div my-customer></div> </div>
JS
angular.module('docsTemplateUrlDirective', []) .controller('Ctrl', function($scope) { $scope.customer = { name: 'Naomi', address: '1600 Amphitheatre' }; }) .directive('myCustomer', function() { return { restrict: 'E', templateUrl: 'my-customer.html' }; });my-customer.html
Name: {{customer.name}} Address: {{customer.address}}Note: 什么時候使用屬性名或元素名呢？ 當創(chuàng)建一個含有自己模板的組件的時候，需要使用元素名，如果僅僅是為已有的元素添加功能的話，使用屬性名。
使用元素名做為myCustomer指令是非常正確的決定，因為你不是用一些'customer'行為來點綴元素，而是定義一個具有自己行為的元素作為customer組件。
隔離指令的作用域
上面我們的myCustomer指令已經(jīng)非常好了，但是它有個致命的缺陷，我們在給定的作用域內(nèi)僅能使用一次。
它現(xiàn)在的實現(xiàn)是，我們每次重用該指令的時候都要為它新創(chuàng)一個控制器。
<div ng-controller="NaomiCtrl"> <my-customer></my-customer></div><hr><div ng-controller="IgorCtrl"> <my-customer></my-customer></div>
JS
angular.module('docsScopeProblemExample', []) .controller('NaomiCtrl', function($scope) { $scope.customer = { name: 'Naomi', address: '1600 Amphitheatre' }; }) .controller('IgorCtrl', function($scope) { $scope.customer = { name: 'Igor', address: '123 Somewhere' }; }) .directive('myCustomer', function() { return { restrict: 'E', templateUrl: 'my-customer.html' }; });my-customer.html
Name: {{customer.name}} Address: {{customer.address}}這很明顯不是一個好的解決方案。
我們想要做的是能夠把指令的作用域與外部的作用域隔離開來，然后映射外部的作用域到指令內(nèi)部的作用域。可以通過創(chuàng)建isolate scope來完成這個目的。這樣的話，我們使用指令的scope配置。
<div ng-controller="Ctrl"> <my-customer customer="naomi"></my-customer> <hr> <my-customer customer="igor"></my-customer></div>
JS
angular.module('docsIsolateScopeDirective', []) .controller('Ctrl', function($scope) { $scope.naomi = { name: 'Naomi', address: '1600 Amphitheatre' }; $scope.igor = { name: 'Igor', address: '123 Somewhere' }; }) .directive('myCustomer', function() { return { restrict: 'E', scope: { customer: '=customer' }, templateUrl: 'my-customer.html' }; });my-customer.html
Name: {{customer.name}} Address: {{customer.address}}首先看hmtl，第一個<my-customer>綁定內(nèi)部作用域的customer到naomi。這個naomi我們在控制器中已經(jīng)定義好了。第二個是綁定customer到igor。
現(xiàn)在看看scope是如何配置的。
//...scope: { customer: '=customer'},//...屬性名(customer)是myCustomer指令上isolated scope的變量名。它的值(=customer)告訴編譯器綁定到customer屬性。
Note: 指令作用域配置中的'=attr'屬性名是被規(guī)范化過后的名字，比如要綁定<div bind-to-this="thing">中的屬性，你就要使用'=bindToThis'的綁定。
對于屬性名和你想要綁定的值的名字一樣，你可以使用這樣的快捷語法:
//...scope: { // same as '=customer' customer: '='},//...使用isolated scope還有另外一個用處，那就是可以綁定不同的數(shù)據(jù)到指令內(nèi)部的作用域。
在我們的例子中，我們可以添加另外一個屬性vojta到我們的作用域，然后在我們的指令模板中訪問它。
<div ng-controller="Ctrl"> <my-customer customer="naomi"></my-customer></div>
JS
angular.module('docsIsolationExample', []) .controller('Ctrl', function($scope) { $scope.naomi = { name: 'Naomi', address: '1600 Amphitheatre' }; $scope.vojta = { name: 'Vojta', address: '3456 Somewhere Else' }; }) .directive('myCustomer', function() { return { restrict: 'E', scope: { customer: '=customer' }, templateUrl: 'my-customer-plus-vojta.html' }; });my-customer-plus-vojta.html
Name: {{customer.name}} Address: {{customer.address}}<hr>Name: {{vojta.name}} Address: {{vojta.address}}注意到，{{vojta.name}}和{{vojta.address}}都是空的，意味著他們是undefined, 雖然我們在控制器中定義了vojta，但是在指令內(nèi)部訪問不到。
就像它的名字暗示的一樣， 指令的isolate scope隔離了除了你添加到作用域:{}對象中的數(shù)據(jù)模型外的一切東西。這對于你要建立一個可重復使用的組件是非常有用的，因為它阻止了除了你想要傳入的數(shù)據(jù)模型外其他東西改變你數(shù)據(jù)模型的狀態(tài)。
Note: 正常情況下，作用域是原型繼承自父作用域。但是isolate scope沒有這樣的繼承。
Best Practice: 當你想要使你的組件在應用范圍內(nèi)可重用，那么使用scope配置去創(chuàng)建一個isolate scopes
創(chuàng)建一個操作DOM的指令
在這個例子中，我們會創(chuàng)建一個顯示當前時間的指令，每秒一次更新DOM以正確的顯示當前的時間。
指令修改DOM通常是在link配置中，link選項接受一個帶有如下標簽的函數(shù)function link(scope,element,attrs) {...}其中：
-scope是angular scope對象
-element指令匹配的jqLite封裝的元素(angular內(nèi)部實現(xiàn)的類jquery的庫)
-attrs是一個帶有規(guī)范化后屬性名字和相應值的對象
在我們的link函數(shù)中，我們更新顯示時間每秒一次，或者當用戶改變指定綁定的時間格式字符串的時候。我們也要移除定時器，當指令被刪除的時候，以避免引入內(nèi)存泄露。
<div ng-controller="Ctrl2"> Date format: <input ng-model="format"> <hr/> Current time is: <span my-current-time="format"></span></div>
JS
angular.module('docsTimeDirective', []) .controller('Ctrl2', function($scope) { $scope.format = 'M/d/yy h:mm:ss a'; }) .directive('myCurrentTime', function($timeout, dateFilter) { function link(scope, element, attrs) { var format, timeoutId; function updateTime() { element.text(dateFilter(new Date(), format)); } scope.$watch(attrs.myCurrentTime, function(value) { format = value; updateTime(); }); function scheduleUpdate() { // save the timeoutId for canceling timeoutId = $timeout(function() { updateTime(); // update DOM scheduleUpdate(); // schedule the next update }, 1000); } element.on('$destroy', function() { $timeout.cancel(timeoutId); }); // start the UI update process. scheduleUpdate(); } return { link: link }; });這里有很多東西值得注意的，就像module.controller API, module.directive中函數(shù)參數(shù)是依賴注入，因此，我們可以在Link函數(shù)內(nèi)部使用$timeout和dataFilter服務。
我們注冊了一個事件element.on('$destroy', ...), 是什么觸發(fā)了這個$destory事件呢？
AngularJS會觸發(fā)一些特定的事件，當一個被angular編譯過的DOM元素被移除的時候，它會觸發(fā)一個$destory事件，同樣的，當一個angular作用域被移除的時候，它會向下廣播$destory事件到所有監(jiān)聽的作用域。
通過監(jiān)聽事件，你可以移除可能引起內(nèi)存泄露的事件監(jiān)聽器，注冊在元素和作用域上的監(jiān)聽器在它們被移除的時候，會自動會清理掉，但是假如注冊一個事件在服務或者沒有被刪除的DOM節(jié)點上，你就必須手工清理，否則會有內(nèi)存泄露的風險。
Best Practice:執(zhí)行被移除的時候應該做一些清理的操作， 可以使用element.on('$destroy', ...)或者scope.on('$destroy', ...)來運行解除綁定的函數(shù)，
創(chuàng)建包裹其他元素的指令
我們現(xiàn)在已經(jīng)實現(xiàn)了，使用isolate scopes傳遞數(shù)據(jù)模型到指令里面。但是有時候我們需要能夠傳遞一整個模板而不是字符串或者對象。讓我們通過創(chuàng)建'dialog box'組件來說明。這個'dialog box'組件應該能夠包裹任意內(nèi)容。
要實現(xiàn)這個，我們使用transclude配置
<div ng-controller="Ctrl"> <my-dialog>Check out the contents, {{name}}!</my-dialog></div>JS
angular.module('docsTransclusionDirective', []) .controller('Ctrl', function($scope) { $scope.name = 'Tobias'; }) .directive('myDialog', function() { return { restrict: 'E', transclude: true, templateUrl: 'my-dialog.html' }; });my-dialog.html
<div class="alert" ng-transclude></div>
這個transclude配置用來干嘛呢？ transclude使帶有這個配置的指令的內(nèi)容能夠訪問指令外部的作用域。
參照以下例子，注意到我們增加了一個link函數(shù)，在這個link函數(shù)內(nèi)部我們重定義了name屬性的值為Jeff，那么現(xiàn)在這個{{name}}會被解析成哪個值呢？
<div ng-controller="Ctrl"> <my-dialog>Check out the contents, {{name}}!</my-dialog></div>JS
angular.module('docsTransclusionDirective', []) .controller('Ctrl', function($scope) { $scope.name = 'Tobias'; }) .directive('myDialog', function() { return { restrict: 'E', transclude: true, templateUrl: 'my-dialog.html', link: function (element, scope) { scope.name = 'Jeff'; } }; });my-dialog.html
<div class="alert" ng-transclude></div>
一般，我們會認為{{name}}會被解析為Jeff，然而這里，我們看到這個例子中的{{name}}還是被解析成了Tobias.
transclude配置改變了指令相互嵌套的方式，他使指令的內(nèi)容擁有任何指令外部的作用域，而不是內(nèi)部的作用域。為了實現(xiàn)這個，它給指令內(nèi)容一次訪問外部作用域的機會。
這樣的行為對于包裹內(nèi)容的指令是非常有意義的。因為如果不這樣的話，你就必須分別傳入每個你需要使用的數(shù)據(jù)模型。如果你需要傳入每個要使用的數(shù)據(jù)模型，那么你就無法做到適應各種不同內(nèi)容的情況。
Best Practice: 僅當你要創(chuàng)建一個包裹任意內(nèi)容的指令的時候使用transclude:true。
下一步，我們增加一個按鈕到'dialog box'組件里面，允許用戶使用指令綁定自己定義的行為。
<div ng-controller="Ctrl"> <my-dialog ng-hide="dialogIsHidden" on-close="dialogIsHidden = true"> Check out the contents, {{name}}! </my-dialog></div>JS
angular.module('docsIsoFnBindExample', []) .controller('Ctrl', function($scope, $timeout) { $scope.name = 'Tobias'; $scope.hideDialog = function () { $scope.dialogIsHidden = true; $timeout(function () { $scope.dialogIsHidden = false; }, 2000); }; }) .directive('myDialog', function() { return { restrict: 'E', transclude: true, scope: { 'close': '&onClose' }, templateUrl: 'my-dialog-close.html' }; });my-dialog-close.html
<div class="alert"> <a href class="close" ng-click="close()">×</a> <div ng-transclude></div></div>
我們想要通過在指令的作用域上調(diào)用，來運行我們傳遞進去的函數(shù)，但是這個函數(shù)是運行在定義時候的上下文(js通常都是這樣子的)。
先前我們看到如何scope配置使用'=prop'，但是在上文的例子中，我們使用'&prop'，'&'綁定開放了一個函數(shù)到isolated scope，允許 isolated scope調(diào)用它，同時維持原來函數(shù)的作用域(這里的作用域都是指$scope)。所以當一個用戶點擊x時候，就會運行Ctrl控制器的close函數(shù)。
Best Practice: 當你的指令想要開放一個API去綁定特定的行為，在scope配置中使用'&prop'.
創(chuàng)建一個添加事件監(jiān)聽器的指令
先前，我們使用link函數(shù)創(chuàng)建一個操作DOM元素的指令，基于上面的例子，我們創(chuàng)建一個在元素上添加事件監(jiān)聽的指令。
舉個例子，假如我們想要創(chuàng)建一個讓用戶可拖拽的元素，該怎么做呢？
Drag ME
JS
angular.module('dragModule', []). directive('myDraggable', function($document) { return function(scope, element, attr) { var startX = 0, startY = 0, x = 0, y = 0; element.css({ position: 'relative', border: '1px solid red', backgroundColor: 'lightgrey', cursor: 'pointer' }); element.on('mousedown', function(event) { // Prevent default dragging of selected content event.preventDefault(); startX = event.screenX - x; startY = event.screenY - y; $document.on('mousemove', mousemove); $document.on('mouseup', mouseup); }); function mousemove(event) { y = event.screenY - startY; x = event.screenX - startX; element.css({ top: y + 'px', left: x + 'px' }); } function mouseup() { $document.unbind('mousemove', mousemove); $document.unbind('mouseup', mouseup); } } });創(chuàng)建相互通信的指令
你可以通過在模板使用指令來組合任何指令。
有時候，你想要一個指令從其他的指令上面創(chuàng)建
想象你想要一個帶有tab的容器，容器的內(nèi)容對應于激活的tab。
<my-tabs> <my-pane title="Hello"> <h5 id="creating-custom-directives_source_hello">Hello</h5> <p>Lorem ipsum dolor sit amet</p> </my-pane> <my-pane title="World"> <h5 id="creating-custom-directives_source_world">World</h5> <em>Mauris elementum elementum enim at suscipit.</em> <p><a href ng-click="i = i + 1">counter: {{i || 0}}</a></p> </my-pane></my-tabs>JS
angular.module('docsTabsExample', []) .directive('myTabs', function() { return { restrict: 'E', transclude: true, scope: {}, controller: function($scope) { var panes = $scope.panes = []; $scope.select = function(pane) { angular.forEach(panes, function(pane) { pane.selected = false; }); pane.selected = true; }; this.addPane = function(pane) { if (panes.length == 0) { $scope.select(pane); } panes.push(pane); }; }, templateUrl: 'my-tabs.html' }; }) .directive('myPane', function() { return { require: '^myTabs', restrict: 'E', transclude: true, scope: { title: '@' }, link: function(scope, element, attrs, tabsCtrl) { tabsCtrl.addPane(scope); }, templateUrl: 'my-pane.html' }; });my-tabs.html
<div class="tabbable"> <ul class="nav nav-tabs"> <li ng-repeat="pane in panes" ng-class="{active:pane.selected}"> <a href="" ng-click="select(pane)">{{pane.title}}</a> </li> </ul> <div class="tab-content" ng-transclude></div></div>my-pane.html
<div class="tab-pane" ng-show="selected" ng-transclude></div>
myPane指令有一個require:'^myTabs'的配置，當指令使用這個配置，$compile服務叫myTabs的指令并獲取它的控制器實例，如果沒有找到，將會拋出一個錯誤。'^'前綴意味著指令在它的父元素上面搜索控制器(沒有'^'前綴的話，指令默認會在自身的元素上面搜索指定的指令)。
這里myTabs的控制器是來自何處呢？通過使用controller配置可以為指令指定一個控制器, 上問例子中myTab就是使用這個配置。就像ngController, 這個配置為指令的模板綁定了一個控制器。
再看我們的myPane's定義，注意到link函數(shù)的最后一個參數(shù): tabCtrl，當一個指令包含另一個指令(通過require方式)，它會接收該指令的控制器實例作為link函數(shù)的第四個參數(shù)，利用這個，myPane可以調(diào)用myTabs的addPane函數(shù)。
精明的讀者可能想知道link跟controller之間的區(qū)別，最基本的區(qū)別就是控制器開放一個API(就是這個控制器實例可以被其他實例讀取到)，link函數(shù)可以通過require與控制器交互。
Best Practice: 當你要開放一個API給其他指令的時候使用控制器，否則使用link函數(shù)。
總結
這里我們講解了一個些指令的主要使用案例。每一個都可以作為你創(chuàng)建自己指令的很好的起點。
如果你想更深入的了解編譯的處理過程，可以查看compiler guide相關內(nèi)容
$compile API頁面有directive每個配置項的具體解釋，可以參閱。
希望本文所述對大家AngularJS程序設計有所幫助。
新聞熱點
疑難解答
