angular-cn/aio/dist/generated/docs/guide/migration-injectable.json

5 lines
8.7 KiB
JSON

{
"id": "guide/migration-injectable",
"title": "Migration for missing @Injectable() decorators and incomplete provider definitions",
"contents": "\n\n\n<div class=\"github-links\">\n <a href=\"https://github.com/angular/angular/edit/master/aio/content/guide/migration-injectable.md?message=docs%3A%20describe%20your%20change...\" aria-label=\"Suggest Edits\" title=\"Suggest Edits\"><i class=\"material-icons\" aria-hidden=\"true\" role=\"img\">mode_edit</i></a>\n</div>\n\n\n<div class=\"content\">\n <h1 id=\"migration-for-missing-injectable-decorators-and-incomplete-provider-definitions\">Migration for missing <code>@<a href=\"api/core/Injectable\" class=\"code-anchor\">Injectable</a>()</code> decorators and incomplete provider definitions<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/migration-injectable#migration-for-missing-injectable-decorators-and-incomplete-provider-definitions\"><i class=\"material-icons\">link</i></a></h1>\n<h3 id=\"what-does-this-schematic-do\">What does this schematic do?<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/migration-injectable#what-does-this-schematic-do\"><i class=\"material-icons\">link</i></a></h3>\n<ol>\n<li>This schematic adds an <code>@<a href=\"api/core/Injectable\" class=\"code-anchor\">Injectable</a>()</code> decorator to classes which are provided in the\napplication but are not decorated.</li>\n<li>The schematic updates providers which follow the <code>{provide: SomeToken}</code> pattern\nto explicitly specify <code>useValue: undefined</code>.</li>\n</ol>\n<p><strong>Example for missing <code>@<a href=\"api/core/Injectable\" class=\"code-anchor\">Injectable</a>()</code></strong></p>\n<p><em>Before migration:</em></p>\n<code-example language=\"typescript\">\nexport class MyService {...}\nexport class MyOtherService {...}\nexport class MyThirdClass {...}\nexport class MyFourthClass {...}\nexport class MyFifthClass {...}\n\n@<a href=\"api/core/NgModule\" class=\"code-anchor\">NgModule</a>({\n providers: [\n MyService,\n {provide: SOME_TOKEN, useClass: MyOtherService},\n // The following classes do not need to be decorated because they\n // are never instantiated and just serve as DI tokens.\n {provide: MyThirdClass, useValue: ...},\n {provide: MyFourthClass, useFactory: ...},\n {provide: MyFifthClass, useExisting: ...},\n ]\n})\n</code-example>\n<p><em>After migration:</em></p>\n<code-example language=\"ts\">\n@<a href=\"api/core/Injectable\" class=\"code-anchor\">Injectable</a>()\nexport class MyService {...}\n@<a href=\"api/core/Injectable\" class=\"code-anchor\">Injectable</a>()\nexport class MyOtherService {...}\nexport class MyThirdClass {...}\nexport class MyFourthClass {...}\nexport class MySixthClass {...}\n\n...\n</code-example>\n<p>Note that <code>MyThirdClass</code>, <code>MyFourthClass</code> and <code>MyFifthClass</code> do not need to be decorated\nwith <code>@<a href=\"api/core/Injectable\" class=\"code-anchor\">Injectable</a>()</code> because they are never instantiated, but just used as a <a href=\"guide/glossary#di-token\">DI token</a>.</p>\n<p><strong>Example for provider needing <code>useValue: undefined</code></strong></p>\n<p>This example shows a provider following the <code>{provide: X}</code> pattern.\nThe provider needs to be migrated to a more explicit definition where <code>useValue: undefined</code> is specified.</p>\n<p><em>Before migration</em>:</p>\n<code-example language=\"typescript\">\n{provide: MyToken}\n</code-example>\n<p><em>After migration</em>:</p>\n<code-example language=\"typescript\">\n{provide: MyToken, useValue: undefined}\n</code-example>\n<h3 id=\"why-is-adding-injectable-necessary\">Why is adding <code>@<a href=\"api/core/Injectable\" class=\"code-anchor\">Injectable</a>()</code> necessary?<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/migration-injectable#why-is-adding-injectable-necessary\"><i class=\"material-icons\">link</i></a></h3>\n<p>In our docs, we've always recommended adding <code>@<a href=\"api/core/Injectable\" class=\"code-anchor\">Injectable</a>()</code> decorators to any class that is provided or injected in your application.\nHowever, older versions of Angular did allow injection of a class without the decorator in certain cases, such as AOT mode.\nThis means if you accidentally omitted the decorator, your application may have continued to work despite missing <code>@<a href=\"api/core/Injectable\" class=\"code-anchor\">Injectable</a>()</code> decorators in some places.\nThis is problematic for future versions of Angular.\nEventually, we plan to strictly require the decorator because doing so enables further optimization of both the compiler and the runtime.\nThis schematic adds any <code>@<a href=\"api/core/Injectable\" class=\"code-anchor\">Injectable</a>()</code> decorators that may be missing to future-proof your app.</p>\n<h3 id=\"why-is-adding-usevalue-undefined-necessary\">Why is adding <code>useValue: undefined</code> necessary?<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/migration-injectable#why-is-adding-usevalue-undefined-necessary\"><i class=\"material-icons\">link</i></a></h3>\n<p>Consider the following pattern:</p>\n<code-example language=\"typescript\">\n@<a href=\"api/core/NgModule\" class=\"code-anchor\">NgModule</a>({\n providers: [{provide: MyService}]\n})\n</code-example>\n<p>Providers using this pattern will behave as if they provide <code>MyService</code> as <a href=\"guide/glossary#di-token\">DI token</a>\nwith the value of <code>undefined</code>.\nThis is not the case in Ivy where such providers will be interpreted as if <code>useClass: MyService</code> is specified.\nThis means that these providers will behave differently when updating to version 9 and above.\nTo ensure that the provider behaves the same as before, the DI value should be explicitly set to <code>undefined</code>.</p>\n<h3 id=\"when-should-i-be-adding-injectable-decorators-to-classes\">When should I be adding <code>@<a href=\"api/core/Injectable\" class=\"code-anchor\">Injectable</a>()</code> decorators to classes?<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/migration-injectable#when-should-i-be-adding-injectable-decorators-to-classes\"><i class=\"material-icons\">link</i></a></h3>\n<p>Any class that is provided must have an <code>@<a href=\"api/core/Injectable\" class=\"code-anchor\">Injectable</a>()</code> decorator.\nThe decorator is necessary for the framework to properly create an instance of that class through DI.</p>\n<p>However, classes which are already decorated with <code>@<a href=\"api/core/Pipe\" class=\"code-anchor\">Pipe</a></code>, <code>@<a href=\"api/core/Component\" class=\"code-anchor\">Component</a></code> or <code>@<a href=\"api/core/Directive\" class=\"code-anchor\">Directive</a></code> do not need both decorators.\nThe existing class decorator already instructs the compiler to generate the\nneeded information.</p>\n<h3 id=\"should-i-update-my-library\">Should I update my library?<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/migration-injectable#should-i-update-my-library\"><i class=\"material-icons\">link</i></a></h3>\n<p>Yes, if your library has any classes that are meant to be injected, they should be updated with the <code>@<a href=\"api/core/Injectable\" class=\"code-anchor\">Injectable</a>()</code> decorator.\nIn a future version of Angular, a missing <code>@<a href=\"api/core/Injectable\" class=\"code-anchor\">Injectable</a>()</code> decorator will always throw an error.</p>\n<p>Additionally, providers in your library that follow the described <code>{provide: X}</code> pattern should be updated to specify an explicit value.\nWithout explicit value, these providers can behave differently based on the Angular version in applications consuming your library.</p>\n\n \n</div>\n\n<!-- links to this doc:\n - guide/ivy-compatibility-examples\n-->\n<!-- links from this doc:\n - api/core/Component\n - api/core/Directive\n - api/core/Injectable\n - api/core/NgModule\n - api/core/Pipe\n - guide/glossary#di-token\n - guide/migration-injectable#migration-for-missing-injectable-decorators-and-incomplete-provider-definitions\n - guide/migration-injectable#should-i-update-my-library\n - guide/migration-injectable#what-does-this-schematic-do\n - guide/migration-injectable#when-should-i-be-adding-injectable-decorators-to-classes\n - guide/migration-injectable#why-is-adding-injectable-necessary\n - guide/migration-injectable#why-is-adding-usevalue-undefined-necessary\n - https://github.com/angular/angular/edit/master/aio/content/guide/migration-injectable.md?message=docs%3A%20describe%20your%20change...\n-->"
}