@angular/core
Version:
Angular - the core framework
1,489 lines (1,436 loc) • 646 kB
TypeScript
/**
* @license Angular v18.1.0
* (c) 2010-2024 Google LLC. https://angular.io/
* License: MIT
*/
import { BehaviorSubject } from 'rxjs';
import { EnvironmentProviders as EnvironmentProviders_2 } from '@angular/core';
import { EventContract } from '@angular/core/primitives/event-dispatch';
import { Observable } from 'rxjs';
import { ReactiveNode } from '@angular/core/primitives/signals';
import { SIGNAL } from '@angular/core/primitives/signals';
import { SignalNode } from '@angular/core/primitives/signals';
import { Subject } from 'rxjs';
import { Subscribable } from 'rxjs';
import { Subscription } from 'rxjs';
import { ɵProfiler as ɵProfiler_2 } from '@angular/core';
/**
* @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. It will run after the content
* has been checked and most of the time it's during a change detection cycle.
*
* @see {@link AfterViewChecked}
* @see [Lifecycle hooks guide](guide/components/lifecycle)
*
* @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. It will run only once when the projected content is initialized.
* Define an `ngAfterContentInit()` method to handle any additional initialization tasks.
*
* @see {@link OnInit}
* @see {@link AfterViewInit}
* @see [Lifecycle hooks guide](guide/components/lifecycle)
*
* @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;
}
/**
* Register callbacks to be invoked the next time the application finishes rendering, during the
* specified phases. The available phases are:
* - `earlyRead`
* Use this phase to **read** from the DOM before a subsequent `write` callback, for example to
* perform custom layout that the browser doesn't natively support. Prefer the `read` phase if
* reading can wait until after the write phase. **Never** write to the DOM in this phase.
* - `write`
* Use this phase to **write** to the DOM. **Never** read from the DOM in this phase.
* - `mixedReadWrite`
* Use this phase to read from and write to the DOM simultaneously. **Never** use this phase if
* it is possible to divide the work among the other phases instead.
* - `read`
* Use this phase to **read** from the DOM. **Never** write to the DOM in this phase.
*
* <div class="alert is-critical">
*
* You should prefer using the `read` and `write` phases over the `earlyRead` and `mixedReadWrite`
* phases when possible, to avoid performance degradation.
*
* </div>
*
* Note that:
* - Callbacks run in the following phase order *once, after the next render*:
* 1. `earlyRead`
* 2. `write`
* 3. `mixedReadWrite`
* 4. `read`
* - Callbacks in the same phase run in the order they are registered.
* - Callbacks run on browser platforms only, they will not run on the server.
*
* The first phase callback to run as part of this spec will receive no parameters. Each
* subsequent phase callback in this spec will receive the return value of the previously run
* phase callback as a parameter. This can be used to coordinate work across multiple phases.
*
* Angular is unable to verify or enforce that phases are used correctly, and instead
* relies on each developer to follow the guidelines documented for each value and
* carefully choose the appropriate one, refactoring their code if necessary. By doing
* so, Angular is better able to minimize the performance degradation associated with
* manual DOM access, ensuring the best experience for the end users of your application
* or library.
*
* <div class="alert is-important">
*
* Components are not guaranteed to be [hydrated](guide/hydration) before the callback runs.
* You must use caution when directly reading or writing the DOM and layout.
*
* </div>
*
* @param spec The callback functions to register
* @param options Options to control the behavior of the callback
*
* @usageNotes
*
* Use `afterNextRender` to read or write the DOM once,
* for example to initialize a non-Angular library.
*
* ### Example
* ```ts
* @Component({
* selector: 'my-chart-cmp',
* template: `<div #chart>{{ ... }}</div>`,
* })
* export class MyChartCmp {
* @ViewChild('chart') chartRef: ElementRef;
* chart: MyChart|null;
*
* constructor() {
* afterNextRender({
* write: () => {
* this.chart = new MyChart(this.chartRef.nativeElement);
* }
* });
* }
* }
* ```
*
* @developerPreview
*/
export declare function afterNextRender<E = never, W = never, M = never>(spec: {
earlyRead?: () => E;
write?: (...args: ɵFirstAvailable<[E]>) => W;
mixedReadWrite?: (...args: ɵFirstAvailable<[W, E]>) => M;
read?: (...args: ɵFirstAvailable<[M, W, E]>) => void;
}, options?: Omit<AfterRenderOptions, 'phase'>): AfterRenderRef;
/**
* Register a callback to be invoked the next time the application finishes rendering, during the
* `mixedReadWrite` phase.
*
* <div class="alert is-critical">
*
* You should prefer specifying an explicit phase for the callback instead, or you risk significant
* performance degradation.
*
* </div>
*
* Note that the callback will run
* - in the order it was registered
* - on browser platforms only
* - during the `mixedReadWrite` phase
*
* <div class="alert is-important">
*
* Components are not guaranteed to be [hydrated](guide/hydration) before the callback runs.
* You must use caution when directly reading or writing the DOM and layout.
*
* </div>
*
* @param callback A callback function to register
* @param options Options to control the behavior of the callback
*
* @usageNotes
*
* Use `afterNextRender` to read or write the DOM once,
* for example to initialize a non-Angular library.
*
* ### Example
* ```ts
* @Component({
* selector: 'my-chart-cmp',
* template: `<div #chart>{{ ... }}</div>`,
* })
* export class MyChartCmp {
* @ViewChild('chart') chartRef: ElementRef;
* chart: MyChart|null;
*
* constructor() {
* afterNextRender({
* write: () => {
* this.chart = new MyChart(this.chartRef.nativeElement);
* }
* });
* }
* }
* ```
*
* @developerPreview
*/
export declare function afterNextRender(callback: VoidFunction, options?: AfterRenderOptions): AfterRenderRef;
/**
* Register callbacks to be invoked each time the application finishes rendering, during the
* specified phases. The available phases are:
* - `earlyRead`
* Use this phase to **read** from the DOM before a subsequent `write` callback, for example to
* perform custom layout that the browser doesn't natively support. Prefer the `read` phase if
* reading can wait until after the write phase. **Never** write to the DOM in this phase.
* - `write`
* Use this phase to **write** to the DOM. **Never** read from the DOM in this phase.
* - `mixedReadWrite`
* Use this phase to read from and write to the DOM simultaneously. **Never** use this phase if
* it is possible to divide the work among the other phases instead.
* - `read`
* Use this phase to **read** from the DOM. **Never** write to the DOM in this phase.
*
* <div class="alert is-critical">
*
* You should prefer using the `read` and `write` phases over the `earlyRead` and `mixedReadWrite`
* phases when possible, to avoid performance degradation.
*
* </div>
*
* Note that:
* - Callbacks run in the following phase order *after each render*:
* 1. `earlyRead`
* 2. `write`
* 3. `mixedReadWrite`
* 4. `read`
* - Callbacks in the same phase run in the order they are registered.
* - Callbacks run on browser platforms only, they will not run on the server.
*
* The first phase callback to run as part of this spec will receive no parameters. Each
* subsequent phase callback in this spec will receive the return value of the previously run
* phase callback as a parameter. This can be used to coordinate work across multiple phases.
*
* Angular is unable to verify or enforce that phases are used correctly, and instead
* relies on each developer to follow the guidelines documented for each value and
* carefully choose the appropriate one, refactoring their code if necessary. By doing
* so, Angular is better able to minimize the performance degradation associated with
* manual DOM access, ensuring the best experience for the end users of your application
* or library.
*
* <div class="alert is-important">
*
* Components are not guaranteed to be [hydrated](guide/hydration) before the callback runs.
* You must use caution when directly reading or writing the DOM and layout.
*
* </div>
*
* @param spec The callback functions to register
* @param options Options to control the behavior of the callback
*
* @usageNotes
*
* Use `afterRender` to read or write the DOM after each render.
*
* ### Example
* ```ts
* @Component({
* selector: 'my-cmp',
* template: `<span #content>{{ ... }}</span>`,
* })
* export class MyComponent {
* @ViewChild('content') contentRef: ElementRef;
*
* constructor() {
* afterRender({
* read: () => {
* console.log('content height: ' + this.contentRef.nativeElement.scrollHeight);
* }
* });
* }
* }
* ```
*
* @developerPreview
*/
export declare function afterRender<E = never, W = never, M = never>(spec: {
earlyRead?: () => E;
write?: (...args: ɵFirstAvailable<[E]>) => W;
mixedReadWrite?: (...args: ɵFirstAvailable<[W, E]>) => M;
read?: (...args: ɵFirstAvailable<[M, W, E]>) => void;
}, options?: Omit<AfterRenderOptions, 'phase'>): AfterRenderRef;
/**
* Register a callback to be invoked each time the application finishes rendering, during the
* `mixedReadWrite` phase.
*
* <div class="alert is-critical">
*
* You should prefer specifying an explicit phase for the callback instead, or you risk significant
* performance degradation.
*
* </div>
*
* Note that the callback will run
* - in the order it was registered
* - once per render
* - on browser platforms only
* - during the `mixedReadWrite` phase
*
* <div class="alert is-important">
*
* Components are not guaranteed to be [hydrated](guide/hydration) before the callback runs.
* You must use caution when directly reading or writing the DOM and layout.
*
* </div>
*
* @param callback A callback function to register
* @param options Options to control the behavior of the callback
*
* @usageNotes
*
* Use `afterRender` to read or write the DOM after each render.
*
* ### Example
* ```ts
* @Component({
* selector: 'my-cmp',
* template: `<span #content>{{ ... }}</span>`,
* })
* export class MyComponent {
* @ViewChild('content') contentRef: ElementRef;
*
* constructor() {
* afterRender({
* read: () => {
* console.log('content height: ' + this.contentRef.nativeElement.scrollHeight);
* }
* });
* }
* }
* ```
*
* @developerPreview
*/
export declare function afterRender(callback: VoidFunction, options?: AfterRenderOptions): AfterRenderRef;
/**
* Options passed to `afterRender` and `afterNextRender`.
*
* @developerPreview
*/
export declare interface AfterRenderOptions {
/**
* The `Injector` to use during creation.
*
* If this is not provided, the current injection context will be used instead (via `inject`).
*/
injector?: Injector;
/**
* The phase the callback should be invoked in.
*
* <div class="alert is-critical">
*
* Defaults to `AfterRenderPhase.MixedReadWrite`. You should choose a more specific
* phase instead. See `AfterRenderPhase` for more information.
*
* </div>
*
* @deprecated Specify the phase for your callback to run in by passing a spec-object as the first
* parameter to `afterRender` or `afterNextRender` instead of a function.
*/
phase?: AfterRenderPhase;
}
/**
* The phase to run an `afterRender` or `afterNextRender` callback in.
*
* Callbacks in the same phase run in the order they are registered. Phases run in the
* following order after each render:
*
* 1. `AfterRenderPhase.EarlyRead`
* 2. `AfterRenderPhase.Write`
* 3. `AfterRenderPhase.MixedReadWrite`
* 4. `AfterRenderPhase.Read`
*
* Angular is unable to verify or enforce that phases are used correctly, and instead
* relies on each developer to follow the guidelines documented for each value and
* carefully choose the appropriate one, refactoring their code if necessary. By doing
* so, Angular is better able to minimize the performance degradation associated with
* manual DOM access, ensuring the best experience for the end users of your application
* or library.
*
* @deprecated Specify the phase for your callback to run in by passing a spec-object as the first
* parameter to `afterRender` or `afterNextRender` instead of a function.
*/
export declare enum AfterRenderPhase {
/**
* Use `AfterRenderPhase.EarlyRead` for callbacks that only need to **read** from the
* DOM before a subsequent `AfterRenderPhase.Write` callback, for example to perform
* custom layout that the browser doesn't natively support. Prefer the
* `AfterRenderPhase.EarlyRead` phase if reading can wait until after the write phase.
* **Never** write to the DOM in this phase.
*
* <div class="alert is-important">
*
* Using this value can degrade performance.
* Instead, prefer using built-in browser functionality when possible.
*
* </div>
*/
EarlyRead = 0,
/**
* Use `AfterRenderPhase.Write` for callbacks that only **write** to the DOM. **Never**
* read from the DOM in this phase.
*/
Write = 1,
/**
* Use `AfterRenderPhase.MixedReadWrite` for callbacks that read from or write to the
* DOM, that haven't been refactored to use a different phase. **Never** use this phase if
* it is possible to divide the work among the other phases instead.
*
* <div class="alert is-critical">
*
* Using this value can **significantly** degrade performance.
* Instead, prefer dividing work into the appropriate phase callbacks.
*
* </div>
*/
MixedReadWrite = 2,
/**
* Use `AfterRenderPhase.Read` for callbacks that only **read** from the DOM. **Never**
* write to the DOM in this phase.
*/
Read = 3
}
/**
* A callback that runs after render.
*
* @developerPreview
*/
export declare interface AfterRenderRef {
/**
* Shut down the callback, preventing it from being called again.
*/
destroy(): void;
}
/**
* @description
* A lifecycle hook that is called after the default change detector has
* completed checking a component's view for changes.
*
* @see {@link AfterContentChecked}
* @see [Lifecycle hooks guide](guide/components/lifecycle)
*
* @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 {@link OnInit}
* @see {@link AfterContentInit}
* @see [Lifecycle hooks guide](guide/components/lifecycle)
*
* @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](api/core/InjectionToken) that indicates which animations
* module has been loaded.
* @publicApi
*/
export declare const ANIMATION_MODULE_TYPE: InjectionToken<"NoopAnimations" | "BrowserAnimations">;
/**
* A DI token 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<readonly ((compRef: ComponentRef<any>) => void)[]>;
/**
* A DI token representing a string ID, used
* primarily for prefixing application attributes and CSS styles when
* {@link ViewEncapsulation#Emulated} is being used.
*
* The token is needed in cases when multiple applications are bootstrapped on a page
* (for example, using `bootstrapApplication` calls). In this case, ensure that those applications
* have different `APP_ID` value setup. For example:
*
* ```
* bootstrapApplication(ComponentA, {
* providers: [
* { provide: APP_ID, useValue: 'app-a' },
* // ... other providers ...
* ]
* });
*
* bootstrapApplication(ComponentB, {
* providers: [
* { provide: APP_ID, useValue: 'app-b' },
* // ... other providers ...
* ]
* });
* ```
*
* By default, when there is only one application bootstrapped, you don't need to provide the
* `APP_ID` token (the `ng` will be used as an app ID).
*
* @publicApi
*/
export declare const APP_ID: InjectionToken<string>;
/**
* A DI token 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 {@link ApplicationInitStatus}
*
* @usageNotes
*
* The following example illustrates how to configure a multi-provider using `APP_INITIALIZER` token
* and a function returning a promise.
* ### Example with NgModule-based application
* ```
* 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 {}
* ```
*
* ### Example with standalone application
* ```
* export function initializeApp(http: HttpClient) {
* return (): Promise<any> =>
* firstValueFrom(
* http
* .get("https://someUrl.com/api/user")
* .pipe(tap(user => { ... }))
* );
* }
*
* bootstrapApplication(App, {
* providers: [
* provideHttpClient(),
* {
* provide: APP_INITIALIZER,
* useFactory: initializeApp,
* multi: true,
* deps: [HttpClient],
* },
* ],
* });
* ```
*
*
* 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.
*
* ### Example with NgModule-based application
* ```
* 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 {}
* ```
*
* ### Example with standalone application
* ```
* function initializeAppFactory(httpClient: HttpClient): () => Observable<any> {
* return () => httpClient.get("https://someUrl.com/api/user")
* .pipe(
* tap(user => { ... })
* );
* }
*
* bootstrapApplication(App, {
* providers: [
* provideHttpClient(),
* {
* provide: APP_INITIALIZER,
* useFactory: initializeAppFactory,
* multi: true,
* deps: [HttpClient],
* },
* ],
* });
* ```
*
* @publicApi
*/
export declare const APP_INITIALIZER: InjectionToken<readonly (() => Observable<unknown> | Promise<unknown> | void)[]>;
/**
* Set of config options available during the application bootstrap operation.
*
* @publicApi
*/
export declare interface ApplicationConfig {
/**
* List of providers that should be available to the root component and all its children.
*/
providers: Array<Provider | EnvironmentProviders>;
}
/**
* A class that reflects the state of running {@link APP_INITIALIZER} functions.
*
* @publicApi
*/
export declare class ApplicationInitStatus {
private resolve;
private reject;
private initialized;
readonly done = false;
readonly donePromise: Promise<any>;
private readonly appInits;
constructor();
static ɵfac: i0.ɵɵFactoryDeclaration<ApplicationInitStatus, never>;
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 _destroyed;
private _destroyListeners;
private readonly internalErrorHandler;
private readonly afterRenderEffectManager;
private readonly zonelessEnabled;
private externalTestViews;
private beforeRender;
/**
* 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.
*/
readonly isStable: Observable<boolean>;
private readonly _injector;
/**
* 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;
private detectChangesInAttachedViews;
/**
* 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;
/**
* Registers a listener to be called when an instance is destroyed.
*
* @param callback A callback function to add as a listener.
* @returns A function which unregisters a listener.
*/
onDestroy(callback: () => void): VoidFunction;
/**
* 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>;
}
/**
* Marks a component for check (in case of OnPush components) and synchronously
* performs change detection on the application this component belongs to.
*
* @param component Component to {@link ChangeDetectorRef#markForCheck mark for check}.
*
* @publicApi
* @globalApi ng
*/
declare function applyChanges(component: {}): void;
/**
* @publicApi
*/
export declare function asNativeElements(debugEls: DebugElement[]): any;
/**
* Asserts that the current stack frame is within an [injection
* context](guide/di/dependency-injection-context) and has access to `inject`.
*
* @param debugFn a reference to the function making the assertion (used for the error message).
*
* @publicApi
*/
export declare function assertInInjectionContext(debugFn: Function): void;
/**
* Asserts that the current stack frame is not within a reactive context. Useful
* to disallow certain code from running inside a reactive context (see {@link toSignal}).
*
* @param debugFn a reference to the function making the assertion (used for the error message).
*
* @publicApi
*/
export declare function assertNotInReactiveContext(debugFn: Function, extraContext?: string): void;
/**
* 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;
}
/**
* Transforms a value (typically a string) to a boolean.
* Intended to be used as a transform function of an input.
*
* @usageNotes
* ```typescript
* @Input({ transform: booleanAttribute }) status!: boolean;
* ```
* @param value Value to be transformed.
*
* @publicApi
*/
export declare function booleanAttribute(value: unknown): boolean;
/**
* 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;
/**
* When false, change detection is scheduled when Angular receives
* a clear indication that templates need to be refreshed. This includes:
*
* - calling `ChangeDetectorRef.markForCheck`
* - calling `ComponentRef.setInput`
* - updating a signal that is read in a template
* - when bound host or template listeners are triggered
* - attaching a view that is marked dirty
* - removing a view
* - registering a render hook (templates are only refreshed if render hooks do one of the above)
*/
ignoreChangesOutsideZone?: boolean;
}
/**
* The strategy that the default change detector uses to detect changes.
* When set, takes effect the next time change detection is triggered.
*
* @see [Change detection usage](/api/core/ChangeDetectorRef?tab=usage-notes)
* @see [Skipping component subtrees](/best-practices/skipping-subtrees)
*
* @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/components/lifecycle#using-change-detection-hooks)
* @see [Defining custom change detection](guide/components/lifecycle#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.
*
* <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} (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}
* 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.
*
* @deprecated This is a test-only API that does not have a place in production interface.
* `checkNoChanges` is already part of an `ApplicationRef` tick when the app is running in dev
* mode. For more granular `checkNoChanges` validation, use `ComponentFixture`.
*/
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 interface ChangeDetectorRefInterface extends ChangeDetectorRef {
}
declare const CHILD_HEAD = 12;
declare const CHILD_TAIL = 13;
declare interface ClassDebugInfo {
className: string;
filePath?: string;
lineNumber?: number;
forbidOrphanRendering?: boolean;
}
/**
* Configures the `Injector` to return an instance of `useClass` for a token.
* @see [Dependency Injection Guide](guide/di/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/di/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.
*/
export declare class Compiler {
/**
* Compiles the given NgModule and all of its components. All templates of the components
* 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.
*/
export declare abstract class CompilerFactory {
abstract createCompiler(options?: CompilerOptions[]): Compiler;
}
/**
* Options for creating a compiler.
*
* @publicApi
*/
export declare type CompilerOptions = {
defaultEncapsulation?: ViewEncapsulation;
providers?: StaticProvider[];
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`.
*
* @deprecated This option does not have any effect. Will be removed in Angular v17.
*/
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 relative paths or an absolute URL for files containing CSS stylesheet to use
* in this component.
*/
styleUrl?: string;
/**
* 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 | string[];
/**
* O