mirror of
https://github.com/element-plus/element-plus.git
synced 2024-11-27 02:01:15 +08:00
docs: update theming doc (#5806)
This commit is contained in:
iamkun
GitHub
parent
17553e919c
commit
6ff6270cdc
@ -10,7 +10,7 @@ you need to replace styles at a large scale, e.g. change the theme color from
|
||||
blue to orange or green, maybe overriding them one by one is not a good idea. We
|
||||
provide four ways to change the style variables.
|
||||
|
||||
## Change theme color <el-tag type="success" style="vertical-align: middle;">since 1.1.0-beta.1</el-tag>
|
||||
## Change theme color
|
||||
|
||||
These are examples about custom theme.
|
||||
|
||||
@ -218,173 +218,3 @@ el.style['--el-color-primary'] = 'red'
|
||||
|
||||
If you want a more elegant way, check this out.
|
||||
[useCssVar | VueUse](https://vueuse.org/core/usecssvar/)
|
||||
|
||||
## Change theme color <el-tag type="error" style="vertical-align: middle;">Deprecated since 1.1.0-beta.1</el-tag>
|
||||
|
||||
If you just want to change the theme color of Element Plus, the
|
||||
[theme preview website](https://element-plus.github.io/theme-chalk-preview/#/en-US)
|
||||
is recommended.
|
||||
The theme color of Element Plus is bright and friendly blue. By changing it, you
|
||||
can make Element Plus more visually connected to specific projects.
|
||||
|
||||
The above website enables you to preview theme of a new theme color in real-time,
|
||||
and it can generate a complete style package based on the new theme color for you
|
||||
to download directly (to import new style files in your project, please refer to
|
||||
the 'Import custom theme' or 'Import component theme on demand' part of this section).
|
||||
|
||||
### Update SCSS variables in your project
|
||||
|
||||
`theme-chalk` is written in SCSS. If your project also uses SCSS, you can directly
|
||||
change Element Plus style variables. Create a new style file, e.g. `element-variables.scss`:
|
||||
|
||||
```scss
|
||||
/* theme color */
|
||||
$--color-primary: teal; /* icon font path, required */
|
||||
$--font-path: '~element-plus/lib/theme-chalk/fonts';
|
||||
@use '~element-plus/packages/theme-chalk/src/index';
|
||||
```
|
||||
|
||||
Then in the entry file of your project, import this style file instead of Element's
|
||||
built CSS:
|
||||
|
||||
```ts
|
||||
import Vue from 'vue'
|
||||
import ElementPlus from 'element-plus'
|
||||
import './element-variables.scss'
|
||||
import App from './App.vue'
|
||||
|
||||
const app = createApp(App)
|
||||
app.use(ElementPlus)
|
||||
```
|
||||
|
||||
:::tip
|
||||
|
||||
Note that it is required to override icon font path to the relative path of
|
||||
Element's font files.
|
||||
|
||||
:::
|
||||
|
||||
### CLI theme tool
|
||||
|
||||
If you project doesn't use SCSS, you can customize themes with our CLI theme tool:
|
||||
|
||||
#### Installation
|
||||
|
||||
First install the theme generator globally or locally. Local install is
|
||||
recommended because in this way, when others clone your project, npm will
|
||||
automatically install it for them.
|
||||
|
||||
```shell
|
||||
npm i element-theme -g
|
||||
```
|
||||
|
||||
Then install the chalk theme from npm or GitHub.
|
||||
|
||||
```shell
|
||||
# from npm
|
||||
npm i element-theme-chalk -D
|
||||
|
||||
# from GitHub
|
||||
npm i https://github.com/ElementUI/theme-chalk -D
|
||||
```
|
||||
|
||||
#### Initialize variable file
|
||||
|
||||
After successfully installing the above packages, a command named `et` is
|
||||
available in CLI (if the packages are installed locally, use `node_modules/.bin/et`
|
||||
instead).
|
||||
Run `-i` to initialize the variable file which outputs to `element-variables.scss`
|
||||
by default. And you can specify its output directory as you will.
|
||||
|
||||
```shell
|
||||
et -i [custom output file]
|
||||
|
||||
> ✅ Generator variables file
|
||||
```
|
||||
|
||||
In `element-variables.scss` you can find all the variables we used to style
|
||||
Element Plus and they are defined in SCSS format. Here's a snippet:
|
||||
|
||||
```css
|
||||
$--color-primary: #409EFF !default;
|
||||
$--color-primary-light-1: mix($--color-white, $--color-primary, 10%) !default; /* 53a8ff */
|
||||
$--color-primary-light-2: mix($--color-white, $--color-primary, 20%) !default; /* 66b1ff */
|
||||
$--color-primary-light-3: mix($--color-white, $--color-primary, 30%) !default; /* 79bbff */
|
||||
$--color-primary-light-4: mix($--color-white, $--color-primary, 40%) !default; /* 8cc5ff */
|
||||
$--color-primary-light-5: mix($--color-white, $--color-primary, 50%) !default; /* a0cfff */
|
||||
$--color-primary-light-6: mix($--color-white, $--color-primary, 60%) !default; /* b3d8ff */
|
||||
$--color-primary-light-7: mix($--color-white, $--color-primary, 70%) !default; /* c6e2ff */
|
||||
$--color-primary-light-8: mix($--color-white, $--color-primary, 80%) !default; /* d9ecff */
|
||||
$--color-primary-light-9: mix($--color-white, $--color-primary, 90%) !default; /* ecf5ff */
|
||||
|
||||
$--color-success: #67c23a !default;
|
||||
$--color-warning: #e6a23c !default;
|
||||
$--color-danger: #f56c6c !default;
|
||||
$--color-info: #909399 !default;
|
||||
|
||||
...
|
||||
```
|
||||
|
||||
#### Modify variables
|
||||
|
||||
Just edit `element-variables.scss`, e.g. changing the theme color to red:
|
||||
|
||||
```CSS
|
||||
$--color-primary: red;
|
||||
```
|
||||
|
||||
#### Build theme
|
||||
|
||||
After saving the variable file, use `et` to build your theme. You can activate
|
||||
`watch` mode by adding a parameter `-w`. And if you customized the variable
|
||||
file's output, you need to add a parameter `-c` and variable file's name. By
|
||||
default the build theme file is placed inside `./theme`. You can specify its
|
||||
output directory with parameter `-o`.
|
||||
|
||||
```shell
|
||||
et
|
||||
|
||||
> ✅ build theme font
|
||||
> ✅ build element theme
|
||||
```
|
||||
|
||||
### Use custom theme
|
||||
|
||||
We will cover how to use your customized theme in your project in this section
|
||||
|
||||
#### Import custom theme
|
||||
|
||||
Importing your own theme is just like importing the default theme, only
|
||||
this time you import the file built from "Online Theme Roller" or "CLI tool":
|
||||
|
||||
```javascript
|
||||
import { createApp } from 'vue'
|
||||
import '../theme/index.css'
|
||||
import ElementPlus from 'element-plus'
|
||||
|
||||
createApp(App).use(ElementPlus)
|
||||
```
|
||||
|
||||
#### Import component theme on demand
|
||||
|
||||
If you are using `babel-plugin-component` for on-demand import, just modify
|
||||
`.babelrc` and specify `styleLibraryName` to the path where your custom theme
|
||||
is located relative to `.babelrc`. Note that `~` is required:
|
||||
|
||||
```json
|
||||
{
|
||||
"plugins": [
|
||||
[
|
||||
"component",
|
||||
{
|
||||
"libraryName": "element-plus",
|
||||
"styleLibraryName": "~theme"
|
||||
}
|
||||
]
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
If you are unfamiliar with `babel-plugin-component`, please refer to [Quick Start](/en-US/guide/quickstart.html).
|
||||
For more details, check out the [project repository](https://github.com/ElementUI/element-theme)
|
||||
of `element-theme`.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user