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

docs(compiler): compiler related api docs

This commit is contained in:
Igor Minar 2015-09-18 15:46:26 -07:00
parent 0319417a1b
commit 7ee295ad94
7 changed files with 177 additions and 75 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

17
modules/angular2/src/core/compiler/compiler.ts
View File

@ -70,8 +70,7 @@ export class CompilerCache {
}
}
/**
*
/*
* ## URL Resolution
*
* ```
@ -88,9 +87,15 @@ export class CompilerCache {
* var url = viewAnnotation.templateUrl;
* var componentUrl = componentUrlMapper.getUrl(componentType);
* var componentResolvedUrl = urlResolver.resolve(appRootUrl.value, componentUrl);
* var templateResolvedUrl = urlResolver.resolve(componetResolvedUrl, url);
* var templateResolvedUrl = urlResolver.resolve(componentResolvedUrl, url);
* ```
*/
/**
* Service for compiling {@link Component}s so that they can be later instantiated and their
* {@link View}s can be rendered.
*
* <!-- TODO: check Component and View links, they should likely go to glossary instead -->
*/
@Injectable()
export class Compiler {
private _compiling: Map<Type, Promise<AppProtoView>> = new Map();
@ -127,8 +132,10 @@ export class Compiler {
return PipeBinding.createFromType(typeOrBinding, meta);
}
// Create a hostView as if the compiler encountered <hostcmp></hostcmp>.
// Used for bootstrapping.
/**
* Compiles an {@link EntryPointComponent entry-point Component} and returns a promise for a
* {@link ProtoViewRef} that can be passed into {@link AppViewManager
*/
compileInHost(componentType: Type): Promise<ProtoViewRef> {
var r = wtfStartTimeRange('Compiler#compile()', stringify(componentType));

14
modules/angular2/src/core/compiler/dynamic_component_loader.ts
View File

@ -7,9 +7,8 @@ import {ElementRef} from './element_ref';
import {ViewRef, HostViewRef} from './view_ref';
/**
* Angular's reference to a component instance.
*
* `ComponentRef` represents a component instance lifecycle and meta information.
* Represents a component instance as a node in application's component tree and provides access to
* other objects related to this component instance.
*/
export class ComponentRef {
/**
@ -24,7 +23,6 @@ export class ComponentRef {
componentType: Type;
injector: Injector;
/**
@ -54,11 +52,15 @@ export class ComponentRef {
}
/**
* Service for dynamically loading a Component into an arbitrary position in the internal Angular
* application tree.
* Service for creating an instance of a component and attaching it to the component tree of an
* application at a specified location.
*/
@Injectable()
export class DynamicComponentLoader {
/**
* @private
*/
constructor(private _compiler: Compiler, private _viewManager: AppViewManager) {}
/**

48
modules/angular2/src/core/compiler/element_ref.ts
View File

@ -3,20 +3,28 @@ import {ViewRef} from './view_ref';
import {RenderViewRef, RenderElementRef, Renderer} from 'angular2/src/core/render/api';
/**
* An opaque reference to the underlying element.
* Represents a location in a View that has an injection, change-detection and render contexts
* associated with it.
*
* The underlying native element is a DOM Element in a browser context, but may represent other
* types on other rendering platforms. In the browser the `ElementRef` can be sent to the Web
* Worker. Web Workers can not have references to the DOM Elements.
* An `ElementRef` is created for each element in the Template that contains a Directive, Component
* or data-binding.
*
* An `ElementRef` is backed by a render-specific element. In the browser context, this is usually a
* DOM element.
*/
export class ElementRef implements RenderElementRef {
/**
* Reference to the {@link ViewRef} where the `ElementRef` is inside of.
* @private
*
* Reference to the {@link ViewRef} that this `ElementRef` is part of.
*/
parentView: ViewRef;
/**
* @private
*
* Index of the element inside the {@link ViewRef}.
*
* This is used internally by the Angular framework to locate elements.
@ -24,12 +32,17 @@ export class ElementRef implements RenderElementRef {
boundElementIndex: number;
/**
* @private
*
* Index of the element inside the `RenderViewRef`.
*
* This is used internally by the Angular framework to locate elements.
*/
renderBoundElementIndex: number;
/**
* @private
*/
constructor(parentView: ViewRef, boundElementIndex: number, renderBoundElementIndex: number,
private _renderer: Renderer) {
this.parentView = parentView;
@ -38,7 +51,7 @@ export class ElementRef implements RenderElementRef {
}
/**
*
* @private
*/
get renderView(): RenderViewRef { return this.parentView.render; }
@ -48,15 +61,22 @@ export class ElementRef implements RenderElementRef {
set renderView(viewRef: RenderViewRef) { throw new BaseException('Abstract setter'); }
/**
* Returns the native Element implementation.
* The underlying native element or `null` if direct access to native elements is not supported
* (e.g. when the application runs in a web worker).
*
* In the browser this represents the DOM element.
*
* The `nativeElement` can be used as an escape hatch when direct DOM manipulation is needed. Use
* this with caution, as it creates tight coupling between your application and the browser, which
* will not work in Web Workers.
*
* NOTE: This method will return null in the webworker scenario!
* <div class="callout is-critical">
* <header>Use with caution</header>
* <p>
* Use this api as the last resort when direct access to DOM is needed. Use templating and
* data-binding provided by Angular instead.
* </p>
* <p>
* Relying on direct DOM access creates tight coupling between your application and rendering
* layers which will make it impossible to separate the two and deploy your application in into a
* web worker.
* </p>
* <!-- TODO: add info about custom renderers that should be used instead -->
* </div>
*/
get nativeElement(): any { return this._renderer.getNativeElementSync(this); }
}

23
modules/angular2/src/core/compiler/template_ref.ts
View File

@ -3,17 +3,26 @@ import {ElementRef} from './element_ref';
import * as viewModule from './view';
/**
* Reference to a template within a component.
* Represents an Embedded Template that can be used for creating Embedded Views.
*
* Represents an opaque reference to the underlying template that can
* be instantiated using the {@link ViewContainerRef}.
* Use {@link ViewContainerRef#createEmbeddedView} method to instantiate an Embedded View and attach
* it to a View Container.
*
* <!-- TODO: how to get hold of it? -->
*/
export class TemplateRef {
/**
* The location of the template
* The location in the View where the Embedded View logically belong to.
*
* This `ElementRef` provides the data-binding and injection context for Embedded Views created
* from this `TemplateRef`.
*/
elementRef: ElementRef;
/**
* @private
*/
constructor(elementRef: ElementRef) { this.elementRef = elementRef; }
private _getProtoView(): viewModule.AppProtoView {
@ -23,10 +32,14 @@ export class TemplateRef {
.nestedProtoView;
}
/**
* Reference to the ProtoView created by compiling the original Embedded Template, from which the
* Embedded View is instatiated.
*/
get protoViewRef(): ProtoViewRef { return this._getProtoView().ref; }
/**
* Whether this template has a local variable with the given name
* Returns true if the Template declares a Local Variable with the given name.
*/
hasLocal(name: string): boolean { return this._getProtoView().variableBindings.has(name); }
}

93
modules/angular2/src/core/compiler/view_container_ref.ts
View File

@ -10,17 +10,44 @@ import {TemplateRef} from './template_ref';
import {ViewRef, HostViewRef, ProtoViewRef, internalView} from './view_ref';
/**
* A location where {@link ViewRef}s can be attached.
* Represents a container where one or more Views can be attached.
*
* A `ViewContainerRef` represents a location in a {@link ViewRef} where other child
* {@link ViewRef}s can be inserted. Adding and removing views is the only way of structurally
* changing the rendered DOM of the application.
* The container can contain two kinds of Views. Host Views, created by instantiating a
* {@link Component} via {@link #createHostView}s, and Embedded Views, created by instantiating an
* {@link TemplateRef Embedded Template} via {@link #createEmbeddedView}).
*
* The location of the View Container within the containing View is specified by the Anchor
* `element`. Each View Container can have only one Anchor Element and each Anchor Element can only
* have a single View Container.
*
* Root elements of Views attached to this container become siblings of the Anchor Element in
* the Rendered View.
*
* To access a ViewContainerRef of an Element, you can either place a {@link Directive} injected
* with `ViewContainerRef` on the Element, or you obtain it via
* {@link ViewManager#getViewContainer}.
*
* <!-- TODO: Is ViewContainerRef#element a public api? Should it be renamed? to anchor or anchorElementRef? -->
* <!-- TODO: rename all atIndex params to just index or get(index) to get(atIndex) -->
*/
export class ViewContainerRef {
/**
* @private
*/
constructor(public viewManager: avmModule.AppViewManager, public element: ElementRef) {}
constructor(
/**
* @private
*/
public viewManager: avmModule.AppViewManager,
/**
* Anchor element that specifies the location of this container in the containing View.
*/
public element: ElementRef
) {
}
private _getViews(): Array<viewModule.AppView> {
var vc = internalView(this.element.parentView).viewContainers[this.element.boundElementIndex];
@ -28,7 +55,7 @@ export class ViewContainerRef {
}
/**
* Remove all {@link ViewRef}s at current location.
* Destroys all Views in the container.
*/
clear(): void {
for (var i = this.length - 1; i >= 0; i--) {
@ -37,28 +64,22 @@ export class ViewContainerRef {
}
/**
* Return a {@link ViewRef} at specific index.
* Returns the {@link ViewRef} for the View located in this container at the specified index.
*/
get(index: number): ViewRef { return this._getViews()[index].ref; }
/**
* Returns number of {@link ViewRef}s currently attached at this location.
* Returns the number of Views currently attached to this container.
*/
get length(): number { return this._getViews().length; }
/**
* Create and insert a {@link ViewRef} into the view-container.
* Instantiates an Embedded View based on the {@link TemplateRef `templateRef`} and inserts it
* into this container at index specified via `atIndex`.
*
* - `protoViewRef` (optional) {@link ProtoViewRef} - The `ProtoView` to use for creating
* `View` to be inserted at this location. If `ViewContainer` is created at a location
* of inline template, then `protoViewRef` is the `ProtoView` of the template.
* - `atIndex` (optional) `number` - location of insertion point. (Or at the end if unspecified.)
* - `context` (optional) {@link ElementRef} - Context (for expression evaluation) from the
* {@link ElementRef} location. (Or current context if unspecified.)
* - `bindings` (optional) Array of {@link ResolvedBinding} - Used for configuring
* `ElementInjector`.
* If `atIndex` is not specified, the new View will be inserted as the last View in the container.
*
* Returns newly created {@link ViewRef}.
* Returns the {@link ViewRef} for the newly created View.
*/
// TODO(rado): profile and decide whether bounds checks should be added
// to the methods below.
@ -67,6 +88,20 @@ export class ViewContainerRef {
return this.viewManager.createEmbeddedViewInContainer(this.element, atIndex, templateRef);
}
/**
* Instantiates a single {@link Component} and inserts it into this container at index specified
* via `atIndex`.
*
* The component is instantiated using its {@link ProtoViewRef `protoViewRef`} which can be
* obtained via {@link Compiler#compileInHost}.
*
* If `atIndex` is not specified, the new View will be inserted as the last View in the container.
*
* You can optionally specify `dynamicallyCreatedBindings`, which configure the {@link Injector}
* that will be created for the new Host View. <!-- TODO: what is host view? it's never defined!!! -->
*
* Returns the {@link ViewRef} for the newly created View.
*/
createHostView(protoViewRef: ProtoViewRef = null, atIndex: number = -1,
dynamicallyCreatedBindings: ResolvedBinding[] = null): HostViewRef {
if (atIndex == -1) atIndex = this.length;
@ -75,12 +110,14 @@ export class ViewContainerRef {
}
/**
* Insert a {@link ViewRef} at specefic index.
* <!-- TODO: refactor into move and remove -->
* Inserts a View identified by a {@link ViewRef} into the container at index specified via
* `atIndex`.
*
* The index is location at which the {@link ViewRef} should be attached. If omitted it is
* inserted at the end.
* If `atIndex` is not specified, the new View will be inserted as the last View in the container.
*
* Returns the inserted {@link ViewRef}.
* <!-- TODO: why does it return ViewRef? looks useless -->
*/
insert(viewRef: ViewRef, atIndex: number = -1): ViewRef {
if (atIndex == -1) atIndex = this.length;
@ -88,16 +125,17 @@ export class ViewContainerRef {
}
/**
* Return the index of already inserted {@link ViewRef}.
* Returns the index of the View, specified via {@link ViewRef}, within the current container.
*/
indexOf(viewRef: ViewRef): number {
return ListWrapper.indexOf(this._getViews(), internalView(viewRef));
}
/**
* Remove a {@link ViewRef} at specific index.
* <!-- TODO: rename to destroy -->
* Destroys a View attached to this container at index specified via `atIndex`.
*
* If the index is omitted last {@link ViewRef} is removed.
* If `atIndex` is not specified, the last View in the container will be removed.
*/
remove(atIndex: number = -1): void {
if (atIndex == -1) atIndex = this.length - 1;
@ -106,8 +144,11 @@ export class ViewContainerRef {
}
/**
* The method can be used together with insert to implement a view move, i.e.
* moving the DOM nodes while the directives in the view stay intact.
* <!-- TODO: refactor into move and remove -->
* Use along with {@link #insert} to move a View within the current container.
*
* If the `atIndex` param is omitted, the last {@link ViewRef} is detached.
* <!-- TODO: why does it return ViewRef? looks useless -->
*/
detach(atIndex: number = -1): ViewRef {
if (atIndex == -1) atIndex = this.length - 1;

12
modules/angular2/src/core/compiler/view_manager.ts
View File

@ -19,9 +19,10 @@ import {AppViewListener} from './view_listener';
import {wtfCreateScope, wtfLeave, WtfScopeFn} from '../profile/profile';
/**
* Entry point for creating, moving views in the view hierarchy and destroying views.
* This manager contains all recursion and delegates to helper methods
* in AppViewManagerUtils and the Renderer, so unit tests get simpler.
* Service exposing low level API for creating, moving and destroying Views.
*
* Most applications should use higher-level abstractions like {@link DynamicComponentLoader} and
* {@link ViewContainerRef} instead.
*/
@Injectable()
export class AppViewManager {
@ -178,6 +179,7 @@ export class AppViewManager {
_createEmbeddedViewInContainerScope: WtfScopeFn =
wtfCreateScope('AppViewManager#createEmbeddedViewInContainer()');
/**
* <!-- TODO: why "InContainer"? createRootHostView doesn't use this suffix. seems redundant -->
*
* See {@link AppViewManager#destroyViewInContainer}.
*/
@ -195,6 +197,7 @@ export class AppViewManager {
_createHostViewInContainerScope: WtfScopeFn =
wtfCreateScope('AppViewManager#createHostViewInContainer()');
/**
* <!-- TODO: why "InContainer"? createRootHostView doesn't use this suffix. seems redundant -->
*
* See {@link AppViewManager#destroyViewInContainer}.
*/
@ -258,6 +261,7 @@ export class AppViewManager {
_destroyViewInContainerScope = wtfCreateScope('AppViewMananger#destroyViewInContainer()');
/**
* <!-- TODO: why "InContainer"? createRootHostView doesn't use this suffix. seems redundant -->
*
* See {@link AppViewManager#createViewInContainer}.
*/
@ -271,6 +275,7 @@ export class AppViewManager {
_attachViewInContainerScope = wtfCreateScope('AppViewMananger#attachViewInContainer()');
/**
* <!-- TODO: why "InContainer"? createRootHostView doesn't use this suffix. seems redundant -->
*
* See {@link AppViewManager#detachViewInContainer}.
*/
@ -293,6 +298,7 @@ export class AppViewManager {
_detachViewInContainerScope = wtfCreateScope('AppViewMananger#detachViewInContainer()');
/**
* <!-- TODO: why "InContainer"? createRootHostView doesn't use this suffix. seems redundant -->
*
* See {@link AppViewManager#attachViewInContainer}.
*/

45
modules/angular2/src/core/compiler/view_ref.ts
View File

@ -13,21 +13,31 @@ export function internalProtoView(protoViewRef: ProtoViewRef): viewModule.AppPro
return isPresent(protoViewRef) ? protoViewRef._protoView : null;
}
export interface HostViewRef { changeDetectorRef: ChangeDetectorRef; }
/**
* Represents the View of a {@link Component} that was compiled via {@link Compiler#compileInHost
*/
export interface HostViewRef {
/**
* @private
*/
changeDetectorRef: ChangeDetectorRef;
}
/**
* A reference to an Angular View.
* Represents an Angular View.
*
* A View is a fundamental building block of Application UI. A View is the smallest set of
* elements which are created and destroyed together. A View can change properties on the elements
* within the view, but it can not change the structure of those elements.
* <!-- TODO: move the next two paragraphs to the dev guide -->
* A View is a fundamental building block of the application UI. It is the smallest grouping of
* Elements which are created and destroyed together.
*
* To change structure of the elements, the Views can contain zero or more {@link ViewContainerRef}s
* which allow the views to be nested.
* Properties of elements in a View can change, but the structure (number and order) of elements in
* a View cannot. Changing the structure of elements can only be done by inserting, moving or
* removing nested Views via a View Container. Each View can contain many View Containers.
* <!-- /TODO -->
*
* ## Example
*
* Given this template
* Given this template...
*
* ```
* Count: {{items.length}}
@ -36,9 +46,9 @@ export interface HostViewRef { changeDetectorRef: ChangeDetectorRef; }
* </ul>
* ```
*
* The above example we have two {@link ProtoViewRef}s:
* ... we have two {@link ProtoViewRef}s:
*
* Outter {@link ProtoViewRef}:
* Outer {@link ProtoViewRef}:
* ```
* Count: {{items.length}}
* <ul>
@ -53,7 +63,7 @@ export interface HostViewRef { changeDetectorRef: ChangeDetectorRef; }
*
* Notice that the original template is broken down into two separate {@link ProtoViewRef}s.
*
* The outter/inner {@link ProtoViewRef}s are then assembled into views like so:
* The outer/inner {@link ProtoViewRef}s are then assembled into views like so:
*
* ```
* <!-- ViewRef: outer-0 -->
@ -85,6 +95,8 @@ export class ViewRef implements HostViewRef {
get renderFragment(): RenderFragmentRef { return this._view.renderFragment; }
/**
* @private
*
* Return `ChangeDetectorRef`
*/
get changeDetectorRef(): ChangeDetectorRef {
@ -107,13 +119,14 @@ export class ViewRef implements HostViewRef {
}
/**
* A reference to an Angular ProtoView.
* Represents Angular's ProtoView.
*
* A ProtoView is a reference to a template for easy creation of views.
* (See {@link AppViewManager#createViewInContainer `AppViewManager#createViewInContainer`} and
* A ProtoView is a prototypical View that is the result of Template compilation and enables
* Angular to efficiently create an instance of a View based on the compiled Template.
*
* A ProtoView is created {@link AppViewManager#createViewInContainer} and
* {@link AppViewManager#createRootHostView `AppViewManager#createRootHostView`}).
*
* A `ProtoView` is a factory for creating `View`s.
*
* ## Example
*
@ -128,7 +141,7 @@ export class ViewRef implements HostViewRef {
*
* The above example we have two {@link ProtoViewRef}s:
*
* Outter {@link ProtoViewRef}:
* Outer {@link ProtoViewRef}:
* ```
* Count: {{items.length}}
* <ul>