AngularJSでカスタム命令を作成する方法の詳細な説明

この記事の例では、AngularJS でカスタム命令を作成する方法を説明します。参考のために皆さんと共有してください。詳細は次のとおりです:

これは Angular 開発者からの指示の翻訳です。主に、Angular 開発の基本をすでに理解している開発者を対象としています。このドキュメントでは、独自の指示を作成する必要がある場合と、その作成方法について説明します。

ディレクティブとは何ですか? 大まかに言えば、ディレクティブは angular $compile サービスの説明であり、DOM に特定のタグ (属性、要素名、またはコメント) が表示されると、指定されたものを追加するようにコンパイラーに指示します。 DOM に対する動作。

プロセスは非常に簡単です。 angular には、ngBind や ngView などの便利な組み込み命令が多数あり、コントローラーやサービスを作成するのと同じように、独自の命令を作成することもできます。 Angular が起動すると、Angular のコンパイラは HTML を解析してディレクティブと一致するため、ディレクティブが動作を登録したり DOM を変更したりできるようになります。

命令のマッチング

命令を書く前に、まず知っておく必要があるのは、angular が命令とどのように一致するかということです。次の例では、入力要素が 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/>

ベスト プラクティス: 「-」の使用を優先します。 format 名前を付けます (例: 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>

に解析できます。ベスト プラクティス: タグ名と属性名の使用を優先して命令を使用します。これにより、指定した要素がどの要素に一致するかを理解しやすくなります。

ベスト プラクティス: 注釈は通常、テーブル要素などの複数の要素にまたがる命令の作成を制限したり、ネストの繰り返しを制限したりするために DOM API で使用されるため、注釈を使用する必要があります。 AngularJS バージョン 1.2 では、より良い解決策として ng-repeat-start と ng-repeat-end を使用することで、この問題は解決されています。可能な場合は、このアプローチをお勧めします。

テキストと属性のバインド

コンパイルプロセス中、コンパイラは $interpolate サービスを使用して、一致したテキストと属性の値に埋め込み式が含まれているかどうかを検出します。これらの式はウォッチとして登録され、ダイジェスト サイクル中に更新できます。

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

ngAttr 属性バインディング

ブラウザは、正当であると考える属性値について非常にうるさい場合があります (つまり、一部の要素の属性は任意に割り当てることができず、そうでない場合はエラーが報告されます)。

例:

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

この書き込み方法を使用すると、コンソールにエラーが報告されます: エラー: 属性 cx="{{cx}}" の値が無効です これは制限によるものです。単純に cx="{{cx}}" と記述することはできません。

ng-attr-cx を使用すると、この問題を解決できます

バインドされた属性が ngAttr プレフィックス (または ng-attr) を使用している場合)、バインド内で、対応するプレフィックスのない属性に適用されます。このメソッドを使用すると、ブラウザーによってすぐに処理される必要がある属性 (SVG 要素のcircle[cx] 属性など) にバインドできます。

したがって、上記の問題を解決するには、次のように書くことができます:

<svg>
 <circle ng-attr-cx="{{cx}}"></circle>
</svg>

命令を作成する

まず、命令を登録するための API について説明します。コントローラーと同様に、命令はモジュールに登録されます。違いは、ディレクティブが module.directive API を通じて登録されることです。 module.directive は、標準化された名前とファクトリ関数を受け入れます。このファクトリ関数は、さまざまな設定を含むオブジェクトを返します。このオブジェクトは、$compile サービスに次のステップに進む方法を指示するために使用されます。

ファクトリー関数は、コンパイラーが初めて命令と一致したときに 1 回だけ呼び出されます。通常、初期化作業はファクトリー関数で実行されます。この関数は $injector.invoke を使用して呼び出されるため、コントローラーと同様に依存関係の注入に使用できます。

ベスト プラクティス: 関数を返すよりも、定義されたオブジェクトを返すことを優先します。

次に、最初にいくつかの一般的な例を理解してから、さまざまな構成項目の原則とコンパイルプロセスについて詳しく説明します。

Best Practice: 为了避免与某些未来的标准命名冲突，最好前缀化你自己的指令，比如你创建一个dfdf839e4285f6d29afc838443bb892c指令，它可能会产生冲突，加入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编译链接dc2b607441da0f63f26f57c02dd103ad 16b28748ea4df4d9c2150843fecfba68之后，它将会匹配子元素的指令。这意味着你可以组合一些指令。以下例子中你会看到如何做到这一点。

这个例子中，我们直接在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}}

   

非常好，但是如果我们想让我们的指令匹配标签名b5ec7581f2dd2b6bdff0e91d4906055c？ 如果我们只是简单的把b5ec7581f2dd2b6bdff0e91d4906055c元素放在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，第一个b5ec7581f2dd2b6bdff0e91d4906055c绑定内部作用域的customer到naomi。这个naomi我们在控制器中已经定义好了。第二个是绑定customer到igor。

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

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

   

属性名(customer)是myCustomer指令上isolated scope的变量名。它的值(=customer)告诉编译器绑定到customer属性。

Note: 指令作用域配置中的'=attr'属性名是被规范化过后的名字，比如要绑定a3b95b23d96360596431d5277e3a09ca中的属性，你就要使用'=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程序设计有所帮助。