5 lines
37 KiB
JSON
5 lines
37 KiB
JSON
{
|
|
"id": "api/upgrade/static/downgradeModule",
|
|
"title": "downgradeModule",
|
|
"contents": "\n\n<article>\n <div class=\"breadcrumb-container\">\n <div class=\"breadcrumb\">\n <script type=\"application/ld+json\">\n {\n \"@context\": \"http://schema.org\",\n \"@type\": \"BreadcrumbList\",\n \"itemListElement\": [\n { \"@type\": \"ListItem\", \"position\": 1, \"item\": { \"@id\": \"https://angular.io//api\", \"name\": \"API\" } },\n { \"@type\": \"ListItem\", \"position\": 2, \"item\": { \"@id\": \"https://angular.io/api/upgrade\", \"name\": \"@angular/upgrade\" } },\n { \"@type\": \"ListItem\", \"position\": 3, \"item\": { \"@id\": \"https://angular.io/api/upgrade/static\", \"name\": \"@angular/upgrade/static\" } },\n { \"@type\": \"ListItem\", \"position\": 4, \"item\": { \"@id\": \"https://angular.io/api/upgrade/static/downgradeModule\", \"name\": \"downgradeModule\" } }\n ]\n }\n </script>\n <a href=\"/api\">API</a> > <a href=\"api/upgrade\">@angular/upgrade</a> > <a href=\"api/upgrade/static\">@angular/upgrade/static</a>\n </div>\n <div class=\"github-links\">\n <a href=\"https://github.com/angular/angular/edit/master/packages/upgrade/static/src/downgrade_module.ts?message=docs(upgrade)%3A%20describe%20your%20change...#L21-L191\" aria-label=\"Suggest Edits\" title=\"Suggest Edits\"><i class=\"material-icons\" aria-hidden=\"true\" role=\"img\">mode_edit</i></a>\n <a href=\"https://github.com/angular/angular/tree/12.0.0-next.7/packages/upgrade/static/src/downgrade_module.ts#L21-L191\" aria-label=\"View Source\" title=\"View Source\"><i class=\"material-icons\" aria-hidden=\"true\" role=\"img\">code</i></a>\n</div>\n </div>\n \n <header class=\"api-header\">\n <h1 id=\"downgrademodule\">downgradeModule<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"api/upgrade/static/downgradeModule#downgrademodule\"><i class=\"material-icons\">link</i></a></h1>\n \n <label class=\"api-type-label function\">function</label>\n \n \n \n </header>\n \n <aio-toc class=\"embedded\"></aio-toc>\n\n <div class=\"api-body\">\n \n <section class=\"short-description\">\n <p>A helper function for creating an AngularJS module that can bootstrap an Angular module\n\"on-demand\" (possibly lazily) when a <a href=\"api/upgrade/static/downgradeComponent\">downgraded component</a> needs to be\ninstantiated.</p>\n\n <p><a href=\"api/upgrade/static/downgradeModule#description\">See more...</a></p>\n </section>\n \n \n \n\n <div class=\"overload-info\">\n \n\n <code-example language=\"ts\" hidecopy=\"true\" class=\"no-box api-heading\"> <span class=\"member-name\"><a href=\"api/upgrade/static/downgradeModule\" class=\"code-anchor\">downgradeModule</a></span><T>(moduleFactoryOrBootstrapFn: <a href=\"api/core/NgModuleFactory\" class=\"code-anchor\">NgModuleFactory</a><T> | ((extraProviders: <a href=\"api/core/StaticProvider\" class=\"code-anchor\">StaticProvider</a>[]) => Promise<<a href=\"api/core/NgModuleRef\" class=\"code-anchor\">NgModuleRef</a><T>>)): string</code-example>\n\n \n\n <h6 class=\"no-anchor\" id=\"parameters\">Parameters</h6>\n <table class=\"is-full-width list-table parameters-table function-overload-parameters\">\n <tbody>\n \n <tr class=\"function-overload-parameter\">\n <td class=\"param-name\">\n <a id=\"\"></a>\n <code>moduleFactoryOrBootstrapFn</code>\n </td>\n <td class=\"param-type\"><code><a href=\"api/core/NgModuleFactory\" class=\"code-anchor\">NgModuleFactory</a><t> | ((extraProviders: <a href=\"api/core/StaticProvider\" class=\"code-anchor\">StaticProvider</a>[]) => Promise<ngmoduleref<t>>)</ngmoduleref<t></t></code></td>\n <td class=\"param-description\">\n \n \n </td>\n </tr>\n </tbody>\n</table>\n\n \n <h6 class=\"no-anchor\" id=\"returns\">Returns</h6>\n <p><code>string</code></p>\n\n \n\n\n \n\n \n</div>\n\n\n \n\n \n\n<section class=\"description\">\n <h2 id=\"description\">Description<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"api/upgrade/static/downgradeModule#description\"><i class=\"material-icons\">link</i></a></h2>\n <p><em>Part of the <a href=\"api?query=upgrade/static\">upgrade/static</a> library for hybrid upgrade apps that\nsupport AOT compilation.</em></p>\n<p>It allows loading/bootstrapping the Angular part of a hybrid application lazily and not having to\npay the cost up-front. For example, you can have an AngularJS application that uses Angular for\nspecific routes and only instantiate the Angular modules if/when the user visits one of these\nroutes.</p>\n<p>The Angular module will be bootstrapped once (when requested for the first time) and the same\nreference will be used from that point onwards.</p>\n<p><code><a href=\"api/upgrade/static/downgradeModule\" class=\"code-anchor\">downgradeModule</a>()</code> requires either an <code><a href=\"api/core/NgModuleFactory\" class=\"code-anchor\">NgModuleFactory</a></code> or a function:</p>\n<ul>\n<li><code><a href=\"api/core/NgModuleFactory\" class=\"code-anchor\">NgModuleFactory</a></code>: If you pass an <code><a href=\"api/core/NgModuleFactory\" class=\"code-anchor\">NgModuleFactory</a></code>, it will be used to instantiate a module\nusing <code><a href=\"api/platform-browser/platformBrowser\" class=\"code-anchor\">platformBrowser</a></code>'s <a href=\"api/core/PlatformRef#bootstrapModuleFactory\">bootstrapModuleFactory()</a>.</li>\n<li><code>Function</code>: If you pass a function, it is expected to return a promise resolving to an\n<code><a href=\"api/core/NgModuleRef\" class=\"code-anchor\">NgModuleRef</a></code>. The function is called with an array of extra <a href=\"api/core/StaticProvider\">Providers</a>\nthat are expected to be available from the returned <code><a href=\"api/core/NgModuleRef\" class=\"code-anchor\">NgModuleRef</a></code>'s <code><a href=\"api/core/Injector\" class=\"code-anchor\">Injector</a></code>.</li>\n</ul>\n<p><code><a href=\"api/upgrade/static/downgradeModule\" class=\"code-anchor\">downgradeModule</a>()</code> returns the name of the created AngularJS wrapper module. You can use it to\ndeclare a dependency in your main AngularJS module.</p>\n<code-example path=\"upgrade/static/ts/lite/module.ts\" region=\"basic-how-to\">\n// Alternatively, we could import and use an `<a href=\"api/core/NgModuleFactory\" class=\"code-anchor\">NgModuleFactory</a>` instead:\n// import {MyLazyAngularModuleNgFactory} from './my-lazy-angular-module.ngfactory';\nimport {<a href=\"api/platform-browser-dynamic/platformBrowserDynamic\" class=\"code-anchor\">platformBrowserDynamic</a>} from '@angular/platform-browser-dynamic';\nimport {<a href=\"api/upgrade/static/downgradeModule\" class=\"code-anchor\">downgradeModule</a>} from '@angular/upgrade/<a href=\"api/upgrade/static\" class=\"code-anchor\">static</a>';\n\n\n// The function that will bootstrap the Angular module (when/if necessary).\n// (This would be omitted if we provided an `<a href=\"api/core/NgModuleFactory\" class=\"code-anchor\">NgModuleFactory</a>` directly.)\nconst ng2BootstrapFn = (extraProviders: <a href=\"api/core/StaticProvider\" class=\"code-anchor\">StaticProvider</a>[]) =>\n <a href=\"api/platform-browser-dynamic/platformBrowserDynamic\" class=\"code-anchor\">platformBrowserDynamic</a>(extraProviders).bootstrapModule(MyLazyAngularModule);\n\n\n// This AngularJS module represents the AngularJS pieces of the application.\nconst myMainAngularJsModule = angular.module('myMainAngularJsModule', [\n // We declare a dependency on the \"downgraded\" Angular module.\n <a href=\"api/upgrade/static/downgradeModule\" class=\"code-anchor\">downgradeModule</a>(ng2BootstrapFn)\n // or\n // <a href=\"api/upgrade/static/downgradeModule\" class=\"code-anchor\">downgradeModule</a>(MyLazyAngularModuleFactory)\n]);\n\n</code-example>\n<p>For more details on how to use <code><a href=\"api/upgrade/static/downgradeModule\" class=\"code-anchor\">downgradeModule</a>()</code> see\n<a href=\"guide/upgrade-performance\">Upgrading for Performance</a>.</p>\n\n <p>Further information available in the <a href=\"api/upgrade/static/downgradeModule#usage-notes\">Usage Notes</a>...</p>\n</section>\n\n\n\n \n<section class=\"usage-notes\">\n <h2 id=\"usage-notes\">Usage notes<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"api/upgrade/static/downgradeModule#usage-notes\"><i class=\"material-icons\">link</i></a></h2>\n <p>Apart from <code><a href=\"api/upgrade/static/UpgradeModule\" class=\"code-anchor\">UpgradeModule</a></code>, you can use the rest of the <code><a href=\"api/upgrade/static\" class=\"code-anchor\">upgrade/static</a></code> helpers as usual to\nbuild a hybrid application. Note that the Angular pieces (e.g. downgraded services) will not be\navailable until the downgraded module has been bootstrapped, i.e. by instantiating a downgraded\ncomponent.</p>\n<div class=\"alert is-important\">\n<p> You cannot use <code><a href=\"api/upgrade/static/downgradeModule\" class=\"code-anchor\">downgradeModule</a>()</code> and <code><a href=\"api/upgrade/static/UpgradeModule\" class=\"code-anchor\">UpgradeModule</a></code> in the same hybrid application.<br>\nUse one or the other.</p>\n</div>\n<h3 id=\"differences-with-upgrademodule\">Differences with <code><a href=\"api/upgrade/static/UpgradeModule\" class=\"code-anchor\">UpgradeModule</a></code><a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"api/upgrade/static/downgradeModule#differences-with-upgrademodule\"><i class=\"material-icons\">link</i></a></h3>\n<p>Besides their different API, there are two important internal differences between\n<code><a href=\"api/upgrade/static/downgradeModule\" class=\"code-anchor\">downgradeModule</a>()</code> and <code><a href=\"api/upgrade/static/UpgradeModule\" class=\"code-anchor\">UpgradeModule</a></code> that affect the behavior of hybrid applications:</p>\n<ol>\n<li>Unlike <code><a href=\"api/upgrade/static/UpgradeModule\" class=\"code-anchor\">UpgradeModule</a></code>, <code><a href=\"api/upgrade/static/downgradeModule\" class=\"code-anchor\">downgradeModule</a>()</code> does not bootstrap the main AngularJS module\ninside the <a href=\"api/core/NgZone\">Angular zone</a>.</li>\n<li>Unlike <code><a href=\"api/upgrade/static/UpgradeModule\" class=\"code-anchor\">UpgradeModule</a></code>, <code><a href=\"api/upgrade/static/downgradeModule\" class=\"code-anchor\">downgradeModule</a>()</code> does not automatically run a\n<a href=\"https://docs.angularjs.org/api/ng/type/$rootScope.Scope#$digest\">$digest()</a> when changes are\ndetected in the Angular part of the application.</li>\n</ol>\n<p>What this means is that applications using <code><a href=\"api/upgrade/static/UpgradeModule\" class=\"code-anchor\">UpgradeModule</a></code> will run change detection more\nfrequently in order to ensure that both frameworks are properly notified about possible changes.\nThis will inevitably result in more change detection runs than necessary.</p>\n<p><code><a href=\"api/upgrade/static/downgradeModule\" class=\"code-anchor\">downgradeModule</a>()</code>, on the other side, does not try to tie the two change detection systems as\ntightly, restricting the explicit change detection runs only to cases where it knows it is\nnecessary (e.g. when the inputs of a downgraded component change). This improves performance,\nespecially in change-detection-heavy applications, but leaves it up to the developer to manually\nnotify each framework as needed.</p>\n<p>For a more detailed discussion of the differences and their implications, see\n<a href=\"guide/upgrade-performance\">Upgrading for Performance</a>.</p>\n<div class=\"alert is-helpful\">\n<p> You can manually trigger a change detection run in AngularJS using\n<a href=\"https://docs.angularjs.org/api/ng/type/$rootScope.Scope#$apply\">scope.$apply(...)</a> or\n<a href=\"https://docs.angularjs.org/api/ng/type/$rootScope.Scope#$digest\">$rootScope.$digest()</a>.</p>\n<p> You can manually trigger a change detection run in Angular using <a href=\"api/core/NgZone#run\">ngZone.run(...)</a>.</p>\n</div>\n<h3 id=\"downgrading-multiple-modules\">Downgrading multiple modules<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"api/upgrade/static/downgradeModule#downgrading-multiple-modules\"><i class=\"material-icons\">link</i></a></h3>\n<p>It is possible to downgrade multiple modules and include them in an AngularJS application. In\nthat case, each downgraded module will be bootstrapped when an associated downgraded component or\ninjectable needs to be instantiated.</p>\n<p>Things to keep in mind, when downgrading multiple modules:</p>\n<ul>\n<li>\n<p>Each downgraded component/injectable needs to be explicitly associated with a downgraded\nmodule. See <code><a href=\"api/upgrade/static/downgradeComponent\" class=\"code-anchor\">downgradeComponent</a>()</code> and <code><a href=\"api/upgrade/static/downgradeInjectable\" class=\"code-anchor\">downgradeInjectable</a>()</code> for more details.</p>\n</li>\n<li>\n<p>If you want some injectables to be shared among all downgraded modules, you can provide them as\n<code><a href=\"api/core/StaticProvider\" class=\"code-anchor\">StaticProvider</a></code>s, when creating the <code><a href=\"api/core/PlatformRef\" class=\"code-anchor\">PlatformRef</a></code> (e.g. via <code><a href=\"api/platform-browser/platformBrowser\" class=\"code-anchor\">platformBrowser</a></code> or\n<code><a href=\"api/platform-browser-dynamic/platformBrowserDynamic\" class=\"code-anchor\">platformBrowserDynamic</a></code>).</p>\n</li>\n<li>\n<p>When using <a href=\"api/core/PlatformRef#bootstrapmodule\">`bootstrapModule()`</a> or\n<a href=\"api/core/PlatformRef#bootstrapmodulefactory\">`bootstrapModuleFactory()`</a> to bootstrap the\ndowngraded modules, each one is considered a \"root\" module. As a consequence, a new instance\nwill be created for every injectable provided in <code>\"root\"</code> (via\n<a href=\"api/core/Injectable#providedIn\">`providedIn`</a>).\nIf this is not your intention, you can have a shared module (that will act as act as the \"root\"\nmodule) and create all downgraded modules using that module's injector:</p>\n<code-example path=\"upgrade/static/ts/lite-multi-shared/module.ts\" region=\"shared-root-module\">\nlet rootInjectorPromise: Promise<<a href=\"api/core/Injector\" class=\"code-anchor\">Injector</a>>|null = null;\nconst getRootInjector = (extraProviders: <a href=\"api/core/StaticProvider\" class=\"code-anchor\">StaticProvider</a>[]) => {\n if (!rootInjectorPromise) {\n rootInjectorPromise = <a href=\"api/platform-browser-dynamic/platformBrowserDynamic\" class=\"code-anchor\">platformBrowserDynamic</a>(extraProviders)\n .bootstrapModule(Ng2RootModule)\n .then(moduleRef => moduleRef.injector);\n }\n return rootInjectorPromise;\n};\n\nconst downgradedNg2AModule = <a href=\"api/upgrade/static/downgradeModule\" class=\"code-anchor\">downgradeModule</a>(async (extraProviders: <a href=\"api/core/StaticProvider\" class=\"code-anchor\">StaticProvider</a>[]) => {\n const rootInjector = await getRootInjector(extraProviders);\n const moduleAFactory = await rootInjector.get(<a href=\"api/core/Compiler\" class=\"code-anchor\">Compiler</a>).compileModuleAsync(Ng2AModule);\n return moduleAFactory.create(rootInjector);\n});\nconst downgradedNg2BModule = <a href=\"api/upgrade/static/downgradeModule\" class=\"code-anchor\">downgradeModule</a>(async (extraProviders: <a href=\"api/core/StaticProvider\" class=\"code-anchor\">StaticProvider</a>[]) => {\n const rootInjector = await getRootInjector(extraProviders);\n const moduleBFactory = await rootInjector.get(<a href=\"api/core/Compiler\" class=\"code-anchor\">Compiler</a>).compileModuleAsync(Ng2BModule);\n return moduleBFactory.create(rootInjector);\n});\n/* . . . */\nconst appModule =\n angular\n .module(\n 'exampleAppModule', [downgradedNg2AModule, downgradedNg2BModule, downgradedNg2CModule])\n\n</code-example>\n</li>\n</ul>\n\n</section>\n\n\n\n </div>\n</article>\n\n<!-- links to this doc:\n - api/upgrade/static\n - api/upgrade/static/downgradeComponent\n - api/upgrade/static/downgradeInjectable\n - api/upgrade/static/testing/createAngularJSTestingModule\n - api/upgrade/static/testing/createAngularTestingModule\n - guide/upgrade-performance\n-->\n<!-- links from this doc:\n - /api\n - api/core/Compiler\n - api/core/Injectable#providedIn\n - api/core/Injector\n - api/core/NgModuleFactory\n - api/core/NgModuleRef\n - api/core/NgZone\n - api/core/NgZone#run\n - api/core/PlatformRef\n - api/core/PlatformRef#bootstrapModuleFactory\n - api/core/PlatformRef#bootstrapmodule\n - api/core/PlatformRef#bootstrapmodulefactory\n - api/core/StaticProvider\n - api/platform-browser-dynamic/platformBrowserDynamic\n - api/platform-browser/platformBrowser\n - api/upgrade\n - api/upgrade/static\n - api/upgrade/static/UpgradeModule\n - api/upgrade/static/downgradeComponent\n - api/upgrade/static/downgradeInjectable\n - api/upgrade/static/downgradeModule#description\n - api/upgrade/static/downgradeModule#differences-with-upgrademodule\n - api/upgrade/static/downgradeModule#downgrademodule\n - api/upgrade/static/downgradeModule#downgrading-multiple-modules\n - api/upgrade/static/downgradeModule#usage-notes\n - api?query=upgrade/static\n - guide/upgrade-performance\n - https://docs.angularjs.org/api/ng/type/$rootScope.Scope#$apply\n - https://docs.angularjs.org/api/ng/type/$rootScope.Scope#$digest\n - https://github.com/angular/angular/edit/master/packages/upgrade/static/src/downgrade_module.ts?message=docs(upgrade)%3A%20describe%20your%20change...#L21-L191\n - https://github.com/angular/angular/tree/12.0.0-next.7/packages/upgrade/static/src/downgrade_module.ts#L21-L191\n-->"
|
|
} |