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

docs: update view-related api doc (#25582) 

PR Close #25582
This commit is contained in:
Judy Bogart 2018-08-20 14:32:11 -07:00 committed by Ben Lesh
parent dd5e35ee67
commit 78d42a9503
4 changed files with 112 additions and 82 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
packages/core/src/change_detection/change_detector_ref.ts
View File

@ -44,7 +44,7 @@
* when the `live` property is set to false, and reattaches it when the property
* becomes true.
*
* <code-example path="core/ts/change_detect/change-detection.ts" region="detach"></code-example>
* <code-example path="core/ts/change_detect/change-detection.ts" region="reattach"></code-example>
*
*/
export abstract class ChangeDetectorRef {

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

@ -15,36 +15,35 @@ import {NgModuleRef} from './ng_module_factory';
import {ViewRef} from './view_ref';
/**
* Represents an instance of a Component created via a {@link ComponentFactory}.
*
* `ComponentRef` provides access to the Component Instance as well other objects related to this
* Component Instance and allows you to destroy the Component Instance via the {@link #destroy}
* method.
* Represents a component created by a `ComponentFactory`.
* Provides access to the component instance and related objects,
* and provides the means of destroying the instance.
*
*/
export abstract class ComponentRef<C> {
/**
* Location of the Host Element of this Component Instance.
* The host or anchor [element](guide/glossary#element) for this component instance.
*/
abstract get location(): ElementRef;
/**
* The injector on which the component instance exists.
* The [dependency injector](guide/glossary#injector) for this component instance.
*/
abstract get injector(): Injector;
/**
* The instance of the Component.
* This component instance.
*/
abstract get instance(): C;
/**
* The {@link ViewRef} of the Host View of this Component instance.
* The [host view](guide/glossary#view-tree) defined by the template
* for this component instance.
*/
abstract get hostView(): ViewRef;
/**
* The {@link ChangeDetectorRef} of the Component instance.
* The change detector for this component instance.
*/
abstract get changeDetectorRef(): ChangeDetectorRef;
@ -59,24 +58,33 @@ export abstract class ComponentRef<C> {
abstract destroy(): void;
/**
* Allows to register a callback that will be called when the component is destroyed.
* A lifecycle hook that provides additional developer-defined cleanup
* functionality for the component.
* @param callback A handler function that cleans up developer-defined data
* associated with this component. Called when the `destroy()` method is invoked.
*/
abstract onDestroy(callback: Function): void;
}
export abstract class ComponentFactory<C> {
/**
* The comonent's HTML selector.
*/
abstract get selector(): string;
/**
* The component's type
*/
abstract get componentType(): Type<any>;
/**
* selector for all <ng-content> elements in the component.
* Selector for all <ng-content> elements in the component.
*/
abstract get ngContentSelectors(): string[];
/**
* the inputs of the component.
* The inputs of the component.
*/
abstract get inputs(): {propName: string, templateName: string}[];
/**
* the outputs of the component.
* The outputs of the component.
*/
abstract get outputs(): {propName: string, templateName: string}[];
/**

104
packages/core/src/linker/view_container_ref.ts
View File

@ -15,111 +15,121 @@ import {EmbeddedViewRef, ViewRef} from './view_ref';
/**
* Represents a container where one or more Views can be attached.
*
* The container can contain two kinds of Views. Host Views, created by instantiating a
* {@link Component} via {@link #createComponent}, 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 a {@link ViewChild} query.
* Represents a container where one or more views can be attached to a component.
* Can contain _host_ views (created by instantiating a
* Component` with the `createComponent()` method), and _embedded views_
* (created by instantiating a `TemplateRef` with the `createEmbeddedView()` method.
*
*/
export abstract class ViewContainerRef {
/**
* Anchor element that specifies the location of this container in the containing View.
* Anchor element that specifies the location of this container in the containing view.
* Each view container can have only one anchor element, and each anchor element
* can have only a single view container.
*
* Root elements of views attached to this container become siblings of the anchor element in
* the rendered view.
*
* Access the `ViewContainerRef` of an element by placing a `Directive` injected
* with `ViewContainerRef` on the element, or use a `ViewChild` query.
*
* <!-- TODO: rename to anchorElement -->
*/
abstract get element(): ElementRef;
/**
* The [dependency injector](guide/glossary#injector) for this view container.
*/
abstract get injector(): Injector;
/** @deprecated No replacement */
abstract get parentInjector(): Injector;
/**
* Destroys all Views in this container.
* Destroys all views in this container.
*/
abstract clear(): void;
/**
* Returns the {@link ViewRef} for the View located in this container at the specified index.
* Retrieves a view from this container.
* @param index The 0-based index of the view to retrieve.
* @returns The `ViewRef` instance, or null if the index is out of range.
*/
abstract get(index: number): ViewRef|null;
/**
* Returns the number of Views currently attached to this container.
* Reports how many views are currently attached to this container.
* @returns The number of views.
*/
abstract get length(): number;
/**
* Instantiates an Embedded View based on the {@link TemplateRef `templateRef`} and inserts it
* into this container at the specified `index`.
* Instantiates an embedded view and inserts it
* into this container.
* @param templateRef The HTML template that defines the view.
* @param index The 0-based index at which to insert the new view into this container.
* If not specified, appends the new view as the last entry.
*
* If `index` is not specified, the new View will be inserted as the last View in the container.
*
* Returns the {@link ViewRef} for the newly created View.
* @returns The `ViewRef` instance for the newly created view.
*/
abstract createEmbeddedView<C>(templateRef: TemplateRef<C>, context?: C, index?: number):
EmbeddedViewRef<C>;
/**
* Instantiates a single {@link Component} and inserts its Host View into this container at the
* specified `index`.
* Instantiates a single component and inserts its host view into this container.
*
* The component is instantiated using its {@link ComponentFactory} which can be obtained via
* {@link ComponentFactoryResolver#resolveComponentFactory resolveComponentFactory}.
* @param componentFactory The factory to use.
* @param index The index at which to insert the new component's host view into this container.
* If not specified, appends the new view as the last entry.
* @param injector The injector to use as the parent for the new component.
* @param projectableNodes
* @param ngModule
*
* If `index` is not specified, the new View will be inserted as the last View in the container.
* @returns The new component instance, containing the host view.
*
* You can optionally specify the {@link Injector} that will be used as parent for the Component.
*
* Returns the {@link ComponentRef} of the Host View created for the newly instantiated Component.
*/
abstract createComponent<C>(
componentFactory: ComponentFactory<C>, index?: number, injector?: Injector,
projectableNodes?: any[][], ngModule?: NgModuleRef<any>): ComponentRef<C>;
/**
* Inserts a View identified by a {@link ViewRef} into the container at the specified `index`.
* Inserts a view into this container.
* @param viewRef The view to insert.
* @param index The 0-based index at which to insert the view.
* If not specified, appends the new view as the last entry.
* @returns The inserted `ViewRef` instance.
*
* If `index` is not specified, the new View will be inserted as the last View in the container.
*
* Returns the inserted {@link ViewRef}.
*/
abstract insert(viewRef: ViewRef, index?: number): ViewRef;
/**
* Moves a View identified by a {@link ViewRef} into the container at the specified `index`.
*
* Returns the inserted {@link ViewRef}.
* Moves a view to a new location in this container.
* @param viewRef The view to move.
* @param index The 0-based index of the new location.
* @returns The moved `ViewRef` instance.
*/
abstract move(viewRef: ViewRef, currentIndex: number): ViewRef;
/**
* Returns the index of the View, specified via {@link ViewRef}, within the current container or
* `-1` if this container doesn't contain the View.
* Returns the index of a view within the current container.
* @parem viewRef The view to query.
* @returns The 0-based index of the view's position in this container,
* or `-1` if this container doesn't contain the view.
*/
abstract indexOf(viewRef: ViewRef): number;
/**
* Destroys a View attached to this container at the specified `index`.
*
* If `index` is not specified, the last View in the container will be removed.
* Destroys a view attached to this container
* @param index The 0-based index of the view to destroy.
* If not specified, the last view in the container is removed.
*/
abstract remove(index?: number): void;
/**
* Use along with {@link #insert} to move a View within the current container.
*
* If the `index` param is omitted, the last {@link ViewRef} is detached.
* Detaches a view from this container without destroying it.
* Use along with `insert()` to move a view within the current container.
* @param index The 0-based index of the view to detach.
* If not specified, the last view in the container is detached.
*/
abstract detach(index?: number): ViewRef|null;
}

52
packages/core/src/linker/view_ref.ts
View File

@ -9,33 +9,49 @@
import {ApplicationRef} from '../application_ref';
import {ChangeDetectorRef} from '../change_detection/change_detector_ref';
/**
* Represents an Angular [view](guide/glossary#view),
* specifically the [host view](guide/glossary#view-tree) that is defined by a component.
* Also serves as the base class
* that adds destroy methods for [embedded views](guide/glossary#view-tree).
*
* @see `EmbeddedViewRef`
*/
export abstract class ViewRef extends ChangeDetectorRef {
/**
* Destroys the view and all of the data structures associated with it.
* Destroys this view and all of the data structures associated with it.
*/
abstract destroy(): void;
/**
* Reports whether this view has been destroyed.
* @returns True after the `destroy()` method has been called, false otherwise.
*/
abstract get destroyed(): boolean;
/**
* A lifecycle hook that provides additional developer-defined cleanup
* functionality for views.
* @param callback A handler function that cleans up developer-defined data
* associated with a view. Called when the `destroy()` method is invoked.
*/
abstract onDestroy(callback: Function): any /** TODO #9100 */;
}
/**
* Represents an Angular View.
* Represents an Angular [view](guide/glossary#view) in a view container.
* An [embedded view](guide/glossary#view-tree) can be referenced from a component
* other than the hosting component whose template defines it, or it can be defined
* independently by a `TemplateRef`.
*
* <!-- 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.
* Properties of elements in a view can change, but the structure (number and order) of elements in
* a view cannot. Change the structure of elements by inserting, moving, or
* removing nested views in a view container.
*
* 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 `ViewContainerRef`. Each View can contain many View Containers.
* <!-- /TODO -->
* @see `ViewContainerRef`
*
* @usageNotes
* ### Example
*
* Given this template...
* The following template breaks down into two separate `TemplateRef` instances,
* an outer one and and an inner one.
*
* ```
* Count: {{items.length}}
@ -44,9 +60,7 @@ export abstract class ViewRef extends ChangeDetectorRef {
* </ul>
* ```
*
* We have two `TemplateRef`s:
*
* Outer `TemplateRef`:
* This is the outer `TemplateRef`:
*
* ```
* Count: {{items.length}}
@ -55,15 +69,13 @@ export abstract class ViewRef extends ChangeDetectorRef {
* </ul>
* ```
*
* Inner `TemplateRef`:
* This is the inner `TemplateRef`:
*
* ```
* <li>{{item}}</li>
* ```
*
* Notice that the original template is broken down into two separate `TemplateRef`s.
*
* The outer/inner `TemplateRef`s are then assembled into views like so:
* The outer and inner `TemplateRef` instances are assembled into views as follows:
*
* ```
* <!-- ViewRef: outer-0 -->