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

docs: add di-related api doc (#27731) 

PR Close #27731
This commit is contained in:
Judy Bogart 2018-07-23 17:11:30 -07:00 committed by Miško Hevery
parent f8b9e61469
commit 644e7a28d8
5 changed files with 150 additions and 74 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
aio/content/guide/dependency-injection-in-action.md
View File

@ -262,6 +262,8 @@ Using a custom provider allows you to provide a concrete implementation for impl
The `factory` function returns the `localStorage` property that is attached to the browser window object. The `Inject` decorator is a constructor parameter used to specify a custom provider of a dependency. This custom provider can now be overridden during testing with a mock API of `localStorage` instead of interactive with real browser APIs.
{@a skip}
### Modify the provider search with `@Self` and `@SkipSelf`
Providers can also be scoped by injector through constructor parameter decorators. The following example overrides the `BROWSER_STORAGE` token in the `Component` class `providers` with the `sessionStorage` browser API. The same `BrowserStorageService` is injected twice in the constructor, decorated with `@Self` and `@SkipSelf` to define which injector handles the provider dependency.
@ -784,4 +786,3 @@ If you want to show only one of them, use the directive to make sure __??of what
`<hero-overview heroCache></hero-overview>`
--->

13
packages/common/src/location/location_strategy.ts
View File

@ -40,16 +40,15 @@ export abstract class LocationStrategy {
/**
* The `APP_BASE_HREF` token represents the base href to be used with the
* {@link PathLocationStrategy}.
*
* If you're using {@link PathLocationStrategy}, you must provide a provider to a string
* representing the URL prefix that should be preserved when generating and recognizing
* URLs.
* A predefined [DI token](guide/glossary#di-token) for the base href
* to be used with the `PathLocationStrategy`.
* The base href is the URL prefix that should be preserved when generating
* and recognizing URLs.
*
* @usageNotes
*
* ### Example
* The following example shows how to use this token to configure the root app injector
* with a base href value, so that the DI framework can supply the dependency anywhere in the app.
*
* ```typescript
* import {Component, NgModule} from '@angular/core';

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

@ -30,17 +30,20 @@ export type InjectableProvider = ValueSansProvider | ExistingSansProvider |
*/
export interface InjectableDecorator {
/**
* A marker metadata that marks a class as available to `Injector` for creation.
* Marks a class as available to `Injector` for creation.
*
* For more details, see the ["Dependency Injection Guide"](guide/dependency-injection).
* @see [Introduction to Services and DI](guide/architecture-services)
* @see [Dependency Injection Guide](guide/dependency-injection)
*
* @usageNotes
* ### Example
*
* The following example shows how service classes are properly marked as
* injectable.
*
* {@example core/di/ts/metadata_spec.ts region='Injectable'}
*
* `Injector` will throw an error when trying to instantiate a class that
* does not have `@Injectable` marker, as shown in the example below.
* `Injector` throws an error if it tries to instantiate a class that
* is not decorated with `@Injectable`, as shown in the following example.
*
* {@example core/di/ts/metadata_spec.ts region='InjectableThrows'}
*
@ -56,7 +59,15 @@ export interface InjectableDecorator {
*
* @publicApi
*/
export interface Injectable { providedIn?: Type<any>|'root'|null; }
export interface Injectable {
/**
* Determines which injectors will provide the injectable,
* by either associating it with an @NgModule or other `InjectorType`,
* or by specifying that this injectable should be provided in the
* 'root' injector, which will be the application-level injector in most apps.
*/
providedIn?: Type<any>|'root'|null;
}
/**
* Injectable decorator and metadata.

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

@ -17,10 +17,10 @@ import {makeParamDecorator} from '../util/decorators';
*/
export interface InjectDecorator {
/**
* A constructor parameter decorator that specifies a
* custom provider of a dependency.
* A parameter decorator on a dependency parameter of a class constructor
* that specifies a custom provider of the dependency.
*
* @see ["Dependency Injection Guide"](guide/dependency-injection).
* Learn more in the ["Dependency Injection Guide"](guide/dependency-injection).
*
* @usageNotes
* The following example shows a class constructor that specifies a
@ -28,7 +28,7 @@ export interface InjectDecorator {
*
* {@example core/di/ts/metadata_spec.ts region='Inject'}
*
* When `@Inject()` is not present, the `Injector` uses the type annotation of the
* When `@Inject()` is not present, the injector uses the type annotation of the
* parameter as the provider.
*
* {@example core/di/ts/metadata_spec.ts region='InjectWithoutDecorator'}
@ -44,7 +44,7 @@ export interface InjectDecorator {
*/
export interface Inject {
/**
* Injector token that maps to the dependency to be injected.
* A [DI token](guide/glossary#di-token) that maps to the dependency to be injected.
*/
token: any;
}
@ -65,14 +65,21 @@ export const Inject: InjectDecorator = makeParamDecorator('Inject', (token: any)
*/
export interface OptionalDecorator {
/**
* A constructor parameter decorator that marks a dependency as optional.
*
* A 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.
* For example, the following code allows the possibility of a null result:
*
* Can be used together with other parameter decorators
* that modify how dependency injection operates.
*
* Learn more in the ["Dependency Injection Guide"](guide/dependency-injection).
*
* @usageNotes
*
* The following code allows the possibility of a null result:
*
* {@example core/di/ts/metadata_spec.ts region='Optional'}
*
* @see ["Dependency Injection Guide"](guide/dependency-injection).
*/
(): any;
new (): Optional;
@ -100,8 +107,13 @@ export const Optional: OptionalDecorator = makeParamDecorator('Optional');
*/
export interface SelfDecorator {
/**
* A constructor parameter decorator that tells the DI framework
* to retrieve a dependency only from the local injector.
* A 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
* of this class must configure their own providers or be prepared for a null result.
*
* @usageNotes
*
* In the following example, the dependency can be resolved
* by the local injector when instantiating the class itself, but not
@ -109,8 +121,8 @@ export interface SelfDecorator {
*
* {@example core/di/ts/metadata_spec.ts region='Self'}
*
* @see ["Dependency Injection Guide"](guide/dependency-injection).
*
* @see `SkipSelf`
* @see `Optional`
*
*/
(): any;
@ -140,16 +152,23 @@ export const Self: SelfDecorator = makeParamDecorator('Self');
*/
export interface SkipSelfDecorator {
/**
* A constructor parameter decorator that tells the DI framework
* that dependency resolution should start from the parent injector.
* A 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.
*
* @usageNotes
*
* In the following example, the dependency can be resolved when
* instantiating a child, but not when instantiating the class itself.
*
* {@example core/di/ts/metadata_spec.ts region='SkipSelf'}
*
* @see ["Dependency Injection Guide"](guide/dependency-injection).
* Learn more in the
* [Dependency Injection guide](guide/dependency-injection-in-action#skip).
*
* @see `Self`
* @see `Optional`
*
*/
(): any;
@ -178,14 +197,17 @@ export const SkipSelf: SkipSelfDecorator = makeParamDecorator('SkipSelf');
*/
export interface HostDecorator {
/**
* A constructor parameter decorator that tells the DI framework
* to retrieve a dependency from any injector until
* reaching the host element of the current component.
* A 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.
*
* @see ["Dependency Injection Guide"](guide/dependency-injection).
* For an extended example, see
* ["Dependency Injection Guide"](guide/dependency-injection-in-action#optional).
*
* @usageNotes
*
* The following shows use with the `@Optional` decorator, and allows for a null result.
*
* {@example core/di/ts/metadata_spec.ts region='Host'}
*/
(): any;

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

@ -11,15 +11,16 @@ import {Type} from '../interface/type';
import {makePropDecorator} from '../util/decorators';
/**
* This token can be used to create a virtual provider that will populate the
* `entryComponents` fields of components and ng modules based on its `useValue`.
* A DI token that you can use to create a virtual [provider](guide/glossary#provider)
* that will populate the `entryComponents` field of components and NgModules
* based on its `useValue` property value.
* All components that are referenced in the `useValue` value (either directly
* or in a nested array or map) will be added to the `entryComponents` property.
* or in a nested array or map) are added to the `entryComponents` property.
*
* @usageNotes
* ### Example
*
* The following example shows how the router can populate the `entryComponents`
* field of an NgModule based on the router configuration which refers
* field of an NgModule based on a router configuration that refers
* to components.
*
* ```typescript
@ -47,6 +48,48 @@ import {makePropDecorator} from '../util/decorators';
*/
export const ANALYZE_FOR_ENTRY_COMPONENTS = new InjectionToken<any>('AnalyzeForEntryComponents');
/**
* Type of the `Attribute` decorator / constructor function.
*
* @publicApi
*/
export interface AttributeDecorator {
/**
* Specifies that a constant attribute value should be injected.
*
* 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`.
*
* ```html
* <input type="text">
* ```
*
* A decorator can inject string literal `text` as in the following example.
*
* {@example core/ts/metadata/metadata.ts region='attributeMetadata'}
*
* @publicApi
*/
(name: string): any;
new (name: string): Attribute;
}
/**
* Type of the Attribute metadata.
*
* @publicApi
*/
export interface Attribute {
/**
* The name of the attribute to be injected into the constructor.
*/
attributeName?: string;
}
/**
* Type of the Query metadata.