Element Plus

Element Plus 是一个功能强大、易于使用的 Vue.js UI 组件库，可以帮助开发者快速构建美观、交互丰富的 Web 应用程序界面。

安装

npm install element-plus

使用(按需引入)

安装插件

npm install -D unplugin-vue-components unplugin-auto-import

配置 Vite

// vite.config.*
import { defineConfig } from 'vite'
import AutoImport from 'unplugin-auto-import/vite'
import Components from 'unplugin-vue-components/vite'
import { ElementPlusResolver } from 'unplugin-vue-components/resolvers'

export default defineConfig({
  plugins: [
    AutoImport({
      resolvers: [ElementPlusResolver()]
    }),
    Components({
      resolvers: [ElementPlusResolver()]
    })
  ]
})

注意

按需引入只对使用 Element-Plus 组件及样式有效，对于使用非 Element-Plus 组件(如：ElMessage)及样式无效，此时需要安装 unplugin-element-plus 插件或手动导入样式:

1. 插件

• 安装

npm install -D unplugin-element-plus

• 配置 Vite

// vite.config.ts
import ElementPlus from 'unplugin-element-plus/vite'

export default {
  plugins: [
    ElementPlus({
      // options
    }),
  ],
}

2. 手动导入

import 'element-plus/es/components/message/style/css'
import { ElMessage } from 'element-plus'

全局配置 ConfigProvider

size & zIndex

size 用于设置表单组件的默认尺寸，zIndex 用于设置弹出组件的层级，zIndex 的默认值为 2000。

<template>
  <el-config-provider :size="size" :z-index="zIndex">
    <app />
  </el-config-provider>
</template>

<script setup>
  import { defineComponent } from 'vue'
  import { ElConfigProvider } from 'element-plus'

  const size = ref('small')
  const zIndex = ref(3000)
</script>

i18n

Element Plus 组件默认使用英语。

<template>
  <el-config-provider :locale="locale">
    <el-pagination />
  </el-config-provider>
</template>

<script setup>
  import { ref, defineComponent } from 'vue'
  import { ElConfigProvider } from 'element-plus'
  import zhCn from 'element-plus/dist/locale/zh-cn.mjs'

  const locale = ref(zhCn)
</script>

日期和时间本地化

Element Plus 组件默认使用 Day.js 库来管理组件的日期和时间，例如 DatePicker。

import 'dayjs/locale/zh-cn'

namespace

Element Plus 提供的默认前缀为 el。

1. 设置 ElConfigProvider

使用 <el-config-provider> 包装根组件。

<!-- App.vue -->
<template>
  <el-config-provider namespace="ep">
    <!-- ... -->
  </el-config-provider>
</template>

2. 设置 SCSS 变量

// assets/styles/element.scss
@forward 'element-plus/theme-chalk/src/mixins/config.scss' with (
  $namespace: 'ep'
);

// vite.config.ts
import { defineConfig } from 'vite'

export default defineConfig({
  // ...
  css: {
    preprocessorOptions: {
      scss: {
        additionalData: `@use "@/assets/styles/element.scss" as *;`
      }
    }
  }
  // ...
})

button

自动在两个中文字符之间插入空格。

<template>
  <el-config-provider :button="config">
    <el-button>中文</el-button>
  </el-config-provider>
</template>

<script lang="ts" setup>
  import { reactive } from 'vue'

  const config = reactive({
    autoInsertSpace: true
  })
</script>

message

可同时显示的消息最大数量。

<template>
  <el-config-provider :message="config">
    <el-button @click="open">OPEN</el-button>
  </el-config-provider>
</template>

<script lang="ts" setup>
  import { reactive } from 'vue'
  import { ElMessage } from 'element-plus'

  const config = reactive({
    max: 3
  })
  const open = () => {
    ElMessage('This is a message.')
  }
</script>

自定义主题

Element Plus 默认提供一套主题，CSS 命名采用 BEM 的风格，方便使用者覆盖样式。

点击查找样式变量

通过 Scss 变量

1. 创建 Scss

// assets/styles/element.scss
@forward 'element-plus/theme-chalk/src/common/var.scss' with (
  $colors: (
    'primary': (
      'base': #409eff
    )
  )
);

2. 配置 Vite

// vite.config.*
import { fileURLToPath, URL } from 'node:url'

import { defineConfig } from 'vite'
import AutoImport from 'unplugin-auto-import/vite'
import Components from 'unplugin-vue-components/vite'
import { ElementPlusResolver } from 'unplugin-vue-components/resolvers'

export default defineConfig({
  resolve: {
    alias: {
      '@': fileURLToPath(new URL('./src', import.meta.url))
    }
  },
  css: {
    preprocessorOptions: {
      scss: {
        additionalData: `@use "@/assets/styles/element.scss" as *;`
      }
    }
  },
  plugins: [
    AutoImport({
      resolvers: [ElementPlusResolver()]
    }),
    Components({
      resolvers: [ElementPlusResolver({ importStyle: 'sass' })]
    })
  ]
})

通过 CSS 变量

全局组件

/* style.css */
:root {
  --el-color-primary: #409eff !important;
}

单个组件

• HTML

<el-tag style="--el-tag-bg-color: red; --el-color-primary: white">Tag</el-tag>

• CSS

.custom-class {
  --el-tag-bg-color: red;
  --el-color-primary: white;
}

• JavaScript：点击查看 useCssVar | VueUse 用法

<script setup lang="ts">
  import { ref } from 'vue'
  import { useCssVar } from '@vueuse/core'

  const el = ref(null)
  const color = useCssVar('--color', el)

  function switchColor() {
    if (color.value === '#df8543') color.value = '#7fa998'
    else color.value = '#df8543'
  }
</script>

<template>
  <div ref="el" style="--color: #7fa998; color: var(--color)">
    Sample text, {{ color }}
  </div>
  <button @click="switchColor">Change Color</button>
</template>