docs(core): add docs to HostBinding and HostListener
This commit is contained in:
parent
a87ebb28e2
commit
617acf4cd6
|
@ -472,19 +472,7 @@ export interface OutputFactory {
|
|||
}
|
||||
|
||||
/**
|
||||
* {@link HostBindingMetadata} factory for creating decorators.
|
||||
*
|
||||
* ## Example as TypeScript Decorator
|
||||
*
|
||||
* ```
|
||||
* @Directive({
|
||||
* selector: 'sample-dir'
|
||||
* })
|
||||
* class SampleDir {
|
||||
* @HostBinding() prop1; // Same as @HostBinding('prop1') prop1;
|
||||
* @HostBinding("el-prop") prop1;
|
||||
* }
|
||||
* ```
|
||||
* {@link HostBindingMetadata} factory function.
|
||||
*/
|
||||
export interface HostBindingFactory {
|
||||
(hostPropertyName?: string): any;
|
||||
|
@ -492,18 +480,7 @@ export interface HostBindingFactory {
|
|||
}
|
||||
|
||||
/**
|
||||
* {@link HostListenerMetadata} factory for creating decorators.
|
||||
*
|
||||
* ## Example as TypeScript Decorator
|
||||
*
|
||||
* ```
|
||||
* @Directive({
|
||||
* selector: 'sample-dir'
|
||||
* })
|
||||
* class SampleDir {
|
||||
* @HostListener("change", ['$event.target.value']) onChange(value){}
|
||||
* }
|
||||
* ```
|
||||
* {@link HostListenerMetadata} factory function.
|
||||
*/
|
||||
export interface HostListenerFactory {
|
||||
(eventName: string, args?: string[]): any;
|
||||
|
|
|
@ -517,9 +517,9 @@ export class DirectiveMetadata extends InjectableMetadata {
|
|||
/**
|
||||
* Specify the events, actions, properties and attributes related to the host element.
|
||||
*
|
||||
* ## Events
|
||||
* ## Host Listeners
|
||||
*
|
||||
* Specifies which DOM hostListeners a directive listens to via a set of `(event)` to `method`
|
||||
* Specifies which DOM events a directive listens to via a set of `(event)` to `method`
|
||||
* key-value pairs:
|
||||
*
|
||||
* - `event1`: the DOM event that the directive listens to.
|
||||
|
@ -530,76 +530,86 @@ export class DirectiveMetadata extends InjectableMetadata {
|
|||
* To listen to global events, a target must be added to the event name.
|
||||
* The target can be `window`, `document` or `body`.
|
||||
*
|
||||
* When writing a directive event binding, you can also refer to the following local variables:
|
||||
* - `$event`: Current event object which triggered the event.
|
||||
* - `$target`: The source of the event. This will be either a DOM element or an Angular
|
||||
* directive. (will be implemented in later release)
|
||||
* When writing a directive event binding, you can also refer to the $event local variable.
|
||||
*
|
||||
* ## Syntax
|
||||
* ### Example ([live demo](http://plnkr.co/edit/DlA5KU?p=preview))
|
||||
*
|
||||
* ```
|
||||
* The following example declares a directive that attaches a click listener to the button and
|
||||
* counts clicks.
|
||||
*
|
||||
* ```typescript
|
||||
* @Directive({
|
||||
* selector: 'button[counting]',
|
||||
* host: {
|
||||
* '(event1)': 'onMethod1(arguments)',
|
||||
* '(target:event2)': 'onMethod2(arguments)',
|
||||
* ...
|
||||
* }
|
||||
* }
|
||||
* ```
|
||||
*
|
||||
* ## Basic Event Binding:
|
||||
*
|
||||
* Suppose you want to write a directive that reacts to `change` events in the DOM and on
|
||||
* `resize` events in window.
|
||||
* You would define the event binding as follows:
|
||||
*
|
||||
* ```
|
||||
* @Directive({
|
||||
* selector: 'input',
|
||||
* host: {
|
||||
* '(change)': 'onChange($event)',
|
||||
* '(window:resize)': 'onResize($event)'
|
||||
* '(click)': 'onClick($event.target)'
|
||||
* }
|
||||
* })
|
||||
* class InputDirective {
|
||||
* onChange(event:Event) {
|
||||
* // invoked when the input element fires the 'change' event
|
||||
* }
|
||||
* onResize(event:Event) {
|
||||
* // invoked when the window fires the 'resize' event
|
||||
* class CountClicks {
|
||||
* numberOfClicks = 0;
|
||||
*
|
||||
* onClick(btn) {
|
||||
* console.log("button", btn, "number of clicks:", this.numberOfClicks++);
|
||||
* }
|
||||
* }
|
||||
*
|
||||
* @Component({selector: 'app'})
|
||||
* @View({
|
||||
* template: `<button counting>Increment</button>`,
|
||||
* directives: [CountClicks]
|
||||
* })
|
||||
* class App {}
|
||||
*
|
||||
* bootstrap(App);
|
||||
* ```
|
||||
*
|
||||
* ## Properties
|
||||
* ## Host Property Bindings
|
||||
*
|
||||
* Specifies which DOM properties a directives updates.
|
||||
* Specifies which DOM properties a directive updates.
|
||||
*
|
||||
* ## Syntax
|
||||
* Angular automatically checks host property bindings during change detection.
|
||||
* If a binding changes, it will update the host element of the directive.
|
||||
*
|
||||
* ```
|
||||
* ### Example ([live demo](http://plnkr.co/edit/gNg0ED?p=preview))
|
||||
*
|
||||
* The following example creates a directive that sets the `valid` and `invalid` classes
|
||||
* on the DOM element that has ng-model directive on it.
|
||||
*
|
||||
* ```typescript
|
||||
* @Directive({
|
||||
* selector: 'input',
|
||||
* selector: '[ng-model]',
|
||||
* host: {
|
||||
* '[prop]': 'expression'
|
||||
* '[class.valid]': 'valid',
|
||||
* '[class.invalid]': 'invalid'
|
||||
* }
|
||||
* })
|
||||
* class InputDirective {
|
||||
* value:string;
|
||||
* class NgModelStatus {
|
||||
* constructor(public control:NgModel) {}
|
||||
* get valid { return this.control.valid; }
|
||||
* get invalid { return this.control.invalid; }
|
||||
* }
|
||||
* ```
|
||||
*
|
||||
* In this example the `prop` property of the host element is updated with the expression value
|
||||
* every time it changes.
|
||||
* @Component({selector: 'app'})
|
||||
* @View({
|
||||
* template: `<input [(ng-model)]="prop">`,
|
||||
* directives: [FORM_DIRECTIVES, NgModelStatus]
|
||||
* })
|
||||
* class App {
|
||||
* prop;
|
||||
* }
|
||||
*
|
||||
* bootstrap(App);
|
||||
* ```
|
||||
*
|
||||
* ## Attributes
|
||||
*
|
||||
* Specifies static attributes that should be propagated to a host element. Attributes specified
|
||||
* in `hostAttributes` are propagated only if a given attribute is not present on a host element.
|
||||
* Specifies static attributes that should be propagated to a host element.
|
||||
*
|
||||
* ## Syntax
|
||||
* ### Example
|
||||
*
|
||||
* ```
|
||||
* In this example using `my-button` directive (ex.: `<div my-button></div>`) on a host element
|
||||
* (here: `<div>` ) will ensure that this element will get the "button" role.
|
||||
*
|
||||
* ```typescript
|
||||
* @Directive({
|
||||
* selector: '[my-button]',
|
||||
* host: {
|
||||
|
@ -609,10 +619,6 @@ export class DirectiveMetadata extends InjectableMetadata {
|
|||
* class MyButton {
|
||||
* }
|
||||
* ```
|
||||
*
|
||||
* In this example using `my-button` directive (ex.: `<div my-button></div>`) on a host element
|
||||
* (here: `<div>` ) will ensure that this element will get the "button" role.
|
||||
*
|
||||
*/
|
||||
host: StringMap<string, string>;
|
||||
|
||||
|
@ -926,9 +932,9 @@ export class PipeMetadata extends InjectableMetadata {
|
|||
*
|
||||
* Angular automatically updates data-bound properties during change detection.
|
||||
*
|
||||
* `InputMetadata` takes an optional parameters that specifies that name
|
||||
* `InputMetadata` takes an optional parameter that specifies the name
|
||||
* used when instantiating a component in the template. When not provided,
|
||||
* the class property name is used.
|
||||
* the name of the decorated property is used.
|
||||
*
|
||||
* ### Example
|
||||
*
|
||||
|
@ -977,9 +983,9 @@ export class InputMetadata {
|
|||
* When an output property emits an event, an event handler attached to that event
|
||||
* the template is invoked.
|
||||
*
|
||||
* `OutputMetadata` takes an optional parameters that specifies that name
|
||||
* `OutputMetadata` takes an optional parameter that specifies the name
|
||||
* used when instantiating a component in the template. When not provided,
|
||||
* the class property name is used.
|
||||
* the name of the decorated property is used.
|
||||
*
|
||||
* ### Example
|
||||
*
|
||||
|
@ -1018,33 +1024,38 @@ export class OutputMetadata {
|
|||
}
|
||||
|
||||
/**
|
||||
* Declares a host binding property.
|
||||
* Declares a host property binding.
|
||||
*
|
||||
* Angular automatically updates data-bound properties during change detection.
|
||||
* Angular automatically checks host property bindings during change detection.
|
||||
* If a binding changes, it will update the host element of the directive.
|
||||
*
|
||||
* `HostBindingMetadata` takes an optional parameter that specifies the property
|
||||
* name of the host element that will be updated. When not provided,
|
||||
* the class property name is used.
|
||||
*
|
||||
* ### Example
|
||||
*
|
||||
* ```
|
||||
* @Directive({
|
||||
* selector: 'sample-dir'
|
||||
* })
|
||||
* class SampleDir {
|
||||
* @HostBinding() prop1; // Same as @HostBinding('prop1') prop1;
|
||||
* @HostBinding("el-prop") prop2;
|
||||
* }
|
||||
* ```
|
||||
* The following example creates a directive that sets the `valid` and `invalid` classes
|
||||
* on the DOM element that has ng-model directive on it.
|
||||
*
|
||||
* This is equivalent to
|
||||
*
|
||||
* ```
|
||||
* @Directive({
|
||||
* selector: 'sample-dir',
|
||||
* host: {'[prop1]': 'prop1', '[el-prop]': 'prop2'}
|
||||
* })
|
||||
* class SampleDir {
|
||||
* prop1;
|
||||
* prop2;
|
||||
* ```typescript
|
||||
* @Directive({selector: '[ng-model]'})
|
||||
* class NgModelStatus {
|
||||
* constructor(public control:NgModel) {}
|
||||
* @HostBinding('[class.valid]') get valid { return this.control.valid; }
|
||||
* @HostBinding('[class.invalid]') get invalid { return this.control.invalid; }
|
||||
* }
|
||||
*
|
||||
* @Component({selector: 'app'})
|
||||
* @View({
|
||||
* template: `<input [(ng-model)]="prop">`,
|
||||
* directives: [FORM_DIRECTIVES, NgModelStatus]
|
||||
* })
|
||||
* class App {
|
||||
* prop;
|
||||
* }
|
||||
*
|
||||
* bootstrap(App);
|
||||
* ```
|
||||
*/
|
||||
@CONST()
|
||||
|
@ -1053,29 +1064,37 @@ export class HostBindingMetadata {
|
|||
}
|
||||
|
||||
/**
|
||||
* Declare a host listener.
|
||||
* Declares a host listener.
|
||||
*
|
||||
* ## Example
|
||||
* Angular will invoke the decorated method when the host element emits the specified event.
|
||||
*
|
||||
* ```
|
||||
* @Directive({
|
||||
* selector: 'sample-dir'
|
||||
* })
|
||||
* class SampleDir {
|
||||
* @HostListener("change", ['$event.target.value']) onChange(value){}
|
||||
* If the decorated method returns `false`, then `preventDefault` is applied on the DOM
|
||||
* event.
|
||||
*
|
||||
* ### Example
|
||||
*
|
||||
* The following example declares a directive that attaches a click listener to the button and
|
||||
* counts clicks.
|
||||
*
|
||||
* ```typescript
|
||||
* @Directive({selector: 'button[counting]'})
|
||||
* class CountClicks {
|
||||
* numberOfClicks = 0;
|
||||
*
|
||||
* @HostListener('click', ['$event.target'])
|
||||
* onClick(btn) {
|
||||
* console.log("button", btn, "number of clicks:", this.numberOfClicks++);
|
||||
* }
|
||||
* ```
|
||||
*
|
||||
* This is equivalent to
|
||||
*
|
||||
* ```
|
||||
* @Directive({
|
||||
* selector: 'sample-dir',
|
||||
* host: {'(change)': 'onChange($event.target.value)'}
|
||||
* })
|
||||
* class SampleDir {
|
||||
* onChange(value){}
|
||||
* }
|
||||
*
|
||||
* @Component({selector: 'app'})
|
||||
* @View({
|
||||
* template: `<button counting>Increment</button>`,
|
||||
* directives: [CountClicks]
|
||||
* })
|
||||
* class App {}
|
||||
*
|
||||
* bootstrap(App);
|
||||
* ```
|
||||
*/
|
||||
@CONST()
|
||||
|
|
Loading…
Reference in New Issue