From bc69182bdd2f084466a2f722afc85cde425e1454 Mon Sep 17 00:00:00 2001 From: David Shevitz Date: Thu, 24 Sep 2020 20:30:13 +0000 Subject: [PATCH] docs: Migrate section, view encapsulation, from Component Styles topic into its own topic. (#38986) PR Close #38986 --- .pullapprove.yml | 1 + aio/content/guide/component-styles.md | 88 +------------------------ aio/content/guide/view-encapsulation.md | 83 +++++++++++++++++++++++ aio/content/navigation.json | 5 ++ 4 files changed, 90 insertions(+), 87 deletions(-) create mode 100644 aio/content/guide/view-encapsulation.md diff --git a/.pullapprove.yml b/.pullapprove.yml index 11e5274bde..ca111fe112 100644 --- a/.pullapprove.yml +++ b/.pullapprove.yml @@ -324,6 +324,7 @@ groups: 'aio/content/examples/component-interaction/**', 'aio/content/images/guide/component-interaction/**', 'aio/content/guide/component-styles.md', + 'aio/content/guide/view-encapsulation.md', 'aio/content/examples/component-styles/**', 'aio/content/guide/dependency-injection.md', 'aio/content/examples/dependency-injection/**', diff --git a/aio/content/guide/component-styles.md b/aio/content/guide/component-styles.md index 918d350e37..dc7b1b9f77 100644 --- a/aio/content/guide/component-styles.md +++ b/aio/content/guide/component-styles.md @@ -119,7 +119,7 @@ The `/deep/` combinator also has the aliases `>>>`, and `::ng-deep`. Use `/deep/`, `>>>` and `::ng-deep` only with *emulated* view encapsulation. Emulated is the default and most commonly used view encapsulation. For more information, see the -[Controlling view encapsulation](guide/component-styles#view-encapsulation) section. +[View Encapsulation](guide/view-encapsulation) section. @@ -267,89 +267,3 @@ as explained in the [CLI wiki](https://github.com/angular/angular-cli/wiki/stori Style strings added to the `@Component.styles` array _must be written in CSS_ because the CLI cannot apply a preprocessor to inline styles. - -{@a view-encapsulation} - -## View encapsulation - -As discussed earlier, component CSS styles are encapsulated into the component's view and don't -affect the rest of the application. - -To control how this encapsulation happens on a *per -component* basis, you can set the *view encapsulation mode* in the component metadata. -Choose from the following modes: - -* `ShadowDom` view encapsulation uses the browser's native shadow DOM implementation (see - [Shadow DOM](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Shadow_DOM) - on the [MDN](https://developer.mozilla.org) site) - to attach a shadow DOM to the component's host element, and then puts the component - view inside that shadow DOM. The component's styles are included within the shadow DOM. - -* `Native` view encapsulation uses a now deprecated version of the browser's native shadow DOM implementation - [learn about the changes](https://hayato.io/2016/shadowdomv1/). - -* `Emulated` view encapsulation (the default) emulates the behavior of shadow DOM by preprocessing - (and renaming) the CSS code to effectively scope the CSS to the component's view. - For details, see [Inspecting generated CSS](guide/component-styles#inspect-generated-css) below. - -* `None` means that Angular does no view encapsulation. - Angular adds the CSS to the global styles. - The scoping rules, isolations, and protections discussed earlier don't apply. - This is essentially the same as pasting the component's styles into the HTML. - -To set the components encapsulation mode, use the `encapsulation` property in the component metadata: - - - -`ShadowDom` view encapsulation only works on browsers that have native support -for shadow DOM (see [Shadow DOM v1](https://caniuse.com/#feat=shadowdomv1) on the -[Can I use](http://caniuse.com) site). The support is still limited, -which is why `Emulated` view encapsulation is the default mode and recommended -in most cases. - -{@a inspect-generated-css} - -## Inspecting generated CSS - -When using emulated view encapsulation, Angular preprocesses -all component styles so that they approximate the standard shadow CSS scoping rules. - -In the DOM of a running Angular application with emulated view -encapsulation enabled, each DOM element has some extra attributes -attached to it: - - - <hero-details _nghost-pmm-5> - <h2 _ngcontent-pmm-5>Mister Fantastic</h2> - <hero-team _ngcontent-pmm-5 _nghost-pmm-6> - <h3 _ngcontent-pmm-6>Team</h3> - </hero-team> - </hero-detail> - - - -There are two kinds of generated attributes: - -* An element that would be a shadow DOM host in native encapsulation has a - generated `_nghost` attribute. This is typically the case for component host elements. -* An element within a component's view has a `_ngcontent` attribute -that identifies to which host's emulated shadow DOM this element belongs. - -The exact values of these attributes aren't important. They are automatically -generated and you never refer to them in application code. But they are targeted -by the generated component styles, which are in the `` section of the DOM: - - - [_nghost-pmm-5] { - display: block; - border: 1px solid black; - } - - h3[_ngcontent-pmm-6] { - background-color: white; - border: 1px solid #777; - } - - -These styles are post-processed so that each selector is augmented -with `_nghost` or `_ngcontent` attribute selectors. -These extra selectors enable the scoping rules described in this page. diff --git a/aio/content/guide/view-encapsulation.md b/aio/content/guide/view-encapsulation.md new file mode 100644 index 0000000000..0c82a247c8 --- /dev/null +++ b/aio/content/guide/view-encapsulation.md @@ -0,0 +1,83 @@ +# View encapsulation + +In Angular, component CSS styles are encapsulated into the component's view and don't +affect the rest of the application. + +To control how this encapsulation happens on a *per +component* basis, you can set the *view encapsulation mode* in the component metadata. +Choose from the following modes: + +* `ShadowDom` view encapsulation uses the browser's native shadow DOM implementation (see + [Shadow DOM](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Shadow_DOM) + on the [MDN](https://developer.mozilla.org) site) + to attach a shadow DOM to the component's host element, and then puts the component + view inside that shadow DOM. The component's styles are included within the shadow DOM. + +* `Native` view encapsulation uses a now deprecated version of the browser's native shadow DOM implementation - [learn about the changes](https://hayato.io/2016/shadowdomv1/). + +* `Emulated` view encapsulation (the default) emulates the behavior of shadow DOM by preprocessing + (and renaming) the CSS code to effectively scope the CSS to the component's view. + For details, see [Inspecting generated CSS](guide/view-encapsulation#inspect-generated-css) below. + +* `None` means that Angular does no view encapsulation. + Angular adds the CSS to the global styles. + The scoping rules, isolations, and protections discussed earlier don't apply. + This is essentially the same as pasting the component's styles into the HTML. + +To set the components encapsulation mode, use the `encapsulation` property in the component metadata: + + + +`ShadowDom` view encapsulation only works on browsers that have native support +for shadow DOM (see [Shadow DOM v1](https://caniuse.com/#feat=shadowdomv1) on the +[Can I use](http://caniuse.com) site). The support is still limited, +which is why `Emulated` view encapsulation is the default mode and recommended +in most cases. + +{@a inspect-generated-css} + +## Inspecting generated CSS + +When using emulated view encapsulation, Angular preprocesses +all component styles so that they approximate the standard shadow CSS scoping rules. + +In the DOM of a running Angular application with emulated view +encapsulation enabled, each DOM element has some extra attributes +attached to it: + + + <hero-details _nghost-pmm-5> + <h2 _ngcontent-pmm-5>Mister Fantastic</h2> + <hero-team _ngcontent-pmm-5 _nghost-pmm-6> + <h3 _ngcontent-pmm-6>Team</h3> + </hero-team> + </hero-detail> + + + +There are two kinds of generated attributes: + +* An element that would be a shadow DOM host in native encapsulation has a + generated `_nghost` attribute. This is typically the case for component host elements. +* An element within a component's view has a `_ngcontent` attribute +that identifies to which host's emulated shadow DOM this element belongs. + +The exact values of these attributes aren't important. They are automatically +generated and you never refer to them in application code. But they are targeted +by the generated component styles, which are in the `` section of the DOM: + + + [_nghost-pmm-5] { + display: block; + border: 1px solid black; + } + + h3[_ngcontent-pmm-6] { + background-color: white; + border: 1px solid #777; + } + + +These styles are post-processed so that each selector is augmented +with `_nghost` or `_ngcontent` attribute selectors. +These extra selectors enable the scoping rules described in this page. \ No newline at end of file diff --git a/aio/content/navigation.json b/aio/content/navigation.json index ef4f25f3e9..efac7d1af5 100644 --- a/aio/content/navigation.json +++ b/aio/content/navigation.json @@ -116,6 +116,11 @@ "title": "Component Lifecycle", "tooltip": "Angular calls lifecycle hook methods on directives and components as it creates, changes, and destroys them." }, + { + "url": "guide/view-encapsulation", + "title": "View Encapsulation", + "tooltip": "Describes how component CSS styles are encapsulated into a component's view." + }, { "url": "guide/component-interaction", "title": "Component Interaction",