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 * 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. * as the first argument, and any parameters as the second argument in list form.
* *
* @usageNotes * @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'; * import {Pipe, PipeTransform} from '@angular/core';
* *
* @Pipe({name: 'repeat'}) * @Pipe({name: 'repeat'})

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

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

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

@ -17,7 +17,7 @@ import {makeParamDecorator} from '../util/decorators';
*/ */
export interface InjectDecorator { 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. * that specifies a custom provider of the dependency.
* *
* Learn more in the ["Dependency Injection Guide"](guide/dependency-injection). * Learn more in the ["Dependency Injection Guide"](guide/dependency-injection).
@ -30,7 +30,7 @@ export interface InjectDecorator {
* parameter as the provider. * parameter as the provider.
* *
* <code-example path="core/di/ts/metadata_spec.ts" * <code-example path="core/di/ts/metadata_spec.ts"
* region="InjectWithoutDecorator"></code-example> * region="InjectWithoutDecorator" linenums="false"></code-example>
*/ */
(token: any): any; (token: any): any;
new (token: any): Inject; new (token: any): Inject;
@ -64,7 +64,7 @@ export const Inject: InjectDecorator = makeParamDecorator('Inject', (token: any)
*/ */
export interface OptionalDecorator { 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. * which marks the parameter as being an optional dependency.
* The DI framework provides null if the dependency is not found. * 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: * 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; (): any;
@ -106,7 +107,7 @@ export const Optional: OptionalDecorator = makeParamDecorator('Optional');
*/ */
export interface SelfDecorator { 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. * which tells the DI framework to start dependency resolution from the local injector.
* *
* Resolution works upward through the injector hierarchy, so the children * Resolution works upward through the injector hierarchy, so the children
@ -118,7 +119,8 @@ export interface SelfDecorator {
* by the local injector when instantiating the class itself, but not * by the local injector when instantiating the class itself, but not
* when instantiating a child. * 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 `SkipSelf`
@ -152,7 +154,7 @@ export const Self: SelfDecorator = makeParamDecorator('Self');
*/ */
export interface SkipSelfDecorator { 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. * which tells the DI framework to start dependency resolution from the parent injector.
* Resolution works upward through the injector hierarchy, so the local injector * Resolution works upward through the injector hierarchy, so the local injector
* is not checked for a provider. * is not checked for a provider.
@ -162,7 +164,8 @@ export interface SkipSelfDecorator {
* In the following example, the dependency can be resolved when * In the following example, the dependency can be resolved when
* instantiating a child, but not when instantiating the class itself. * 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 * Learn more in the
* [Dependency Injection guide](guide/dependency-injection-in-action#skip). * [Dependency Injection guide](guide/dependency-injection-in-action#skip).
@ -197,7 +200,7 @@ export const SkipSelf: SkipSelfDecorator = makeParamDecorator('SkipSelf');
*/ */
export interface HostDecorator { 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 * 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. * 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. * 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; (): any;
new (): Host; new (): Host;
@ -237,7 +241,7 @@ export const Host: HostDecorator = makeParamDecorator('Host');
*/ */
export interface AttributeDecorator { 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. * a host-element attribute whose value is injected as a constant string literal.
* *
* @usageNotes * @usageNotes
@ -250,11 +254,11 @@ export interface AttributeDecorator {
* *
* The following example uses the decorator to inject the string literal `text`. * 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 as TypeScript Decorator
* *
* {@example core/ts/metadata/metadata.ts region='attributeFactory'} * {@example core/ts/metadata/metadata.ts region='attributeFactory' linenums="false"}
* *
*/ */
(name: string): any; (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 * that create event emitters. When the title is clicked, the emitter
* emits an open or close event to toggle the current visibility state. * emits an open or close event to toggle the current visibility state.
* *
* ``` * ```html
* @Component({ * @Component({
* selector: 'zippy', * selector: 'zippy',
* template: ` * template: `
@ -50,17 +50,10 @@ import {Subject, Subscription} from 'rxjs';
* Access the event object with the `$event` argument passed to the output event * Access the event object with the `$event` argument passed to the output event
* handler: * handler:
* *
* ``` * ```html
* <zippy (open)="onOpen($event)" (close)="onClose($event)"></zippy> * <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 * @publicApi
*/ */
export class EventEmitter<T> extends Subject<T> { 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; abstract get changeDetectorRef(): ChangeDetectorRef;
/** /**
* The component type. * The type of this component (as created by a `ComponentFactory` class).
*/ */
abstract get componentType(): Type<any>; 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 * @publicApi
*/ */
export abstract class ComponentFactory<C> { export abstract class ComponentFactory<C> {
@ -76,7 +82,7 @@ export abstract class ComponentFactory<C> {
*/ */
abstract get selector(): string; abstract get selector(): string;
/** /**
* The component's type * The type of component the factory will create.
*/ */
abstract get componentType(): Type<any>; 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 * @publicApi
*/ */
export abstract class ComponentFactoryResolver { export abstract class ComponentFactoryResolver {
static NULL: ComponentFactoryResolver = new _NullComponentFactoryResolver(); 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>; 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. * The directive can inject constant string literals of host element attributes.
* *
* @usageNotes * @usageNotes
* ### Example
* *
* Suppose we have an `<input>` element and want to know its `type`. * 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. * 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 * @publicApi
*/ */
@ -125,33 +125,34 @@ export abstract class Query {}
*/ */
export interface ContentChildrenDecorator { 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 * Use to get the `QueryList` of elements or directives from the content DOM.
* content DOM. Any time a child element is added, removed, or moved, the query list will be * 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. * updated, and the changes observable of the query list will emit a new value.
* *
* Content queries are set before the `ngAfterContentInit` callback is called. * Content queries are set before the `ngAfterContentInit` callback is called.
* *
* **Metadata Properties**: * **Metadata Properties**:
* *
* * **selector** - the directive type or the name used for querying. * * **selector** - The directive type or the name used for querying.
* * **descendants** - include only direct children or all descendants. * * **descendants** - True to include all descendants, otherwise include only direct children.
* * **read** - read a different token from the queried elements. * * **read** - True to read a different token from the queried elements.
* *
* @usageNotes * @usageNotes
* ### Basic Example
* *
* Here is a simple demonstration of how the `ContentChildren` decorator can be used. * 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 * Here is a slightly more realistic example that shows how `ContentChildren` decorators
* can be used to implement a tab pane component. * 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 * @Annotation
*/ */
@ -188,33 +189,35 @@ export const ContentChildren: ContentChildrenDecorator = makePropDecorator(
*/ */
export interface ContentChildDecorator { 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 * Use to get the first element or the directive matching the selector from the content DOM.
* the content DOM. If the content DOM changes, and a new child matches the selector, * If the content DOM changes, and a new child matches the selector,
* the property will be updated. * the property will be updated.
* *
* Content queries are set before the `ngAfterContentInit` callback is called. * Content queries are set before the `ngAfterContentInit` callback is called.
* *
* **Metadata Properties**: * **Metadata Properties**:
* *
* * **selector** - the directive type or the name used for querying. * * **selector** - The directive type or the name used for querying.
* * **read** - read a different token from the queried element. * * **read** - True to read a different token from the queried element.
* * **static** - whether or not to resolve query results before change detection runs (i.e. * * **static** - True to resolve query results before change detection runs,
* return static results only). If this option is not provided, the compiler will fall back * false to resolve after change detection.
* 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 * When `static` is not provided, uses the query results to determine the timing of query
* resolved after change detection runs. Otherwise, it will be resolved before change detection * 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. * runs.
* *
* @usageNotes * @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
* *
* {@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 * @Annotation
*/ */
@ -251,28 +254,28 @@ export const ContentChild: ContentChildDecorator = makePropDecorator(
*/ */
export interface ViewChildrenDecorator { 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 * Use to get the `QueryList` of elements or directives from the view DOM.
* view DOM. Any time a child element is added, removed, or moved, the query list will be updated, * 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. * and the changes observable of the query list will emit a new value.
* *
* View queries are set before the `ngAfterViewInit` callback is called. * View queries are set before the `ngAfterViewInit` callback is called.
* *
* **Metadata Properties**: * **Metadata Properties**:
* *
* * **selector** - the directive type or the name used for querying. * * **selector** - The directive type or the name used for querying.
* * **read** - read a different token from the queried elements. * * **read** - True to read a different token from the queried elements.
* *
* @usageNotes * @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'
* * linenums="false"}
* {@example core/di/ts/viewChildren/view_children_example.ts region='Component'}
* *
* @Annotation * @Annotation
*/ */
@ -316,37 +319,40 @@ export interface ViewChildDecorator {
* *
* **Metadata Properties**: * **Metadata Properties**:
* *
* * **selector** - the directive type or the name used for querying. * * **selector** - The directive type or the name used for querying.
* * **read** - read a different token from the queried elements. * * **read** - True to read a different token from the queried elements.
* * **static** - whether or not to resolve query results before change detection runs (i.e. * * **static** - True to resolve query results before change detection runs
* 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 * When `static` is not provided, uses 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 * resolution. If any query results are inside a nested view (such as `*ngIf`), the query is
* resolved after change detection runs. Otherwise, it will be resolved before change detection * resolved after change detection runs. Otherwise, it is resolved before change detection
* runs. * runs.
* *
* Supported selectors include: * The following selectors are supported.
* * any class with the `@Component` or `@Directive` decorator * * Any class with the `@Component` or `@Directive` decorator
* * a template reference variable as a string (e.g. query `<my-component #cmp></my-component>` * * A template reference variable as a string (e.g. query `<my-component #cmp></my-component>`
* with `@ViewChild('cmp')`) * 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`) * `@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`) * 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;`) * template;`)
* *
* @usageNotes * @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 * @Annotation
*/ */

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

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

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

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

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

@ -11,7 +11,6 @@ import {Component, ContentChild, Directive, Input} from '@angular/core';
@Directive({selector: 'pane'}) @Directive({selector: 'pane'})
export class Pane { export class Pane {
// TODO(issue/24571): remove '!'.
@Input() id !: string; @Input() id !: string;
} }
@ -22,7 +21,6 @@ export class Pane {
` `
}) })
export class Tab { export class Tab {
// TODO(issue/24571): remove '!'.
@ContentChild(Pane, {static: false}) pane !: Pane; @ContentChild(Pane, {static: false}) pane !: Pane;
} }

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

@ -11,7 +11,6 @@ import {Component, ContentChildren, Directive, Input, QueryList} from '@angular/
@Directive({selector: 'pane'}) @Directive({selector: 'pane'})
export class Pane { export class Pane {
// TODO(issue/24571): remove '!'.
@Input() id !: string; @Input() id !: string;
} }

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

@ -15,7 +15,6 @@ class ChildDirective {
@Directive({selector: 'someDir'}) @Directive({selector: 'someDir'})
class SomeDir implements AfterContentInit { class SomeDir implements AfterContentInit {
// TODO(issue/24571): remove '!'.
@ContentChildren(ChildDirective) contentChildren !: QueryList<ChildDirective>; @ContentChildren(ChildDirective) contentChildren !: QueryList<ChildDirective>;
ngAfterContentInit() { 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', () => { describe('ClassProvider', () => {
it('works', () => { it('works', () => {
// #docregion ClassProvider // #docregion ClassProvider
abstract class Shape { // TODO(issue/24571): remove '!'. abstract class Shape { name !: string; }
name !: string;
}
class Square extends Shape { class Square extends Shape {
name = 'square'; name = 'square';
@ -94,9 +92,7 @@ import {Injectable, InjectionToken, Injector, Optional, ReflectiveInjector} from
describe('StaticClassProvider', () => { describe('StaticClassProvider', () => {
it('works', () => { it('works', () => {
// #docregion StaticClassProvider // #docregion StaticClassProvider
abstract class Shape { // TODO(issue/24571): remove '!'. abstract class Shape { name !: string; }
name !: string;
}
class Square extends Shape { class Square extends Shape {
name = 'square'; name = 'square';

1
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'}) @Directive({selector: 'pane'})
export class Pane { export class Pane {
// TODO(issue/24571): remove '!'.
@Input() id !: string; @Input() id !: string;
} }

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'}) @Component({selector: 'someCmp', templateUrl: 'someCmp.html'})
class SomeCmp implements AfterViewInit { class SomeCmp implements AfterViewInit {
// TODO(issue/24571): remove '!'.
@ViewChild(ChildDirective, {static: false}) child !: ChildDirective; @ViewChild(ChildDirective, {static: false}) child !: ChildDirective;
ngAfterViewInit() { ngAfterViewInit() {

2
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'}) @Directive({selector: 'pane'})
export class Pane { export class Pane {
// TODO(issue/24571): remove '!'.
@Input() id !: string; @Input() id !: string;
} }
@ -28,7 +27,6 @@ export class Pane {
`, `,
}) })
export class ViewChildrenComp implements AfterViewInit { export class ViewChildrenComp implements AfterViewInit {
// TODO(issue/24571): remove '!'.
@ViewChildren(Pane) panes !: QueryList<Pane>; @ViewChildren(Pane) panes !: QueryList<Pane>;
serializedPanes: string = ''; 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'}) @Component({selector: 'someCmp', templateUrl: 'someCmp.html'})
class SomeCmp implements AfterViewInit { class SomeCmp implements AfterViewInit {
// TODO(issue/24571): remove '!'.
@ViewChildren(ChildDirective) viewChildren !: QueryList<ChildDirective>; @ViewChildren(ChildDirective) viewChildren !: QueryList<ChildDirective>;
ngAfterViewInit() { ngAfterViewInit() {