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

docs(core): document di and minor renames (#20855) 

PR Close #20855
This commit is contained in:
Kara Erickson 2017-12-13 14:28:36 -08:00 committed by Igor Minar
parent 8fdb1e09c1
commit 5bc869cb24
2 changed files with 130 additions and 38 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

156
packages/core/src/render3/di.ts
View File

@ -6,12 +6,23 @@
* found in the LICENSE file at https://angular.io/license
*/
import {ComponentFactory, ComponentRef as IComponentRef, ElementRef as IElementRef, EmbeddedViewRef as IEmbeddedViewRef, Injector, NgModuleRef as INgModuleRef, TemplateRef as ITemplateRef, Type, ViewContainerRef as IViewContainerRef, ViewRef as IViewRef} from '../core';
// We are temporarily importing the existing viewEngine from core so we can be sure we are
// correctly implementing its interfaces for backwards compatibility.
import * as viewEngine from '../core';
import {BLOOM_SIZE, NG_ELEMENT_ID, getOrCreateNodeInjector} from './instructions';
import {LContainer, LNodeFlags, LNodeInjector} from './interfaces';
import {ComponentTemplate, DirectiveDef} from './public_interfaces';
import {stringify} from './util';
import {stringify, notImplemented} from './util';
/**
* Injection flags for DI.
*
* Optional: The dependency is not required.
*
* CheckSelf: Should check the current node for the dependency.
*
* CheckParent: Should check parent nodes for the dependency.
*/
export const enum InjectFlags {
Optional = 1 << 0,
CheckSelf = 1 << 1,
@ -19,17 +30,40 @@ export const enum InjectFlags {
Default = CheckSelf | CheckParent
}
function createError(text: string, token: any) {
/**
* Constructs an injection error with the given text and token.
*
* @param text The text of the error
* @param token The token associated with the error
* @returns The error that was created
*/
function createInjectionError(text: string, token: any) {
return new Error(`ElementInjector: ${text} [${stringify(token)}]`);
}
export function inject<T>(token: Type<T>, flags?: InjectFlags): T {
/**
* Searches for an instance of the given directive type up the injector tree and returns
* that instance if found.
*
* Specifically, it gets the bloom filter bit associated with the directive (see bloomHashBit),
* checks that bit against the bloom filter structure to identify an injector that might have
* the directive (see bloomFindPossibleInjector), then searches the directives on that injector
* for a match.
*
* If not found, it will propagate up to the next parent injector until the token
* is found or the top is reached.
*
* @param token The directive type to search for
* @param flags Injection flags (e.g. CheckParent)
* @returns The instance found
*/
export function inject<T>(token: viewEngine.Type<T>, flags?: InjectFlags): T {
const di = getOrCreateNodeInjector();
const bloomHash = bloomHashBit(token);
if (bloomHash === null) {
const moduleInjector = di.injector;
if (!moduleInjector) {
throw createError('NotFound', token);
throw createInjectionError('NotFound', token);
}
moduleInjector.get(token);
} else {
@ -55,14 +89,45 @@ export function inject<T>(token: Type<T>, flags?: InjectFlags): T {
}
}
}
throw createError('Not found', token);
throw createInjectionError('Not found', token);
}
function bloomHashBit(type: Type<any>): number|null {
/**
* Given a directive type, this function returns the bit in an injector's bloom filter
* that should be used to determine whether or not the directive is present.
*
* When the directive was added to the bloom filter, it was given a unique ID that can be
* retrieved on the class. Since there are only BLOOM_SIZE slots per bloom filter, the directive's
* ID must be modulo-ed by BLOOM_SIZE to get the correct bloom bit (directives share slots after
* BLOOM_SIZE is reached).
*
* @param type The directive type
* @returns The bloom bit to check for the directive
*/
function bloomHashBit(type: viewEngine.Type<any>): number|null {
let id: number|undefined = (type as any)[NG_ELEMENT_ID];
return typeof id === 'number' ? id % BLOOM_SIZE : null;
}
/**
* Finds the closest injector that might have a certain directive.
*
* Each directive corresponds to a bit in an injector's bloom filter. Given the bloom bit to
* check and a starting injector, this function propagates up injectors until it finds an
* injector that contains a 1 for that bit in its bloom filter. A 1 indicates that the
* injector may have that directive. It only *may* have the directive because directives begin
* to share bloom filter bits after the BLOOM_SIZE is reached, and it could correspond to a
* different directive sharing the bit.
*
* Note: We can skip checking further injectors up the tree if an injector's cbf structure
* has a 0 for that bloom bit. Since cbf contains the merged value of all the parent
* injectors, a 0 in the bloom bit indicates that the parents definitely do not contain
* the directive and do not need to be checked.
*
* @param injector The starting injector to check
* @param bloomBit The bit to check in each injector's bloom filter
* @returns An injector that might have the directive
*/
export function bloomFindPossibleInjector(injector: LNodeInjector, bloomBit: number): LNodeInjector|
null {
const mask = 1 << bloomBit;
@ -83,72 +148,89 @@ export function bloomFindPossibleInjector(injector: LNodeInjector, bloomBit: num
return null;
}
export function injectElementRef(): IElementRef {
/**
* Creates an ElementRef and stores it on the injector. Or, if the ElementRef already
* exists, retrieves the existing ElementRef.
*
* @returns The ElementRef instance to use
*/
export function injectElementRef(): viewEngine.ElementRef {
let di = getOrCreateNodeInjector();
return di.elementRef || (di.elementRef = new ElementRef(di.node.native));
}
class ElementRef implements IElementRef {
/** A ref to a node's native element. */
class ElementRef implements viewEngine.ElementRef {
readonly nativeElement: any;
constructor(nativeElement: any) { this.nativeElement = nativeElement; }
}
export function injectTemplateRef(): ITemplateRef<any> {
/**
* Creates a TemplateRef and stores it on the injector. Or, if the TemplateRef already
* exists, retrieves the existing TemplateRef.
*
* @returns The TemplateRef instance to use
*/
export function injectTemplateRef(): viewEngine.TemplateRef<any> {
let di = getOrCreateNodeInjector();
const data = (di.node as LContainer).data;
if (data === null || data.template === null) {
throw createError('Directive not used in structural way.', null);
throw createInjectionError('Directive does not have a template.', null);
}
return di.templateRef ||
(di.templateRef = new TemplateRef<any>(injectElementRef(), data.template));
}
class TemplateRef<T> implements ITemplateRef<T> {
readonly elementRef: IElementRef;
/** A ref to a particular template. */
class TemplateRef<T> implements viewEngine.TemplateRef<T> {
readonly elementRef: viewEngine.ElementRef;
constructor(elementRef: IElementRef, template: ComponentTemplate<T>) {
constructor(elementRef: viewEngine.ElementRef, template: ComponentTemplate<T>) {
this.elementRef = elementRef;
}
createEmbeddedView(context: T): IEmbeddedViewRef<T> { throw notImplemented(); }
createEmbeddedView(context: T): viewEngine.EmbeddedViewRef<T> { throw notImplemented(); }
}
export function injectViewContainerRef(): IViewContainerRef {
/**
* Creates a ViewContainerRef and stores it on the injector. Or, if the ViewContainerRef
* already exists, retrieves the existing ViewContainerRef.
*
* @returns The ViewContainerRef instance to use
*/
export function injectViewContainerRef(): viewEngine.ViewContainerRef {
let di = getOrCreateNodeInjector();
return di.viewContainerRef || (di.viewContainerRef = new ViewContainerRef(di.node as LContainer));
}
class ViewContainerRef implements IViewContainerRef {
element: IElementRef;
injector: Injector;
parentInjector: Injector;
/**
* A ref to a container that enables adding and removing views from that container
* imperatively.
*/
class ViewContainerRef implements viewEngine.ViewContainerRef {
element: viewEngine.ElementRef;
injector: viewEngine.Injector;
parentInjector: viewEngine.Injector;
constructor(node: LContainer) {}
clear(): void { throw notImplemented(); }
get(index: number): IViewRef|null { throw notImplemented(); }
get(index: number): viewEngine.ViewRef|null { throw notImplemented(); }
length: number;
createEmbeddedView<C>(
templateRef: ITemplateRef<C>, context?: C|undefined,
index?: number|undefined): IEmbeddedViewRef<C> {
templateRef: viewEngine.TemplateRef<C>, context?: C|undefined,
index?: number|undefined): viewEngine.EmbeddedViewRef<C> {
throw notImplemented();
}
createComponent<C>(
componentFactory: ComponentFactory<C>, index?: number|undefined,
injector?: Injector|undefined, projectableNodes?: any[][]|undefined,
ngModule?: INgModuleRef<any>|undefined): IComponentRef<C> {
componentFactory: viewEngine.ComponentFactory<C>, index?: number|undefined,
injector?: viewEngine.Injector|undefined, projectableNodes?: any[][]|undefined,
ngModule?: viewEngine.NgModuleRef<any>|undefined): viewEngine.ComponentRef<C> {
throw notImplemented();
}
insert(viewRef: IViewRef, index?: number|undefined): IViewRef { throw notImplemented(); }
move(viewRef: IViewRef, currentIndex: number): IViewRef { throw notImplemented(); }
indexOf(viewRef: IViewRef): number { throw notImplemented(); }
insert(viewRef: viewEngine.ViewRef, index?: number|undefined): viewEngine.ViewRef { throw notImplemented(); }
move(viewRef: viewEngine.ViewRef, currentIndex: number): viewEngine.ViewRef { throw notImplemented(); }
indexOf(viewRef: viewEngine.ViewRef): number { throw notImplemented(); }
remove(index?: number|undefined): void { throw notImplemented(); }
detach(index?: number|undefined): IViewRef|null { throw notImplemented(); }
}
function notImplemented() {
return new Error('Method not implemented.');
detach(index?: number|undefined): viewEngine.ViewRef|null { throw notImplemented(); }
}

12
packages/core/src/render3/util.ts
View File

@ -20,4 +20,14 @@ export function stringify(value: any): string {
if (typeof value == 'string') return value;
if (value == null) return '';
return '' + value;
}
}
/**
* Function that throws a "not implemented" error so it's clear certain
* behaviors/methods aren't yet ready.
*
* @returns Not implemented error
*/
export function notImplemented(): Error {
return new Error('NotImplemented');
}