diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index d3f4871e2c..410656958e 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -844,6 +844,7 @@ testing/** @angular/fw-test /aio/content/guide/deprecations.md @angular/fw-docs-packaging @angular/framework-global-approvers @angular/framework-global-approvers-for-docs-only-changes /aio/content/guide/migration-renderer.md @angular/fw-docs-packaging @angular/framework-global-approvers @angular/framework-global-approvers-for-docs-only-changes /aio/content/guide/migration-undecorated-classes.md @angular/fw-docs-packaging @angular/framework-global-approvers @angular/framework-global-approvers-for-docs-only-changes +/aio/content/guide/migration-dynamic-flag.md @angular/fw-docs-packaging @angular/framework-global-approvers @angular/framework-global-approvers-for-docs-only-changes # ================================================ diff --git a/aio/content/guide/deprecations.md b/aio/content/guide/deprecations.md index f9e7a1ef05..f972401a26 100644 --- a/aio/content/guide/deprecations.md +++ b/aio/content/guide/deprecations.md @@ -401,6 +401,11 @@ See the [dedicated migration guide for Renderer](guide/migration-renderer). ### Migrating undecorated classes See the [dedicated migration guide for undecorated classes](guide/migration-undecorated-classes). +{@a flag-migration} +### Dynamic queries flag migration + + See the [dedicated migration guide for dynamic queries](guide/migration-dynamic-flag). + {@a removed} ## Removed APIs diff --git a/aio/content/guide/migration-dynamic-flag.md b/aio/content/guide/migration-dynamic-flag.md new file mode 100644 index 0000000000..7b095f6478 --- /dev/null +++ b/aio/content/guide/migration-dynamic-flag.md @@ -0,0 +1,107 @@ + +# Dynamic queries flag migration + +## What does this migration do? + +In Angular version 8, a schematic added `static` flags to all `@ViewChild()` +and `@ContentChild()` queries. +This was the first step towards changing the default behavior. +With version 9, the default value +changes to `static: false` and the flag becomes optional. + +This schematic scans classes in the compilation and for each +class, checks if the members have a `@ViewChild()` or +`@ContentChild()` query with the `static` flag set to +`false`. If so, the schematic removes the flag, as it +now matches the default. + +**Before:** +```ts +@ViewChild('foo', {static: false}) foo: ElementRef; + +@ViewChild('bar', {static: true}) bar: ElementRef; +``` + + +**After:** +```ts +@ViewChild('foo') foo: ElementRef; + +// this query doesn't change because the static value is true +@ViewChild('bar', {static: true}) bar: ElementRef; +``` + +Note that the flag is not supported in `@ViewChildren()` +or `@ContentChildren()` queries, so the schematic +will not check these properties. + + +## Why is this migration necessary? + +This schematic performs a code cleanup to remove `static` +flags that match the default, as they are no longer +necessary. Functionally, the code change should be a noop. + +Before version 9, Angular figured out the static or +dynamic nature of a query automatically, based +on how the template was written. Looking at templates +in this way, however, caused buggy and surprising behavior +(see more about that in the [Static Query Migration Guide](guide/static-query-migration#what-does-this-flag-mean)). + As of version 9, Angular uses dynamic queries +(`static: false`) by default, which simplifies +queries. Developers can still explicitly set a +query to `static: true` if necessary. + + +