cargdev/angular
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add api doc to commonly queried elements

Browse Source
This commit is contained in:
Judy Bogart
2018-07-02 12:06:52 -07:00
committed by Victor Berchet
parent 86203736e9
commit f1ab394218
11 changed files with 712 additions and 473 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@ -6,179 +6,101 @@
* found in the LICENSE file at https://angular.io/license
*/
/**
* Base class for Angular Views, provides change detection functionality.
* A change-detection tree collects all views that are to be checked for changes.
* Use the methods to add and remove views from the tree, initiate change-detection,
* and exlicitly mark views as _dirty_, meaning that they have changed and need to be rerendered.
*
* @usageNotes
*
* The following examples demonstrate how to modify default change-detection behavior
* to perform explicit detection when needed.
*
* ### Use `markForCheck()` with `checkOnce` strategy
*
* The following example sets the `OnPush` change-detection strategy for a component
* (`checkOnce`, rather than the default `checkAlways`), then forces a second check
* after an interval. See [live demo](http://plnkr.co/edit/GC512b?p=preview).
*
* <code-example path="core/ts/change_detect/change-detection.ts"
* region="mark-for-check"></code-example>
*
* ### Detach change detector to limit how often check occurs
*
* The following example defines a component with a large list of read-only data
* that is expected to change constantly, many times per second.
* To improve performance, we want to check and update the list
* less often than the changes actually occur. To do that, we detach
* the component's change detector and perform an explicit local check every five seconds.
*
* <code-example path="core/ts/change_detect/change-detection.ts" region="detach"></code-example>
*
*
* ### Reattaching a detached component
*
* The following example creates a component displaying live data.
* The component detaches its change detector from the main change detector tree
* 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>
*
*/
export abstract class ChangeDetectorRef {
/**
* Marks a view and all of its ancestors dirty.
* When a view uses the {@link ChangeDetectionStrategy#OnPush OnPush} (checkOnce)
* change detection strategy, explicitly marks the view as changed so that
* it can be checked again.
*
* This can be used to ensure an {@link ChangeDetectionStrategy#OnPush OnPush} component is
* checked when it needs to be re-rendered but the two normal triggers haven't marked it
* dirty (i.e. inputs haven't changed and events haven't fired in the view).
* Components are normally marked as dirty (in need of rerendering) when inputs
* have changed or events have fired in the view. Call this method to ensure that
* a component is checked even if these triggers have not occured.
*
* <!-- TODO: Add a link to a chapter on OnPush components -->
*
* @usageNotes
* ### Example
*
* ```typescript
* @Component({
* selector: 'my-app',
* template: `Number of ticks: {{numberOfTicks}}`
* changeDetection: ChangeDetectionStrategy.OnPush,
* })
* class AppComponent {
* numberOfTicks = 0;
*
* constructor(private ref: ChangeDetectorRef) {
* setInterval(() => {
* this.numberOfTicks++;
* // the following is required, otherwise the view will not be updated
* this.ref.markForCheck();
* }, 1000);
* }
* }
* ```
*/
abstract markForCheck(): void;
/**
* Detaches the view from the change detection tree.
* Detaches this view from the change-detection tree.
* A detached view is not checked until it is reattached.
* Use in combination with `detectChanges()` to implement local change detection checks.
*
* Detached views will not be checked during change detection runs until they are
* re-attached, even if they are dirty. `detach` can be used in combination with
* {@link ChangeDetectorRef#detectChanges detectChanges} to implement local change
* detection checks.
* Detached views are not checked during change detection runs until they are
* re-attached, even if they are marked as dirty.
*
* <!-- TODO: Add a link to a chapter on detach/reattach/local digest -->
* <!-- TODO: Add a live demo once ref.detectChanges is merged into master -->
*
* @usageNotes
* ### Example
*
* The following example defines a component with a large list of readonly data.
* Imagine the data changes constantly, many times per second. For performance reasons,
* we want to check and update the list every five seconds. We can do that by detaching
* the component's change detector and doing a local check every five seconds.
*
* ```typescript
* class DataProvider {
* // in a real application the returned data will be different every time
* get data() {
* return [1,2,3,4,5];
* }
* }
*
* @Component({
* selector: 'giant-list',
* template: `
* <li *ngFor="let d of dataProvider.data">Data {{d}}</li>
* `,
* })
* class GiantList {
* constructor(private ref: ChangeDetectorRef, private dataProvider: DataProvider) {
* ref.detach();
* setInterval(() => {
* this.ref.detectChanges();
* }, 5000);
* }
* }
*
* @Component({
* selector: 'app',
* providers: [DataProvider],
* template: `
* <giant-list><giant-list>
* `,
* })
* class App {
* }
* ```
*/
abstract detach(): void;
/**
* Checks the view and its children.
*
* This can also be used in combination with {@link ChangeDetectorRef#detach detach} to implement
* local change detection checks.
* Checks this view and its children. Use in combination with {@link ChangeDetectorRef#detach
* detach}
* to implement local change detection checks.
*
* <!-- TODO: Add a link to a chapter on detach/reattach/local digest -->
* <!-- TODO: Add a live demo once ref.detectChanges is merged into master -->
*
* @usageNotes
*
* Imagine, the data changes constantly, many times per second. For performance reasons,
* we want to check and update the list every five seconds.
*
* We can do that by detaching the component's change detector and doing a local change detection
* check every five seconds.
*
* See {@link ChangeDetectorRef#detach detach} for more information.
*/
abstract detectChanges(): void;
/**
* Checks the change detector and its children, and throws if any changes are detected.
*
* This is used in development mode to verify that running change detection doesn't introduce
* Use in development mode to verify that running change detection doesn't introduce
* other changes.
*/
abstract checkNoChanges(): void;
/**
* Re-attaches the view to the change detection tree.
*
* This can be used to re-attach views that were previously detached from the tree
* using {@link ChangeDetectorRef#detach detach}. Views are attached to the tree by default.
* Re-attaches the previously detached view to the change detection tree.
* Views are attached to the tree by default.
*
* <!-- TODO: Add a link to a chapter on detach/reattach/local digest -->
*
* @usageNotes
* ### Example
*
* The following example creates a component displaying `live` data. The component will detach
* its change detector from the main change detector tree when the component's live property
* is set to false.
*
* ```typescript
* class DataProvider {
* data = 1;
*
* constructor() {
* setInterval(() => {
* this.data = this.data * 2;
* }, 500);
* }
* }
*
* @Component({
* selector: 'live-data',
* inputs: ['live'],
* template: 'Data: {{dataProvider.data}}'
* })
* class LiveData {
* constructor(private ref: ChangeDetectorRef, private dataProvider: DataProvider) {}
*
* set live(value) {
* if (value) {
* this.ref.reattach();
* } else {
* this.ref.detach();
* }
* }
* }
*
* @Component({
* selector: 'my-app',
* providers: [DataProvider],
* template: `
* Live Update: <input type="checkbox" [(ngModel)]="live">
* <live-data [live]="live"><live-data>
* `,
* })
* class AppComponent {
* live = true;
* }
* ```
*/
abstract reattach(): void;
}

41
packages/core/src/change_detection/constants.ts
View File

@ -8,63 +8,74 @@
/**
* Describes within the change detector which strategy will be used the next time change
* detection is triggered.
* The strategy that the default change detector uses to detect changes.
* When set, takes effect the next time change detection is triggered.
*
*/
export enum ChangeDetectionStrategy {
/**
* `OnPush` means that the change detector's mode will be initially set to `CheckOnce`.
* Use the `CheckOnce` strategy, meaning that automatic change detection is deactivated
* until reactivated by setting the strategy to `Default` (`CheckAlways`).
* Change detection can still be explictly invoked.
*/
OnPush = 0,
/**
* `Default` means that the change detector's mode will be initially set to `CheckAlways`.
* Use the default `CheckAlways` strategy, in which change detection is automatic until
* explicitly deactivated.
*/
Default = 1,
}
/**
* Describes the status of the detector.
* Defines the possible states of the default change detector.
* @see `ChangeDetectorRef`
*/
export enum ChangeDetectorStatus {
/**
* `CheckOnce` means that after calling detectChanges the mode of the change detector
* will become `Checked`.
* A state in which, after calling `detectChanges()`, the change detector
* state becomes `Checked`, and must be explicitly invoked or reactivated.
*/
CheckOnce,
/**
* `Checked` means that the change detector should be skipped until its mode changes to
* `CheckOnce`.
* A state in which change detection is skipped until the change detector mode
* becomes `CheckOnce`.
*/
Checked,
/**
* `CheckAlways` means that after calling detectChanges the mode of the change detector
* will remain `CheckAlways`.
* A state in which change detection continues automatically until explictly
* deactivated.
*/
CheckAlways,
/**
* `Detached` means that the change detector sub tree is not a part of the main tree and
* A state in which a change detector sub tree is not a part of the main tree and
* should be skipped.
*/
Detached,
/**
* `Errored` means that the change detector encountered an error checking a binding
* Indicates that the change detector encountered an error checking a binding
* or calling a directive lifecycle method and is now in an inconsistent state. Change
* detectors in this state will no longer detect changes.
* detectors in this state do not detect changes.
*/
Errored,
/**
* `Destroyed` means that the change detector is destroyed.
* Indicates that the change detector has been destroyed.
*/
Destroyed,
}
/**
* Reports whether a given strategy is currently the default for change detection.
* @param changeDetectionStrategy The strategy to check.
* @returns True if the given strategy is the current default, false otherwise.
* @see `ChangeDetectorStatus`
* @see `ChangeDetectorRef`
*/
export function isDefaultChangeDetectionStrategy(changeDetectionStrategy: ChangeDetectionStrategy):
boolean {
return changeDetectionStrategy == null ||