cargdev/angular
1
0
Fork 0
Code Issues 10 Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add api doc to commonly queried elements

Browse Source
This commit is contained in:
Judy Bogart
2018-07-02 12:06:52 -07:00
committed by Victor Berchet
parent 86203736e9
commit f1ab394218
11 changed files with 712 additions and 473 deletions
Download Patch File Download Diff File Expand all files Collapse all files

9
packages/core/src/metadata/di.ts
View File

@ -309,11 +309,10 @@ export const ViewChildren: ViewChildrenDecorator = makePropDecorator(
export interface ViewChildDecorator {
/**
* @description
* Configures a view query.
*
* You can use ViewChild to get the first element or the directive matching the selector from the
* view DOM. If the view DOM changes, and a new child matches the selector,
* the property will be updated.
* Property decorator that configures a view query.
* The change detector looks for the first element or the directive matching the selector
* in the view DOM. If the view DOM changes, and a new child matches the selector,
* the property is updated.
*
* View queries are set before the `ngAfterViewInit` callback is called.
*

212
packages/core/src/metadata/directives.ts
View File

@ -19,37 +19,18 @@ import {ViewEncapsulation} from './view';
*/
export interface DirectiveDecorator {
/**
* Marks a class as an Angular directive and collects directive configuration
* metadata.
*
* Directive decorator allows you to mark a class as an Angular directive and provide additional
* metadata that determines how the directive should be processed, instantiated and used at
* Marks a class as an Angular directive. You can define your own
* directives to attach custom behavior to elements in the DOM.
* The options provide configuration metadata that determines
* how the directive should be processed, instantiated and used at
* runtime.
*
* Directives allow you to attach behavior to elements in the DOM..
* Directive classes, like component classes, can implement
* [life-cycle hoooks](guide/lifecycle-hooks) to influence their configuration and behavior.
*
* A directive must belong to an NgModule in order for it to be usable
* by another directive, component, or application. To specify that a directive is a member of an
* NgModule,
* you should list it in the `declarations` field of that NgModule.
*
* In addition to the metadata configuration specified via the Directive decorator,
* directives can control their runtime behavior by implementing various Life-Cycle hooks.
*
* **Metadata Properties:**
*
* * **exportAs** - name under which the component instance is exported in a template. Can be
* given a single name or a comma-delimited list of names.
* * **host** - map of class property to host element bindings for events, properties and
* attributes
* * **inputs** - list of class property names to data-bind as component inputs
* * **outputs** - list of class property names that expose output events that others can
* subscribe to
* * **providers** - list of providers available to this component and its children
* * **queries** - configure queries that can be injected into the component
* * **selector** - css selector that identifies this component in a template
*
* @usageNotes
* To define a directive, mark the class with the decorator and provide metadata.
*
* ```
* import {Directive} from '@angular/core';
@ -58,9 +39,27 @@ export interface DirectiveDecorator {
* selector: 'my-directive',
* })
* export class MyDirective {
* ...
* }
* ```
*
* ### Declaring directives
*
* Directives are [declarables](guide/glossary#declarable).
* Like component and pipes, they must be declared by an NgModule
* in order to be usable in an app.
*
* A directive must belong to exactly one NgModule. Do not re-declare
* a directive imported from another module.
* List the directive class in the `declarations` field of an NgModule.
*
* ```
* declarations: [
* AppComponent,
* MyDirective
* ],
* ```
*
* @Annotation
*/
(obj: Directive): TypeDecorator;
@ -75,10 +74,7 @@ export interface Directive {
/**
* The CSS selector that triggers the instantiation of a directive.
*
* Angular only allows directives to trigger on CSS selectors that do not cross element
* boundaries.
*
* `selector` may be declared as one of the following:
* Declare as one of the following:
*
* - `element-name`: select by element name.
* - `.class`: select by class name.
@ -87,12 +83,10 @@ export interface Directive {
* - `:not(sub_selector)`: select only if the element does not match the `sub_selector`.
* - `selector1, selector2`: select if either `selector1` or `selector2` matches.
*
* @usageNotes
* ### Example
*
* Suppose we have a directive with an `input[type=text]` selector.
*
* And the following HTML:
* Angular only allows directives to trigger on CSS selectors that do not cross element
* boundaries. For example, consider a directive with an `input[type=text]` selector.
* For the following HTML, the directive is instantiated only on the
* `<input type="text">` element.
*
* ```html
* <form>
@ -101,8 +95,6 @@ export interface Directive {
* <form>
* ```
*
* The directive would only be instantiated on the `<input type="text">` element.
*
*/
selector?: string;
@ -110,7 +102,6 @@ export interface Directive {
* Enumerates the set of data-bound input properties for a directive
*
* Angular automatically updates input properties during change detection.
*
* The `inputs` property defines a set of `directiveProperty` to `bindingProperty`
* configuration:
*
@ -118,8 +109,8 @@ export interface Directive {
* - `bindingProperty` specifies the DOM property where the value is read from.
*
* When `bindingProperty` is not provided, it is assumed to be equal to `directiveProperty`.
*
* @usageNotes
*
* ### Example
*
* The following example creates a component with two data-bound properties.
@ -154,6 +145,7 @@ export interface Directive {
* - `bindingProperty` specifies the DOM property the event handler is attached to.
*
* @usageNotes
*
* ### Example
*
* ```typescript
@ -175,138 +167,8 @@ export interface Directive {
outputs?: string[];
/**
* Specify the events, actions, properties and attributes related to the host element.
*
* @usageNotes
* The key corresponds to the name of the event, property or attribute on the host to
* bind. The value is formatted differently depending upon the type of the binding.
*
* ### Host Listeners
*
* Specifies which DOM events a directive listens to via a set of `(event)` to `method`
* key-value pairs:
*
* - `event`: the DOM event that the directive listens to.
* - `statement`: the statement to execute when the event occurs.
* If the evaluation of the statement returns `false`, then `preventDefault`is applied on the DOM
* event.
*
* 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 $event local variable.
*
* The following example declares a directive that attaches a click listener to the button and
* counts clicks.
*
* ```typescript
* @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 {}
* ```
* See [live demo](http://plnkr.co/edit/DlA5KU?p=preview)
*
* ### Host Property Bindings
*
* Specifies which DOM properties a directive updates.
*
* Angular automatically checks host property bindings during change detection.
* If a binding changes, it will update the host element of the directive.
*
* The following example creates a directive that sets the `valid` and `invalid` classes
* on the DOM element that has ngModel directive on it.
*
* ```typescript
* @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;
* }
* ```
* See [live demo](http://plnkr.co/edit/gNg0ED?p=preview).
*
* ### Attributes
*
* Specifies static attributes that should be propagated to a host element.
*
* 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: {
* 'role': 'button'
* }
* })
* class MyButton {
* }
* ```
* Attaching the `my-button` directive to the host `<div>` element
* ensures that this element gets the "button" role.
*
* ```html
* <div my-button></div>
* ```
*
* @usageNotes
* ### Simple Example
*
* The following simple example shows how a class is injected,
* using a provider specified in the directive metadata:
*
* ```
* class Greeter {
* greet(name:string) {
* return 'Hello ' + name + '!';
* }
* }
*
* @Directive({
* selector: 'greet',
* providers: [
* Greeter
* ]
* })
* class HelloWorld {
* greeter:Greeter;
*
* constructor(greeter:Greeter) {
* this.greeter = greeter;
* }
* }
* ```
* A set of injection tokens that allow the DI system to
* provide a dependency to this directive or component.
*/
providers?: Provider[];
@ -314,6 +176,7 @@ export interface Directive {
* Defines the name that can be used in the template to assign this directive to a variable.
*
* @usageNotes
*
* ### Simple Example
*
* ```
@ -330,7 +193,6 @@ export interface Directive {
* })
* class MainComponent {
* }
*
* ```
*/
exportAs?: string;
@ -456,7 +318,9 @@ export interface Directive {
host?: {[key: string]: string};
/**
* See the `Component` decorator.
* Configures the [injector](guide/glossary#injector) of this
* directive or component with a [token](guide/glossary#di-token)
* that maps to a [provider](guide/glossary#provider) of a dependency.
*/
providers?: Provider[];

245
packages/core/src/metadata/lifecycle_hooks.ts
View File

@ -10,138 +10,225 @@ import {SimpleChange} from '../change_detection/change_detection_util';
/**
* A `changes` object whose keys are property names and
* values are instances of {@link SimpleChange}. See {@link OnChanges}
* Defines an object that associates properties with
* instances of `SimpleChange`.
*
* @see `OnChanges`
*
*/
export interface SimpleChanges { [propName: string]: SimpleChange; }
/**
* @description
* A lifecycle hook that is called when any data-bound property of a directive changes.
* Define an `ngOnChanges()` method to handle the changes.
*
* @see `DoCheck`
* @see `OnInit`
* @see [Lifecycle Hooks](guide/lifecycle-hooks#onchanges) guide
*
* @usageNotes
* The following snippet shows how a component can implement this interface to
* define an on-changes handler for an input property.
*
* {@example core/ts/metadata/lifecycle_hooks_spec.ts region='OnChanges'}
*
* @description
* Lifecycle hook that is called when any data-bound property of a directive changes.
*
* `ngOnChanges` is called right after the data-bound properties have been checked and before view
* and content children are checked if at least one of them has changed.
* The `changes` parameter contains the changed properties.
*
* See ["Lifecycle Hooks Guide"](guide/lifecycle-hooks#onchanges).
*
*
*/
export interface OnChanges { ngOnChanges(changes: SimpleChanges): void; }
export interface OnChanges {
/**
* A callback method that is invoked immediately after the
* default change detector has checked data-bound properties
* if at least one has changed, and before the view and content
* children are checked.
* @param changes The changed properties.
*/
ngOnChanges(changes: SimpleChanges): void;
}
/**
* @description
* A lifecycle hook that is called after Angular has initialized
* all data-bound properties of a directive.
* Define an `ngOnInit()` method to handle any additional initialization tasks.
*
* @see `AfterContentInit`
* @see [Lifecycle Hooks](guide/lifecycle-hooks#onchanges) guide
*
* @usageNotes
* The following snippet shows how a component can implement this interface to
* define its own initialization method.
*
* {@example core/ts/metadata/lifecycle_hooks_spec.ts region='OnInit'}
*
* @description
* Lifecycle hook that is called after data-bound properties of a directive are
* initialized.
*
* `ngOnInit` is called right after the directive's data-bound properties have been checked for the
* first time, and before any of its children have been checked. It is invoked only once when the
* directive is instantiated.
*
* See ["Lifecycle Hooks Guide"](guide/lifecycle-hooks).
*
*
*/
export interface OnInit { ngOnInit(): void; }
export interface OnInit {
/**
* A callback method that is invoked immediately after the
* default change detector has checked the directive's
* data-bound properties for the first time,
* and before any of the view or content children have been checked.
* It is invoked only once when the directive is instantiated.
*/
ngOnInit(): void;
}
/**
* A lifecycle hook that invokes a custom change-detection function for a directive,
* in addition to the check performed by the default change-detector.
*
* The default change-detection algorithm looks for differences by comparing
* bound-property values by reference across change detection runs. You can use this
* hook to check for and respond to changes by some other means.
*
* When the default change detector detects changes, it invokes `ngOnChanges()` if supplied,
* regardless of whether you perform additional change detection.
* Typically, you should not use both `DoCheck` and `OnChanges` to respond to
* changes on the same input.
*
* @see `OnChanges`
* @see [Lifecycle Hooks](guide/lifecycle-hooks#onchanges) guide
*
* @usageNotes
* The following snippet shows how a component can implement this interface
* to invoke it own change-detection cycle.
*
* {@example core/ts/metadata/lifecycle_hooks_spec.ts region='DoCheck'}
*
* @description
* Lifecycle hook that is called when Angular dirty checks a directive.
*
* `ngDoCheck` gets called to check the changes in the directives in addition to the default
* algorithm. The default change detection algorithm looks for differences by comparing
* bound-property values by reference across change detection runs.
*
* Note that a directive typically should not use both `DoCheck` and {@link OnChanges} to respond to
* changes on the same input, as `ngOnChanges` will continue to be called when the default change
* detector detects changes.
*
* See {@link KeyValueDiffers} and {@link IterableDiffers} for implementing custom dirty checking
* for collections.
*
* See ["Lifecycle Hooks Guide"](guide/lifecycle-hooks#docheck).
*
*
*/
export interface DoCheck { ngDoCheck(): void; }
export interface DoCheck {
/**
* A callback method that performs change-detection, invoked
* after the default change-detector runs.
* @see `KeyValueDiffers` and `IterableDiffers` for implementing
* custom change checking for collections.
*
*/
ngDoCheck(): void;
}
/**
* A lifecycle hook that is called when a directive, pipe, or service is destroyed.
* Use for any custom cleanup that needs to occur when the
* instance is destroyed.
* @see [Lifecycle Hooks](guide/lifecycle-hooks#onchanges) guide
*
* @usageNotes
* The following snippet shows how a component can implement this interface
* to define it own custom clean-up method.
*
* {@example core/ts/metadata/lifecycle_hooks_spec.ts region='OnDestroy'}
*
* @description
* Lifecycle hook that is called when a directive, pipe or service is destroyed.
*
* `ngOnDestroy` callback is typically used for any custom cleanup that needs to occur when the
* instance is destroyed.
*
* See ["Lifecycle Hooks Guide"](guide/lifecycle-hooks).
*
*
*/
export interface OnDestroy { ngOnDestroy(): void; }
export interface OnDestroy {
/**
* A callback method that performs custom clean-up, invoked immediately
* after a directive, pipe, or service instance is destroyed.
*/
ngOnDestroy(): void;
}
/**
* @description
* A lifecycle hook that is called after Angular has fully initialized
* all content of a directive.
* Define an `ngAfterContentInit()` method to handle any additional initialization tasks.
*
* @see `OnInit`
* @see `AfterViewInit`
* @see [Lifecycle Hooks](guide/lifecycle-hooks#onchanges) guide
*
* @usageNotes
* The following snippet shows how a component can implement this interface to
* define its own content initialization method.
*
* {@example core/ts/metadata/lifecycle_hooks_spec.ts region='AfterContentInit'}
*
* @description
* Lifecycle hook that is called after a directive's content has been fully
* initialized.
*
* See ["Lifecycle Hooks Guide"](guide/lifecycle-hooks#aftercontent).
*
*
*/
export interface AfterContentInit { ngAfterContentInit(): void; }
export interface AfterContentInit {
/**
* A callback method that is invoked immediately after
* Angular has completed initialization of all of the directive's
* content.
* It is invoked only once when the directive is instantiated.
*/
ngAfterContentInit(): void;
}
/**
* @description
* A lifecycle hook that is called after the default change detector has
* completed checking all content of a directive.
*
* @see `AfterViewChecked`
* @see [Lifecycle Hooks](guide/lifecycle-hooks#onchanges) guide
*
* @usageNotes
* The following snippet shows how a component can implement this interface to
* define its own after-check functionality.
*
* {@example core/ts/metadata/lifecycle_hooks_spec.ts region='AfterContentChecked'}
*
* @description
* Lifecycle hook that is called after every check of a directive's content.
*
* See ["Lifecycle Hooks Guide"](guide/lifecycle-hooks#aftercontent).
*
*
*/
export interface AfterContentChecked { ngAfterContentChecked(): void; }
export interface AfterContentChecked {
/**
* A callback method that is invoked immediately after the
* default change detector has completed checking all of the directive's
* content.
*/
ngAfterContentChecked(): void;
}
/**
* @description
* A lifecycle hook that is called after Angular has fully initialized
* a component's view.
* Define an `ngAfterViewInit()` method to handle any additional initialization tasks.
*
* @see `OnInit`
* @see `AfterContentInit`
* @see [Lifecycle Hooks](guide/lifecycle-hooks#onchanges) guide
*
* @usageNotes
* The following snippet shows how a component can implement this interface to
* define its own view initialization method.
*
* {@example core/ts/metadata/lifecycle_hooks_spec.ts region='AfterViewInit'}
*
* @description
* Lifecycle hook that is called after a component's view has been fully
* initialized.
*
* See ["Lifecycle Hooks Guide"](guide/lifecycle-hooks#afterview).
*
*
*/
export interface AfterViewInit { ngAfterViewInit(): void; }
export interface AfterViewInit {
/**
* A callback method that is invoked immediately after
* Angular has completed initialization of a component's view.
* It is invoked only once when the view is instantiated.
*
*/
ngAfterViewInit(): void;
}
/**
* @description
* A lifecycle hook that is called after the default change detector has
* completed checking a component's view for changes.
*
* @see `AfterContentChecked`
* @see [Lifecycle Hooks](guide/lifecycle-hooks#onchanges) guide
*
* @usageNotes
* The following snippet shows how a component can implement this interface to
* define its own after-check functionality.
*
* {@example core/ts/metadata/lifecycle_hooks_spec.ts region='AfterViewChecked'}
*
* @description
* Lifecycle hook that is called after every check of a component's view.
*
* See ["Lifecycle Hooks Guide"](guide/lifecycle-hooks#afterview).
*
*
*/
export interface AfterViewChecked { ngAfterViewChecked(): void; }
export interface AfterViewChecked {
/**
* A callback method that is invoked immediately after the
* default change detector has completed one change-check cycle
* for a component's view.
*/
ngAfterViewChecked(): void;
}

81
packages/core/src/metadata/ng_module.ts
View File

@ -136,9 +136,26 @@ export interface NgModule {
/**
* The set of injectable objects that are available in the injector
* of this module.
*
* @see [Dependency Injection guide](guide/dependency-injection)
* @see [NgModule guide](guide/providers)
*
* @usageNotes
*
* Dependencies whose providers are listed here become available for injection
* into any component, directive, pipe or service that is a child of this injector.
* The NgModule used for bootstrapping uses the root injector, and can provide dependencies
* to any part of the app.
*
* A lazy-loaded module has its own injector, typically a child of the app root injector.
* Lazy-loaded services are scoped to the lazy-loaded module's injector.
* If a lazy-loaded module also provides the `UserService`, any component created
* within that module's context (such as by router navigation) gets the local instance
* of the service, not the instance in the root injector.
* Components in external modules continue to receive the instance provided by their injectors.
*
* ### Example
*
* The following example defines a class that is injected in
* the HelloWorld NgModule:
*
@ -166,10 +183,20 @@ export interface NgModule {
providers?: Provider[];
/**
* The set of directives and pipes that belong to this module.
* The set of components, directives, and pipes ([declarables](guide/glossary#declarable))
* that belong to this module.
*
* @usageNotes
*
* The set of selectors that are available to a template include those declared here, and
* those that are exported from imported NgModules.
*
* Declarables must belong to exactly one module.
* The compiler emits an error if you try to declare the same class in more than one module.
* Be careful not to declare a class that is imported from another module.
*
* ### Example
*
* The following example allows the CommonModule to use the `NgFor`
* directive.
*
@ -184,13 +211,19 @@ export interface NgModule {
declarations?: Array<Type<any>|any[]>;
/**
* The set of NgModules, with or without providers,
* whose exported directives/pipes
* The set of NgModules whose exported directives and pipes
* are available to templates in this module.
*
* @usageNotes
*
* The following example allows MainModule to use CommonModule:
* A template can exported declarables from any
* imported module, including those that are imported indirectly.
* For example, `CommonModule` imports `BrowserModule`, make the
* `BrowserModule` exports available wherever `CommonModule` is imported.
*
* ### Example
*
* The following example allows MainModule to use `CommonModule`:
*
* ```javascript
* @NgModule({
@ -199,17 +232,31 @@ export interface NgModule {
* class MainModule {
* }
* ```
* @see {@link ModuleWithProviders}
*
*/
imports?: Array<Type<any>|ModuleWithProviders|any[]>;
/**
* The set of directives, pipe, and NgModules that can be used
* within the template of any component that is part of an
* NgModule that imports this NgModule.
* The set of components, directives, and pipes declared in this
* NgModule that can be used in the template of any component that is part of an
* NgModule that imports this NgModule. Exported declarations are the module's public API.
*
* @usageNotes
*
* Declarations are private by default. If this module does not export UserComponent,
* then only the components within this module can use UserComponent.
*
* Importing a module does not automatically re-export the imported module's imports.
* Module 'B' can't use `ngIf` just because it imported module 'A' which imported `CommonModule`.
* Module 'B' must import `CommonModule` itself.
*
* A module can list another module among its exports, in which case all of that module's
* public declaration are exported. Re-export makes module transitivity explicit.
* If Module 'A' re-exports `CommonModule` and Module 'B' imports Module 'A',
* then Module 'B' components can use `ngIf` even though 'B' itself did not import `CommonModule`.
*
* ### Example
*
* The following example exports the `NgFor` directive from CommonModule.
*
* ```javascript
@ -223,9 +270,18 @@ export interface NgModule {
exports?: Array<Type<any>|any[]>;
/**
* The set of components to compile when this NgModule is defined.
* The set of components to compile when this NgModule is defined,
* so that they can be dynamically loaded into the view.
*
* For each component listed here, Angular creates a `ComponentFactory`
* and stores it in the `ComponentFactoryResolver`.
*
* Angular automatically adds components in the module's bootstrap
* and route definitions into the `entryComponents` list. Use this
* option to add components that are bootstrapped
* using one of the imperative techniques, such as `ViewComponentRef.createComponent()`.
*
* @see [Entry Components](guide/entry-components)
*/
entryComponents?: Array<Type<any>|any[]>;
@ -285,5 +341,12 @@ export const NgModule: NgModuleDecorator = makeDecorator(
/**
* Decorator that marks the following class as an NgModule, and supplies
* configuration metadata for it.
*
* * The `declarations` and `entryComponents` options configure the compiler
* with information about what belongs to the NgModule.
* * The `providers` options configures the NgModule's injector to provide
* dependencies the NgModule members.
* * The `import` and `export` options bring in members from other modules, and make
* this module's members available to others.
*/
(type: Type<any>, meta: NgModule) => (R3_COMPILE_NGMODULE || preR3NgModuleCompile)(type, meta));