skills/angular__angular
1
0
Fork 0
mirror of https://github.com/angular/angular.git synced 2026-09-14 13:54:52 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: add guide for theming your own components (#1385)

Browse Source
This commit is contained in:
Bruno da Silva joão
2016-10-18 16:24:29 -02:00
committed by Jeremy Elbourn
parent cbecbced7d
commit 3c1e8d2d28
2 changed files with 88 additions and 29 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/theming-your-components.md
+69
View File
@@ -0,0 +1,69 @@
#Theming your custom components
In order to style your own components with Angular Material's tooling, the component's styles must be defined with Sass.
## Using `@mixin` to automatically apply a theme
### Why using `@mixin`
The advantage of using a `@mixin` function is that when you change your theme, every file that uses it will be updated automatically.
Calling it with a different theme argument allow multiple themes within the app or component.
### How to use `@mixin`
We can better theming our custom components adding a `@mixin` function to its theme file and then calling this function to apply a theme.
All you need is to create a `@mixin` function in the custom-component-theme.scss
```sass
// Import all the tools needed to customize the theme and extract parts of it
@import '~@angular/material/core/theming/all-theme';
// Define a mixin that accepts a theme and outputs the color styles for the component.
@mixin candy-carousel-theme($theme) {
// Extract whichever individual palettes you need from the theme.
$primary: map-get($theme, primary);
$accent: map-get($theme, accent);
// Use md-color to extract individual colors from a palette as necessary.
.candy-carousel {
background-color: md-color($primary);
border-color: md-color($accent, A400);
}
}
```
Now you just have have to call the `@mixin` function to apply the theme:
```sass
// Import a pre-built theme
@import '~@angular/material/core/theming/prebuilt/deep-purple-amber';
// Import your custom input theme file so you can call the custom-input-theme function
@import 'app/candy-carousel/candy-carousel-theme.scss';
// Using the $theme variable from the pre-built theme you can call the theming function
@include candy-carousel-theme($theme);
```
For more details about the theming functions, see the comments in the
[source](https://github.com/angular/material2/blob/master/src/lib/core/theming/_theming.scss).
### Best practices using `@mixin`
When using `@mixin`, the theme file should only contain the definitions that are affected by the passed-in theme.
All styles that are not affected by the theme should be placed in a `candy-carousel.scss` file. This file should contain everything that is not affected by the theme like sizes, transitions...
Styles that are affected by the theme should be placed in a separated theming file as `_candy-carousel-theme.scss` and the file should have a `_` before the name. This file should contain the `@mixin` function responsible for applying the theme to the component.
## Using colors from a pallete
You can consume the theming functions from the `@angular/material/core/theming/theming` and Material pallete vars from `@angular/material/core/theming/palette`. You can use the `md-color` function to extract a specific color from a palette. For example:
```scss
// Import theming functions
@import '~@angular/material/core/theming/theming';
// Import your custom theme
@import 'src/unicorn-app-theme.scss';
// Use md-color to extract individual colors from a palette as necessary.
.candy-carousel {
background-color: md-color($candy-app-primary);
border-color: md-color($candy-app-accent, A400);
}
```
docs/theming.md
+19 -29
View File
@@ -3,9 +3,9 @@
### What is a theme?
A **theme** is the set of colors that will be applied to the Angular Material components. The
library's approach to theming is based on the guidance from the [Material Design spec][1].
library's approach to theming is based on the guidance from the [Material Design spec][1].
In Angular Material, a theme is created by composing multiple palettes. In particular,
In Angular Material, a theme is created by composing multiple palettes. In particular,
a theme consists of:
* A primary palette: colors most widely used across all screens and components.
* An accent palette: colors used for the floating action button and interactive elements.
@@ -21,9 +21,9 @@ app doesn't have to spend cycles generating theme styles on startup.
### Using a pre-built theme
Angular Material comes prepackaged with several pre-built theme css files. These theme files also
include all of the styles for core (styles common to all components), so you only have to include a
single css file for Angular Material in your app.
single css file for Angular Material in your app.
You can include a theme file directly into your application from
You can include a theme file directly into your application from
`@angular/material/core/theming/prebuilt`
If you're using Angular CLI, this is as simple as including one line
@@ -35,8 +35,8 @@ in your `style.css` file:
Alternatively, you can just reference the file directly. This would look something like
```html
<link href="node_modules/@angular/material/core/theming/prebuilt/indigo-pink.css" rel="stylesheet">
```
The actual path will depend on your server setup.
```
The actual path will depend on your server setup.
You can also concatenate the file with the rest of your application's css.
@@ -56,25 +56,25 @@ the corresponding styles. A typical theme file will look something like this:
// Define the palettes for your theme using the Material Design palettes available in palette.scss
// (imported above). For each palette, you can optionally specify a default, lighter, and darker
// hue.
$primary: md-palette($md-indigo);
$accent: md-palette($md-pink, A200, A100, A400);
$candy-app-primary: md-palette($md-indigo);
$candy-app-accent: md-palette($md-pink, A200, A100, A400);
// The warn palette is optional (defaults to red).
$warn: md-palette($md-red);
$candy-app-warn: md-palette($md-red);
// Create the theme object (a Sass map containing all of the palettes).
$theme: md-light-theme($primary, $accent, $warn);
$candy-app-theme: md-light-theme($candy-app-primary, $candy-app-accent, $candy-app-warn);
// Include theme styles for core and each component used in your app.
// Alternatively, you can import and @include the theme mixins for each component
// that you are using.
@include angular-material-theme($theme);
@include angular-material-theme($candy-app-theme);
```
You only need this single Sass file; you do not need to use Sass to style the rest of your app.
If you are using the Angular CLI, support for compiling Sass to css is built-in; you only have to
add a new entry to the `"styles"` list in `angular-cli.json` pointing to the theme
If you are using the Angular CLI, support for compiling Sass to css is built-in; you only have to
add a new entry to the `"styles"` list in `angular-cli.json` pointing to the theme
file (e.g., `unicorn-app-theme.scss`).
If you're not using the Angular CLI, you can use any existing Sass tooling to build the file (such
@@ -87,8 +87,8 @@ and then include the output file in your application.
The theme file can be concatenated and minified with the rest of the application's css.
#### Multiple themes
You can extend the example above to define a second (or third or fourth) theme that is gated by
some selector. For example, we could append the following to the example above to define a
You can extend the example above to define a second (or third or fourth) theme that is gated by
some selector. For example, we could append the following to the example above to define a
secondary dark theme:
```scss
.unicorn-dark-theme {
@@ -97,26 +97,16 @@ secondary dark theme:
$dark-warn: md-palette($md-deep-orange);
$dark-theme: md-dark-theme($dark-primary, $dark-accent, $dark-warn);
@include angular-material-theme($dark-theme);
@include angular-material-theme($dark-theme);
}
```
With this, any element inside of a parent with the `unicorn-dark-theme` class will use this
dark theme.
### Styling your own components
In order to style your own components with our tooling, the component's styles must be defined
with Sass.
You can consume the theming functions and variables from the `@angular/material/core/theming`.
You can use the `md-color` function to extract a specific color from a palette. For example:
```scss
.unicorn-carousel {
background-color: md-color($primary);
color: md-color($primary, default-contrast);
}
```
### Theming your own components
For more details about theming your own components, see [theming-your-components.md](https://github.com/angular/material2/blob/master/docs/theming-your-components.md)
### Future work
* Once CSS variables (custom properties) are available in all the browsers we support,