摘要：我們通常通過其區分大小寫的規范化名稱例如，來定義指令。在其目前的實現上，我們應該需要去創建一些不同點控制器用來重用這個指令。如此，綁定是理想的將回調函數綁定到指令行為。這被指令調用指明。前綴表示該指令在其父元素上搜索控制

文檔翻譯至angularjs.org. 文檔解釋了您何時想在AngularJS應用程序中創建自己的指令，以及如何實現它們。 | 建議搭配原文食用 |

在高層次上，指令時DOM元素上的標記（作為屬性，元素名，注釋和CSS類）用來告訴Angularjs的HTML Compiler（$compile）附加特定的行為在此DOM元素上（例如，通過事件監聽），或者甚至去轉換DOM元素和他的子元素。

Angularjs附加了一系列內建的執行，像ngBind, ngModel, and ngClass. 和你創建的控制器和服務一樣，你可以創建你自己的指令來供Angularjs使用. 當Angularjs 啟動（bootstraps）你的應用時，HTML compiler遍歷DOM匹配DOM元素對應的指令。

What does it mean to "compile" an HTML template? For AngularJS, "compilation" means attaching directives to the HTML to make it interactive. The reason we use the term "compile" is that the recursive process of attaching directives mirrors the process of compiling source code in compiled programming languages.

指令匹配
在我們開始寫指令之前， 我們需要知道當使用一個給定的指令, Angularjs的 HTML Compiler是如何判斷的

與元素匹配選擇器（element matches a selector）時使用的術語類似，當指令是其聲明的一部分時，我們說元素匹配指令。

在下面的例子中，我們說元素匹配ngModel指令

以下元素也匹配ngModel：

以下元素與person指示相匹配：

{{name}}

AngularJS規范化元素的標簽和屬性名稱，以確定哪些元素與哪些指令相匹配。我們通常通過其區分大小寫的camelCase規范化名稱（例如，ngModel）來定義（refer to）指令。然而，由于HTML是大小寫不敏感的，我們通過小寫形式在DOM中引用指令，通常使用dash（-）分割符分割不同的單詞（例如ng-model）

規范化過程如下：
1.剔除 元素/屬性開頭的 x- ， data- ；
2.將 - ， _ ，: 分隔符轉換為小駝峰式 camelCas
例如，以下形式都是等同的，并且與ngBind指令相匹配：

  Hello  

   

   

   

   

   

A - attributes    
 
C - class name    
 
E - element name   
M - comments    

Best Practice: Prefer using directives via tag name and attributes over comment and class names.Doing so generally makes it easier to determine what directives a given element matches.

Best Practice: Comment directives were commonly used in places where the DOM API limits the ability to create directives that spanned multiple elements (e.g. inside

首先讓我們討論下注冊指令的API（API for registering directives）. 和控制器一樣，指令也是注冊在模塊之上的。為了注冊一個指令，你需要使用 module.directive API。module.directive接受標準化的指令名稱，后跟一個工廠函數。這個工廠函數應該返回一個具有不同選項的對象來告訴$compile指令在匹配時應該如何表現。

當$conpile第一次匹配指令時，工廠函數僅被調用一次。你可以在這里指令任意的初始化工作。該（工廠）函數使用 $injector.invoke 來調用這使得它可以像控制器一樣是可注射。

我們將通過一些常見的指令示例，然后深入探討不同的選項和編譯過程。

Best Practice: In order to avoid collisions with some future standard, it"s best to prefix your own directive names. For instance, if you created a directive, it would be problematic if HTML7 introduced the same element. A two or three letter prefix (e.g. btfCarousel) works well. Similarly, do not prefix your own directives with ng or they might conflict with directives included in a future version of AngularJS.

作為后續示例，我們將使用my前綴（例如 myCustomer）。

假設您有一大塊代表客戶信息的模板。這個模板在您的代碼中重復多次。當你在一個地方改變它時，你必須在其他幾個地方改變它。這是使用指令簡化模板的好機會。

讓我們創建一個指令，用一個靜態模板簡單地替換它的內容：
https://jsfiddle.net/TommyLee...

注意我們在這個指令中有bindings。在$compile編譯和鏈接

在上面的例子中，我們列出了模板選項（template attribute of return object in factory function），但隨著模板大小的增長，這將變得令人討厭。

Best Practice: Unless your template is very small, it"s typically better to break it apart into its own HTML file and load it with the templateUrl option.

如果你熟悉ngInclude，templateUrl就像它一樣工作。下面是使用templateUrl代替的相同示例：
https://plnkr.co/edit/idFOZ8Q...

templateUrl也可以是一個函數，它返回要加載和用于指令的HTML模板的URL。AngularJS將使用兩個參數調用templateUrl函數：指令被調用的元素以及與該元素相關聯的attr對象。

Note: You do not currently have the ability to access scope variables from the templateUrl function, since the template is requested before the scope is initialized
注：(要訪問socpe上的值，應該在post-link階段).

https://plnkr.co/edit/gaSYwnp...

restrict 選項通常設置為：

When should I use an attribute versus an element? Use an element when you are creating a component that is in control of the template.The common case for this is when you are creating a Domain-Specific Language for parts of your template. Use an attribute when you are decorating an existing element with new functionality.

用元素來使用myCustomer指令時明智的選擇，因為你不用一些“customer”行為修飾一個元素，你定義一個元素核心行為作為一個costomer組建。

我們以上的myCustomer指令很好，但是它有一個致命缺陷。我們只有在一個給定的scope下使用。

在其目前的實現上，我們應該需要去創建一些不同點控制器用來重用這個指令。
https://plnkr.co/edit/CKEgb1e...

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

我們說項的是把指令內部的scope與外部scope（controller scope）分離，并且映射外部scope到指令內部scope。我們可以通過創建一個isolate scope來做。為此，我們可以使用指令的scope選項。

https://plnkr.co/edit/E6dTrgm...
看index.html文件，第一個元素綁定info屬性值為naomi，它是我們已經暴露在我們的控制器上的scope。第二個綁定info為igor。

讓我們仔細看看scope選項

//... 
scope: { customerInfo: "=info" },
//...

除了可以將不同的數據綁定到指令中的作用域外，使用isolated scope還有其他作用。

我們可以通過添加另一個屬性vojta來展示，到我們的scope并嘗試從我們的指令模板中訪問它：
https://plnkr.co/edit/xLVqnzt...

請注意{{vojta.name}}和{{vojta.address}}為空，意味著它們未定義（undefined）。雖然我們在控制器中定義了vojta，但它在指令中不可用。

顧名思義，該指令的 isolate scope隔離了除顯式添加到作用域的模型之外的所有內容：scope: {}散列對象. 這在構建可重用組件時很有用，因為它可以防止組件改變模型狀態，除了顯式傳入。

Note: Normally, a scope prototypically inherits from its parent. An isolated scope does not. See the "Directive Definition Object - scope"section for more information about isolate scopes.

Best Practice: Use the scope option to create isolate scopes when making components that you want to reuse throughout your app.

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

想要修改DOM的指令通常使用link選項來注冊DOM監聽器以及更新DOM。它在模板被克隆之后執行，并且是放置指令邏輯的地方。

link接受一個帶有一下簽名的函數function link(scope, element, attrs, controller, transcludeFn) { ... }, 其中：

scope是一個Angularjs scope 對象

element 是一個此指令匹配的jqLite包裝元素

attrs是一個具有標準化屬性名稱及其對應屬性值的鍵值對的散列對象。

controller是指令所需的控制器實例或其自己的控制器（如果有的話）。確切的值取決于指令的 require屬性。

transcludeFn是預先綁定到正確的包含范圍的transclude鏈接函數。

For more details on the link option refer to the $compile API page.

在我們的link函數中，我們想每秒鐘更新顯示時間，或者一個用戶改變了我們指令綁定的時間格式字符串。我們將會使用$interval服務定期調用處理程序。這比使用$ timeout更容易，但對于端到端測試也更好，我們希望確保在完成測試之前完成所有$timeout。如果指令被刪除，我們也想刪除$ interval，所以我們不會引入內存泄漏
https://plnkr.co/edit/vIhhmNp...

這里有幾件事需要注意。就像module.controller API一樣，module.directive中的函數參數是依賴注入的。因此，我們可以在指令的鏈接函數中使用$ interval和dateFilter。

我們注冊一個事件element.on（"$ destroy"，...）。什么引發了這個$ destroy事件？

AngularJS發布了一些特殊事件。當用AngularJS的編譯器編譯的DOM節點被銷毀時，它會發起$ destroy事件。同樣，當Angularjs scope被銷毀，他會廣播（broadcasts）一個$destory事件監聽scopes。

通過監聽此事件，可以刪除可能導致內存泄漏的事件偵聽器。注冊到scope和element的監聽事件在銷毀DOM時會自動清理，但是如果您在服務上注冊了偵聽器，或者在未被刪除的DOM節點上注冊了偵聽器，你必須自己清理它，否則你有冒險引入內存泄漏的風險。

Best Practice: Directives should clean up after themselves. You can use element.on("$destroy", ...) or scope.$on("$destroy", ...) to run a clean-up function when the directive is removed.

我們已經看到，您可以使用isolate scope將模型傳遞給指令，但是有時候想要能傳入一整個模板而不是一個字符串或者對象。我們說我們想要創建一個“dialog box”組建。dialog box應該有能力包裝任意的內容（any arbitrary content）。

為此，我們需要使用transclude選項。
https://plnkr.co/edit/empMwVW...

transclude選項到底做了什么呢？transclude使指令的內容通過此選項擁有可訪問外部指令的scope不是內部的scope。

為了說明了這一點，請看下面的例子。注意，我們在script.js中添加了一個link函數，將名稱重新定義為Jeff。您認為{{name}}綁定將會得到什么結果？
https://plnkr.co/edit/OEdkXY4...

照常，我們以為{{name}}應該是Jeff。但是，我們看見的是Tobias。

transclude選項改變了scope的嵌套方式。它使得一個transcluded指令的內容具有在指令之外的任何scope內容，而不是任何內部的scope。這樣做，它可以讓內容訪問外部scope。

請注意，如果指令沒有創建自己的獨立作用域，那么scope.name ="Jeff"中的作用域將引用外部作用域，我們會在輸出中看到Jeff。

這種行為對于封裝某些內容的指令是有意義的，因為否則，您必須分別傳入每個您想要使用的模型。如果你必須傳入每一個你想要的model，那么你不能真正的使用任意的內容，對嗎？

Best Practice: only use transclude: true when you want to create a directive that wraps arbitrary content.

接下來，我們要在此對話框中添加按鈕，并允許使用該指令的用戶將自己的行為綁定到該對話框。
https://plnkr.co/edit/Bo5lona...

我們希望通過從指令的作用域調用它來運行我們傳遞的函數，但是它會在注冊作用域的上下文中運行。

我們在之前已經看到在scope選項中如何使用 =attr，但是在上面的例子中，我們使用了&attr代替。 &綁定允許一個指令去觸發一個原始范圍內的表達式的評估，在一個特定時間點上。任何合法的表達式都是允許的，包括一個含有函數調用的表達式。如此，& 綁定是理想的將回調函數綁定到指令行為。

當用戶點擊dialog中的 x，指令的close函數被調用，多虧于ng-click。這個close調用在isolated scope之上，實際上會在原始scope的上下文中評估表達式 hideDialog（message），導致運行Controller中的hideDialog function。

通常期望通過一個表達式從isolate scope傳入數據到父scope，這可以通過將局部變量名稱和值的映射傳遞到表達式包裝函數來完成。例如，hideDialkog函數接受一個message來顯示當dialog被隱藏是。這被指令調用 close({message: "closing for now"})指明。接著局部變量message將在on-close表達式內被訪問(is available).

Best Practice: use &attr in the scope option when you want your directive to expose an API for binding to behaviors.

以前，我們使用鏈接函數來創建操縱其DOM元素的指令。在這個例子的基礎上，讓我們制定一個對其元素事件做出反應的指令。

例如，如果我們想創建一個允許用戶拖拽元素的指令呢？
https://plnkr.co/edit/hcUyuBY...

你可以組建任何指令通過模板使用他們。

有時，你需要一個由指令組合構建的組件。

想象你想要有一個容器，其中容器的內容對應于哪個選項卡處于活動狀態的選項卡。
https://plnkr.co/edit/kqLjcwG...

myPane指令有require選項值為^^myTabs. 當指令使用此選項，&compile將拋出一個錯誤除非特定的controller被找到。 ^^前綴表示該指令在其父元素上搜索控制器。（^前綴將使指令在自身元素或她的父元素上尋找控制器；又沒任何前綴，指令將值操作自身）

所以這個myTabs contoller從哪里來的？指令可以特定一個controllers通過使用 controller選項。如你所見，myTabs指令使用了此選項。就像ngController，此選項附加一個控制器到指令的模板上。

如果需要從模板中引用控制器或綁定到控制器的任何功能，則可以使用選項controllerAs將控制器的名稱指定為別名。該指令需要定義要使用的此配置的范圍。這在指令被用作組件的情況下特別有用。

回頭看myPane的定義，注意到link函數的最后一個參數：tabCtrl。當指令需要控制器時，它將接收該控制器作為其link函數的第四個參數。利用這一點，myPane可以調用myTabs的addPane函數。

如果需要多個控制器，則指令的require選項可以采用數組參數。發送給鏈接函數的相應參數也將是一個數組。

angular.module("docsTabsExample", [])
.directive("myPane", function() {
  return {
    require: ["^^myTabs", "ngModel"],
    restrict: "E",
    transclude: true,
    scope: {
      title: "@"
    },
    link: function(scope, element, attrs, controllers) {
      var tabsCtrl = controllers[0],
          modelCtrl = controllers[1];

      tabsCtrl.addPane(scope);
    },
    templateUrl: "my-pane.html"
  };
});

明的讀者可能想知道鏈接和控制器之間的區別。基本的區別是控制器可以暴露一個API，并且鏈接函數可以使用require與控制器交互。

Best Practice: use controller when you want to expose an API to other directives. Otherwise use link.

到此我們已經看了大多數指令的用法，每一個樣例演示了一個創建你自己指令的好的起始點。

你可能深入感興趣于編譯過程的解釋可以在這里獲得compiler guide.

$compile API 有一個全面的指令清單選項以供參考。

如有任何問題和建議歡迎發送至郵箱討論：
翻譯不易，若您覺得對您有幫助，歡迎打賞

微信：

支付寶：

• 上一篇：ajax實現下拉刷新+上拉加載
• 下一篇：AJAX 之 Promise

zzbo

男|高級講師

我要關注 我要私信

TA的文章

閱讀更多

• 編程界也有修仙秘籍？程序員碼字3年終得《JavaScript 百煉成仙》

  閱讀 1891·2021-11-22 09:34

• 水濁度傳感器

  閱讀 3025·2021-09-28 09:35

• 502網關錯誤是什么錯誤?502網關錯誤,連接源站失敗解決方法

  閱讀 13430·2021-09-09 11:34

• 對vuex在項目中的使用

  閱讀 3599·2019-08-29 16:25

• FCC 成都社區·技術周刊 第 12 期

  閱讀 2826·2019-08-29 15:23

• 使用css實現全兼容的三角形

  閱讀 2041·2019-08-28 17:55

• 10分鐘理解JS引擎的執行機制

  閱讀 2431·2019-08-26 17:04

• 項目中配置Babel轉碼器的詳細教程

  閱讀 3049·2019-08-26 12:21

最新活動