AngularJS建立自訂指令的方法詳解_AngularJS

本文執行個體講述了AngularJS建立自訂指令的方法。分享給大家供大家參考，具體如下：

這是一篇譯文，來自angular開發人員說明的指令。主要面向已經熟悉angular開發基礎的開發人員。這篇文檔解釋了什麼情況下需要建立自己的指令，和如何去建立指令。

什麼是指令

從一個高的層面來講，指令是angular $compile服務的說明，當特定的標籤(屬性，元素名，或者注釋) 出現在DOM中的時候，它讓編譯器附加指定的行為到DOM上。

這個過程是很簡單的。angular內部有很用這樣內建的指令，比如說ngBind, ngView,就像你建立控制器和服務一樣，你也可以建立自己的指令。當angular啟動的時候，Angular的編譯器分析html去匹配指令，這允許指令註冊行為或者改變DOM。

匹配指令

在寫指令之前，我們首先需要知道的是angular是如何匹配到一個指令的，在以下的例子我們說input元素匹配到ngModel指令.

<input ng-model="foo">

下面這種方法同樣也會匹配到ngModel：

<input data-ng:model="foo">

Angular會正常化一個元素的標籤名和屬性名稱，以便確定哪一個元素匹配到哪一個指令。我們在js中是通過使用正常化後的駝峰式的名字來引用指令(比如ngModel)。在HTML中常常使用'-'劃定的屬性名稱字來調用指令(比如說ng-model).

正常化的處理過程：

-去掉元素或屬性上面的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: 優先使用'-'格式的命名(比如說ng-bind匹配ngBind)。如果你想在HTML驗證工具中通過，你可以用'data-'首碼的方式(比如data-ng-bind)。其他格式的命名是因為曆史遺留的原因存在，避免使用它們。

$compile服務可以基於元素的名字，屬性名稱，類名，和注釋來匹配指令

所有Angular內部提供的指令都匹配屬性名稱，標籤名，注釋，或者類名。以下不同的方式都可以被解析到

<my-dir></my-dir><span my-dir="exp"></span><!-- directive: my-dir exp --><span class="my-dir: exp;"></span>

Best Practice: 優先利用標籤名和屬性名稱的方式使用指令。這樣子更容易理解指定的元素匹配到了哪個元素。

Best Practice: 注釋的方式通常被用在DOM API限制建立跨越多個元素的指令，比如說table元素，限制重複嵌套，這樣就要用注釋的方式。在AngularJS 1.2版本中，通過使用ng-repeat-start 和 ng-repeat-end 作為一個更好的方案來解決這個問題。在可能的情況下，推薦使用這種方式。

文本和屬性的綁定

在編譯過程中，編譯器會使用$interpolate服務來檢測匹配到的文本和屬性值是否包含內嵌運算式。這些運算式被註冊為watches，可以在digest迴圈時被更新。

<a ng-href="img/{{username}}.jpg">Hello {{username}}!</a>

ngAttr屬性的綁定

瀏覽器有些時候會對它認為合法的屬性值非常的挑剔(就是某些元素的屬性是不可以任意賦值的，否則會報錯)。

比如：

<svg> <circle cx="{{cx}}"></circle></svg>

使用這樣的寫法時，我們會發現控制台中報錯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>

建立指令

首先我們來談論下註冊指令的API，跟controller一樣，指令是註冊在module上，不同的是，指令是通過module.directive API來註冊的。module.directive接受的是一個正常化的名字和工廠函數，這個工廠函數返回一個包含不同配置的對象，這個對象用來告訴$compile服務如何進行下一步處理。

工廠函數僅在編譯器第一次匹配到指令的時候調用一次。通常在工廠函數中執行初始化的工作。該函數使用$injector.invoke調用，所以它可以像controller一樣進行依賴注入。

Best Practice: 優先返回一個定義好的對象，而不是返回一個函數。

接下來，我們先會瞭解一些常見的例子，然後再深入瞭解不同的配置項的原理和編譯過程。

Best Practice: 為了避免與某些未來的標準命名衝突，最好首碼化你自己的指令，比如你建立一個<carousel>指令，它可能會產生衝突，加入HTML7引入相同的元素。推薦使用兩三個單詞的首碼(比如btfCarousel)，同樣不能使用ng或者其他可能與angular未來版本起衝突的首碼。

以下的例子中，我們統一使用my首碼。

模板擴充的指令

當你有大量代表客戶資訊的模板。這個模板在你的代碼中重複了很多次，當你改變一個地方的時候，你不得不在其他地方同時改動，這時候，你就要使用指令來簡化你的模板。

我們來建立一個指令，簡單的時候靜態模板來替換它的內容。

<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配置項裡寫上模板，但是隨著模板大小的增加，這樣非常不優雅。

Best Practice: 除非你的模板非常小，否則更好的是分割成單獨的hmtl檔案，然後使用templateUrl選項來載入。

假如你熟悉ngInclude，templateUrl跟它非常類似。現在我們使用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上面，會發現沒有效果。

Note: 建立指令的時候，預設僅使用屬性的方式。為了建立一個能由元素名字觸發的指令，你需要用到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: 什麼時候使用屬性名稱或元素名呢？ 當建立一個含有自己模板的組件的時候，需要使用元素名，如果僅僅是為已有的元素添加功能的話，使用屬性名稱。

使用元素名做為myCustomer指令是非常正確的決定，因為你不是用一些'customer'行為來點綴元素，而是定義一個具有自己行為的元素作為customer組件。

隔離指令的範圍

上面我們的myCustomer指令已經非常好了，但是它有個致命的缺陷，我們在給定的範圍內僅能使用一次。

它現在的實現是，我們每次重用該指令的時候都要為它新創一個控制器。

<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}}

這很明顯不是一個好的解決方案。

我們想要做的是能夠把指令的範圍與外部的範圍隔離開來，然後映射外部的範圍到指令內部的範圍。可以通過建立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>綁定內部範圍的customer到naomi。這個naomi我們在控制器中已經定義好了。第二個是綁定customer到igor。

現在看看scope是如何配置的。

//...scope: { customer: '=customer'},//...

屬性名稱(customer)是myCustomer指令上isolated scope的變數名。它的值(=customer)告訴編譯器綁定到customer屬性。

Note: 指令範圍配置中的'=attr'屬性名稱是被正常化過後的名字，比如要綁定<div bind-to-this="thing">中的屬性，你就要使用'=bindToThis'的綁定。

對於屬性名稱和你想要綁定的值的名字一樣，你可以使用這樣的快捷文法:

//...scope: { // same as '=customer' customer: '='},//...

使用isolated scope還有另外一個用處，那就是可以綁定不同的資料到指令內部的範圍。

在我們的例子中，我們可以添加另外一個屬性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，但是在指令內部訪問不到。

就像它的名字暗示的一樣， 指令的isolate scope隔離了除了你添加到範圍:{}對象中的資料模型外的一切東西。這對於你要建立一個可重複使用的組件是非常有用的，因為它阻止了除了你想要傳入的資料模型外其他東西改變你資料模型的狀態。

Note: 正常情況下，範圍是原型繼承自父範圍。但是isolate scope沒有這樣的繼承。

Best Practice: 當你想要使你的組件在應用範圍內可重用，那麼使用scope配置去建立一個isolate scopes

建立一個操作DOM的指令

在這個例子中，我們會建立一個顯示目前時間的指令，每秒一次更新DOM以正確的顯示當前的時間。

指令修改DOM通常是在link配置中，link選項接受一個帶有如下標籤的函數function link(scope,element,attrs) {...}其中：

-scope是angular scope對象
-element指令匹配的jqLite封裝的元素(angular內部實現的類jquery的庫)
-attrs是一個帶有正常化後屬性名稱字和相應值的對象

在我們的link函數中，我們更新顯示時間每秒一次，或者當使用者改變指定綁定的時間格式字串的時候。我們也要移除定時器，當指令被刪除的時候，以避免引入記憶體泄露。

<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中函數參數是依賴注入，因此，我們可以在Link函數內部使用$timeout和dataFilter服務。

我們註冊了一個事件element.on('$destroy', ...), 是什麼觸發了這個$destory事件呢？

AngularJS會觸發一些特定的事件，當一個被angular編譯過的DOM元素被移除的時候，它會觸發一個$destory事件，同樣的，當一個angular範圍被移除的時候，它會向下廣播$destory事件到所有監聽的範圍。

通過監聽事件，你可以移除可能引起記憶體泄露的事件監聽器，註冊在元素和範圍上的監聽器在它們被移除的時候，會自動會清理掉，但是假如註冊一個事件在服務或者沒有被刪除的DOM節點上，你就必須手工清理，否則會有記憶體泄露的風險。

Best Practice:執行被移除的時候應該做一些清理的操作， 可以使用element.on('$destroy', ...)或者scope.on('$destroy', ...)來運行解除綁定的函數，

建立包裹其他元素的指令

我們現在已經實現了，使用isolate scopes傳遞資料模型到指令裡面。但是有時候我們需要能夠傳遞一整個模板而不是字串或者對象。讓我們通過建立'dialog box'組件來說明。這個'dialog box'組件應該能夠包裹任意內容。

要實現這個，我們使用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使帶有這個配置的指令的內容能夠訪問指令外部的範圍。

參照以下例子，注意到我們增加了一個link函數，在這個link函數內部我們重定義了name屬性的值為Jeff，那麼現在這個{{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配置改變了指令相互嵌套的方式，他使指令的內容擁有任何指令外部的範圍，而不是內部的範圍。為了實現這個，它給指令內容一次訪問外部範圍的機會。

這樣的行為對於包裹內容的指令是非常有意義的。因為如果不這樣的話，你就必須分別傳入每個你需要使用的資料模型。如果你需要傳入每個要使用的資料模型，那麼你就無法做到適應各種不同內容的情況。

Best Practice: 僅當你要建立一個包裹任意內容的指令的時候使用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>

我們想要通過在指令的範圍上調用，來運行我們傳遞進去的函數，但是這個函數是運行在定義時候的上下文(js通常都是這樣子的)。

先前我們看到如何scope配置使用'=prop'，但是在上文的例子中，我們使用'&prop'，'&'綁定開放了一個函數到isolated scope，允許 isolated scope調用它，同時維持原來函數的範圍(這裡的範圍都是指$scope)。所以當一個使用者點擊x時候，就會運行Ctrl控制器的close函數。

Best Practice: 當你的指令想要開放一個API去綁定特定的行為，在scope配置中使用'&prop'.

建立一個添加事件監聽器的指令

先前，我們使用link函數建立一個操作DOM元素的指令，基於上面的例子，我們建立一個在元素上添加事件監聽的指令。

舉個例子，假如我們想要建立一個讓使用者可拖拽的元素，該怎麼做呢？

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);  } } });

建立相互連信的指令

你可以通過在模板使用指令來組合任何指令。

有時候，你想要一個指令從其他的指令上面建立

想象你想要一個帶有tab的容器，容器的內容對應於啟用的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函數的最後一個參數: tabCtrl，當一個指令包含另一個指令(通過require方式)，它會接收該指令的控制器執行個體作為link函數的第四個參數，利用這個，myPane可以調用myTabs的addPane函數。

精明的讀者可能想知道link跟controller之間的區別，最基本的區別就是控制器開放一個API(就是這個控制器執行個體可以被其他執行個體讀取到)，link函數可以通過require與控制器互動。

Best Practice: 當你要開放一個API給其他指令的時候使用控制器，否則使用link函數。

總結

這裡我們講解了一個些指令的主要使用案例。每一個都可以作為你建立自己指令的很好的起點。

如果你想更深入的瞭解編譯的處理過程，可以查看compiler guide相關內容

$compile API頁面有directive每個配置項的具體解釋，可以參閱。

希望本文所述對大家AngularJS程式設計有所協助。