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

docs: api doc cleanup (#31377) 

PR Close #31377
This commit is contained in:
Judy Bogart 2019-07-01 12:31:42 -07:00 committed by Jason Aden
parent 35f8bfce8b
commit 40aaa42f44
18 changed files with 184 additions and 210 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
packages/core/src/change_detection/pipe_transform.ts
View File

@ -7,17 +7,15 @@
*/
/**
* To create a Pipe, you must implement this interface.
*
* An interface that is implemented by pipes in order to perform a transformation.
* Angular invokes the `transform` method with the value of a binding
* as the first argument, and any parameters as the second argument in list form.
*
* @usageNotes
* ### Example
*
* The `RepeatPipe` below repeats the value as many times as indicated by the first argument:
* In the following example, `RepeatPipe` repeats a given value a given number of times.
*
* ```
* ```ts
* import {Pipe, PipeTransform} from '@angular/core';
*
* @Pipe({name: 'repeat'})

5
packages/core/src/di/injectable.ts
View File

@ -31,7 +31,7 @@ export type InjectableProvider = ValueSansProvider | ExistingSansProvider |
*/
export interface InjectableDecorator {
/**
* Marks a class as available to `Injector` for creation.
* Decorator that marks a class as available to `Injector` for creation.
*
* @see [Introduction to Services and DI](guide/architecture-services)
* @see [Dependency Injection Guide](guide/dependency-injection)
@ -41,7 +41,8 @@ export interface InjectableDecorator {
* The following example shows how service classes are properly marked as
* injectable.
*
* <code-example path="core/di/ts/metadata_spec.ts" region="Injectable"></code-example>
* <code-example path="core/di/ts/metadata_spec.ts" region="Injectable"
* linenums="false"></code-example>
*
*/
(): TypeDecorator;

121
packages/core/src/di/interface/provider.ts
View File

@ -23,29 +23,28 @@ export interface ValueSansProvider {
/**
* Configures the `Injector` to return a value for a token.
*
* For more details, see the ["Dependency Injection Guide"](guide/dependency-injection).
* @see ["Dependency Injection Guide"](guide/dependency-injection).
*
* @usageNotes
*
* ### Example
*
* {@example core/di/ts/provider_spec.ts region='ValueProvider'}
* {@example core/di/ts/provider_spec.ts region='ValueProvider' linenums="false"}
*
* ### Multi-value example
*
* {@example core/di/ts/provider_spec.ts region='MultiProviderAspect'}
* {@example core/di/ts/provider_spec.ts region='MultiProviderAspect' linenums="false"}
*
* @publicApi
*/
export interface ValueProvider extends ValueSansProvider {
/**
* An injection token. (Typically an instance of `Type` or `InjectionToken`, but can be `any`).
* An injection token. Typically an instance of `Type` or `InjectionToken`, but can be `any`.
*/
provide: any;
/**
* If true, then injector returns an array of instances. This is useful to allow multiple
* When true, injector returns an array of instances. This is useful to allow multiple
* providers spread across many files to provide configuration information to a common token.
*/
multi?: boolean;
@ -59,13 +58,13 @@ export interface ValueProvider extends ValueSansProvider {
*/
export interface StaticClassSansProvider {
/**
* An optional class to instantiate for the `token`. (If not provided `provide` is assumed to be a
* class to instantiate)
* An optional class to instantiate for the `token`. By default, the `provide`
* class is instantiated.
*/
useClass: Type<any>;
/**
* A list of `token`s which need to be resolved by the injector. The list of values is then
* A list of `token`s to be resolved by the injector. The list of values is then
* used as arguments to the `useClass` constructor.
*/
deps: any[];
@ -73,33 +72,30 @@ export interface StaticClassSansProvider {
/**
* Configures the `Injector` to return an instance of `useClass` for a token.
*
* For more details, see the ["Dependency Injection Guide"](guide/dependency-injection).
* @see ["Dependency Injection Guide"](guide/dependency-injection).
*
* @usageNotes
*
* ### Example
*
* {@example core/di/ts/provider_spec.ts region='StaticClassProvider'}
*
* Note that following two providers are not equal:
*
* {@example core/di/ts/provider_spec.ts region='StaticClassProviderDifference'}
* {@example core/di/ts/provider_spec.ts region='StaticClassProviderDifference' linenums="false"}
*
* ### Multi-value example
*
* {@example core/di/ts/provider_spec.ts region='MultiProviderAspect'}
* {@example core/di/ts/provider_spec.ts region='MultiProviderAspect' linenums="false"}
*
* @publicApi
*/
export interface StaticClassProvider extends StaticClassSansProvider {
/**
* An injection token. (Typically an instance of `Type` or `InjectionToken`, but can be `any`).
* An injection token. Typically an instance of `Type` or `InjectionToken`, but can be `any`.
*/
provide: any;
/**
* If true, then injector returns an array of instances. This is useful to allow multiple
* When true, injector returns an array of instances. This is useful to allow multiple
* providers spread across many files to provide configuration information to a common token.
*/
multi?: boolean;
@ -108,13 +104,11 @@ export interface StaticClassProvider extends StaticClassSansProvider {
/**
* Configures the `Injector` to return an instance of a token.
*
* For more details, see the ["Dependency Injection Guide"](guide/dependency-injection).
* @see ["Dependency Injection Guide"](guide/dependency-injection).
*
* @usageNotes
*
* ### Example
*
* ```
* ```ts
* @Injectable(SomeModule, {deps: []})
* class MyService {}
* ```
@ -123,8 +117,7 @@ export interface StaticClassProvider extends StaticClassSansProvider {
*/
export interface ConstructorSansProvider {
/**
* A list of `token`s which need to be resolved by the injector. The list of values is then
* used as arguments to the `useClass` constructor.
* A list of `token`s to be resolved by the injector.
*/
deps?: any[];
}
@ -132,28 +125,26 @@ export interface ConstructorSansProvider {
/**
* Configures the `Injector` to return an instance of a token.
*
* For more details, see the ["Dependency Injection Guide"](guide/dependency-injection).
* @see ["Dependency Injection Guide"](guide/dependency-injection).
*
* @usageNotes
*
* ### Example
*
* {@example core/di/ts/provider_spec.ts region='ConstructorProvider'}
* {@example core/di/ts/provider_spec.ts region='ConstructorProvider' linenums="false"}
*
* ### Multi-value example
*
* {@example core/di/ts/provider_spec.ts region='MultiProviderAspect'}
* {@example core/di/ts/provider_spec.ts region='MultiProviderAspect' linenums="false"}
*
* @publicApi
*/
export interface ConstructorProvider extends ConstructorSansProvider {
/**
* An injection token. (Typically an instance of `Type` or `InjectionToken`, but can be `any`).
* An injection token. Typically an instance of `Type` or `InjectionToken`, but can be `any`.
*/
provide: Type<any>;
/**
* If true, then injector returns an array of instances. This is useful to allow multiple
* When true, injector returns an array of instances. This is useful to allow multiple
* providers spread across many files to provide configuration information to a common token.
*/
multi?: boolean;
@ -162,13 +153,14 @@ export interface ConstructorProvider extends ConstructorSansProvider {
/**
* Configures the `Injector` to return a value of another `useExisting` token.
*
* For more details, see the ["Dependency Injection Guide"](guide/dependency-injection).
* @see `ExistingProvider`
* @see ["Dependency Injection Guide"](guide/dependency-injection).
*
* @publicApi
*/
export interface ExistingSansProvider {
/**
* Existing `token` to return. (equivalent to `injector.get(useExisting)`)
* Existing `token` to return. (Equivalent to `injector.get(useExisting)`)
*/
useExisting: any;
}
@ -176,28 +168,26 @@ export interface ExistingSansProvider {
/**
* Configures the `Injector` to return a value of another `useExisting` token.
*
* For more details, see the ["Dependency Injection Guide"](guide/dependency-injection).
* @see ["Dependency Injection Guide"](guide/dependency-injection).
*
* @usageNotes
*
* ### Example
*
* {@example core/di/ts/provider_spec.ts region='ExistingProvider'}
* {@example core/di/ts/provider_spec.ts region='ExistingProvider' linenums="false"}
*
* ### Multi-value example
*
* {@example core/di/ts/provider_spec.ts region='MultiProviderAspect'}
* {@example core/di/ts/provider_spec.ts region='MultiProviderAspect' linenums="false"}
*
* @publicApi
*/
export interface ExistingProvider extends ExistingSansProvider {
/**
* An injection token. (Typically an instance of `Type` or `InjectionToken`, but can be `any`).
* An injection token. Typically an instance of `Type` or `InjectionToken`, but can be `any`.
*/
provide: any;
/**
* If true, then injector returns an array of instances. This is useful to allow multiple
* When true, injector returns an array of instances. This is useful to allow multiple
* providers spread across many files to provide configuration information to a common token.
*/
multi?: boolean;
@ -206,7 +196,8 @@ export interface ExistingProvider extends ExistingSansProvider {
/**
* Configures the `Injector` to return a value by invoking a `useFactory` function.
*
* For more details, see the ["Dependency Injection Guide"](guide/dependency-injection).
* @see `FactoryProvider`
* @see ["Dependency Injection Guide"](guide/dependency-injection).
*
* @publicApi
*/
@ -218,7 +209,7 @@ export interface FactorySansProvider {
useFactory: Function;
/**
* A list of `token`s which need to be resolved by the injector. The list of values is then
* A list of `token`s to be resolved by the injector. The list of values is then
* used as arguments to the `useFactory` function.
*/
deps?: any[];
@ -226,22 +217,19 @@ export interface FactorySansProvider {
/**
* Configures the `Injector` to return a value by invoking a `useFactory` function.
*
* For more details, see the ["Dependency Injection Guide"](guide/dependency-injection).
* @see ["Dependency Injection Guide"](guide/dependency-injection).
*
* @usageNotes
*
* ### Example
*
* {@example core/di/ts/provider_spec.ts region='FactoryProvider'}
* {@example core/di/ts/provider_spec.ts region='FactoryProvider' linenums="false"}
*
* Dependencies can also be marked as optional:
*
* {@example core/di/ts/provider_spec.ts region='FactoryProviderOptionalDeps'}
* {@example core/di/ts/provider_spec.ts region='FactoryProviderOptionalDeps' linenums="false"}
*
* ### Multi-value example
*
* {@example core/di/ts/provider_spec.ts region='MultiProviderAspect'}
* {@example core/di/ts/provider_spec.ts region='MultiProviderAspect' linenums="false"}
*
* @publicApi
*/
@ -252,20 +240,15 @@ export interface FactoryProvider extends FactorySansProvider {
provide: any;
/**
* If true, then injector returns an array of instances. This is useful to allow multiple
* When true, injector returns an array of instances. This is useful to allow multiple
* providers spread across many files to provide configuration information to a common token.
*/
multi?: boolean;
}
/**
* Describes how the `Injector` should be configured in a static way (Without reflection).
*
* For more details, see the ["Dependency Injection Guide"](guide/dependency-injection).
*
* @see `ValueProvider`
* @see `ExistingProvider`
* @see `FactoryProvider`
* Describes how the `Injector` should be configured as static (that is, without reflection).
* @see ["Dependency Injection Guide"](guide/dependency-injection).
*
* @publicApi
*/
@ -283,9 +266,7 @@ export type StaticProvider = ValueProvider | ExistingProvider | StaticClassProvi
*
* @usageNotes
*
* ### Example
*
* {@example core/di/ts/provider_spec.ts region='TypeProvider'}
* {@example core/di/ts/provider_spec.ts region='TypeProvider' linenums="false"}
*
* @publicApi
*/
@ -295,7 +276,7 @@ export interface TypeProvider extends Type<any> {}
* Configures the `Injector` to return a value by invoking a `useClass` function.
* Base for `ClassProvider` decorator.
*
* For more details, see the ["Dependency Injection Guide"](guide/dependency-injection).
* @see ["Dependency Injection Guide"](guide/dependency-injection).
*
* @publicApi
*/
@ -308,22 +289,19 @@ export interface ClassSansProvider {
/**
* Configures the `Injector` to return an instance of `useClass` for a token.
*
* For more details, see the ["Dependency Injection Guide"](guide/dependency-injection).
* @see ["Dependency Injection Guide"](guide/dependency-injection).
*
* @usageNotes
*
* ### Example
*
* {@example core/di/ts/provider_spec.ts region='ClassProvider'}
* {@example core/di/ts/provider_spec.ts region='ClassProvider' linenums="false"}
*
* Note that following two providers are not equal:
*
* {@example core/di/ts/provider_spec.ts region='ClassProviderDifference'}
* {@example core/di/ts/provider_spec.ts region='ClassProviderDifference' linenums="false"}
*
* ### Multi-value example
*
* {@example core/di/ts/provider_spec.ts region='MultiProviderAspect'}
* {@example core/di/ts/provider_spec.ts region='MultiProviderAspect' linenums="false"}
*
* @publicApi
*/
@ -334,7 +312,7 @@ export interface ClassProvider extends ClassSansProvider {
provide: any;
/**
* If true, then injector returns an array of instances. This is useful to allow multiple
* When true, injector returns an array of instances. This is useful to allow multiple
* providers spread across many files to provide configuration information to a common token.
*/
multi?: boolean;
@ -342,11 +320,8 @@ export interface ClassProvider extends ClassSansProvider {
/**
* Describes how the `Injector` should be configured.
* @see ["Dependency Injection Guide"](guide/dependency-injection).
*
* For more details, see the ["Dependency Injection Guide"](guide/dependency-injection).
*
* @see `TypeProvider`
* @see `ClassProvider`
* @see `StaticProvider`
*
* @publicApi
@ -355,7 +330,7 @@ export type Provider = TypeProvider | ValueProvider | ClassProvider | Constructo
ExistingProvider | FactoryProvider | any[];
/**
* Describes a function that is used to process provider list (for example in case of provider
* Describes a function that is used to process provider lists (such as provider
* overrides).
*/
export type ProcessProvidersFunction = (providers: Provider[]) => Provider[];

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

@ -17,7 +17,7 @@ import {makeParamDecorator} from '../util/decorators';
*/
export interface InjectDecorator {
/**
* A parameter decorator on a dependency parameter of a class constructor
* Parameter decorator on a dependency parameter of a class constructor
* that specifies a custom provider of the dependency.
*
* Learn more in the ["Dependency Injection Guide"](guide/dependency-injection).
@ -30,7 +30,7 @@ export interface InjectDecorator {
* parameter as the provider.
*
* <code-example path="core/di/ts/metadata_spec.ts"
* region="InjectWithoutDecorator"></code-example>
* region="InjectWithoutDecorator" linenums="false"></code-example>
*/
(token: any): any;
new (token: any): Inject;
@ -64,7 +64,7 @@ export const Inject: InjectDecorator = makeParamDecorator('Inject', (token: any)
*/
export interface OptionalDecorator {
/**
* A parameter decorator to be used on constructor parameters,
* Parameter decorator to be used on constructor parameters,
* which marks the parameter as being an optional dependency.
* The DI framework provides null if the dependency is not found.
*
@ -77,7 +77,8 @@ export interface OptionalDecorator {
*
* The following code allows the possibility of a null result:
*
* <code-example path="core/di/ts/metadata_spec.ts" region="Optional"></code-example>
* <code-example path="core/di/ts/metadata_spec.ts" region="Optional"
* linenums="false"></code-example>
*
*/
(): any;
@ -106,7 +107,7 @@ export const Optional: OptionalDecorator = makeParamDecorator('Optional');
*/
export interface SelfDecorator {
/**
* A parameter decorator to be used on constructor parameters,
* Parameter decorator to be used on constructor parameters,
* which tells the DI framework to start dependency resolution from the local injector.
*
* Resolution works upward through the injector hierarchy, so the children
@ -118,8 +119,9 @@ export interface SelfDecorator {
* by the local injector when instantiating the class itself, but not
* when instantiating a child.
*
* <code-example path="core/di/ts/metadata_spec.ts" region="Self"></code-example>
*
* <code-example path="core/di/ts/metadata_spec.ts" region="Self"
* linenums="false"></code-example>
*
*
* @see `SkipSelf`
* @see `Optional`
@ -152,7 +154,7 @@ export const Self: SelfDecorator = makeParamDecorator('Self');
*/
export interface SkipSelfDecorator {
/**
* A parameter decorator to be used on constructor parameters,
* Parameter decorator to be used on constructor parameters,
* which tells the DI framework to start dependency resolution from the parent injector.
* Resolution works upward through the injector hierarchy, so the local injector
* is not checked for a provider.
@ -162,7 +164,8 @@ export interface SkipSelfDecorator {
* In the following example, the dependency can be resolved when
* instantiating a child, but not when instantiating the class itself.
*
* <code-example path="core/di/ts/metadata_spec.ts" region="SkipSelf"></code-example>
* <code-example path="core/di/ts/metadata_spec.ts" region="SkipSelf"
* linenums="false"></code-example>
*
* Learn more in the
* [Dependency Injection guide](guide/dependency-injection-in-action#skip).
@ -197,7 +200,7 @@ export const SkipSelf: SkipSelfDecorator = makeParamDecorator('SkipSelf');
*/
export interface HostDecorator {
/**
* A parameter decorator on a view-provider parameter of a class constructor
* Parameter decorator on a view-provider parameter of a class constructor
* that tells the DI framework to resolve the view by checking injectors of child
* elements, and stop when reaching the host element of the current component.
*
@ -208,7 +211,8 @@ export interface HostDecorator {
*
* The following shows use with the `@Optional` decorator, and allows for a null result.
*
* <code-example path="core/di/ts/metadata_spec.ts" region="Host"></code-example>
* <code-example path="core/di/ts/metadata_spec.ts" region="Host"
* linenums="false"></code-example>
*/
(): any;
new (): Host;
@ -237,7 +241,7 @@ export const Host: HostDecorator = makeParamDecorator('Host');
*/
export interface AttributeDecorator {
/**
* A parameter decorator for a directive constructor that designates
* Parameter decorator for a directive constructor that designates
* a host-element attribute whose value is injected as a constant string literal.
*
* @usageNotes
@ -250,11 +254,11 @@ export interface AttributeDecorator {
*
* The following example uses the decorator to inject the string literal `text`.
*
* {@example core/ts/metadata/metadata.ts region='attributeMetadata'}
* {@example core/ts/metadata/metadata.ts region='attributeMetadata' linenums="false"}
*
* ### Example as TypeScript Decorator
*
* {@example core/ts/metadata/metadata.ts region='attributeFactory'}
* {@example core/ts/metadata/metadata.ts region='attributeFactory' linenums="false"}
*
*/
(name: string): any;

11
packages/core/src/event_emitter.ts
View File

@ -21,7 +21,7 @@ import {Subject, Subscription} from 'rxjs';
* that create event emitters. When the title is clicked, the emitter
* emits an open or close event to toggle the current visibility state.
*
* ```
* ```html
* @Component({
* selector: 'zippy',
* template: `
@ -50,17 +50,10 @@ import {Subject, Subscription} from 'rxjs';
* Access the event object with the `$event` argument passed to the output event
* handler:
*
* ```
* ```html
* <zippy (open)="onOpen($event)" (close)="onClose($event)"></zippy>
* ```
*
* ### Notes
*
* Uses Rx.Observable but provides an adapter to make it work as specified here:
* https://github.com/jhusain/observable-spec
*
* Once a reference implementation of the spec is available, switch to it.
*
* @publicApi
*/
export class EventEmitter<T> extends Subject<T> {

10
packages/core/src/linker/component_factory.ts
View File

@ -49,7 +49,7 @@ export abstract class ComponentRef<C> {
abstract get changeDetectorRef(): ChangeDetectorRef;
/**
* The component type.
* The type of this component (as created by a `ComponentFactory` class).
*/
abstract get componentType(): Type<any>;
@ -68,6 +68,12 @@ export abstract class ComponentRef<C> {
}
/**
* Base class for a factory that can create a component dynamically.
* Instantiate a factory for a given type of component with `resolveComponentFactory()`.
* Use the resulting `ComponentFactory.create()` method to create a component of that type.
*
* @see [Dynamic Components](guide/dynamic-component-loader)
*
* @publicApi
*/
export abstract class ComponentFactory<C> {
@ -76,7 +82,7 @@ export abstract class ComponentFactory<C> {
*/
abstract get selector(): string;
/**
* The component's type
* The type of component the factory will create.
*/
abstract get componentType(): Type<any>;
/**

10
packages/core/src/linker/component_factory_resolver.ts
View File

@ -34,10 +34,20 @@ class _NullComponentFactoryResolver implements ComponentFactoryResolver {
}
/**
* A simple registry that maps `Components` to generated `ComponentFactory` classes
* that can be used to create instances of components.
* Use to obtain the factory for a given component type,
* then use the factory's `create()` method to create a component of that type.
*
* @see [Dynamic Components](guide/dynamic-component-loader)
* @publicApi
*/
export abstract class ComponentFactoryResolver {
static NULL: ComponentFactoryResolver = new _NullComponentFactoryResolver();
/**
* Retrieves the factory object that creates a component of the given type.
* @param component The component type.
*/
abstract resolveComponentFactory<T>(component: Type<T>): ComponentFactory<T>;
}

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

@ -60,7 +60,6 @@ export interface AttributeDecorator {
* The directive can inject constant string literals of host element attributes.
*
* @usageNotes
* ### Example
*
* Suppose we have an `<input>` element and want to know its `type`.
*
@ -70,7 +69,8 @@ export interface AttributeDecorator {
*
* A decorator can inject string literal `text` as in the following example.
*
* {@example core/ts/metadata/metadata.ts region='attributeMetadata'}
* {@example core/ts/metadata/metadata.ts region='attributeMetadata'
* linenums="false"}
*
* @publicApi
*/
@ -125,33 +125,34 @@ export abstract class Query {}
*/
export interface ContentChildrenDecorator {
/**
* Configures a content query.
* Parameter decorator that configures a content query.
*
* You can use ContentChildren to get the `QueryList` of elements or directives from the
* content DOM. Any time a child element is added, removed, or moved, the query list will be
* Use to get the `QueryList` of elements or directives from the content DOM.
* Any time a child element is added, removed, or moved, the query list will be
* updated, and the changes observable of the query list will emit a new value.
*
* Content queries are set before the `ngAfterContentInit` callback is called.
*
* **Metadata Properties**:
*
* * **selector** - the directive type or the name used for querying.
* * **descendants** - include only direct children or all descendants.
* * **read** - read a different token from the queried elements.
* * **selector** - The directive type or the name used for querying.
* * **descendants** - True to include all descendants, otherwise include only direct children.
* * **read** - True to read a different token from the queried elements.
*
* @usageNotes
* ### Basic Example
*
* Here is a simple demonstration of how the `ContentChildren` decorator can be used.
*
* {@example core/di/ts/contentChildren/content_children_howto.ts region='HowTo'}
* {@example core/di/ts/contentChildren/content_children_howto.ts region='HowTo'
* linenums="false"}
*
* ### Tab-pane Example
* ### Tab-pane example
*
* Here is a slightly more realistic example that shows how `ContentChildren` decorators
* can be used to implement a tab pane component.
*
* {@example core/di/ts/contentChildren/content_children_example.ts region='Component'}
* {@example core/di/ts/contentChildren/content_children_example.ts region='Component'
* linenums="false"}
*
* @Annotation
*/
@ -188,33 +189,35 @@ export const ContentChildren: ContentChildrenDecorator = makePropDecorator(
*/
export interface ContentChildDecorator {
/**
* Configures a content query.
* Parameter decorator that configures a content query.
*
* You can use ContentChild to get the first element or the directive matching the selector from
* the content DOM. If the content DOM changes, and a new child matches the selector,
* Use to get the first element or the directive matching the selector from the content DOM.
* If the content DOM changes, and a new child matches the selector,
* the property will be updated.
*
* Content queries are set before the `ngAfterContentInit` callback is called.
*
* **Metadata Properties**:
*
* * **selector** - the directive type or the name used for querying.
* * **read** - read a different token from the queried element.
* * **static** - whether or not to resolve query results before change detection runs (i.e.
* return static results only). If this option is not provided, the compiler will fall back
* to its default behavior, which is to use query results to determine the timing of query
* resolution. If any query results are inside a nested view (e.g. *ngIf), the query will be
* resolved after change detection runs. Otherwise, it will be resolved before change detection
* * **selector** - The directive type or the name used for querying.
* * **read** - True to read a different token from the queried element.
* * **static** - True to resolve query results before change detection runs,
* false to resolve after change detection.
*
* When `static` is not provided, uses the query results to determine the timing of query
* resolution. If any query results are inside a nested view (such as `*ngIf`), the query is
* resolved after change detection runs. Otherwise, it is resolved before change detection
* runs.
*
* @usageNotes
* ### Example
*
* {@example core/di/ts/contentChild/content_child_howto.ts region='HowTo'}
* {@example core/di/ts/contentChild/content_child_howto.ts region='HowTo'
* linenums="false"}
*
* ### Example
*
* {@example core/di/ts/contentChild/content_child_example.ts region='Component'}
* {@example core/di/ts/contentChild/content_child_example.ts region='Component'
* linenums="false"}
*
* @Annotation
*/
@ -251,28 +254,28 @@ export const ContentChild: ContentChildDecorator = makePropDecorator(
*/
export interface ViewChildrenDecorator {
/**
* Configures a view query.
* Parameter decorator that configures a view query.
*
* You can use ViewChildren to get the `QueryList` of elements or directives from the
* view DOM. Any time a child element is added, removed, or moved, the query list will be updated,
* Use to get the `QueryList` of elements or directives from the view DOM.
* Any time a child element is added, removed, or moved, the query list will be updated,
* and the changes observable of the query list will emit a new value.
*
* View queries are set before the `ngAfterViewInit` callback is called.
*
* **Metadata Properties**:
*
* * **selector** - the directive type or the name used for querying.
* * **read** - read a different token from the queried elements.
* * **selector** - The directive type or the name used for querying.
* * **read** - True to read a different token from the queried elements.
*
* @usageNotes
*
* ### Example
* {@example core/di/ts/viewChildren/view_children_howto.ts region='HowTo'
* linenums="false"}
*
* {@example core/di/ts/viewChildren/view_children_howto.ts region='HowTo'}
* ### Another example
*
* ### Example
*
* {@example core/di/ts/viewChildren/view_children_example.ts region='Component'}
* {@example core/di/ts/viewChildren/view_children_example.ts region='Component'
* linenums="false"}
*
* @Annotation
*/
@ -316,37 +319,40 @@ export interface ViewChildDecorator {
*
* **Metadata Properties**:
*
* * **selector** - the directive type or the name used for querying.
* * **read** - read a different token from the queried elements.
* * **static** - whether or not to resolve query results before change detection runs (i.e.
* return static results only). If this option is not provided, the compiler will fall back
* to its default behavior, which is to use query results to determine the timing of query
* resolution. If any query results are inside a nested view (e.g. *ngIf), the query will be
* resolved after change detection runs. Otherwise, it will be resolved before change detection
* * **selector** - The directive type or the name used for querying.
* * **read** - True to read a different token from the queried elements.
* * **static** - True to resolve query results before change detection runs
*
* When `static` is not provided, uses query results to determine the timing of query
* resolution. If any query results are inside a nested view (such as `*ngIf`), the query is
* resolved after change detection runs. Otherwise, it is resolved before change detection
* runs.
*
* Supported selectors include:
* * any class with the `@Component` or `@Directive` decorator
* * a template reference variable as a string (e.g. query `<my-component #cmp></my-component>`
* The following selectors are supported.
* * Any class with the `@Component` or `@Directive` decorator
* * A template reference variable as a string (e.g. query `<my-component #cmp></my-component>`
* with `@ViewChild('cmp')`)
* * any provider defined in the child component tree of the current component (e.g.
* * Any provider defined in the child component tree of the current component (e.g.
* `@ViewChild(SomeService) someService: SomeService`)
* * any provider defined through a string token (e.g. `@ViewChild('someToken') someTokenVal:
* * Any provider defined through a string token (e.g. `@ViewChild('someToken') someTokenVal:
* any`)
* * a `TemplateRef` (e.g. query `<ng-template></ng-template>` with `@ViewChild(TemplateRef)
* * A `TemplateRef` (e.g. query `<ng-template></ng-template>` with `@ViewChild(TemplateRef)
* template;`)
*
* @usageNotes
*
* {@example core/di/ts/viewChild/view_child_example.ts region='Component'}
* {@example core/di/ts/viewChild/view_child_example.ts region='Component'
* linenums="false"}
*
* ### Example
* ### Example 2
*
* {@example core/di/ts/viewChild/view_child_howto.ts region='HowTo'}
* {@example core/di/ts/viewChild/view_child_howto.ts region='HowTo'
* linenums="false"}
*
* ### Example
* ### Example 3
*
* {@example core/di/ts/viewChild/view_child_example.ts region='Component'}
* {@example core/di/ts/viewChild/view_child_example.ts region='Component'
* linenums="false"}
*
* @Annotation
*/

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

@ -24,8 +24,9 @@ import {ViewEncapsulation} from './view';
*/
export interface DirectiveDecorator {
/**
* Marks a class as an Angular directive. You can define your own
* directives to attach custom behavior to elements in the DOM.
* Decorator that 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.
@ -37,7 +38,7 @@ export interface DirectiveDecorator {
* @usageNotes
* To define a directive, mark the class with the decorator and provide metadata.
*
* ```
* ```ts
* import {Directive} from '@angular/core';
*
* @Directive({
@ -58,7 +59,7 @@ export interface DirectiveDecorator {
* a directive imported from another module.
* List the directive class in the `declarations` field of an NgModule.
*
* ```
* ```ts
* declarations: [
* AppComponent,
* MyDirective
@ -122,9 +123,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
* @usageNotes
*
* The following example creates a component with two data-bound properties.
*
@ -160,8 +160,6 @@ export interface Directive {
*
* @usageNotes
*
* ### Example
*
* ```typescript
* @Component({
* selector: 'child-dir',
@ -202,9 +200,7 @@ export interface Directive {
*
* @usageNotes
*
* ### Simple Example
*
* ```
* ```ts
* @Directive({
* selector: 'child-dir',
* exportAs: 'child'
@ -231,12 +227,10 @@ export interface Directive {
*
* @usageNotes
*
* ### Example
*
* The following example shows how queries are defined
* and when their results are available in lifecycle hooks:
*
* ```
* ```ts
* @Component({
* selector: 'someDir',
* queries: {
@ -338,7 +332,8 @@ export interface ComponentDecorator {
* The following example creates a component with two data-bound properties,
* specified by the `inputs` value.
*
* <code-example path="core/ts/metadata/directives.ts" region="component-input">
* <code-example path="core/ts/metadata/directives.ts" region="component-input"
* linenums="false">
* </code-example>
*
*
@ -347,14 +342,15 @@ export interface ComponentDecorator {
* The following example shows two event emitters that emit on an interval. One
* emits an output every second, while the other emits every five seconds.
*
* {@example core/ts/metadata/directives.ts region='component-output-interval'}
* {@example core/ts/metadata/directives.ts region='component-output-interval
* linenums="false"}
*
* ### Injecting a class with a view provider
*
* The following simple example injects a class into a component
* using the view provider specified in component metadata:
*
* ```
* ```ts
* class Greeter {
* greet(name:string) {
* return 'Hello ' + name + '!';
@ -395,13 +391,13 @@ export interface ComponentDecorator {
* * Trims all whitespaces at the beginning and the end of a template.
* * Removes whitespace-only text nodes. For example,
*
* ```
* ```html
* <button>Action 1</button> <button>Action 2</button>
* ```
*
* becomes:
*
* ```
* ```html
* <button>Action 1</button><button>Action 2</button>
* ```
*
@ -844,9 +840,10 @@ export interface HostListener {
}
/**
* Binds a DOM event to a host listener and supplies configuration metadata.
* Decorator that binds a DOM event to a host listener and supplies configuration metadata.
* Angular invokes the supplied handler method when the host element emits the specified event,
* and updates the bound element with the result.
*
* If the handler method returns false, applies `preventDefault` on the bound element.
*
* @usageNotes
@ -854,7 +851,7 @@ export interface HostListener {
* The following example declares a directive
* that attaches a click listener to a button and counts clicks.
*
* ```
* ```ts
* @Directive({selector: 'button[counting]'})
* class CountClicks {
* numberOfClicks = 0;

9
packages/core/src/util/decorators.ts
View File

@ -9,11 +9,8 @@
import {Type} from '../interface/type';
/**
* An interface implemented by all Angular type decorators, which allows them to be used as ES7
* decorators as well as
* Angular DSL syntax.
*
* ES7 syntax:
* An interface implemented by all Angular type decorators, which allows them to be used as
* decorators as well as Angular syntax.
*
* ```
* @ng.Component({...})
@ -24,7 +21,7 @@ import {Type} from '../interface/type';
*/
export interface TypeDecorator {
/**
* Invoke as ES7 decorator.
* Invoke as decorator.
*/
<T extends Type<any>>(type: T): T;

6
packages/examples/core/di/ts/contentChild/content_child_example.ts
View File

@ -11,18 +11,16 @@ import {Component, ContentChild, Directive, Input} from '@angular/core';
@Directive({selector: 'pane'})
export class Pane {
// TODO(issue/24571): remove '!'.
@Input() id !: string;
}
@Component({
selector: 'tab',
template: `
<div>pane: {{pane?.id}}</div>
<div>pane: {{pane?.id}}</div>
`
})
export class Tab {
// TODO(issue/24571): remove '!'.
@ContentChild(Pane, {static: false}) pane !: Pane;
}
@ -33,7 +31,7 @@ export class Tab {
<pane id="1" *ngIf="shouldShow"></pane>
<pane id="2" *ngIf="!shouldShow"></pane>
</tab>
<button (click)="toggle()">Toggle</button>
`,
})

5
packages/examples/core/di/ts/contentChildren/content_children_example.ts
View File

@ -11,14 +11,13 @@ import {Component, ContentChildren, Directive, Input, QueryList} from '@angular/
@Directive({selector: 'pane'})
export class Pane {
// TODO(issue/24571): remove '!'.
@Input() id !: string;
}
@Component({
selector: 'tab',
template: `
<div class="top-level">Top level panes: {{serializedPanes}}</div>
<div class="top-level">Top level panes: {{serializedPanes}}</div>
<div class="nested">Arbitrary nested panes: {{serializedNestedPanes}}</div>
`
})
@ -47,7 +46,7 @@ export class Tab {
</tab>
</pane>
</tab>
<button (click)="show()">Show 3</button>
`,
})

1
packages/examples/core/di/ts/contentChildren/content_children_howto.ts
View File

@ -15,7 +15,6 @@ class ChildDirective {
@Directive({selector: 'someDir'})
class SomeDir implements AfterContentInit {
// TODO(issue/24571): remove '!'.
@ContentChildren(ChildDirective) contentChildren !: QueryList<ChildDirective>;
ngAfterContentInit() {

8
packages/examples/core/di/ts/provider_spec.ts
View File

@ -55,9 +55,7 @@ import {Injectable, InjectionToken, Injector, Optional, ReflectiveInjector} from
describe('ClassProvider', () => {
it('works', () => {
// #docregion ClassProvider
abstract class Shape { // TODO(issue/24571): remove '!'.
name !: string;
}
abstract class Shape { name !: string; }
class Square extends Shape {
name = 'square';
@ -94,9 +92,7 @@ import {Injectable, InjectionToken, Injector, Optional, ReflectiveInjector} from
describe('StaticClassProvider', () => {
it('works', () => {
// #docregion StaticClassProvider
abstract class Shape { // TODO(issue/24571): remove '!'.
name !: string;
}
abstract class Shape { name !: string; }
class Square extends Shape {
name = 'square';

7
packages/examples/core/di/ts/viewChild/view_child_example.ts
View File

@ -11,7 +11,6 @@ import {Component, Directive, Input, ViewChild} from '@angular/core';
@Directive({selector: 'pane'})
export class Pane {
// TODO(issue/24571): remove '!'.
@Input() id !: string;
}
@ -20,10 +19,10 @@ export class Pane {
template: `
<pane id="1" *ngIf="shouldShow"></pane>
<pane id="2" *ngIf="!shouldShow"></pane>
<button (click)="toggle()">Toggle</button>
<div>Selected: {{selectedPane}}</div>
<div>Selected: {{selectedPane}}</div>
`,
})
export class ViewChildComp {

1
packages/examples/core/di/ts/viewChild/view_child_howto.ts
View File

@ -15,7 +15,6 @@ class ChildDirective {
@Component({selector: 'someCmp', templateUrl: 'someCmp.html'})
class SomeCmp implements AfterViewInit {
// TODO(issue/24571): remove '!'.
@ViewChild(ChildDirective, {static: false}) child !: ChildDirective;
ngAfterViewInit() {

8
packages/examples/core/di/ts/viewChildren/view_children_example.ts
View File

@ -11,7 +11,6 @@ import {AfterViewInit, Component, Directive, Input, QueryList, ViewChildren} fro
@Directive({selector: 'pane'})
export class Pane {
// TODO(issue/24571): remove '!'.
@Input() id !: string;
}
@ -21,14 +20,13 @@ export class Pane {
<pane id="1"></pane>
<pane id="2"></pane>
<pane id="3" *ngIf="shouldShow"></pane>
<button (click)="show()">Show 3</button>
<div>panes: {{serializedPanes}}</div>
<div>panes: {{serializedPanes}}</div>
`,
})
export class ViewChildrenComp implements AfterViewInit {
// TODO(issue/24571): remove '!'.
@ViewChildren(Pane) panes !: QueryList<Pane>;
serializedPanes: string = '';

1
packages/examples/core/di/ts/viewChildren/view_children_howto.ts
View File

@ -15,7 +15,6 @@ class ChildDirective {
@Component({selector: 'someCmp', templateUrl: 'someCmp.html'})
class SomeCmp implements AfterViewInit {
// TODO(issue/24571): remove '!'.
@ViewChildren(ChildDirective) viewChildren !: QueryList<ChildDirective>;
ngAfterViewInit() {