@angular/core
Version:
Angular - the core framework
1,461 lines (1,413 loc) • 534 kB
TypeScript
/**
* @license Angular v15.1.5
* (c) 2010-2022 Google LLC. https://angular.io/
* License: MIT
*/
import { Observable } from 'rxjs';
import { Subject } from 'rxjs';
import { Subscribable } from 'rxjs';
import { Subscription } from 'rxjs';
/**
* @description
*
* Represents an abstract class `T`, if applied to a concrete class it would stop being
* instantiable.
*
* @publicApi
*/
export declare interface AbstractType<T> extends Function {
prototype: T;
}
/**
* @description
* A lifecycle hook that is called after the default change detector has
* completed checking all content of a directive.
*
* @see `AfterViewChecked`
* @see [Lifecycle hooks guide](guide/lifecycle-hooks)
*
* @usageNotes
* The following snippet shows how a component can implement this interface to
* define its own after-check functionality.
*
* {@example core/ts/metadata/lifecycle_hooks_spec.ts region='AfterContentChecked'}
*
* @publicApi
*/
export declare interface AfterContentChecked {
/**
* A callback method that is invoked immediately after the
* default change detector has completed checking all of the directive's
* content.
*/
ngAfterContentChecked(): void;
}
/**
* @description
* A lifecycle hook that is called after Angular has fully initialized
* all content of a directive.
* Define an `ngAfterContentInit()` method to handle any additional initialization tasks.
*
* @see `OnInit`
* @see `AfterViewInit`
* @see [Lifecycle hooks guide](guide/lifecycle-hooks)
*
* @usageNotes
* The following snippet shows how a component can implement this interface to
* define its own content initialization method.
*
* {@example core/ts/metadata/lifecycle_hooks_spec.ts region='AfterContentInit'}
*
* @publicApi
*/
export declare interface AfterContentInit {
/**
* A callback method that is invoked immediately after
* Angular has completed initialization of all of the directive's
* content.
* It is invoked only once when the directive is instantiated.
*/
ngAfterContentInit(): void;
}
/**
* @description
* A lifecycle hook that is called after the default change detector has
* completed checking a component's view for changes.
*
* @see `AfterContentChecked`
* @see [Lifecycle hooks guide](guide/lifecycle-hooks)
*
* @usageNotes
* The following snippet shows how a component can implement this interface to
* define its own after-check functionality.
*
* {@example core/ts/metadata/lifecycle_hooks_spec.ts region='AfterViewChecked'}
*
* @publicApi
*/
export declare interface AfterViewChecked {
/**
* A callback method that is invoked immediately after the
* default change detector has completed one change-check cycle
* for a component's view.
*/
ngAfterViewChecked(): void;
}
/**
* @description
* A lifecycle hook that is called after Angular has fully initialized
* a component's view.
* Define an `ngAfterViewInit()` method to handle any additional initialization tasks.
*
* @see `OnInit`
* @see `AfterContentInit`
* @see [Lifecycle hooks guide](guide/lifecycle-hooks)
*
* @usageNotes
* The following snippet shows how a component can implement this interface to
* define its own view initialization method.
*
* {@example core/ts/metadata/lifecycle_hooks_spec.ts region='AfterViewInit'}
*
* @publicApi
*/
export declare interface AfterViewInit {
/**
* A callback method that is invoked immediately after
* Angular has completed initialization of a component's view.
* It is invoked only once when the view is instantiated.
*
*/
ngAfterViewInit(): void;
}
/**
* 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) are added to the `entryComponents` property.
*
* @usageNotes
*
* The following example shows how the router can populate the `entryComponents`
* field of an NgModule based on a router configuration that refers
* to components.
*
* ```typescript
* // helper function inside the router
* function provideRoutes(routes) {
* return [
* {provide: ROUTES, useValue: routes},
* {provide: ANALYZE_FOR_ENTRY_COMPONENTS, useValue: routes, multi: true}
* ];
* }
*
* // user code
* let routes = [
* {path: '/root', component: RootComp},
* {path: '/teams', component: TeamsComp}
* ];
*
* @NgModule({
* providers: [provideRoutes(routes)]
* })
* class ModuleWithRoutes {}
* ```
*
* @publicApi
* @deprecated Since 9.0.0. With Ivy, this property is no longer necessary.
*/
export declare const ANALYZE_FOR_ENTRY_COMPONENTS: InjectionToken<any>;
/**
* A [DI token](guide/glossary#di-token "DI token definition") that indicates which animations
* module has been loaded.
* @publicApi
*/
export declare const ANIMATION_MODULE_TYPE: InjectionToken<"NoopAnimations" | "BrowserAnimations">;
/**
* A [DI token](guide/glossary#di-token "DI token definition") that provides a set of callbacks to
* be called for every component that is bootstrapped.
*
* Each callback must take a `ComponentRef` instance and return nothing.
*
* `(componentRef: ComponentRef) => void`
*
* @publicApi
*/
export declare const APP_BOOTSTRAP_LISTENER: InjectionToken<((compRef: ComponentRef<any>) => void)[]>;
/**
* A [DI token](guide/glossary#di-token "DI token definition") representing a unique string ID, used
* primarily for prefixing application attributes and CSS styles when
* {@link ViewEncapsulation#Emulated ViewEncapsulation.Emulated} is being used.
*
* BY default, the value is randomly generated and assigned to the application by Angular.
* To provide a custom ID value, use a DI provider <!-- TODO: provider --> to configure
* the root {@link Injector} that uses this token.
*
* @publicApi
*/
export declare const APP_ID: InjectionToken<string>;
/**
* A [DI token](guide/glossary#di-token "DI token definition") that you can use to provide
* one or more initialization functions.
*
* The provided functions are injected at application startup and executed during
* app initialization. If any of these functions returns a Promise or an Observable, initialization
* does not complete until the Promise is resolved or the Observable is completed.
*
* You can, for example, create a factory function that loads language data
* or an external configuration, and provide that function to the `APP_INITIALIZER` token.
* The function is executed during the application bootstrap process,
* and the needed data is available on startup.
*
* @see `ApplicationInitStatus`
*
* @usageNotes
*
* The following example illustrates how to configure a multi-provider using `APP_INITIALIZER` token
* and a function returning a promise.
*
* ```
* function initializeApp(): Promise<any> {
* return new Promise((resolve, reject) => {
* // Do some asynchronous stuff
* resolve();
* });
* }
*
* @NgModule({
* imports: [BrowserModule],
* declarations: [AppComponent],
* bootstrap: [AppComponent],
* providers: [{
* provide: APP_INITIALIZER,
* useFactory: () => initializeApp,
* multi: true
* }]
* })
* export class AppModule {}
* ```
*
* It's also possible to configure a multi-provider using `APP_INITIALIZER` token and a function
* returning an observable, see an example below. Note: the `HttpClient` in this example is used for
* demo purposes to illustrate how the factory function can work with other providers available
* through DI.
*
* ```
* function initializeAppFactory(httpClient: HttpClient): () => Observable<any> {
* return () => httpClient.get("https://someUrl.com/api/user")
* .pipe(
* tap(user => { ... })
* );
* }
*
* @NgModule({
* imports: [BrowserModule, HttpClientModule],
* declarations: [AppComponent],
* bootstrap: [AppComponent],
* providers: [{
* provide: APP_INITIALIZER,
* useFactory: initializeAppFactory,
* deps: [HttpClient],
* multi: true
* }]
* })
* export class AppModule {}
* ```
*
* @publicApi
*/
export declare const APP_INITIALIZER: InjectionToken<readonly (() => Observable<unknown> | Promise<unknown> | void)[]>;
declare function _appIdRandomProviderFactory(): string;
/**
* A class that reflects the state of running {@link APP_INITIALIZER} functions.
*
* @publicApi
*/
export declare class ApplicationInitStatus {
private readonly appInits;
private resolve;
private reject;
private initialized;
readonly donePromise: Promise<any>;
readonly done = false;
constructor(appInits: ReadonlyArray<() => Observable<unknown> | Promise<unknown> | void>);
static ɵfac: i0.ɵɵFactoryDeclaration<ApplicationInitStatus, [{ optional: true; }]>;
static ɵprov: i0.ɵɵInjectableDeclaration<ApplicationInitStatus>;
}
/**
* Re-exported by `BrowserModule`, which is included automatically in the root
* `AppModule` when you create a new app with the CLI `new` command. Eagerly injects
* `ApplicationRef` to instantiate it.
*
* @publicApi
*/
export declare class ApplicationModule {
constructor(appRef: ApplicationRef);
static ɵfac: i0.ɵɵFactoryDeclaration<ApplicationModule, never>;
static ɵmod: i0.ɵɵNgModuleDeclaration<ApplicationModule, never, never, never>;
static ɵinj: i0.ɵɵInjectorDeclaration<ApplicationModule>;
}
/**
* A reference to an Angular application running on a page.
*
* @usageNotes
*
* {@a is-stable-examples}
* ### isStable examples and caveats
*
* Note two important points about `isStable`, demonstrated in the examples below:
* - the application will never be stable if you start any kind
* of recurrent asynchronous task when the application starts
* (for example for a polling process, started with a `setInterval`, a `setTimeout`
* or using RxJS operators like `interval`);
* - the `isStable` Observable runs outside of the Angular zone.
*
* Let's imagine that you start a recurrent task
* (here incrementing a counter, using RxJS `interval`),
* and at the same time subscribe to `isStable`.
*
* ```
* constructor(appRef: ApplicationRef) {
* appRef.isStable.pipe(
* filter(stable => stable)
* ).subscribe(() => console.log('App is stable now');
* interval(1000).subscribe(counter => console.log(counter));
* }
* ```
* In this example, `isStable` will never emit `true`,
* and the trace "App is stable now" will never get logged.
*
* If you want to execute something when the app is stable,
* you have to wait for the application to be stable
* before starting your polling process.
*
* ```
* constructor(appRef: ApplicationRef) {
* appRef.isStable.pipe(
* first(stable => stable),
* tap(stable => console.log('App is stable now')),
* switchMap(() => interval(1000))
* ).subscribe(counter => console.log(counter));
* }
* ```
* In this example, the trace "App is stable now" will be logged
* and then the counter starts incrementing every second.
*
* Note also that this Observable runs outside of the Angular zone,
* which means that the code in the subscription
* to this Observable will not trigger the change detection.
*
* Let's imagine that instead of logging the counter value,
* you update a field of your component
* and display it in its template.
*
* ```
* constructor(appRef: ApplicationRef) {
* appRef.isStable.pipe(
* first(stable => stable),
* switchMap(() => interval(1000))
* ).subscribe(counter => this.value = counter);
* }
* ```
* As the `isStable` Observable runs outside the zone,
* the `value` field will be updated properly,
* but the template will not be refreshed!
*
* You'll have to manually trigger the change detection to update the template.
*
* ```
* constructor(appRef: ApplicationRef, cd: ChangeDetectorRef) {
* appRef.isStable.pipe(
* first(stable => stable),
* switchMap(() => interval(1000))
* ).subscribe(counter => {
* this.value = counter;
* cd.detectChanges();
* });
* }
* ```
*
* Or make the subscription callback run inside the zone.
*
* ```
* constructor(appRef: ApplicationRef, zone: NgZone) {
* appRef.isStable.pipe(
* first(stable => stable),
* switchMap(() => interval(1000))
* ).subscribe(counter => zone.run(() => this.value = counter));
* }
* ```
*
* @publicApi
*/
export declare class ApplicationRef {
private _zone;
private _injector;
private _exceptionHandler;
private _views;
private _runningTick;
private _stable;
private _onMicrotaskEmptySubscription;
private _destroyed;
private _destroyListeners;
/**
* Indicates whether this instance was destroyed.
*/
get destroyed(): boolean;
/**
* Get a list of component types registered to this application.
* This list is populated even before the component is created.
*/
readonly componentTypes: Type<any>[];
/**
* Get a list of components registered to this application.
*/
readonly components: ComponentRef<any>[];
/**
* Returns an Observable that indicates when the application is stable or unstable.
*
* @see [Usage notes](#is-stable-examples) for examples and caveats when using this API.
*/
readonly isStable: Observable<boolean>;
/**
* The `EnvironmentInjector` used to create this application.
*/
get injector(): EnvironmentInjector;
/**
* Bootstrap a component onto the element identified by its selector or, optionally, to a
* specified element.
*
* @usageNotes
* ### Bootstrap process
*
* When bootstrapping a component, Angular mounts it onto a target DOM element
* and kicks off automatic change detection. The target DOM element can be
* provided using the `rootSelectorOrNode` argument.
*
* If the target DOM element is not provided, Angular tries to find one on a page
* using the `selector` of the component that is being bootstrapped
* (first matched element is used).
*
* ### Example
*
* Generally, we define the component to bootstrap in the `bootstrap` array of `NgModule`,
* but it requires us to know the component while writing the application code.
*
* Imagine a situation where we have to wait for an API call to decide about the component to
* bootstrap. We can use the `ngDoBootstrap` hook of the `NgModule` and call this method to
* dynamically bootstrap a component.
*
* {@example core/ts/platform/platform.ts region='componentSelector'}
*
* Optionally, a component can be mounted onto a DOM element that does not match the
* selector of the bootstrapped component.
*
* In the following example, we are providing a CSS selector to match the target element.
*
* {@example core/ts/platform/platform.ts region='cssSelector'}
*
* While in this example, we are providing reference to a DOM node.
*
* {@example core/ts/platform/platform.ts region='domNode'}
*/
bootstrap<C>(component: Type<C>, rootSelectorOrNode?: string | any): ComponentRef<C>;
/**
* Bootstrap a component onto the element identified by its selector or, optionally, to a
* specified element.
*
* @usageNotes
* ### Bootstrap process
*
* When bootstrapping a component, Angular mounts it onto a target DOM element
* and kicks off automatic change detection. The target DOM element can be
* provided using the `rootSelectorOrNode` argument.
*
* If the target DOM element is not provided, Angular tries to find one on a page
* using the `selector` of the component that is being bootstrapped
* (first matched element is used).
*
* ### Example
*
* Generally, we define the component to bootstrap in the `bootstrap` array of `NgModule`,
* but it requires us to know the component while writing the application code.
*
* Imagine a situation where we have to wait for an API call to decide about the component to
* bootstrap. We can use the `ngDoBootstrap` hook of the `NgModule` and call this method to
* dynamically bootstrap a component.
*
* {@example core/ts/platform/platform.ts region='componentSelector'}
*
* Optionally, a component can be mounted onto a DOM element that does not match the
* selector of the bootstrapped component.
*
* In the following example, we are providing a CSS selector to match the target element.
*
* {@example core/ts/platform/platform.ts region='cssSelector'}
*
* While in this example, we are providing reference to a DOM node.
*
* {@example core/ts/platform/platform.ts region='domNode'}
*
* @deprecated Passing Component factories as the `Application.bootstrap` function argument is
* deprecated. Pass Component Types instead.
*/
bootstrap<C>(componentFactory: ComponentFactory<C>, rootSelectorOrNode?: string | any): ComponentRef<C>;
/**
* Invoke this method to explicitly process change detection and its side-effects.
*
* In development mode, `tick()` also performs a second change detection cycle to ensure that no
* further changes are detected. If additional changes are picked up during this second cycle,
* bindings in the app have side-effects that cannot be resolved in a single change detection
* pass.
* In this case, Angular throws an error, since an Angular application can only have one change
* detection pass during which all change detection must complete.
*/
tick(): void;
/**
* Attaches a view so that it will be dirty checked.
* The view will be automatically detached when it is destroyed.
* This will throw if the view is already attached to a ViewContainer.
*/
attachView(viewRef: ViewRef): void;
/**
* Detaches a view from dirty checking again.
*/
detachView(viewRef: ViewRef): void;
private _loadComponent;
/**
* Destroys an Angular application represented by this `ApplicationRef`. Calling this function
* will destroy the associated environment injectors as well as all the bootstrapped components
* with their views.
*/
destroy(): void;
/**
* Returns the number of attached views.
*/
get viewCount(): number;
private warnIfDestroyed;
static ɵfac: i0.ɵɵFactoryDeclaration<ApplicationRef, never>;
static ɵprov: i0.ɵɵInjectableDeclaration<ApplicationRef>;
}
/**
* @publicApi
*/
export declare function asNativeElements(debugEls: DebugElement[]): any;
/**
* Checks that there is currently a platform that contains the given token as a provider.
*
* @publicApi
*/
export declare function assertPlatform(requiredToken: any): PlatformRef;
/**
* Type of the Attribute metadata.
*
* @publicApi
*/
export declare interface Attribute {
/**
* The name of the attribute whose value can be injected.
*/
attributeName: string;
}
/**
* Attribute decorator and metadata.
*
* @Annotation
* @publicApi
*/
export declare const Attribute: AttributeDecorator;
/**
* Type of the Attribute decorator / constructor function.
*
* @publicApi
*/
export declare interface AttributeDecorator {
/**
* Parameter decorator for a directive constructor that designates
* a host-element attribute whose value is injected as a constant string literal.
*
* @usageNotes
*
* Suppose we have an `<input>` element and want to know its `type`.
*
* ```html
* <input type="text">
* ```
*
* The following example uses the decorator to inject the string literal `text` in a directive.
*
* {@example core/ts/metadata/metadata.ts region='attributeMetadata'}
*
* The following example uses the decorator in a component constructor.
*
* {@example core/ts/metadata/metadata.ts region='attributeFactory'}
*
*/
(name: string): any;
new (name: string): Attribute;
}
/**
* Provides additional options to the bootstrapping process.
*
* @publicApi
*/
export declare interface BootstrapOptions {
/**
* Optionally specify which `NgZone` should be used.
*
* - Provide your own `NgZone` instance.
* - `zone.js` - Use default `NgZone` which requires `Zone.js`.
* - `noop` - Use `NoopNgZone` which does nothing.
*/
ngZone?: NgZone | 'zone.js' | 'noop';
/**
* Optionally specify coalescing event change detections or not.
* Consider the following case.
*
* ```
* <div (click)="doSomething()">
* <button (click)="doSomethingElse()"></button>
* </div>
* ```
*
* When button is clicked, because of the event bubbling, both
* event handlers will be called and 2 change detections will be
* triggered. We can coalesce such kind of events to only trigger
* change detection only once.
*
* By default, this option will be false. So the events will not be
* coalesced and the change detection will be triggered multiple times.
* And if this option be set to true, the change detection will be
* triggered async by scheduling a animation frame. So in the case above,
* the change detection will only be triggered once.
*/
ngZoneEventCoalescing?: boolean;
/**
* Optionally specify if `NgZone#run()` method invocations should be coalesced
* into a single change detection.
*
* Consider the following case.
* ```
* for (let i = 0; i < 10; i ++) {
* ngZone.run(() => {
* // do something
* });
* }
* ```
*
* This case triggers the change detection multiple times.
* With ngZoneRunCoalescing options, all change detections in an event loop trigger only once.
* In addition, the change detection executes in requestAnimation.
*
*/
ngZoneRunCoalescing?: boolean;
}
/**
* The strategy that the default change detector uses to detect changes.
* When set, takes effect the next time change detection is triggered.
*
* @see {@link ChangeDetectorRef#usage-notes Change detection usage}
*
* @publicApi
*/
export declare enum ChangeDetectionStrategy {
/**
* 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 explicitly invoked.
* This strategy applies to all child directives and cannot be overridden.
*/
OnPush = 0,
/**
* Use the default `CheckAlways` strategy, in which change detection is automatic until
* explicitly deactivated.
*/
Default = 1
}
declare type ChangeDetectionStrategy_2 = number;
/**
* Base class that 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 explicitly mark views as _dirty_, meaning that they have changed and need to be re-rendered.
*
* @see [Using change detection hooks](guide/lifecycle-hooks#using-change-detection-hooks)
* @see [Defining custom change detection](guide/lifecycle-hooks#defining-custom-change-detection)
*
* @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](https://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="reattach"></code-example>
*
* @publicApi
*/
export declare abstract class ChangeDetectorRef {
/**
* 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.
*
* 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 occurred.
*
* <!-- TODO: Add a link to a chapter on OnPush components -->
*
*/
abstract markForCheck(): void;
/**
* 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 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 -->
*
*/
abstract detach(): void;
/**
* 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 -->
*
*/
abstract detectChanges(): void;
/**
* Checks the change detector and its children, and throws if any changes are detected.
*
* Use in development mode to verify that running change detection doesn't introduce
* other changes. Calling it in production mode is a noop.
*/
abstract checkNoChanges(): void;
/**
* 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 -->
*
*/
abstract reattach(): void;
}
declare const CHILD_HEAD = 13;
declare const CHILD_TAIL = 14;
/**
* Configures the `Injector` to return an instance of `useClass` for a token.
* @see ["Dependency Injection Guide"](guide/dependency-injection).
*
* @usageNotes
*
* {@example core/di/ts/provider_spec.ts region='ClassProvider'}
*
* Note that following two providers are not equal:
*
* {@example core/di/ts/provider_spec.ts region='ClassProviderDifference'}
*
* ### Multi-value example
*
* {@example core/di/ts/provider_spec.ts region='MultiProviderAspect'}
*
* @publicApi
*/
export declare interface ClassProvider extends ClassSansProvider {
/**
* An injection token. (Typically an instance of `Type` or `InjectionToken`, but can be `any`).
*/
provide: any;
/**
* When true, injector returns an array of instances. This is useful to allow multiple
* providers spread across many files to provide configuration information to a common token.
*/
multi?: boolean;
}
/**
* Configures the `Injector` to return a value by invoking a `useClass` function.
* Base for `ClassProvider` decorator.
*
* @see ["Dependency Injection Guide"](guide/dependency-injection).
*
* @publicApi
*/
export declare interface ClassSansProvider {
/**
* Class to instantiate for the `token`.
*/
useClass: Type<any>;
}
declare const CLEANUP = 7;
/**
* Low-level service for running the angular compiler during runtime
* to create {@link ComponentFactory}s, which
* can later be used to create and render a Component instance.
*
* Each `@NgModule` provides an own `Compiler` to its injector,
* that will use the directives/pipes of the ng module for compilation
* of components.
*
* @publicApi
*
* @deprecated
* Ivy JIT mode doesn't require accessing this symbol.
* See [JIT API changes due to ViewEngine deprecation](guide/deprecations#jit-api-changes) for
* additional context.
*/
export declare class Compiler {
/**
* Compiles the given NgModule and all of its components. All templates of the components listed
* in `entryComponents` have to be inlined.
*/
compileModuleSync<T>(moduleType: Type<T>): NgModuleFactory<T>;
/**
* Compiles the given NgModule and all of its components
*/
compileModuleAsync<T>(moduleType: Type<T>): Promise<NgModuleFactory<T>>;
/**
* Same as {@link #compileModuleSync} but also creates ComponentFactories for all components.
*/
compileModuleAndAllComponentsSync<T>(moduleType: Type<T>): ModuleWithComponentFactories<T>;
/**
* Same as {@link #compileModuleAsync} but also creates ComponentFactories for all components.
*/
compileModuleAndAllComponentsAsync<T>(moduleType: Type<T>): Promise<ModuleWithComponentFactories<T>>;
/**
* Clears all caches.
*/
clearCache(): void;
/**
* Clears the cache for the given component/ngModule.
*/
clearCacheFor(type: Type<any>): void;
/**
* Returns the id for a given NgModule, if one is defined and known to the compiler.
*/
getModuleId(moduleType: Type<any>): string | undefined;
static ɵfac: i0.ɵɵFactoryDeclaration<Compiler, never>;
static ɵprov: i0.ɵɵInjectableDeclaration<Compiler>;
}
/**
* Token to provide CompilerOptions in the platform injector.
*
* @publicApi
*/
export declare const COMPILER_OPTIONS: InjectionToken<CompilerOptions[]>;
/**
* A factory for creating a Compiler
*
* @publicApi
*
* @deprecated
* Ivy JIT mode doesn't require accessing this symbol.
* See [JIT API changes due to ViewEngine deprecation](guide/deprecations#jit-api-changes) for
* additional context.
*/
export declare abstract class CompilerFactory {
abstract createCompiler(options?: CompilerOptions[]): Compiler;
}
/**
* Options for creating a compiler.
*
* Note: the `useJit` and `missingTranslation` config options are not used in Ivy, passing them has
* no effect. Those config options are deprecated since v13.
*
* @publicApi
*/
export declare type CompilerOptions = {
/**
* @deprecated not used at all in Ivy, providing this config option has no effect.
*/
useJit?: boolean;
defaultEncapsulation?: ViewEncapsulation;
providers?: StaticProvider[];
/**
* @deprecated not used at all in Ivy, providing this config option has no effect.
*/
missingTranslation?: MissingTranslationStrategy;
preserveWhitespaces?: boolean;
};
/**
* Supplies configuration metadata for an Angular component.
*
* @publicApi
*/
export declare interface Component extends Directive {
/**
* The change-detection strategy to use for this component.
*
* When a component is instantiated, Angular creates a change detector,
* which is responsible for propagating the component's bindings.
* The strategy is one of:
* - `ChangeDetectionStrategy#OnPush` sets the strategy to `CheckOnce` (on demand).
* - `ChangeDetectionStrategy#Default` sets the strategy to `CheckAlways`.
*/
changeDetection?: ChangeDetectionStrategy;
/**
* Defines the set of injectable objects that are visible to its view DOM children.
* See [example](#injecting-a-class-with-a-view-provider).
*
*/
viewProviders?: Provider[];
/**
* The module ID of the module that contains the component.
* The component must be able to resolve relative URLs for templates and styles.
* SystemJS exposes the `__moduleName` variable within each module.
* In CommonJS, this can be set to `module.id`.
*
*/
moduleId?: string;
/**
* The relative path or absolute URL of a template file for an Angular component.
* If provided, do not supply an inline template using `template`.
*
*/
templateUrl?: string;
/**
* An inline template for an Angular component. If provided,
* do not supply a template file using `templateUrl`.
*
*/
template?: string;
/**
* One or more relative paths or absolute URLs for files containing CSS stylesheets to use
* in this component.
*/
styleUrls?: string[];
/**
* One or more inline CSS stylesheets to use
* in this component.
*/
styles?: string[];
/**
* One or more animation `trigger()` calls, containing
* [`state()`](api/animations/state) and `transition()` definitions.
* See the [Animations guide](/guide/animations) and animations API documentation.
*
*/
animations?: any[];
/**
* An encapsulation policy for the component's styling.
* Possible values:
* - `ViewEncapsulation.Emulated`: Apply modified component styles in order to emulate
* a native Shadow DOM CSS encapsulation behavior.
* - `ViewEncapsulation.None`: Apply component styles globally without any sort of encapsulation.
* - `ViewEncapsulation.ShadowDom`: Use the browser's native Shadow DOM API to encapsulate styles.
*
* If not supplied, the value is taken from the `CompilerOptions`
* which defaults to `ViewEncapsulation.Emulated`.
*
* If the policy is `ViewEncapsulation.Emulated` and the component has no
* {@link Component#styles styles} nor {@link Component#styleUrls styleUrls},
* the policy is automatically switched to `ViewEncapsulation.None`.
*/
encapsulation?: ViewEncapsulation;
/**
* Overrides the default interpolation start and end delimiters (`{{` and `}}`).
*/
interpolation?: [string, string];
/**
* A set of components that should be compiled along with
* this component. For each component listed here,
* Angular creates a {@link ComponentFactory} and stores it in the
* {@link ComponentFactoryResolver}.
* @deprecated Since 9.0.0. With Ivy, this property is no longer necessary.
*/
entryComponents?: Array<Type<any> | any[]>;
/**
* True to preserve or false to remove potentially superfluous whitespace characters
* from the compiled template. Whitespace characters are those matching the `\s`
* character class in JavaScript regular expressions. Default is false, unless
* overridden in compiler options.
*/
preserveWhitespaces?: boolean;
/**
* Angular components marked as `standalone` do not need to be declared in an NgModule. Such
* components directly manage their own template dependencies (components, directives, and pipes
* used in a template) via the imports property.
*
* More information about standalone components, directives, and pipes can be found in [this
* guide](guide/standalone-components).
*/
standalone?: boolean;
/**
* The imports property specifies the standalone component's template dependencies — those
* directives, components, and pipes that can be used within its template. Standalone components
* can import other standalone components, directives, and pipes as well as existing NgModules.
*
* This property is only available for standalone components - specifying it for components
* declared in an NgModule generates a compilation error.
*
* More information about standalone components, directives, and pipes can be found in [this
* guide](guide/standalone-components).
*/
imports?: (Type<any> | ReadonlyArray<any>)[];
/**
* The set of schemas that declare elements to be allowed in a standalone component. Elements and
* properties that are neither Angular components nor directives must be declared in a schema.
*
* This property is only available for standalone components - specifying it for components
* declared in an NgModule generates a compilation error.
*
* More information about standalone components, directives, and pipes can be found in [this
* guide](guide/standalone-components).
*/
schemas?: SchemaMetadata[];
}
/**
* Component decorator and metadata.
*
* @Annotation
* @publicApi
*/
export declare const Component: ComponentDecorator;
/**
* Component decorator interface
*
* @publicApi
*/
export declare interface ComponentDecorator {
/**
* Decorator that marks a class as an Angular component and provides configuration
* metadata that determines how the component should be processed,
* instantiated, and used at runtime.
*
* Components are the most basic UI building block of an Angular app.
* An Angular app contains a tree of Angular components.
*
* Angular components are a subset of directives, always associated with a template.
* Unlike other directives, only one component can be instantiated for a given element in a
* template.
*
* A component must belong to an NgModule in order for it to be available
* to another component or application. To make it a member of an NgModule,
* list it in the `declarations` field of the `NgModule` metadata.
*
* Note that, in addition to these options for configuring a directive,
* you can control a component's runtime behavior by implementing
* life-cycle hooks. For more information, see the
* [Lifecycle Hooks](guide/lifecycle-hooks) guide.
*
* @usageNotes
*
* ### Setting component inputs
*
* The following example creates a component with two data-bound properties,
* specified by the `inputs` value.
*
* <code-example path="core/ts/metadata/directives.ts" region="component-input"></code-example>
*
*
* ### Setting component outputs
*
* The following example shows two event emitters that emit on an interval. One
* emits an output every second, while the other emits every five seconds.
*
* {@example core/ts/metadata/directives.ts region='component-output-interval'}
*
* ### Injecting a class with a view provider
*
* The following simple example injects a class into a component
* using the view provider specified in component metadata:
*
* ```ts
* class Greeter {
* greet(name:string) {
* return 'Hello ' + name + '!';
* }
* }
*
* @Directive({
* selector: 'needs-greeter'
* })
* class NeedsGreeter {
* greeter:Greeter;
*
* constructor(greeter:Greeter) {
* this.greeter = greeter;
* }
* }
*
* @Component({
* selector: 'greet',
* viewProviders: [
* Greeter
* ],
* template: `<needs-greeter></needs-greeter>`
* })
* class HelloWorld {
* }
*
* ```
*
* ### Preserving whitespace
*
* Removing whitespace can greatly reduce AOT-generated code size and speed up view creation.
* As of Angular 6, the default for `preserveWhitespaces` is false (whitespace is removed).
* To change the default setting for all components in your application, set
* the `preserveWhitespaces` option of the AOT compiler.
*
* By default, the AOT compiler removes whitespace characters as follows:
* * Trims all whitespaces at the beginning and the end of a template.
* * Removes whitespace-only text nodes. For example,
*
* ```html
* <button>Action 1</button> <button>Action 2</button>
* ```
*
* becomes:
*
* ```html
* <button>Action 1</button><button>Action 2</button>
* ```
*
* * Replaces a series of whitespace characters in text nodes with a single space.
* For example, `<span>\n some text\n</span>` becomes `<span> some text </span>`.
* * Does NOT alter text nodes inside HTML tags such as `<pre>` or `<textarea>`,
* where whitespace characters are significant.
*
* Note that these transformations can influence DOM nodes layout, although impact
* should be minimal.
*
* You can override the default behavior to preserve whitespace characters
* in certain fragments of a template. For example, you can exclude an entire
* DOM sub-tree by using the `ngPreserveWhitespaces` attribute:
*
* ```html
* <div ngPreserveWhitespaces>
* whitespaces are preserved here
* <span> and here </span>
* </div>
* ```
*
* You can force a single space to be preserved in a text node by using `&ngsp;`,
* which is replaced with a space character by Angular's template
* compiler:
*
* ```html
* <a>Spaces</a>&ngsp;<a>between</a>&ngsp;<a>links.</a>
* <!-- compiled to be equivalent to:
* <a>Spaces</a> <a>between</a> <a>links.</a> -->
* ```
*
* Note that sequences of `&ngsp;` are still collapsed to just one space character when
* the `preserveWhitespaces` option is set to `false`.
*
* ```html
* <a>before</a>&ngsp;&ngsp;&ngsp;<a>after</a>
* <!-- compiled to be equivalent to:
* <a>before</a> <a>after</a> -->
* ```
*
* To preserve sequences of whitespace characters, use the
* `ngPreserveWhitespaces` attribute.
*
* @Annotation
*/
(obj: Component): TypeDecorator;
/**
* See the `Component` decorator.
*/
new (obj: Component): Component;
}
declare interface ComponentDefFeature {
<T>(componentDef: ɵComponentDef<T>): void;
/**
* Marks a feature as something that {@link InheritDefinitionFeature} will execute
* during inheritance.
*
* NOTE: DO NOT SET IN ROOT OF MODULE! Doing so will result in tree-shakers/bundlers
* identifying the change as a side effect, and the feature will be included in
* every bundle.
*/
ngInherit?: true;
}
/**
* Base class for a factory that can create a component dynamically.
* Instantiate a factory for a given type of component with `resolveComponentFactory()`.
* Use the resulting `ComponentFactory.create()` method to create a component of that type.
*
* @see [Dynamic Components](guide/dynamic-component-loader)
*
* @publicApi
*
* @deprecated Angular no longer requires Component factories. Please use other APIs where
* Component class can be used directly.
*/
declare abstract class ComponentFactory<C> {
/**
* The component's HTML selector.
*/
abstract get selector(): string;
/**
* The type of component the factory will create.
*/
abstract get componentType(): Type<any>;
/**
* Selector for all <ng-content> elements in the component.
*/
abstract get ngContentSelectors(): string[];
/**
* The inputs of the component.
*/
abstract get inputs(): {
propName: string;
templateName: string;
}[];
/**
* The outputs of the component.
*/
abstract get outputs(): {
propName: string;
templateName: string;
}[];
/**
* Creates a new component.
*/
abstract create(injector: Injector, projectableNodes?: any[][], rootSelectorOrNode?: string | any, environmentInjector?: EnvironmentInjector | NgModuleRef<any>): ComponentRef<C>;
}
export { ComponentFactory }
export { ComponentFactory as ɵComponentFactory }
/**
* A simple registry that maps `Components` to generated `ComponentFactory` classes
* that can be used to create instances of components.
* Use to obtain the factory for a given component type,
* then use the factory's `create()` method to create a component of that type.
*
* Note: since v13, dynamic component creation via
* [`ViewContainerRef.createComponent`](api/core/ViewContainerRef#createComponent)
* does **not** require resolving component factory: component class can be used directly.
*
* @publicApi
*
* @deprecated Angular no longer requires Component factories. Please use other APIs where
* Component class can be used directly.
*/
export declare abstract class ComponentFactoryResolver {
static NULL: ComponentFactoryResolver;
/**
* Retrieves the factory object that creates a component of the given type.
* @param component The component type.
*/
abstract resolveComponentFactory<T>(component: Type<T>): ComponentFactory<T>;
}
declare class ComponentFactoryResolver_2 extends ComponentFactoryResolver {
private ngModule?;
/**
* @param ngModule The NgModuleRef to which all resolved factories are bound.
*/
constructor(ngModule?: NgModuleRef<any> | undefined);
resolveComponentFactory<T>(component: Type<T>): ComponentFactory<T>;
}
/**
* An interface that describes the subset of component metadata
* that can be retrieved using the `reflectComponentType` function.
*
* @publicApi
*/
export declare interface ComponentMirror<C> {
/**
* The component's HTML selector.
*/
get selector(): string;
/**
* The type of component the factory will create.
*/
get type(): Type<C>;
/**
* The inputs of the component.
*/
get inputs(): ReadonlyArray<{
readonly propName: string;
readonly templateName: string;
}>;
/**
* The outputs of the component.
*/
get outputs(): ReadonlyArray<{
readonly propName: string;
readonly templateName: string;
}>;
/**
* Selector for all <ng-content> elements in the component.
*/
get ngContentSelectors(): ReadonlyArray<string>;
/**
* Whether this component is marked as standalone.
* Note: an extra flag, not present in `ComponentFactory`.
*/
get isStandalone(): boolean;
}
/**
* Represents a component created by a `ComponentFactory`.
* Provides access to the component instance and related objects,
* and provides the means of destroying the instance.
*
* @publicApi
*/
export declare abstract class ComponentRef<C> {
/**
* Updates a specified input name to a new value. Using this method will properly mark for check
* component using the `OnPush` change detection strategy. It will also assure that the
* `OnChanges` lifecycle hook runs when a dynamically created component is change-detected.
*
* @param name The name of an input.
* @param value The new value of an input.
*/
abstract setInput(name: string, value: unknown): void;
/**
* The host or anchor [element](guide/glossary#element) for this component instance.
*/
abstract get location(): ElementRef;
/**
* The [dependency injector](guide/glossary#injector) for this component instance.
*/
abstract get injector(): Injector;
/**
* This component instance.
*/
abstract get instance(): C;
/**
* The [host view](guide/glossary#view-tree) defined by the template
* for this component instance.
*/
abstract get hostView(): ViewRef;
/**
* The change detector for this component instance.
*/
abstract get changeDetectorRef(): ChangeDetectorRef;
/**
* The type of this component (as created by a `ComponentFactory` class).
*/
abstract get componentType(): Type<any>;
/**
* Destroys the component instance and all of the data structures associated with it.
*/
abstract destroy(): void;
/**
* 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;
}
/**
* Definition of what a template rendering function should look like for a component.
*/
declare type ComponentTemplate<T> = {
<U extends T>(rf: ɵRenderFlags, ctx: T | U): void;
};
/**
* Configures the `Injector` to return an instance of a token.
*
* @see ["Dependency Injection Guide"](guide/dependency-injection).
*
* @usageNotes
*
* {@example core/di/ts/provider_spec.ts region='ConstructorProvider'}
*
* ### Multi-value example
*
* {@example core/di/ts/provider_spec.ts region='MultiProviderAspect'}
*
* @publicApi
*/
export declare interface ConstructorProvider extends ConstructorSansProvider {
/**
* An injection token. Typically an instance of `Type` or `InjectionToken`, but can be `any`.
*/
provide: Type<any>;
/**
* When true, injector returns an array of instances. This is useful to allow multiple
* providers spread across many files to provide configuration information to a common token.
*/
multi?: boolean;
}
/**
* Configures the `Injector` to return an instance of a token.
*
* @see ["Dependency Injection Guide"](guide/dependency-injection).
*
* @usageNotes
*
* ```ts
* @Injectable(SomeModule, {deps: []})
* class MyService {}
* ```
*
* @publicApi
*/
export declare interfac