2021-08-24 13:36:48 +08:00
|
|
|
|
# Quick start
|
2020-08-13 15:18:26 +08:00
|
|
|
|
|
2021-08-24 13:36:48 +08:00
|
|
|
|
This section describes how to use ElementPlus in your project.
|
2020-08-13 15:18:26 +08:00
|
|
|
|
|
2021-08-24 13:36:48 +08:00
|
|
|
|
## Using components
|
2020-08-13 15:18:26 +08:00
|
|
|
|
|
2021-08-24 13:36:48 +08:00
|
|
|
|
### Full import
|
2020-08-13 15:18:26 +08:00
|
|
|
|
|
2021-08-24 13:36:48 +08:00
|
|
|
|
> main.ts
|
2020-08-13 15:18:26 +08:00
|
|
|
|
|
2021-08-24 13:36:48 +08:00
|
|
|
|
```typescript
|
|
|
|
|
|
// main.ts
|
2020-11-23 16:28:06 +08:00
|
|
|
|
import { createApp } from 'vue'
|
2021-08-24 13:36:48 +08:00
|
|
|
|
import ElementPlus from 'element-plus'
|
|
|
|
|
|
import 'element-plus/dist/index.css'
|
|
|
|
|
|
import App from './App.vue'
|
2020-08-13 15:18:26 +08:00
|
|
|
|
|
2020-10-16 11:14:34 +08:00
|
|
|
|
const app = createApp(App)
|
2021-08-24 13:36:48 +08:00
|
|
|
|
|
2020-10-16 11:14:34 +08:00
|
|
|
|
app.use(ElementPlus)
|
|
|
|
|
|
app.mount('#app')
|
2020-08-13 15:18:26 +08:00
|
|
|
|
```
|
|
|
|
|
|
|
2021-08-24 13:36:48 +08:00
|
|
|
|
### Import on demand
|
2021-03-27 19:18:36 +08:00
|
|
|
|
|
2021-08-24 13:36:48 +08:00
|
|
|
|
`ElementPlus` provides out of box [Tree Shaking](https://webpack.js.org/guides/tree-shaking/)
|
|
|
|
|
|
functionalities based on ES Module.
|
2020-08-13 15:18:26 +08:00
|
|
|
|
|
2021-08-24 13:36:48 +08:00
|
|
|
|
> App.vue
|
2020-08-13 15:18:26 +08:00
|
|
|
|
|
2021-08-24 13:36:48 +08:00
|
|
|
|
```html
|
|
|
|
|
|
<template>
|
2021-09-04 19:29:28 +08:00
|
|
|
|
<el-button> I am ElButton </el-button>
|
2021-08-24 13:36:48 +08:00
|
|
|
|
</template>
|
|
|
|
|
|
<script>
|
2021-08-27 14:38:05 +08:00
|
|
|
|
import { defineComponent } from 'vue'
|
|
|
|
|
|
import { ElButton } from 'element-plus'
|
|
|
|
|
|
|
|
|
|
|
|
export default defineComponent({
|
|
|
|
|
|
name: 'app'
|
|
|
|
|
|
components: {
|
|
|
|
|
|
ElButton,
|
|
|
|
|
|
},
|
|
|
|
|
|
})
|
2021-08-24 13:36:48 +08:00
|
|
|
|
</script>
|
2021-02-02 14:15:34 +08:00
|
|
|
|
```
|
|
|
|
|
|
|
2021-08-24 13:36:48 +08:00
|
|
|
|
### Import stylesheets
|
2021-02-02 14:15:34 +08:00
|
|
|
|
|
2021-08-24 13:36:48 +08:00
|
|
|
|
It is **strongly recommended** that you import the **bundled stylesheet file**, even
|
|
|
|
|
|
though this could increase the final output bundle size, but it requires no
|
|
|
|
|
|
packaging plugins for bundling, you can use
|
|
|
|
|
|
[CDN](https://www.cloudflare.com/learning/cdn/what-is-a-cdn/) to load your stylesheet
|
|
|
|
|
|
which would be much more faster than hosting the file on your own server.
|
2021-03-27 19:18:36 +08:00
|
|
|
|
|
2021-08-24 13:36:48 +08:00
|
|
|
|
Import via JavaScript
|
2021-03-27 19:18:36 +08:00
|
|
|
|
|
2021-08-24 13:36:48 +08:00
|
|
|
|
```typescript
|
|
|
|
|
|
import 'element-plus/dist/index.css'
|
2021-03-27 19:18:36 +08:00
|
|
|
|
```
|
|
|
|
|
|
|
2021-08-24 13:36:48 +08:00
|
|
|
|
Import via HTML `head` tag.
|
2021-03-27 19:18:36 +08:00
|
|
|
|
|
2021-08-24 13:36:48 +08:00
|
|
|
|
```html
|
|
|
|
|
|
<!-- index.html -->
|
|
|
|
|
|
<head>
|
2021-08-27 14:38:05 +08:00
|
|
|
|
<link rel="stylesheet" href="//unpkg.com/element-plus/dist/index.css" />
|
2021-08-24 13:36:48 +08:00
|
|
|
|
</head>
|
2020-08-13 15:18:26 +08:00
|
|
|
|
```
|
|
|
|
|
|
|
2021-08-24 13:36:48 +08:00
|
|
|
|
If you also want the style to be imported on demand, you need to use co-responding
|
|
|
|
|
|
plugins based on your bundler, read more: [FAQs](/#/en-US/component/quickstart#faqs)
|
2021-03-27 19:18:36 +08:00
|
|
|
|
|
2021-08-24 13:36:48 +08:00
|
|
|
|
## Starter templates
|
2021-03-27 19:18:36 +08:00
|
|
|
|
|
2021-08-24 13:36:48 +08:00
|
|
|
|
### Using vue-cli@4.5
|
2021-03-27 19:18:36 +08:00
|
|
|
|
|
2021-08-24 13:36:48 +08:00
|
|
|
|
We prepared a plugin [Element Plus VueCLI plugin](https://github.com/element-plus/vue-cli-plugin-element-plus),
|
|
|
|
|
|
for new version [vue-cli](https://cli.vuejs.org/), you can setup a project based
|
|
|
|
|
|
on ElementPlus easily.
|
2021-03-27 19:18:36 +08:00
|
|
|
|
|
2021-08-24 13:36:48 +08:00
|
|
|
|
### Using Starter Kit
|
2021-03-27 19:18:36 +08:00
|
|
|
|
|
2021-08-24 13:36:48 +08:00
|
|
|
|
We provide a general [Project Template](https://github.com/element-plus/element-plus-starter),
|
|
|
|
|
|
also a [Vite Template](https://github.com/element-plus/element-plus-vite-starter).
|
|
|
|
|
|
For Laravel users we have a [Laravel Template](https://github.com/element-plus/element-plus-in-laravel-starter).
|
2021-03-27 19:18:36 +08:00
|
|
|
|
|
2021-08-24 13:36:48 +08:00
|
|
|
|
## Global configuration
|
2021-03-27 19:18:36 +08:00
|
|
|
|
|
2021-08-24 13:36:48 +08:00
|
|
|
|
When registering ElementPlus, you can pass a global config object with `size` and
|
|
|
|
|
|
`zIndex` to set the default `size` for form components, and `zIndex` for
|
|
|
|
|
|
popup components, the default value for `zIndex` is **2000**
|
2021-03-27 19:18:36 +08:00
|
|
|
|
|
2021-08-24 13:36:48 +08:00
|
|
|
|
Full import:
|
2021-03-27 19:18:36 +08:00
|
|
|
|
|
|
|
|
|
|
```js
|
2021-08-24 13:36:48 +08:00
|
|
|
|
import { createApp } from 'vue'
|
2021-08-27 14:38:05 +08:00
|
|
|
|
import ElementPlus from 'element-plus'
|
|
|
|
|
|
import App from './App.vue'
|
2021-03-27 19:18:36 +08:00
|
|
|
|
|
2021-08-24 13:36:48 +08:00
|
|
|
|
const app = createApp(App)
|
2021-08-27 14:38:05 +08:00
|
|
|
|
app.use(ElementPlus, { size: 'small', zIndex: 3000 })
|
2021-03-27 19:18:36 +08:00
|
|
|
|
```
|
|
|
|
|
|
|
2021-08-24 13:36:48 +08:00
|
|
|
|
On demand:
|
2020-08-13 15:18:26 +08:00
|
|
|
|
|
2021-08-24 13:36:48 +08:00
|
|
|
|
```js
|
2020-11-23 16:28:06 +08:00
|
|
|
|
import { createApp } from 'vue'
|
2021-08-27 14:38:05 +08:00
|
|
|
|
import { ElButton } from 'element-plus'
|
|
|
|
|
|
import App from './App.vue'
|
2020-08-13 15:18:26 +08:00
|
|
|
|
|
2020-11-23 16:28:06 +08:00
|
|
|
|
const app = createApp(App)
|
2021-08-24 13:36:48 +08:00
|
|
|
|
app.config.globalProperties.$ELEMENT = option
|
2021-08-27 14:38:05 +08:00
|
|
|
|
app.use(ElButton)
|
2020-08-13 15:18:26 +08:00
|
|
|
|
```
|
|
|
|
|
|
|
2021-08-24 13:36:48 +08:00
|
|
|
|
## Using Nuxt.js
|
2020-08-13 15:18:26 +08:00
|
|
|
|
|
2021-08-24 13:36:48 +08:00
|
|
|
|
We can also use [Nuxt.js](https://nuxtjs.org)：
|
2020-11-23 16:28:06 +08:00
|
|
|
|
|
2021-08-24 13:36:48 +08:00
|
|
|
|
<div class="glitch-embed-wrap" style="height: 420px; width: 100%;">
|
|
|
|
|
|
<iframe src="https://glitch.com/embed/#!/embed/nuxt-with-element?path=nuxt.config.js&previewSize=0&attributionHidden=true" alt="nuxt-with-element on glitch" style="height: 100%; width: 100%; border: 0;"></iframe>
|
|
|
|
|
|
</div>
|
2020-11-23 16:28:06 +08:00
|
|
|
|
|
2021-08-24 13:36:48 +08:00
|
|
|
|
## Let's get started
|
2020-11-23 16:28:06 +08:00
|
|
|
|
|
2021-08-24 13:36:48 +08:00
|
|
|
|
You can bootstrap your project from now on, for each components usage, please
|
|
|
|
|
|
refer to individual component documentation.
|
2020-08-13 15:18:26 +08:00
|
|
|
|
|
2021-08-24 13:36:48 +08:00
|
|
|
|
## FAQs
|
2020-08-13 15:18:26 +08:00
|
|
|
|
|
2021-08-24 13:36:48 +08:00
|
|
|
|
### I'd like to import both components and style at the same time
|
2020-08-13 15:18:26 +08:00
|
|
|
|
|
2021-08-24 13:36:48 +08:00
|
|
|
|
You can achieve that based on the bundler you are currently using, with
|
|
|
|
|
|
ElementPlus supported plugins.
|
2020-08-13 15:18:26 +08:00
|
|
|
|
|
2021-08-24 13:36:48 +08:00
|
|
|
|
#### Using vite
|
2020-11-23 16:28:06 +08:00
|
|
|
|
|
2021-08-24 13:36:48 +08:00
|
|
|
|
If you are using [vite](https://vitejs.dev) as your bundler, then you need to install
|
|
|
|
|
|
`vite-plugin-element-plus` in order to get it work.
|
|
|
|
|
|
|
|
|
|
|
|
```shell
|
|
|
|
|
|
yarn add vite-plugin-element-plus -D
|
|
|
|
|
|
# or
|
|
|
|
|
|
npm install vite-plugin-element-plus -D
|
2020-08-13 15:18:26 +08:00
|
|
|
|
```
|
|
|
|
|
|
|
2021-08-24 13:36:48 +08:00
|
|
|
|
Then you need to add the code below into your `vite.config.[t]js` file.
|
2020-08-13 15:18:26 +08:00
|
|
|
|
|
2021-08-24 13:36:48 +08:00
|
|
|
|
```typescript
|
|
|
|
|
|
import { defineConfig } from 'vite'
|
|
|
|
|
|
import vue from '@vitejs/plugin-vue'
|
|
|
|
|
|
import VitePluginElementPlus from 'vite-plugin-element-plus'
|
|
|
|
|
|
|
|
|
|
|
|
// https://vitejs.dev/config/
|
2021-08-27 14:38:05 +08:00
|
|
|
|
export default defineConfig(({ mode }) => {
|
|
|
|
|
|
return {
|
|
|
|
|
|
plugins: [
|
|
|
|
|
|
vue(),
|
|
|
|
|
|
VitePluginElementPlus({
|
|
|
|
|
|
// if you need to use the *.scss source file, you need to uncomment this comment
|
|
|
|
|
|
// useSource: true
|
|
|
|
|
|
format: mode === 'development' ? 'esm' : 'cjs',
|
|
|
|
|
|
}),
|
|
|
|
|
|
],
|
|
|
|
|
|
}
|
2021-08-24 13:36:48 +08:00
|
|
|
|
})
|
2020-08-13 15:18:26 +08:00
|
|
|
|
```
|
|
|
|
|
|
|
2021-08-24 13:36:48 +08:00
|
|
|
|
For all public API, you can refer to [vite-plugin-element-plus](https://github.com/element-plus/vite-plugin-element-plus)
|
2020-08-13 15:18:26 +08:00
|
|
|
|
|
2021-08-24 13:36:48 +08:00
|
|
|
|
#### Using webpack
|
2020-08-13 15:18:26 +08:00
|
|
|
|
|
2021-08-24 13:36:48 +08:00
|
|
|
|
If you are using webpack as your bundler, then you need to install
|
|
|
|
|
|
[babel-plugin-import](https://github.com/ant-design/babel-plugin-import) in
|
|
|
|
|
|
order to get it work.
|
2020-08-13 15:18:26 +08:00
|
|
|
|
|
2021-08-24 13:36:48 +08:00
|
|
|
|
```shell
|
|
|
|
|
|
yarn add babel-plugin-import -D
|
|
|
|
|
|
# or
|
|
|
|
|
|
npm install babel-plugin-import -D
|
|
|
|
|
|
```
|
2020-08-13 15:18:26 +08:00
|
|
|
|
|
2021-08-24 13:36:48 +08:00
|
|
|
|
Then you need to add the code below into your `babel.config.js` file.
|
2020-08-13 15:18:26 +08:00
|
|
|
|
|
2021-08-24 13:36:48 +08:00
|
|
|
|
> babel.config.js
|
|
|
|
|
|
|
|
|
|
|
|
```javascript
|
|
|
|
|
|
module.exports = {
|
|
|
|
|
|
plugins: [
|
|
|
|
|
|
[
|
2021-08-27 14:38:05 +08:00
|
|
|
|
'import',
|
2021-08-24 13:36:48 +08:00
|
|
|
|
{
|
|
|
|
|
|
libraryName: 'element-plus',
|
2021-08-26 15:11:47 +08:00
|
|
|
|
// import component
|
2021-09-04 19:29:28 +08:00
|
|
|
|
customName: (name) => {
|
2021-08-26 15:11:47 +08:00
|
|
|
|
name = name.slice(3)
|
|
|
|
|
|
return `element-plus/lib/components/${name}`
|
|
|
|
|
|
},
|
|
|
|
|
|
// import style
|
2021-09-04 19:29:28 +08:00
|
|
|
|
customStyleName: (name) => {
|
2021-08-24 13:36:48 +08:00
|
|
|
|
name = name.slice(3)
|
2021-08-26 15:11:47 +08:00
|
|
|
|
// if you need [name].scss source file, you need to uncomment this line
|
|
|
|
|
|
// return `element-plus/lib/components/${name}/style`
|
|
|
|
|
|
// import [name].css
|
|
|
|
|
|
return `element-plus/lib/components/${name}/style/css`
|
2021-08-24 13:36:48 +08:00
|
|
|
|
},
|
|
|
|
|
|
},
|
|
|
|
|
|
],
|
2021-08-27 14:38:05 +08:00
|
|
|
|
],
|
2021-08-26 15:11:47 +08:00
|
|
|
|
}
|
2021-08-24 13:36:48 +08:00
|
|
|
|
```
|
