Theming your Angular Material app

將您的Angular Material應(yīng)用程序主題化

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.
主題是將應(yīng)用于 Angular Material 組件的一組顏色。庫(kù)的主題化方法基于Material設(shè)計(jì)規(guī)范的指導(dǎo)。

In Angular Material, a theme is created by composing multiple palettes. In particular,
a theme consists of:
在Angular Material中，通過(guò)組合多個(gè)調(diào)色板來(lái)創(chuàng)建主題辛友。特別是谐腰，一個(gè)主題包括：

• A primary palette: colors most widely used across all screens and components.
  主調(diào)色板：在所有屏幕和組件中使用最廣泛的顏色胁黑。
• An accent palette: colors used for the floating action button and interactive elements.
  重音調(diào)色板：用于浮動(dòng)動(dòng)作按鈕和交互式元素的顏色僻澎。
• A warn palette: colors used to convey error state.
  警告調(diào)色板：用于傳達(dá)錯(cuò)誤狀態(tài)的顏色貌踏。
• A foreground palette: colors for text and icons.
  前景調(diào)色板：文字和圖標(biāo)的顏色。
• A background palette: colors used for element backgrounds.
  背景調(diào)色板：用于元素背景的顏色怎棱。

In Angular Material, all theme styles are generated statically at build-time so that your
app doesn't have to spend cycles generating theme styles on startup.
在Angular Material中哩俭，所有主題樣式都是在構(gòu)建時(shí)靜態(tài)生成的绷跑，以便您的應(yīng)用程序不必在啟動(dòng)時(shí)花費(fèi)周期來(lái)生成主題樣式拳恋。

Using a pre-built theme

使用預(yù)先構(gòu)建的主題

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.
Angular Material預(yù)裝了幾個(gè)預(yù)先構(gòu)建的主題css文件。這些主題文件還包括核心的所有樣式（所有組件通用的樣式）砸捏，所以你只需要在你的應(yīng)用中包含一個(gè)用于Angular Material的css文件谬运。

You can include a theme file directly into your application from
@angular/material/prebuilt-themes
您可以直接從您的應(yīng)用程序中包含主題文件@angular/material/prebuilt-themes

Available pre-built themes:
可用的預(yù)建主題:

• deeppurple-amber.css
深紫色-琥珀色.css
• indigo-pink.css
靛青-粉紅.css
• pink-bluegrey.css
粉紅-藍(lán)灰
• purple-green.css
紫色-綠.css

If you're using Angular CLI, this is as simple as including one line
in your styles.css file:
如果您使用的是Angular CLI，這與在styles.css文件中包含一行一樣簡(jiǎn)單：

@import '~@angular/material/prebuilt-themes/deeppurple-amber.css';

Alternatively, you can just reference the file directly. This would look something like:
或者垦藏，您可以直接引用該文件梆暖。這看起來(lái)像這樣：

<link href="node_modules/@angular/material/prebuilt-themes/indigo-pink.css" rel="stylesheet">

The actual path will depend on your server setup.
實(shí)際路徑將取決于您的服務(wù)器設(shè)置

You can also concatenate the file with the rest of your application's css.
您還可以將該文件與應(yīng)用程序的其余CSS進(jìn)行連接.

Finally, if your app's content is not placed inside of a mat-sidenav-container element, you
need to add the mat-app-background class to your wrapper element (for example the body). This
ensures that the proper theme background is applied to your page.
最后，如果你的應(yīng)用程序的內(nèi)容沒(méi)有放置在 mat-sidenav-container 元素中掂骏，您需要將 mat-app-background 類添加到包裝器元素（例如正文)轰驳。這可確保正確的主題背景應(yīng)用于您的頁(yè)面

Defining a custom theme

定義自定義主題

When you want more customization than a pre-built theme offers, you can create your own theme file.
當(dāng)您需要比預(yù)先構(gòu)建的主題優(yōu)惠更多的自定義功能時(shí)，您可以創(chuàng)建自己的主題文件弟灼。

A custom theme file does two things:
自定義主題文件有兩件事：

1. Imports the mat-core() sass mixin. This includes all common styles that are used by multiple
   components. This should only be included once in your application. If this mixin is included
   multiple times, your application will end up with multiple copies of these common styles.
   導(dǎo)入 mat-core（） sass 混合级解。這包括多個(gè)組件使用的所有常見(jiàn)樣式。 這應(yīng)該只在你的應(yīng)用程序中包含一次田绑。 如果這個(gè)mixin包含多次勤哗，你的應(yīng)用程序?qū)⒆罱K得到這些常用樣式的多個(gè)副本。
2. Defines a theme data structure as the composition of multiple palettes. This object can be
   created with either the mat-light-theme function or the mat-dark-theme function. The output of
   this function is then passed to the angular-material-theme mixin, which will output all of the
   corresponding styles for the theme.
   將 主題 數(shù)據(jù)結(jié)構(gòu)定義為多個(gè)調(diào)色板的組合掩驱∶⒒可以使用 mat-light-theme 方法或 mat-dark-theme 方法創(chuàng)建此對(duì)象冬竟。
   然后將方法的輸出傳遞給 angular-material-theme 混合，它將輸出主題的所有對(duì)應(yīng)樣式民逼。

A typical theme file will look something like this:
一個(gè)典型的主題文件將如下所示：

@import '~@angular/material/theming';
// Plus imports for other components in your app.

// Include the common styles for Angular Material. We include this here so that you only
// have to load a single css file for Angular Material in your app.
// Be sure that you only ever include this mixin once!
@include mat-core();

// 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. Available color palettes: https://material.io/design/color/
$candy-app-primary: mat-palette($mat-indigo);
$candy-app-accent:  mat-palette($mat-pink, A200, A100, A400);

// The warn palette is optional (defaults to red).
$candy-app-warn:    mat-palette($mat-red);

// Create the theme object (a Sass map containing all of the palettes).
$candy-app-theme: mat-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($candy-app-theme);

You only need this single Sass file; you do not need to use Sass to style the rest of your app.
你只需要這個(gè)單一的Sass文件;您不需要使用Sass來(lái)設(shè)計(jì)應(yīng)用程序的其余部分泵殴。

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).
如果您使用Angular CLI，則支持將Sass編譯為css拼苍，這是內(nèi)置的;您只需在 angular-cli.json 中指向主題文件（例如袋狞，unicorn-app-theme.scss）的 “樣式” 列表中添加一個(gè)新條目。

If you're not using the Angular CLI, you can use any existing Sass tooling to build the file (such
as gulp-sass or grunt-sass). The simplest approach is to use the node-sass CLI; you simply run:
如果您不使用Angular CLI映屋，則可以使用任何現(xiàn)有的Sass工具來(lái)構(gòu)建文件（如gulp-sass或grunt-sass）苟鸯。 最簡(jiǎn)單的方法是使用節(jié)點(diǎn)sass CLI;你只需運(yùn)行：

node-sass src/unicorn-app-theme.scss dist/unicorn-app-theme.css

and then include the output file in your index.html.
然后將輸出文件包含在index.html中。

The theme file should not be imported into other SCSS files. This will cause duplicate styles
to be written into your CSS output. If you want to consume the theme definition object
(e.g., $candy-app-theme) in other SCSS files, then the definition of the theme object should be
broken into its own file, separate from the inclusion of the mat-core and
angular-material-theme mixins.
主題文件不應(yīng)該導(dǎo)入到其他SCSS文件中棚点。這會(huì)導(dǎo)致重復(fù)樣式被寫(xiě)入您的CSS輸出早处。如果您想在其他SCSS文件中使用主題定義對(duì)象（例如 $candy-app-theme）。那么主題對(duì)象的定義應(yīng)該被分解到它自己的文件中瘫析，與包含 mat-core 和 angular-material-theme mixins分開(kāi)砌梆。

The theme file can be concatenated and minified with the rest of the application's css.
主題文件可以與應(yīng)用程序的其余部分進(jìn)行連接和縮小。

Note that if you include the generated theme file in the styleUrls of an Angular component, those
styles will be subject to that component's view encapsulation.
請(qǐng)注意贬循，如果您將生成的主題文件包含在Angular組件的styleUrls中咸包，則這些樣式將受該組件的視圖封裝支配。

Multiple themes

多主題

You can create multiple themes for your application by including the angular-material-theme mixin
multiple times, where each inclusion is gated by an additional CSS class.
您可以通過(guò)多次包含 angular-material-theme 混合來(lái)創(chuàng)建應(yīng)用程序的多個(gè)主題杖虾，其中每個(gè)包含都由額外的CSS類進(jìn)行門(mén)控烂瘫。

Remember to only ever include the @mat-core mixin only once; it should not be included for each
theme.
記住只有一次只包含 @mat-core 混合;它不應(yīng)該包含在每個(gè)主題中。

Example of defining multiple themes:

定義多主題的示例:

@import '~@angular/material/theming';
// Plus imports for other components in your app.

// Include the common styles for Angular Material. We include this here so that you only
// have to load a single css file for Angular Material in your app.
// **Be sure that you only ever include this mixin once!**
@include mat-core();

// Define the default theme (same as the example above).
$candy-app-primary: mat-palette($mat-indigo);
$candy-app-accent:  mat-palette($mat-pink, A200, A100, A400);
$candy-app-theme:   mat-light-theme($candy-app-primary, $candy-app-accent);

// Include the default theme styles.
@include angular-material-theme($candy-app-theme);


// Define an alternate dark theme.
$dark-primary: mat-palette($mat-blue-grey);
$dark-accent:  mat-palette($mat-amber, A200, A100, A400);
$dark-warn:    mat-palette($mat-deep-orange);
$dark-theme:   mat-dark-theme($dark-primary, $dark-accent, $dark-warn);

// Include the alternative theme styles inside of a block with a CSS class. You can make this
// CSS class whatever you want. In this example, any component inside of an element with
// `.unicorn-dark-theme` will be affected by this alternate dark theme instead of the default theme.
.unicorn-dark-theme {
  @include angular-material-theme($dark-theme);
}

In the above example, any component inside of a parent with the unicorn-dark-theme class will use
the dark theme, while other components will fall back to the default $candy-app-theme.
在上面的例子中奇适，具有 unicorn-dark-theme 類的父類中的任何組件都將使用黑色主題坟比，而其他組件將回退到默認(rèn)的$candy-app-theme。

You can include as many themes as you like in this manner. You can also @include the
angular-material-theme in separate files and then lazily load them based on an end-user
interaction (how to lazily load the CSS assets will vary based on your application).
你可以用這種方式包括盡可能多的主題嚷往。您還可以在單??獨(dú)的文件中包含 angular-material-theme葛账，然后基于最終用戶交互延遲加載它們（如何根據(jù)您的應(yīng)用程序延遲加載CSS資產(chǎn)）。

It's important to remember, however, that the mat-core mixin should only ever be included once.
但是皮仁，重要的是要記住籍琳，mat-core 混合只能包含一次。

Multiple themes and overlay-based components

多個(gè)主題和基于覆蓋的組件

Since certain components (e.g. menu, select, dialog, etc.) are inside of a global overlay container,
an additional step is required for those components to be affected by the theme's css class selector
(.unicorn-dark-theme in the example above).
由于某些組件（例如菜單贷祈，選擇趋急，對(duì)話框等）位于全局覆蓋容器的內(nèi)部，因此需要額外的步驟才能使這些組件受到主題的css類選擇器的影響（上例中的 .unicorn-dark-theme ）付燥。

To do this, you can add the appropriate class to the global overlay container. For the example above,
this would look like:
為此宣谈，您可以將相應(yīng)的類添加到全局覆蓋容器。對(duì)于上面的例子键科，這看起來(lái)像：

import {OverlayContainer} from '@angular/cdk/overlay';

@NgModule({
  // ...
})
export class UnicornCandyAppModule {
  constructor(overlayContainer: OverlayContainer) {
    overlayContainer.getContainerElement().classList.add('unicorn-dark-theme');
  }
}

Theming only certain components

僅限某些組件

The angular-material-theme mixin will output styles for all components in the library.
If you are only using a subset of the components (or if you want to change the theme for specific
components), you can include component-specific theme mixins. You also will need to include
the mat-core-theme mixin as well, which contains theme-specific styles for common behaviors
(such as ripples).
angular-material-theme mixin將為庫(kù)中的所有組件輸出樣式闻丑。如果您僅使用組件的子集（或者如果您想更改特定組件的主題）漩怎，則可以包含特定于組件的主題混合. 您還需要包含 mat-core-theme 混合，其中包含常見(jiàn)行為（如漣漪）的主題特定樣式嗦嗡。

@import '~@angular/material/theming';
// Plus imports for other components in your app.

// Include the common styles for Angular Material. We include this here so that you only
// have to load a single css file for Angular Material in your app.
// **Be sure that you only ever include this mixin once!**
@include mat-core();

// Define the theme.
$candy-app-primary: mat-palette($mat-indigo);
$candy-app-accent:  mat-palette($mat-pink, A200, A100, A400);
$candy-app-theme:   mat-light-theme($candy-app-primary, $candy-app-accent);

// Include the theme styles for only specified components.
@include mat-core-theme($candy-app-theme);
@include mat-button-theme($candy-app-theme);
@include mat-checkbox-theme($candy-app-theme);

Theming your own components

主體化您自己的組件

For more details about theming your own components,
see theming-your-components.md.
有關(guān)自己組件的更多細(xì)節(jié)勋锤，請(qǐng)參閱theming-your-components.md。

Future work

未來(lái)的工作

• Once CSS variables (custom properties) are available in all the browsers we support,
  we will explore how to take advantage of them to make theming even simpler.
  一旦CSS變量（自定義屬性）在我們支持的所有瀏覽器中都可用侥祭，我們將探索如何利用它們使其變得更簡(jiǎn)單叁执。
• More prebuilt themes will be added as development continues.
  隨著發(fā)展的繼續(xù)，將增加更多預(yù)建主題矮冬。