diff --git a/public/docs/ts/latest/guide/component-styles.jade b/public/docs/ts/latest/guide/component-styles.jade index 0527c3d4a2..a113ea5fa9 100644 --- a/public/docs/ts/latest/guide/component-styles.jade +++ b/public/docs/ts/latest/guide/component-styles.jade @@ -2,102 +2,98 @@ block includes include ../_util-fns :marked - Angular applications are styled with regular CSS. That means we can apply - everything we know about CSS stylesheets, selectors, rules, and media queries - to our Angular applications directly. + Angular applications are styled with standard CSS. That means you can apply + everything you know about CSS stylesheets, selectors, rules, and media queries + directly to Angular applications. - On top of this, Angular has the ability to bundle *component styles* - with our components enabling a more modular design than regular stylesheets. + Additionally, Angular can bundle *component styles* + with components, enabling a more modular design than regular stylesheets. - In this chapter we learn how to load and apply these *component styles*. + This page describes how to load and apply these component styles. ## Table Of Contents - * [Using Component Styles](#using-component-styles) + * [Using component styles](#using-component-styles) * [Special selectors](#special-selectors) - * [Loading Styles into Components](#loading-styles) - * [Controlling View Encapsulation: Emulated, Native, and None](#view-encapsulation) - * [Appendix 1: Inspecting the generated runtime component styles](#inspect-generated-css) - * [Appendix 2: Loading Styles with Relative URLs](#relative-urls) + * [Loading styles into components](#loading-styles) + * [Controlling view encapsulation: native, emulated, and none](#view-encapsulation) + * [Appendix 1: Inspecting the CSS generated in emulated view encapsulation](#inspect-generated-css) + * [Appendix 2: Loading styles with relative URLs](#relative-urls) - Run the of the code shown in this chapter. + You can run the in Plunker and download the code from there. .l-main-section :marked - ## Using Component Styles + ## Using component styles - For every Angular component we write, we may define not only an HTML template, + For every Angular component you write, you may define not only an HTML template, but also the CSS styles that go with that template, - specifying any selectors, rules, and media queries that we need. + specifying any selectors, rules, and media queries that you need. One way to do this is to set the `styles` property in the component metadata. The `styles` property takes #{_an} #{_array} of strings that contain CSS code. - Usually we give it one string as in this example: + Usually you give it one string, as in the following example: +makeExample('component-styles/ts/src/app/hero-app.component.ts')(format='.') :marked - Component styles differ from traditional, global styles in a couple of ways. - - Firstly, the selectors we put into a component's styles *only apply within the template - of that component*. The `h1` selector in the example above only applies to the `

` tag + The selectors you put into a component's styles apply only within the template + of that component. The `h1` selector in the preceding example applies only to the `

` tag in the template of `HeroAppComponent`. Any `

` elements elsewhere in the application are unaffected. - This is a big improvement in modularity compared to how CSS traditionally works: + This is a big improvement in modularity compared to how CSS traditionally works. - 1. We can use the CSS class names and selectors that make the most sense in the context of each component. - - 1. Class names and selectors are local to the component and won't collide with - classes and selectors used elsewhere in the application. - - 1. Our component's styles *cannot* be changed by changes to styles elsewhere in the application. - - 1. We can co-locate the CSS code of each component with the TypeScript and HTML code of the component, - which leads to a neat and tidy project structure. - - 1. We can change or remove component CSS code in the future without trawling through the - whole application to see where else it may have been used. We just look at the component we're in. + * You can use the CSS class names and selectors that make the most sense in the context of each component. + * Class names and selectors are local to the component and don't collide with + classes and selectors used elsewhere in the application. + * Changes to styles elsewhere in the application don't affect the component's styles. + * You can co-locate the CSS code of each component with the TypeScript and HTML code of the component, + which leads to a neat and tidy project structure. + * You can change or remove component CSS code without searching through the + whole application to find where else the code is used. a(id="special-selectors") .l-main-section :marked ## Special selectors - Component styles have a few special *selectors* from the world of - [shadow DOM style scoping](https://www.w3.org/TR/css-scoping-1): + Component styles have a few special *selectors* from the world of shadow DOM style scoping + (described in the [CSS Scoping Module Level 1](https://www.w3.org/TR/css-scoping-1) page on the + [W3C](https://www.w3.org) site). + The following sections describe these selectors. ### :host Use the `:host` pseudo-class selector to target styles in the element that *hosts* the component (as opposed to - targeting elements *inside* the component's template): + targeting elements *inside* the component's template). +makeExample('component-styles/ts/src/app/hero-details.component.css', 'host')(format='.') :marked - This is the *only* way we can target the host element. We cannot reach - it from inside the component with other selectors, because it is not part of the - component's own template. It is in a parent component's template. + The `:host` selector is the only way to target the host element. You can't reach + the host element from inside the component with other selectors because it's not part of the + component's own template. The host element is in a parent component's template. Use the *function form* to apply host styles conditionally by including another selector inside parentheses after `:host`. - In the next example we target the host element again, but only when it also has the `active` CSS class. + The next example targets the host element again, but only when it also has the `active` CSS class. +makeExample('component-styles/ts/src/app/hero-details.component.css', 'hostfunction')(format=".") :marked ### :host-context - Sometimes it is useful to apply styles based on some condition *outside* a component's view. - For example, there may be a CSS theme class applied to the document `` element, and - we want to change how our component looks based on that. + Sometimes it's useful to apply styles based on some condition *outside* of a component's view. + For example, a CSS theme class could be applied to the document `` element, and + you want to change how your component looks based on that. - Use the `:host-context()` pseudo-class selector. It works just like the function - form of `:host()`. It looks for a CSS class in *any ancestor* of the component host element, all the way - up to the document root. It's useful when combined with another selector. + Use the `:host-context()` pseudo-class selector, which works just like the function + form of `:host()`. The `:host-context()` selector looks for a CSS class in any ancestor of the component host element, + up to the document root. The `:host-context()` selector is useful when combined with another selector. - In the following example, we apply a `background-color` style to all `

` elements *inside* the component, only + The following example applies a `background-color` style to all `

` elements *inside* the component, only if some ancestor element has the CSS class `theme-light`. +makeExample('component-styles/ts/src/app/hero-details.component.css', 'hostcontext')(format='.') @@ -107,151 +103,150 @@ a(id="special-selectors") Component styles normally apply only to the HTML in the component's own template. - We can use the `/deep/` selector to force a style down through the child component tree into all the child component views. - The `/deep/` selector works to any depth of nested components, and it applies *both to the view - children and the content children* of the component. + Use the `/deep/` selector to force a style down through the child component tree into all the child component views. + The `/deep/` selector works to any depth of nested components, and it applies to both the view + children and content children of the component. - In this example, we target all `

` elements, from the host element down - through this component to all of its child elements in the DOM: + The following example targets all `

` elements, from the host element down + through this component to all of its child elements in the DOM. +makeExample('component-styles/ts/src/app/hero-details.component.css', 'deep')(format=".") :marked - The `/deep/` selector also has the alias `>>>`. We can use either of the two interchangeably. + The `/deep/` selector also has the alias `>>>`. You can use either interchangeably. .alert.is-important :marked - The `/deep/` and `>>>` selectors should only be used with **emulated** view encapsulation. - This is the default and it is what we use most of the time. See the - [Controlling View Encapsulation](#view-encapsulation) - section for more details. + Use the `/deep/` and `>>>` selectors only with *emulated* view encapsulation. + Emulated is the default and most commonly used view encapsulation. For more information, see the + [Controlling view encapsulation](#view-encapsulation) section. a(id='loading-styles') .l-main-section :marked - ## Loading Styles into Components + ## Loading styles into components - We have several ways to add styles to a component: - * inline in the template HTML - * by setting `styles` or `styleUrls` metadata - * with CSS imports + There are several ways to add styles to a component: + * By setting `styles` or `styleUrls` metadata. + * Inline in the template HTML. + * With CSS imports. - The scoping rules outlined above apply to each of these loading patterns. + The scoping rules outlined earlier apply to each of these loading patterns. + + ### Styles in metadata - ### Styles in Metadata - - We can add a `styles` #{_array} property to the `@Component` #{_decorator}. + You can add a `styles` #{_array} property to the `@Component` #{_decorator}. Each string in the #{_array} (usually just one string) defines the CSS. - + +makeExample('component-styles/ts/src/app/hero-app.component.ts') - -:marked - ### Template Inline Styles - - We can embed styles directly into the HTML template by putting them - inside `