Angular Directive（指令）

2017-08-26

Directive

将一个TS类装饰为Angular指令，并收集指令配置元数据。

元数据概览


@Directive({ 
  selector?: string
  inputs?: string[]
  outputs?: string[]
  host?: {[key: string]: string}
  providers?: Provider[]
  exportAs?: string
  queries?: {[key: string]: any}
})

如何使用

采用angular-cli脚手架进行开发。在项目根目录下，运行下面命令：

1	ng g d components/firstDirective

first-directive.directive.ts如下：

import { Directive } from "@angular/core";
@Directive({
  selector: "[appFirstDirective]"
})
export class FirstDirectiveDirective {
  constructor() {}
}

描述

Directive 装饰器允许你将一个类标记为Angular指令，并且它提供了决定指令在运行时如何处理、实例化以及使用的附加元数据。

指令允许你讲行为附加到DOM元素中。

一个指令必须从属于一个NgModule，这样才能在其他指令、组件或者应用程序中使用该指令。要指定一个指令是NgModule的成员，应该将其列在NgModule的declarations字段数组中。

除了通过Directive装饰器指定的元数据配置之外，指令也可以通过实现各种生命周期钩子来控制其在各个生命中期时的行为。

元数据属性：

exportAs - 指定可以在模板中使用的指令名称，将该指令通过 #语法解析 赋值给局部变量。
host - 配置宿主元素的事件、行为、特性（attributes）以及属性（properties）。
inputs - 指令的输入属性名称数组；用于绑定组件输入
outputs - 指令的输出事件名称数组；
providers - 组件及其子组件的服务提供商
queries - 配置能够注入该组件的queries
selector - css选择器，在模板中识别这个指令或组件

元数据属性

1	selector?: string

CSS选择器，以便从模板中识别出关联到这个指令的 HTML。

selector的声明可以是以下方式：

element-name：通过标签名称选择
.class：通过类名选择
[attribute]：通过属性名称选择（cli默认生成的是这种方式）
[attribute=value]：通过属性名称和属性选择
:not[sub_selector]：只选择和sub_selector不匹配的元素
selector1,selector2：选择匹配selector1或selector2的元素

示例

假设我们有一个选择器为 input[text=text] 的指令。

下列HTML：

<form>
    <input type="text">
    <input type="radio">
</form>

该指令将只会实例化元素

再比如，下面的指令类

import { Directive } from "@angular/core";
@Directive({
  selector: "[appFirstDirective]"
})
export class FirstDirectiveDirective {
  constructor() {}
}

其匹配的模板中元素可以是

1	<p appFirstDirective></p>

如果将selector改为：

1	selector: "[appFirstDirective],appFirstDirective"

其匹配的模板元素可以是：

1
2
3

<p appFirstDirective></p>
<appFirstDirective></appFirstDirective>

1	inputs?: string[]

枚举了指令的数据绑定输入属性集合。

Angular通过变化检测自动更新输入属性值

inputs输入字符串列表可以使用 directiveProperty：bindingProperty（指令实例属性：标签元素属性）的格式。

1	outputs?: string[]

枚举事件绑定输出属性集合。

当output属性发射一个事件，将触发在模板中绑定的事件处理器

outputs字符串列表可以使用 directiveProperty：bindingProperty（指令实例属性：标签元素属性）的格式。

1	host?: {[key: string]: string}

配置宿主元素的事件、行为、特性（attributes）以及属性（properties）

Host Listeners（宿主事件监听）

通过一组 (event)：method键值对指定指令监听DOM的哪些事件

event：指令监听的DOM事件
method：事件发生时要执行的函数。如果函数返回 false，将在DOM事件上应用preventDefault
如果要监听全局事件，需要在事件名称前添加 window、document、body这些目标
当写指令的事件绑定时，仍然可以应用局部变量 $event。

例子
下面例子声明了一个监听click事件的指令

@Directive({
  selector: 'button[counting]',
  host: {
    '(click)': 'onClick($event.target)'
  }
})
class CountClicks {
  numberOfClicks = 0;
  onClick(btn) {
    console.log("button", btn, "number of clicks:", this.numberOfClicks++);
  }
}
@Component({
  selector: 'app',
  template: `<button counting>Increment</button>`
})
class App {}

Host Property Bindings（宿主属性绑定）

指定指令更新的DOM属性。在变化检测时，Angular会自动更新宿主的属性绑定。如果绑定发生变化，它将会更新指令的宿主的元素。

例子

@Directive({
  selector: '[ngModel]',
  host: {
    '[class.valid]': 'valid',
    '[class.invalid]': 'invalid'
  }
})
class NgModelStatus {
  constructor(public control:NgModel) {}
  get valid { return this.control.valid; }
  get invalid { return this.control.invalid; }
}
@Component({
  selector: 'app',
  template: `<input [(ngModel)]="prop">`
})
class App {
  prop;
}

属性（Attribute）

指定应传递至宿主元素的静态属性。

下面例子，在宿主元素（这里是

）使用 my-button 指令（例如：

）将确保该宿主元素获得“button” role。

@Directive({
  selector: '[my-button]',
  host: {
    'role': 'button'
  }
})
class MyButton {
}

1	providers?: Provider[]

定义了对该指令以及其子DOM可见的可注入对象集合。（依赖注入）

class Greeter {
   greet(name:string) {
     return 'Hello ' + name + '!';
   }
}
@Directive({
  selector: 'greet',
  providers: [
    Greeter
  ]
})
class HelloWorld {
  greeter:Greeter;
    //这里greeter是Greeter的实例，而不是形参
  constructor(greeter:Greeter) {
    this.greeter = greeter;
  }
}

1	exportAs?: string

指定可以在模板中使用的指令名称，将该指令通过 #语法解析赋值给局部变量

@Directive({
  selector: 'child-dir',
  exportAs: 'child'
})
class ChildDir {
}
@Component({
  selector: 'main',
  template: `<child-dir #c="child"></child-dir>`
})
class MainComponent {
}

这里类似于内置的ngForm指令。通过吧 child赋值给c，C将代表这个DOM元素

附录

指令的输入、输出与组件相同。为什么？因为组件就是指令的一种，是带有模板的指令
输入输出可以采用inputs、outputs元数据配置项，也可以采用@Input()、@Output()注解，按照 风格指南，采用注解较好。
在Angular中，组件（指令）的宿主就是 该组件所附着的元素，借助host选项，就可以在指令或组件内部配置宿主元素的样式、事件等等。
参考 https://angular.cn/api/core/Directive#selector
https://angular.cn/guide/attribute-directives