UNPKG

16.6 kBTypeScriptView Raw
1/**
2 * @license Angular v14.0.3
3 * (c) 2010-2022 Google LLC. https://angular.io/
4 * License: MIT
5 */
6
7
8import { CompilerOptions } from '@angular/core';
9import { Injector } from '@angular/core';
10import { NgModuleRef } from '@angular/core';
11import { Type } from '@angular/core';
12import { Version } from '@angular/core';
13
14declare interface IAngularBootstrapConfig {
15 strictDi?: boolean;
16}
17
18declare interface IInjectorService {
19 get(key: string): any;
20 has(key: string): boolean;
21}
22
23declare interface IRootScopeService {
24 $new(isolate?: boolean): IScope;
25 $id: string;
26 $parent: IScope;
27 $root: IScope;
28 $watch(exp: Ng1Expression, fn?: (a1?: any, a2?: any) => void): Function;
29 $on(event: string, fn?: (event?: any, ...args: any[]) => void): Function;
30 $destroy(): any;
31 $apply(exp?: Ng1Expression): any;
32 $digest(): any;
33 $evalAsync(exp: Ng1Expression, locals?: any): void;
34 $on(event: string, fn?: (event?: any, ...args: any[]) => void): Function;
35 $$childTail: IScope;
36 $$childHead: IScope;
37 $$nextSibling: IScope;
38 [key: string]: any;
39}
40
41declare interface IScope extends IRootScopeService {
42}
43
44declare type Ng1Expression = string | Function;
45
46/**
47 * Use `UpgradeAdapter` to allow AngularJS and Angular to coexist in a single application.
48 *
49 * The `UpgradeAdapter` allows:
50 * 1. creation of Angular component from AngularJS component directive
51 * (See [UpgradeAdapter#upgradeNg1Component()])
52 * 2. creation of AngularJS directive from Angular component.
53 * (See [UpgradeAdapter#downgradeNg2Component()])
54 * 3. Bootstrapping of a hybrid Angular application which contains both of the frameworks
55 * coexisting in a single application.
56 *
57 * @usageNotes
58 * ### Mental Model
59 *
60 * When reasoning about how a hybrid application works it is useful to have a mental model which
61 * describes what is happening and explains what is happening at the lowest level.
62 *
63 * 1. There are two independent frameworks running in a single application, each framework treats
64 * the other as a black box.
65 * 2. Each DOM element on the page is owned exactly by one framework. Whichever framework
66 * instantiated the element is the owner. Each framework only updates/interacts with its own
67 * DOM elements and ignores others.
68 * 3. AngularJS directives always execute inside AngularJS framework codebase regardless of
69 * where they are instantiated.
70 * 4. Angular components always execute inside Angular framework codebase regardless of
71 * where they are instantiated.
72 * 5. An AngularJS component can be upgraded to an Angular component. This creates an
73 * Angular directive, which bootstraps the AngularJS component directive in that location.
74 * 6. An Angular component can be downgraded to an AngularJS component directive. This creates
75 * an AngularJS directive, which bootstraps the Angular component in that location.
76 * 7. Whenever an adapter component is instantiated the host element is owned by the framework
77 * doing the instantiation. The other framework then instantiates and owns the view for that
78 * component. This implies that component bindings will always follow the semantics of the
79 * instantiation framework. The syntax is always that of Angular syntax.
80 * 8. AngularJS is always bootstrapped first and owns the bottom most view.
81 * 9. The new application is running in Angular zone, and therefore it no longer needs calls to
82 * `$apply()`.
83 *
84 * ### Example
85 *
86 * ```
87 * const adapter = new UpgradeAdapter(forwardRef(() => MyNg2Module), myCompilerOptions);
88 * const module = angular.module('myExample', []);
89 * module.directive('ng2Comp', adapter.downgradeNg2Component(Ng2Component));
90 *
91 * module.directive('ng1Hello', function() {
92 * return {
93 * scope: { title: '=' },
94 * template: 'ng1[Hello {{title}}!](<span ng-transclude></span>)'
95 * };
96 * });
97 *
98 *
99 * @Component({
100 * selector: 'ng2-comp',
101 * inputs: ['name'],
102 * template: 'ng2[<ng1-hello [title]="name">transclude</ng1-hello>](<ng-content></ng-content>)',
103 * directives:
104 * })
105 * class Ng2Component {
106 * }
107 *
108 * @NgModule({
109 * declarations: [Ng2Component, adapter.upgradeNg1Component('ng1Hello')],
110 * imports: [BrowserModule]
111 * })
112 * class MyNg2Module {}
113 *
114 *
115 * document.body.innerHTML = '<ng2-comp name="World">project</ng2-comp>';
116 *
117 * adapter.bootstrap(document.body, ['myExample']).ready(function() {
118 * expect(document.body.textContent).toEqual(
119 * "ng2[ng1[Hello World!](transclude)](project)");
120 * });
121 *
122 * ```
123 *
124 * @deprecated Deprecated since v5. Use `upgrade/static` instead, which also supports
125 * [Ahead-of-Time compilation](guide/aot-compiler).
126 * @publicApi
127 */
128export declare class UpgradeAdapter {
129 private ng2AppModule;
130 private compilerOptions?;
131 private idPrefix;
132 private downgradedComponents;
133 private upgradedProviders;
134 private ngZone;
135 private ng1Module;
136 private moduleRef;
137 private ng2BootstrapDeferred;
138 constructor(ng2AppModule: Type<any>, compilerOptions?: CompilerOptions | undefined);
139 /**
140 * Allows Angular Component to be used from AngularJS.
141 *
142 * Use `downgradeNg2Component` to create an AngularJS Directive Definition Factory from
143 * Angular Component. The adapter will bootstrap Angular component from within the
144 * AngularJS template.
145 *
146 * @usageNotes
147 * ### Mental Model
148 *
149 * 1. The component is instantiated by being listed in AngularJS template. This means that the
150 * host element is controlled by AngularJS, but the component's view will be controlled by
151 * Angular.
152 * 2. Even thought the component is instantiated in AngularJS, it will be using Angular
153 * syntax. This has to be done, this way because we must follow Angular components do not
154 * declare how the attributes should be interpreted.
155 * 3. `ng-model` is controlled by AngularJS and communicates with the downgraded Angular component
156 * by way of the `ControlValueAccessor` interface from @angular/forms. Only components that
157 * implement this interface are eligible.
158 *
159 * ### Supported Features
160 *
161 * - Bindings:
162 * - Attribute: `<comp name="World">`
163 * - Interpolation: `<comp greeting="Hello {{name}}!">`
164 * - Expression: `<comp [name]="username">`
165 * - Event: `<comp (close)="doSomething()">`
166 * - ng-model: `<comp ng-model="name">`
167 * - Content projection: yes
168 *
169 * ### Example
170 *
171 * ```
172 * const adapter = new UpgradeAdapter(forwardRef(() => MyNg2Module));
173 * const module = angular.module('myExample', []);
174 * module.directive('greet', adapter.downgradeNg2Component(Greeter));
175 *
176 * @Component({
177 * selector: 'greet',
178 * template: '{{salutation}} {{name}}! - <ng-content></ng-content>'
179 * })
180 * class Greeter {
181 * @Input() salutation: string;
182 * @Input() name: string;
183 * }
184 *
185 * @NgModule({
186 * declarations: [Greeter],
187 * imports: [BrowserModule]
188 * })
189 * class MyNg2Module {}
190 *
191 * document.body.innerHTML =
192 * 'ng1 template: <greet salutation="Hello" [name]="world">text</greet>';
193 *
194 * adapter.bootstrap(document.body, ['myExample']).ready(function() {
195 * expect(document.body.textContent).toEqual("ng1 template: Hello world! - text");
196 * });
197 * ```
198 */
199 downgradeNg2Component(component: Type<any>): Function;
200 /**
201 * Allows AngularJS Component to be used from Angular.
202 *
203 * Use `upgradeNg1Component` to create an Angular component from AngularJS Component
204 * directive. The adapter will bootstrap AngularJS component from within the Angular
205 * template.
206 *
207 * @usageNotes
208 * ### Mental Model
209 *
210 * 1. The component is instantiated by being listed in Angular template. This means that the
211 * host element is controlled by Angular, but the component's view will be controlled by
212 * AngularJS.
213 *
214 * ### Supported Features
215 *
216 * - Bindings:
217 * - Attribute: `<comp name="World">`
218 * - Interpolation: `<comp greeting="Hello {{name}}!">`
219 * - Expression: `<comp [name]="username">`
220 * - Event: `<comp (close)="doSomething()">`
221 * - Transclusion: yes
222 * - Only some of the features of
223 * [Directive Definition Object](https://docs.angularjs.org/api/ng/service/$compile) are
224 * supported:
225 * - `compile`: not supported because the host element is owned by Angular, which does
226 * not allow modifying DOM structure during compilation.
227 * - `controller`: supported. (NOTE: injection of `$attrs` and `$transclude` is not supported.)
228 * - `controllerAs`: supported.
229 * - `bindToController`: supported.
230 * - `link`: supported. (NOTE: only pre-link function is supported.)
231 * - `name`: supported.
232 * - `priority`: ignored.
233 * - `replace`: not supported.
234 * - `require`: supported.
235 * - `restrict`: must be set to 'E'.
236 * - `scope`: supported.
237 * - `template`: supported.
238 * - `templateUrl`: supported.
239 * - `terminal`: ignored.
240 * - `transclude`: supported.
241 *
242 *
243 * ### Example
244 *
245 * ```
246 * const adapter = new UpgradeAdapter(forwardRef(() => MyNg2Module));
247 * const module = angular.module('myExample', []);
248 *
249 * module.directive('greet', function() {
250 * return {
251 * scope: {salutation: '=', name: '=' },
252 * template: '{{salutation}} {{name}}! - <span ng-transclude></span>'
253 * };
254 * });
255 *
256 * module.directive('ng2', adapter.downgradeNg2Component(Ng2Component));
257 *
258 * @Component({
259 * selector: 'ng2',
260 * template: 'ng2 template: <greet salutation="Hello" [name]="world">text</greet>'
261 * })
262 * class Ng2Component {
263 * }
264 *
265 * @NgModule({
266 * declarations: [Ng2Component, adapter.upgradeNg1Component('greet')],
267 * imports: [BrowserModule]
268 * })
269 * class MyNg2Module {}
270 *
271 * document.body.innerHTML = '<ng2></ng2>';
272 *
273 * adapter.bootstrap(document.body, ['myExample']).ready(function() {
274 * expect(document.body.textContent).toEqual("ng2 template: Hello world! - text");
275 * });
276 * ```
277 */
278 upgradeNg1Component(name: string): Type<any>;
279 /**
280 * Registers the adapter's AngularJS upgrade module for unit testing in AngularJS.
281 * Use this instead of `angular.mock.module()` to load the upgrade module into
282 * the AngularJS testing injector.
283 *
284 * @usageNotes
285 * ### Example
286 *
287 * ```
288 * const upgradeAdapter = new UpgradeAdapter(MyNg2Module);
289 *
290 * // configure the adapter with upgrade/downgrade components and services
291 * upgradeAdapter.downgradeNg2Component(MyComponent);
292 *
293 * let upgradeAdapterRef: UpgradeAdapterRef;
294 * let $compile, $rootScope;
295 *
296 * // We must register the adapter before any calls to `inject()`
297 * beforeEach(() => {
298 * upgradeAdapterRef = upgradeAdapter.registerForNg1Tests(['heroApp']);
299 * });
300 *
301 * beforeEach(inject((_$compile_, _$rootScope_) => {
302 * $compile = _$compile_;
303 * $rootScope = _$rootScope_;
304 * }));
305 *
306 * it("says hello", (done) => {
307 * upgradeAdapterRef.ready(() => {
308 * const element = $compile("<my-component></my-component>")($rootScope);
309 * $rootScope.$apply();
310 * expect(element.html()).toContain("Hello World");
311 * done();
312 * })
313 * });
314 *
315 * ```
316 *
317 * @param modules any AngularJS modules that the upgrade module should depend upon
318 * @returns an `UpgradeAdapterRef`, which lets you register a `ready()` callback to
319 * run assertions once the Angular components are ready to test through AngularJS.
320 */
321 registerForNg1Tests(modules?: string[]): UpgradeAdapterRef;
322 /**
323 * Bootstrap a hybrid AngularJS / Angular application.
324 *
325 * This `bootstrap` method is a direct replacement (takes same arguments) for AngularJS
326 * [`bootstrap`](https://docs.angularjs.org/api/ng/function/angular.bootstrap) method. Unlike
327 * AngularJS, this bootstrap is asynchronous.
328 *
329 * @usageNotes
330 * ### Example
331 *
332 * ```
333 * const adapter = new UpgradeAdapter(MyNg2Module);
334 * const module = angular.module('myExample', []);
335 * module.directive('ng2', adapter.downgradeNg2Component(Ng2));
336 *
337 * module.directive('ng1', function() {
338 * return {
339 * scope: { title: '=' },
340 * template: 'ng1[Hello {{title}}!](<span ng-transclude></span>)'
341 * };
342 * });
343 *
344 *
345 * @Component({
346 * selector: 'ng2',
347 * inputs: ['name'],
348 * template: 'ng2[<ng1 [title]="name">transclude</ng1>](<ng-content></ng-content>)'
349 * })
350 * class Ng2 {
351 * }
352 *
353 * @NgModule({
354 * declarations: [Ng2, adapter.upgradeNg1Component('ng1')],
355 * imports: [BrowserModule]
356 * })
357 * class MyNg2Module {}
358 *
359 * document.body.innerHTML = '<ng2 name="World">project</ng2>';
360 *
361 * adapter.bootstrap(document.body, ['myExample']).ready(function() {
362 * expect(document.body.textContent).toEqual(
363 * "ng2[ng1[Hello World!](transclude)](project)");
364 * });
365 * ```
366 */
367 bootstrap(element: Element, modules?: any[], config?: IAngularBootstrapConfig): UpgradeAdapterRef;
368 /**
369 * Allows AngularJS service to be accessible from Angular.
370 *
371 * @usageNotes
372 * ### Example
373 *
374 * ```
375 * class Login { ... }
376 * class Server { ... }
377 *
378 * @Injectable()
379 * class Example {
380 * constructor(@Inject('server') server, login: Login) {
381 * ...
382 * }
383 * }
384 *
385 * const module = angular.module('myExample', []);
386 * module.service('server', Server);
387 * module.service('login', Login);
388 *
389 * const adapter = new UpgradeAdapter(MyNg2Module);
390 * adapter.upgradeNg1Provider('server');
391 * adapter.upgradeNg1Provider('login', {asToken: Login});
392 *
393 * adapter.bootstrap(document.body, ['myExample']).ready((ref) => {
394 * const example: Example = ref.ng2Injector.get(Example);
395 * });
396 *
397 * ```
398 */
399 upgradeNg1Provider(name: string, options?: {
400 asToken: any;
401 }): void;
402 /**
403 * Allows Angular service to be accessible from AngularJS.
404 *
405 * @usageNotes
406 * ### Example
407 *
408 * ```
409 * class Example {
410 * }
411 *
412 * const adapter = new UpgradeAdapter(MyNg2Module);
413 *
414 * const module = angular.module('myExample', []);
415 * module.factory('example', adapter.downgradeNg2Provider(Example));
416 *
417 * adapter.bootstrap(document.body, ['myExample']).ready((ref) => {
418 * const example: Example = ref.ng1Injector.get('example');
419 * });
420 *
421 * ```
422 */
423 downgradeNg2Provider(token: any): Function;
424 /**
425 * Declare the AngularJS upgrade module for this adapter without bootstrapping the whole
426 * hybrid application.
427 *
428 * This method is automatically called by `bootstrap()` and `registerForNg1Tests()`.
429 *
430 * @param modules The AngularJS modules that this upgrade module should depend upon.
431 * @returns The AngularJS upgrade module that is declared by this method
432 *
433 * @usageNotes
434 * ### Example
435 *
436 * ```
437 * const upgradeAdapter = new UpgradeAdapter(MyNg2Module);
438 * upgradeAdapter.declareNg1Module(['heroApp']);
439 * ```
440 */
441 private declareNg1Module;
442}
443
444/**
445 * Use `UpgradeAdapterRef` to control a hybrid AngularJS / Angular application.
446 *
447 * @deprecated Deprecated since v5. Use `upgrade/static` instead, which also supports
448 * [Ahead-of-Time compilation](guide/aot-compiler).
449 * @publicApi
450 */
451export declare class UpgradeAdapterRef {
452 ng1RootScope: IRootScopeService;
453 ng1Injector: IInjectorService;
454 ng2ModuleRef: NgModuleRef<any>;
455 ng2Injector: Injector;
456 /**
457 * Register a callback function which is notified upon successful hybrid AngularJS / Angular
458 * application has been bootstrapped.
459 *
460 * The `ready` callback function is invoked inside the Angular zone, therefore it does not
461 * require a call to `$apply()`.
462 */
463 ready(fn: (upgradeAdapterRef: UpgradeAdapterRef) => void): void;
464 /**
465 * Dispose of running hybrid AngularJS / Angular application.
466 */
467 dispose(): void;
468}
469
470/**
471 * @publicApi
472 */
473export declare const VERSION: Version;
474
475export { }