5 lines
22 KiB
JSON
5 lines
22 KiB
JSON
{
|
|
"id": "api/upgrade/static/UpgradeModule",
|
|
"title": "UpgradeModule",
|
|
"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/UpgradeModule\", \"name\": \"UpgradeModule\" } }\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/upgrade_module.ts?message=docs(upgrade)%3A%20describe%20your%20change...#L17-L311\" 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/upgrade_module.ts#L17-L311\" 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=\"upgrademodule\">UpgradeModule<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"api/upgrade/static/UpgradeModule#upgrademodule\"><i class=\"material-icons\">link</i></a></h1>\n \n <label class=\"api-type-label ngmodule\">ngmodule</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>An <code><a href=\"api/core/NgModule\" class=\"code-anchor\">NgModule</a></code>, which you import to provide AngularJS core services,\nand has an instance method used to bootstrap the hybrid upgrade application.</p>\n\n <p><a href=\"api/upgrade/static/UpgradeModule#description\">See more...</a></p>\n </section>\n \n \n \n <section class=\"ngmodule-overview\">\n<code-example language=\"ts\" hidecopy=\"true\">\nclass <a href=\"api/upgrade/static/UpgradeModule\" class=\"code-anchor\">UpgradeModule</a> {\n <a class=\"code-anchor\" href=\"api/upgrade/static/UpgradeModule#%24injector\"><span class=\"member-name\">$injector</span>: any</a>\n <a class=\"code-anchor\" href=\"api/upgrade/static/UpgradeModule#injector\"><span class=\"member-name\">injector</span>: Injector</a>\n <a class=\"code-anchor\" href=\"api/upgrade/static/UpgradeModule#ngZone\"><span class=\"member-name\">ngZone</span>: NgZone</a>\n <a class=\"code-anchor\" href=\"api/upgrade/static/UpgradeModule#bootstrap\"><span class=\"member-name\">bootstrap</span>(element: Element, modules: string[] = [], config?: any)</a>\n}\n</code-example>\n\n \n \n\n</section>\n\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/UpgradeModule#description\"><i class=\"material-icons\">link</i></a></h2>\n <p><em>Part of the <a href=\"api?query=upgrade/static\">upgrade/static</a>\nlibrary for hybrid upgrade apps that support AOT compilation</em></p>\n<p>The <code><a href=\"api/upgrade/static\" class=\"code-anchor\">upgrade/static</a></code> package contains helpers that allow AngularJS and Angular components\nto be used together inside a hybrid upgrade application, which supports AOT compilation.</p>\n<p>Specifically, the classes and functions in the <code><a href=\"api/upgrade/static\" class=\"code-anchor\">upgrade/static</a></code> module allow the following:</p>\n<ol>\n<li>Creation of an Angular directive that wraps and exposes an AngularJS component so\nthat it can be used in an Angular template. See <code><a href=\"api/upgrade/static/UpgradeComponent\" class=\"code-anchor\">UpgradeComponent</a></code>.</li>\n<li>Creation of an AngularJS directive that wraps and exposes an Angular component so\nthat it can be used in an AngularJS template. See <code><a href=\"api/upgrade/static/downgradeComponent\" class=\"code-anchor\">downgradeComponent</a></code>.</li>\n<li>Creation of an Angular root injector provider that wraps and exposes an AngularJS\nservice so that it can be injected into an Angular context. See\n<a href=\"api/upgrade/static/UpgradeModule#upgrading-an-angular-1-service\">Upgrading an AngularJS service</a> below.</li>\n<li>Creation of an AngularJS service that wraps and exposes an Angular injectable\nso that it can be injected into an AngularJS context. See <code><a href=\"api/upgrade/static/downgradeInjectable\" class=\"code-anchor\">downgradeInjectable</a></code>.</li>\n<li>Bootstrapping of a hybrid Angular application which contains both of the frameworks\ncoexisting in a single application.</li>\n</ol>\n\n <p>Further information available in the <a href=\"api/upgrade/static/UpgradeModule#usage-notes\">Usage Notes</a>...</p>\n</section>\n\n \n\n \n\n \n\n \n<section class=\"instance-properties\">\n <h2 id=\"properties\">Properties<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"api/upgrade/static/UpgradeModule#properties\"><i class=\"material-icons\">link</i></a></h2>\n <table class=\"is-full-width list-table property-table\">\n <thead>\n <tr>\n <th>Property</th>\n <th>Description</th>\n </tr>\n </thead>\n <tbody>\n \n <tr class=\"instance-property\">\n <td>\n <a id=\"$injector\"></a>\n <code class=\"\"><span class=\"member-name\">$injector</span>: any</code>\n </td>\n <td>\n \n <p>The AngularJS <code>$injector</code> for the upgrade application.</p>\n\n \n </td>\n </tr>\n \n <tr class=\"instance-property\">\n <td>\n <a id=\"injector\"></a>\n <code class=\"\"><span class=\"member-name\">injector</span>: <a href=\"api/core/Injector\" class=\"code-anchor\">Injector</a></code>\n </td>\n <td>\n \n <p>The Angular Injector *</p>\n\n \n </td>\n </tr>\n \n <tr class=\"instance-property\">\n <td>\n <a id=\"ngZone\"></a>\n <code class=\"\"><span class=\"member-name\">ngZone</span>: <a href=\"api/core/NgZone\" class=\"code-anchor\">NgZone</a></code>\n </td>\n <td>\n \n <p>The bootstrap zone for the upgrade application</p>\n\n \n </td>\n </tr>\n \n </tbody>\n </table>\n</section>\n\n \n\n<section class=\"instance-methods\">\n <h2 id=\"methods\">Methods<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"api/upgrade/static/UpgradeModule#methods\"><i class=\"material-icons\">link</i></a></h2>\n \n <a id=\"bootstrap\"></a>\n<table class=\"is-full-width method-table instance-method\">\n <thead><tr><th>\n <div class=\"with-github-links\">\n <h3 id=\"bootstrap\">\n bootstrap()\n \n <a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"api/upgrade/static/UpgradeModule#bootstrap\"><i class=\"material-icons\">link</i></a></h3>\n <div class=\"github-links\">\n <a href=\"https://github.com/angular/angular/edit/master/packages/upgrade/static/src/upgrade_module.ts?message=docs(upgrade)%3A%20describe%20your%20change...#L167-L310\" 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/upgrade_module.ts#L167-L310\" aria-label=\"View Source\" title=\"View Source\"><i class=\"material-icons\" aria-hidden=\"true\" role=\"img\">code</i></a>\n</div>\n </div>\n </th></tr></thead>\n <tbody>\n <tr>\n <td class=\"short-description\">\n <p>Bootstrap an AngularJS application from this NgModule</p>\n\n </td>\n </tr>\n \n <tr>\n <td>\n <div class=\"overload-info\">\n \n\n <code-example language=\"ts\" hidecopy=\"true\" class=\"no-box api-heading\"><span class=\"member-name\">bootstrap</span>(element: Element, modules: string[] = [], config?: any)</code-example>\n\n \n\n <h6 class=\"no-anchor\" id=\"parameters\">Parameters</h6>\n <table class=\"is-full-width list-table parameters-table instance-method-overload-parameters\">\n <tbody>\n \n <tr class=\"instance-method-overload-parameter\">\n <td class=\"param-name\">\n <a id=\"\"></a>\n <code>element</code>\n </td>\n <td class=\"param-type\"><code>Element</code></td>\n <td class=\"param-description\">\n <p>the element on which to bootstrap the AngularJS application</p>\n\n </td>\n </tr>\n <tr class=\"instance-method-overload-parameter\">\n <td class=\"param-name\">\n <a id=\"\"></a>\n <code>modules</code>\n </td>\n <td class=\"param-type\"><code>string[]</code></td>\n <td class=\"param-description\">\n <p>the AngularJS modules to bootstrap for this application</p>\n<p> Optional. Default is <code>[]</code>.</p>\n\n </td>\n </tr>\n <tr class=\"instance-method-overload-parameter\">\n <td class=\"param-name\">\n <a id=\"\"></a>\n <code>config</code>\n </td>\n <td class=\"param-type\"><code>any</code></td>\n <td class=\"param-description\">\n <p>optional extra AngularJS bootstrap configuration</p>\n<p> Optional. Default is <code>undefined</code>.</p>\n\n </td>\n </tr>\n </tbody>\n</table>\n\n \n\n\n \n\n \n</div>\n </td>\n </tr>\n \n\n \n\n \n </tbody>\n</table>\n\n \n</section>\n\n\n \n \n<section class=\"providers\">\n <h2 id=\"providers\">Providers<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"api/upgrade/static/UpgradeModule#providers\"><i class=\"material-icons\">link</i></a></h2>\n <table class=\"is-full-width list-table property-table\">\n <thead>\n <tr>\n <th>Provider</th>\n </tr>\n </thead>\n <tbody>\n \n <tr>\n <td>\n <code-example language=\"ts\" hidecopy=\"true\" class=\"no-box\">\n angular1Providers\n </code-example>\n </td>\n </tr>\n \n </tbody>\n </table>\n </section>\n\n \n\n \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/UpgradeModule#usage-notes\"><i class=\"material-icons\">link</i></a></h2>\n <code-example language=\"ts\">\nimport {<a href=\"api/upgrade/static/UpgradeModule\" class=\"code-anchor\">UpgradeModule</a>} from '@angular/upgrade/<a href=\"api/upgrade/static\" class=\"code-anchor\">static</a>';\n</code-example>\n<p>See also the <a href=\"api/upgrade/static/UpgradeModule#examples\">examples</a> below.</p>\n<h3 id=\"mental-model\">Mental Model<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"api/upgrade/static/UpgradeModule#mental-model\"><i class=\"material-icons\">link</i></a></h3>\n<p>When reasoning about how a hybrid application works it is useful to have a mental model which\ndescribes what is happening and explains what is happening at the lowest level.</p>\n<ol>\n<li>There are two independent frameworks running in a single application, each framework treats\nthe other as a black box.</li>\n<li>Each DOM element on the page is owned exactly by one framework. Whichever framework\ninstantiated the element is the owner. Each framework only updates/interacts with its own\nDOM elements and ignores others.</li>\n<li>AngularJS directives always execute inside the AngularJS framework codebase regardless of\nwhere they are instantiated.</li>\n<li>Angular components always execute inside the Angular framework codebase regardless of\nwhere they are instantiated.</li>\n<li>An AngularJS component can be \"upgraded\"\" to an Angular component. This is achieved by\ndefining an Angular directive, which bootstraps the AngularJS component at its location\nin the DOM. See <code><a href=\"api/upgrade/static/UpgradeComponent\" class=\"code-anchor\">UpgradeComponent</a></code>.</li>\n<li>An Angular component can be \"downgraded\" to an AngularJS component. This is achieved by\ndefining an AngularJS directive, which bootstraps the Angular component at its location\nin the DOM. See <code><a href=\"api/upgrade/static/downgradeComponent\" class=\"code-anchor\">downgradeComponent</a></code>.</li>\n<li>\n<p>Whenever an \"upgraded\"/\"downgraded\" component is instantiated the host element is owned by\nthe framework doing the instantiation. The other framework then instantiates and owns the\nview for that component.</p>\n<ol>\n<li>This implies that the component bindings will always follow the semantics of the\ninstantiation framework.</li>\n<li>The DOM attributes are parsed by the framework that owns the current template. So\nattributes in AngularJS templates must use kebab-case, while AngularJS templates must use\ncamelCase.</li>\n<li>However the template binding syntax will always use the Angular style, e.g. square\nbrackets (<code>[...]</code>) for property binding.</li>\n</ol>\n</li>\n<li>Angular is bootstrapped first; AngularJS is bootstrapped second. AngularJS always owns the\nroot component of the application.</li>\n<li>The new application is running in an Angular zone, and therefore it no longer needs calls to\n<code>$apply()</code>.</li>\n</ol>\n<h3 id=\"the-upgrademodule-class\">The <code><a href=\"api/upgrade/static/UpgradeModule\" class=\"code-anchor\">UpgradeModule</a></code> class<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"api/upgrade/static/UpgradeModule#the-upgrademodule-class\"><i class=\"material-icons\">link</i></a></h3>\n<p>This class is an <code><a href=\"api/core/NgModule\" class=\"code-anchor\">NgModule</a></code>, which you import to provide AngularJS core services,\nand has an instance method used to bootstrap the hybrid upgrade application.</p>\n<ul>\n<li>\n<p>Core AngularJS services\nImporting this <code><a href=\"api/core/NgModule\" class=\"code-anchor\">NgModule</a></code> will add providers for the core\n<a href=\"https://docs.angularjs.org/api/ng/service\">AngularJS services</a> to the root injector.</p>\n</li>\n<li>\n<p>Bootstrap\nThe runtime instance of this class contains a <a href=\"api/upgrade/static/UpgradeModule#bootstrap\">`bootstrap()`</a>\nmethod, which you use to bootstrap the top level AngularJS module onto an element in the\nDOM for the hybrid upgrade app.</p>\n<p>It also contains properties to access the <a href=\"api/upgrade/static/UpgradeModule#injector\">root injector</a>, the\nbootstrap <code><a href=\"api/core/NgZone\" class=\"code-anchor\">NgZone</a></code> and the\n<a href=\"https://docs.angularjs.org/api/auto/service/$injector\">AngularJS $injector</a>.</p>\n</li>\n</ul>\n<h3 id=\"examples\">Examples<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"api/upgrade/static/UpgradeModule#examples\"><i class=\"material-icons\">link</i></a></h3>\n<p>Import the <code><a href=\"api/upgrade/static/UpgradeModule\" class=\"code-anchor\">UpgradeModule</a></code> into your top level <a href=\"api/core/NgModule\">Angular `NgModule`</a>.</p>\n<code-example path=\"upgrade/static/ts/full/module.ts\" region=\"ng2-module\">\n// This <a href=\"api/core/NgModule\" class=\"code-anchor\">NgModule</a> represents the Angular pieces of the application\n@<a href=\"api/core/NgModule\" class=\"code-anchor\">NgModule</a>({\n declarations: [Ng2HeroesComponent, Ng1HeroComponentWrapper],\n providers: [\n HeroesService,\n // Register an Angular provider whose value is the \"upgraded\" AngularJS service\n {provide: TextFormatter, useFactory: (i: any) => i.get('textFormatter'), deps: ['$injector']}\n ],\n // All components that are to be \"downgraded\" must be declared as `entryComponents`\n entryComponents: [Ng2HeroesComponent],\n // We must import `<a href=\"api/upgrade/static/UpgradeModule\" class=\"code-anchor\">UpgradeModule</a>` to get access to the AngularJS core services\n imports: [<a href=\"api/platform-browser/BrowserModule\" class=\"code-anchor\">BrowserModule</a>, <a href=\"api/upgrade/static/UpgradeModule\" class=\"code-anchor\">UpgradeModule</a>]\n})\nexport class Ng2AppModule {\n}\n\n</code-example>\n<p>Then inject <code><a href=\"api/upgrade/static/UpgradeModule\" class=\"code-anchor\">UpgradeModule</a></code> into your Angular <code><a href=\"api/core/NgModule\" class=\"code-anchor\">NgModule</a></code> and use it to bootstrap the top level\n<a href=\"https://docs.angularjs.org/api/ng/type/angular.Module\">AngularJS module</a> in the\n<code>ngDoBootstrap()</code> method.</p>\n<code-example path=\"upgrade/static/ts/full/module.ts\" region=\"bootstrap-ng1\">\nexport class Ng2AppModule {\n constructor(private upgrade: <a href=\"api/upgrade/static/UpgradeModule\" class=\"code-anchor\">UpgradeModule</a>) {}\n\n ngDoBootstrap() {\n // We bootstrap the AngularJS app.\n this.upgrade.bootstrap(document.body, [ng1AppModule.name]);\n }\n}\n\n</code-example>\n<p>Finally, kick off the whole process, by bootstraping your top level Angular <code><a href=\"api/core/NgModule\" class=\"code-anchor\">NgModule</a></code>.</p>\n<code-example path=\"upgrade/static/ts/full/module.ts\" region=\"bootstrap-ng2\">\n// We bootstrap the Angular module as we would do in a normal Angular app.\n// (We are using the dynamic <a href=\"api/animations/browser\" class=\"code-anchor\">browser</a> platform as this example has not been compiled AOT.)\n<a href=\"api/platform-browser-dynamic/platformBrowserDynamic\" class=\"code-anchor\">platformBrowserDynamic</a>().bootstrapModule(Ng2AppModule);\n\n</code-example>\n<a id=\"upgrading-an-angular-1-service\"></a>\n<h3 id=\"upgrading-an-angularjs-service\">Upgrading an AngularJS service<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"api/upgrade/static/UpgradeModule#upgrading-an-angularjs-service\"><i class=\"material-icons\">link</i></a></h3>\n<p>There is no specific API for upgrading an AngularJS service. Instead you should just follow the\nfollowing recipe:</p>\n<p>Let's say you have an AngularJS service:</p>\n<code-example path=\"upgrade/static/ts/full/module.ts\" region=\"ng1-text-formatter-service\">\nexport class TextFormatter {\n titleCase(value: string) {\n return value.replace(/((^|\\s)[a-z])/g, (_, c) => c.toUpperCase());\n }\n}\n\n// This AngularJS service will be \"upgraded\" to be used in Angular\nng1AppModule.service('textFormatter', [TextFormatter]);\n\n</code-example>\n<p>Then you should define an Angular provider to be included in your <code><a href=\"api/core/NgModule\" class=\"code-anchor\">NgModule</a></code> <code>providers</code>\nproperty.</p>\n<code-example path=\"upgrade/static/ts/full/module.ts\" region=\"upgrade-ng1-service\">\n// Register an Angular provider whose value is the \"upgraded\" AngularJS service\n{provide: TextFormatter, useFactory: (i: any) => i.get('textFormatter'), deps: ['$injector']}\n\n</code-example>\n<p>Then you can use the \"upgraded\" AngularJS service by injecting it into an Angular component\nor service.</p>\n<code-example path=\"upgrade/static/ts/full/module.ts\" region=\"use-ng1-upgraded-service\">\nconstructor(textFormatter: TextFormatter) {\n // Change all the hero names to title case, using the \"upgraded\" AngularJS service\n this.heroes.forEach((hero: Hero) => hero.name = textFormatter.titleCase(hero.name));\n}\n\n</code-example>\n\n</section>\n\n\n\n </div>\n</article>\n\n<!-- links to this doc:\n - api/common/upgrade/$locationShimProvider\n - api/router/upgrade/RouterUpgradeInitializer\n - api/router/upgrade/locationSyncBootstrapListener\n - api/router/upgrade/setUpLocationSync\n - api/upgrade/static\n - api/upgrade/static/downgradeInjectable\n - api/upgrade/static/downgradeModule\n - api/upgrade/static/testing/createAngularJSTestingModule\n - api/upgrade/static/testing/createAngularTestingModule\n - guide/upgrade\n - guide/upgrade-performance\n-->\n<!-- links from this doc:\n - /api\n - api/animations/browser\n - api/core/Injector\n - api/core/NgModule\n - api/core/NgZone\n - api/platform-browser-dynamic/platformBrowserDynamic\n - api/platform-browser/BrowserModule\n - api/upgrade\n - api/upgrade/static\n - api/upgrade/static/UpgradeComponent\n - api/upgrade/static/UpgradeModule#%24injector\n - api/upgrade/static/UpgradeModule#bootstrap\n - api/upgrade/static/UpgradeModule#description\n - api/upgrade/static/UpgradeModule#examples\n - api/upgrade/static/UpgradeModule#injector\n - api/upgrade/static/UpgradeModule#mental-model\n - api/upgrade/static/UpgradeModule#methods\n - api/upgrade/static/UpgradeModule#ngZone\n - api/upgrade/static/UpgradeModule#properties\n - api/upgrade/static/UpgradeModule#providers\n - api/upgrade/static/UpgradeModule#the-upgrademodule-class\n - api/upgrade/static/UpgradeModule#upgrademodule\n - api/upgrade/static/UpgradeModule#upgrading-an-angular-1-service\n - api/upgrade/static/UpgradeModule#upgrading-an-angularjs-service\n - api/upgrade/static/UpgradeModule#usage-notes\n - api/upgrade/static/downgradeComponent\n - api/upgrade/static/downgradeInjectable\n - api?query=upgrade/static\n - https://docs.angularjs.org/api/auto/service/$injector\n - https://docs.angularjs.org/api/ng/service\n - https://docs.angularjs.org/api/ng/type/angular.Module\n - https://github.com/angular/angular/edit/master/packages/upgrade/static/src/upgrade_module.ts?message=docs(upgrade)%3A%20describe%20your%20change...#L167-L310\n - https://github.com/angular/angular/edit/master/packages/upgrade/static/src/upgrade_module.ts?message=docs(upgrade)%3A%20describe%20your%20change...#L17-L311\n - https://github.com/angular/angular/tree/12.0.0-next.7/packages/upgrade/static/src/upgrade_module.ts#L167-L310\n - https://github.com/angular/angular/tree/12.0.0-next.7/packages/upgrade/static/src/upgrade_module.ts#L17-L311\n-->"
|
|
} |