iSharkFly-Docs
/
angular-docs-cn
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs(core): add docs to HostBinding and HostListener

This commit is contained in:
vsavkin 2015-10-01 15:47:51 -07:00
parent a87ebb28e2
commit 617acf4cd6
2 changed files with 116 additions and 120 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

27
modules/angular2/src/core/metadata.ts
View File

@ -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;

209
modules/angular2/src/core/metadata/directives.ts
View File

@ -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)'}
* @Component({selector: 'app'})
* @View({
* template: `<button counting>Increment</button>`,
* directives: [CountClicks]
* })
* class SampleDir {
* onChange(value){}
* }
* class App {}
*
* bootstrap(App);
* ```
*/
@CONST()