創(chuàng)建自定義指令

zzbo 發(fā)布于2019-08-26 11:55 / 362人閱讀

摘要：我們通常通過(guò)其區(qū)分大小寫(xiě)的規(guī)范化名稱(chēng)例如，來(lái)定義指令。在其目前的實(shí)現(xiàn)上，我們應(yīng)該需要去創(chuàng)建一些不同點(diǎn)控制器用來(lái)重用這個(gè)指令。如此，綁定是理想的將回調(diào)函數(shù)綁定到指令行為。這被指令調(diào)用指明。前綴表示該指令在其父元素上搜索控制

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

什么是指令？

在高層次上，指令時(shí)DOM元素上的標(biāo)記（作為屬性，元素名，注釋和CSS類(lèi)）用來(lái)告訴Angularjs的HTML Compiler（$compile）附加特定的行為在此DOM元素上（例如，通過(guò)事件監(jiān)聽(tīng)），或者甚至去轉(zhuǎn)換DOM元素和他的子元素。

Angularjs附加了一系列內(nèi)建的執(zhí)行，像ngBind, ngModel, and ngClass. 和你創(chuàng)建的控制器和服務(wù)一樣，你可以創(chuàng)建你自己的指令來(lái)供Angularjs使用. 當(dāng)Angularjs 啟動(dòng)（bootstraps）你的應(yīng)用時(shí)，HTML compiler遍歷DOM匹配DOM元素對(duì)應(yīng)的指令。

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.

指令匹配
在我們開(kāi)始寫(xiě)指令之前，我們需要知道當(dāng)使用一個(gè)給定的指令, Angularjs的 HTML Compiler是如何判斷的

與元素匹配選擇器（element matches a selector）時(shí)使用的術(shù)語(yǔ)類(lèi)似，當(dāng)指令是其聲明的一部分時(shí)，我們說(shuō)元素匹配指令。

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

以下元素也匹配ngModel：

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

{{name}}

Normalization (暫譯規(guī)范化)

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

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


  Hello

指令類(lèi)型

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

elements). AngularJS 1.2 introduces ng-repeat-start and ng-repeat-end as a better solution to this problem. Developers are encouraged to use this over custom comment directives when possible..

創(chuàng)建指令

首先讓我們討論下注冊(cè)指令的API（API for registering directives）. 和控制器一樣，指令也是注冊(cè)在模塊之上的。為了注冊(cè)一個(gè)指令，你需要使用 module.directive API。module.directive接受標(biāo)準(zhǔn)化的指令名稱(chēng)，后跟一個(gè)工廠函數(shù)。這個(gè)工廠函數(shù)應(yīng)該返回一個(gè)具有不同選項(xiàng)的對(duì)象來(lái)告訴$compile指令在匹配時(shí)應(yīng)該如何表現(xiàn)。

當(dāng)$conpile第一次匹配指令時(shí)，工廠函數(shù)僅被調(diào)用一次。你可以在這里指令任意的初始化工作。該（工廠）函數(shù)使用 $injector.invoke 來(lái)調(diào)用這使得它可以像控制器一樣是可注射。

我們將通過(guò)一些常見(jiàn)的指令示例，然后深入探討不同的選項(xiàng)和編譯過(guò)程。

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.

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

Template-expanding 指令

假設(shè)您有一大塊代表客戶(hù)信息的模板。這個(gè)模板在您的代碼中重復(fù)多次。當(dāng)你在一個(gè)地方改變它時(shí)，你必須在其他幾個(gè)地方改變它。這是使用指令簡(jiǎn)化模板的好機(jī)會(huì)。

讓我們創(chuàng)建一個(gè)指令，用一個(gè)靜態(tài)模板簡(jiǎn)單地替換它的內(nèi)容：
https://jsfiddle.net/TommyLee...

注意我們?cè)谶@個(gè)指令中有bindings。在$compile編譯和鏈接

后，它將會(huì)嘗試在元素的子元素上匹配指令。這意味著你可以組建指令的指令（嵌套指令）。我們將在后續(xù)看到如何編寫(xiě) an example 。

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

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也可以是一個(gè)函數(shù)，它返回要加載和用于指令的HTML模板的URL。AngularJS將使用兩個(gè)參數(shù)調(diào)用templateUrl函數(shù)：指令被調(diào)用的元素以及與該元素相關(guān)聯(lián)的attr對(duì)象。

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
注：(要訪(fǎng)問(wèn)socpe上的值，應(yīng)該在post-link階段).

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

restrict 選項(xiàng)通常設(shè)置為：

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.

用元素來(lái)使用myCustomer指令時(shí)明智的選擇，因?yàn)槟悴挥靡恍癱ustomer”行為修飾一個(gè)元素，你定義一個(gè)元素核心行為作為一個(gè)costomer組建。

隔離指令的Scope

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

在其目前的實(shí)現(xiàn)上，我們應(yīng)該需要去創(chuàng)建一些不同點(diǎn)控制器用來(lái)重用這個(gè)指令。
https://plnkr.co/edit/CKEgb1e...

這明顯不是一個(gè)好的解決方案。

我們說(shuō)項(xiàng)的是把指令內(nèi)部的scope與外部scope（controller scope）分離，并且映射外部scope到指令內(nèi)部scope。我們可以通過(guò)創(chuàng)建一個(gè)isolate scope來(lái)做。為此，我們可以使用指令的scope選項(xiàng)。

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

讓我們仔細(xì)看看scope選項(xiàng)

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

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

我們可以通過(guò)添加另一個(gè)屬性vojta來(lái)展示，到我們的scope并嘗試從我們的指令模板中訪(fǎng)問(wèn)它：
https://plnkr.co/edit/xLVqnzt...

請(qǐng)注意{{vojta.name}}和{{vojta.address}}為空，意味著它們未定義（undefined）。雖然我們?cè)诳刂破髦卸x了vojta，但它在指令中不可用。

顧名思義，該指令的 isolate scope隔離了除顯式添加到作用域的模型之外的所有內(nèi)容：scope: {}散列對(duì)象. 這在構(gòu)建可重用組件時(shí)很有用，因?yàn)樗梢苑乐菇M件改變模型狀態(tài)，除了顯式傳入。

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.

創(chuàng)建一個(gè)操縱DOM的指令

在這個(gè)例子中，我們將建立一個(gè)顯示當(dāng)前時(shí)間的指令。每秒一次，它會(huì)更新DOM以反映當(dāng)前時(shí)間。

想要修改DOM的指令通常使用link選項(xiàng)來(lái)注冊(cè)DOM監(jiān)聽(tīng)器以及更新DOM。它在模板被克隆之后執(zhí)行，并且是放置指令邏輯的地方。

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

scope是一個(gè)Angularjs scope 對(duì)象

element 是一個(gè)此指令匹配的jqLite包裝元素

attrs是一個(gè)具有標(biāo)準(zhǔn)化屬性名稱(chēng)及其對(duì)應(yīng)屬性值的鍵值對(duì)的散列對(duì)象。

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

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

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

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

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

我們注冊(cè)一個(gè)事件element.on（"$ destroy"，...）。什么引發(fā)了這個(gè)$ destroy事件？

AngularJS發(fā)布了一些特殊事件。當(dāng)用AngularJS的編譯器編譯的DOM節(jié)點(diǎn)被銷(xiāo)毀時(shí)，它會(huì)發(fā)起$ destroy事件。同樣，當(dāng)Angularjs scope被銷(xiāo)毀，他會(huì)廣播（broadcasts）一個(gè)$destory事件監(jiān)聽(tīng)scopes。

通過(guò)監(jiān)聽(tīng)此事件，可以刪除可能導(dǎo)致內(nèi)存泄漏的事件偵聽(tīng)器。注冊(cè)到scope和element的監(jiān)聽(tīng)事件在銷(xiāo)毀DOM時(shí)會(huì)自動(dòng)清理，但是如果您在服務(wù)上注冊(cè)了偵聽(tīng)器，或者在未被刪除的DOM節(jié)點(diǎn)上注冊(cè)了偵聽(tīng)器，你必須自己清理它，否則你有冒險(xiǎn)引入內(nèi)存泄漏的風(fēng)險(xiǎn)。

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.

創(chuàng)建包裝其他元素的指令

我們已經(jīng)看到，您可以使用isolate scope將模型傳遞給指令，但是有時(shí)候想要能傳入一整個(gè)模板而不是一個(gè)字符串或者對(duì)象。我們說(shuō)我們想要?jiǎng)?chuàng)建一個(gè)“dialog box”組建。dialog box應(yīng)該有能力包裝任意的內(nèi)容（any arbitrary content）。

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

transclude選項(xiàng)到底做了什么呢？transclude使指令的內(nèi)容通過(guò)此選項(xiàng)擁有可訪(fǎng)問(wèn)外部指令的scope不是內(nèi)部的scope。

為了說(shuō)明了這一點(diǎn)，請(qǐng)看下面的例子。注意，我們?cè)趕cript.js中添加了一個(gè)link函數(shù)，將名稱(chēng)重新定義為Jeff。您認(rèn)為{{name}}綁定將會(huì)得到什么結(jié)果？
https://plnkr.co/edit/OEdkXY4...

照常，我們以為{{name}}應(yīng)該是Jeff。但是，我們看見(jiàn)的是Tobias。

transclude選項(xiàng)改變了scope的嵌套方式。它使得一個(gè)transcluded指令的內(nèi)容具有在指令之外的任何scope內(nèi)容，而不是任何內(nèi)部的scope。這樣做，它可以讓內(nèi)容訪(fǎng)問(wèn)外部scope。

請(qǐng)注意，如果指令沒(méi)有創(chuàng)建自己的獨(dú)立作用域，那么scope.name ="Jeff"中的作用域?qū)⒁猛獠孔饔糜颍覀儠?huì)在輸出中看到Jeff。

這種行為對(duì)于封裝某些內(nèi)容的指令是有意義的，因?yàn)榉駝t，您必須分別傳入每個(gè)您想要使用的模型。如果你必須傳入每一個(gè)你想要的model，那么你不能真正的使用任意的內(nèi)容，對(duì)嗎？

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

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

我們希望通過(guò)從指令的作用域調(diào)用它來(lái)運(yùn)行我們傳遞的函數(shù)，但是它會(huì)在注冊(cè)作用域的上下文中運(yùn)行。

我們?cè)谥耙呀?jīng)看到在scope選項(xiàng)中如何使用 =attr，但是在上面的例子中，我們使用了&attr代替。 &綁定允許一個(gè)指令去觸發(fā)一個(gè)原始范圍內(nèi)的表達(dá)式的評(píng)估，在一個(gè)特定時(shí)間點(diǎn)上。任何合法的表達(dá)式都是允許的，包括一個(gè)含有函數(shù)調(diào)用的表達(dá)式。如此，& 綁定是理想的將回調(diào)函數(shù)綁定到指令行為。

當(dāng)用戶(hù)點(diǎn)擊dialog中的 x，指令的close函數(shù)被調(diào)用，多虧于ng-click。這個(gè)close調(diào)用在isolated scope之上，實(shí)際上會(huì)在原始scope的上下文中評(píng)估表達(dá)式 hideDialog（message），導(dǎo)致運(yùn)行Controller中的hideDialog function。

通常期望通過(guò)一個(gè)表達(dá)式從isolate scope傳入數(shù)據(jù)到父scope，這可以通過(guò)將局部變量名稱(chēng)和值的映射傳遞到表達(dá)式包裝函數(shù)來(lái)完成。例如，hideDialkog函數(shù)接受一個(gè)message來(lái)顯示當(dāng)dialog被隱藏是。這被指令調(diào)用 close({message: "closing for now"})指明。接著局部變量message將在on-close表達(dá)式內(nèi)被訪(fǎng)問(wèn)(is available).

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

創(chuàng)建一個(gè)添加事件監(jiān)聽(tīng)器的指令

以前，我們使用鏈接函數(shù)來(lái)創(chuàng)建操縱其DOM元素的指令。在這個(gè)例子的基礎(chǔ)上，讓我們制定一個(gè)對(duì)其元素事件做出反應(yīng)的指令。

例如，如果我們想創(chuàng)建一個(gè)允許用戶(hù)拖拽元素的指令呢？
https://plnkr.co/edit/hcUyuBY...

創(chuàng)建一個(gè)通信的指令

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

有時(shí)，你需要一個(gè)由指令組合構(gòu)建的組件。

想象你想要有一個(gè)容器，其中容器的內(nèi)容對(duì)應(yīng)于哪個(gè)選項(xiàng)卡處于活動(dòng)狀態(tài)的選項(xiàng)卡。
https://plnkr.co/edit/kqLjcwG...

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

所以這個(gè)myTabs contoller從哪里來(lái)的？指令可以特定一個(gè)controllers通過(guò)使用 controller選項(xiàng)。如你所見(jiàn)，myTabs指令使用了此選項(xiàng)。就像ngController，此選項(xiàng)附加一個(gè)控制器到指令的模板上。

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

回頭看myPane的定義，注意到link函數(shù)的最后一個(gè)參數(shù)：tabCtrl。當(dāng)指令需要控制器時(shí)，它將接收該控制器作為其link函數(shù)的第四個(gè)參數(shù)。利用這一點(diǎn)，myPane可以調(diào)用myTabs的addPane函數(shù)。

如果需要多個(gè)控制器，則指令的require選項(xiàng)可以采用數(shù)組參數(shù)。發(fā)送給鏈接函數(shù)的相應(yīng)參數(shù)也將是一個(gè)數(shù)組。

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

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

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

總結(jié)

到此我們已經(jīng)看了大多數(shù)指令的用法，每一個(gè)樣例演示了一個(gè)創(chuàng)建你自己指令的好的起始點(diǎn)。

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

$compile API 有一個(gè)全面的指令清單選項(xiàng)以供參考。

最后

如有任何問(wèn)題和建議歡迎發(fā)送至郵箱討論：
翻譯不易，若您覺(jué)得對(duì)您有幫助，歡迎打賞

微信：

支付寶：