Миграция с Element UI

Element Plus является современной переработкой Element UI для Vue 3, поэтому при миграции важно понимать ключевые изменения:

  • Поддержка Vue 3: Element Plus использует Composition API и новую систему реактивности Vue 3. Это означает, что синтаксис компонентов, реактивность и слоты могут отличаться.
  • Удаление устаревших API: Некоторые старые свойства и методы из Element UI больше не поддерживаются. Например, size="medium" по умолчанию заменяется на глобальную настройку через config-provider.
  • Изменения в стилях: CSS-классы и структура DOM могут измениться, поэтому кастомизация через классы требует внимательного пересмотра.

Установка и базовая настройка

Для перехода на Element Plus используется современный пакетный менеджер:

npm install element-plus

В проекте на Vue 3 подключение осуществляется через основной файл main.js или main.ts:

import { createApp } from 'vue'
import App from './App.vue'
import ElementPlus from 'element-plus'
import 'element-plus/dist/index.css'

const app = createApp(App)
app.use(ElementPlus)
app.mount('#app')

Особенности настройки глобальных параметров:

import { ElMessage, ElNotification } from 'element-plus'

app.config.globalProperties.$message = ElMessage
app.config.globalProperties.$notify = ElNotification

Это позволяет использовать уведомления и сообщения во всех компонентах, аналогично Element UI.

Компоненты и синтаксис

Кнопки

Кнопки в Element Plus имеют схожий API, но появились новые варианты и улучшена поддержка Composition API:

<template>
  <el-button type="primary" @click="handleClick">Нажать</el-button>
</template>

<script setup>
import { ElButton } from 'element-plus'

function handleClick() {
  console.log('Кнопка нажата')
}
</script>

Изменения по сравнению с Element UI:

  • Компоненты теперь импортируются модульно для уменьшения размера бандла.
  • Поддержка Composition API упрощает использование логики внутри <script setup>.

Формы и валидация

В Element Plus валидация форм стала более гибкой:

<template>
  <el-form :model="form" :rules="rules" ref="formRef">
    <el-form-item label="Имя" prop="name">
      <el-input v-model="form.name"></el-input>
    </el-form-item>
    <el-button @click="submitForm">Отправить</el-button>
  </el-form>
</template>

<script setup>
import { ref } from 'vue'

const form = ref({ name: '' })
const rules = ref({
  name: [{ required: true, message: 'Введите имя', trigger: 'blur' }]
})
const formRef = ref(null)

function submitForm() {
  formRef.value.validate(valid => {
    if (valid) console.log('Форма валидна')
    else console.log('Ошибка валидации')
  })
}
</script>

Изменения:

  • Использование ref вместо this.$refs.
  • Все правила и модели реактивны благодаря Vue 3.

Модальные окна

ElDialog в Element Plus стал полностью поддерживать Composition API:

<template>
  <el-button @click="dialogVisible = true">Открыть диалог</el-button>
  <el-dialog v-model="dialogVisible" title="Диалог">
    Содержимое окна
  </el-dialog>
</template>

<script setup>
import { ref } from 'vue'

const dialogVisible = ref(false)
</script>

Изменения по сравнению с Element UI:

  • Управление видимостью через реактивное свойство вместо this.dialogVisible.
  • Новые слоты и события позволяют гибко кастомизировать заголовки и футер.

Глобальная конфигурация

Element Plus предлагает ElConfigProvider для глобальных настроек компонентов:

<el-config-provider :size="'small'" :z-index="3000">
  <App />
</el-config-provider>

Это заменяет устаревшую настройку Vue.prototype.$ELEMENT.

Импорт компонентов по требованию

Для оптимизации бандла рекомендуется использовать модульный импорт через Vite или Webpack:

import { ElButton, ElForm, ElFormItem } from 'element-plus'
import 'element-plus/es/components/button/style/css'
import 'element-plus/es/components/form/style/css'
import 'element-plus/es/components/form-item/style/css'

Особенности:

  • Исключает загрузку всех компонентов, ускоряя сборку.
  • Поддерживает Tree Shaking.

Изменения событий и слотов

  • События теперь соответствуют стандарту Vue 3: вместо .native применяется обычный @click.
  • Слоты стали именованными через <template #slotName>, старый синтаксис <template slot="slotName"> устарел.
  • Асинхронные события (before-close в диалогах) можно обрабатывать через промисы.

Сообщения и уведомления

В Element Plus глобальные уведомления теперь являются отдельными функциями:

import { ElMessage, ElNotification } from 'element-plus'

ElMessage({
  message: 'Операция выполнена',
  type: 'success'
})

ElNotification({
  title: 'Важное уведомление',
  message: 'Содержимое уведомления'
})

Особенности миграции:

  • Не требуется регистрация через Vue.prototype, достаточно импорта.
  • Поддержка Composition API и реактивных данных.

Темизация и кастомные стили

  • В Element Plus используется CSS Variables для удобной кастомизации.
  • Возможность менять темы динамически через изменение переменных:
:root {
  --el-color-primary: #409eff;
  --el-color-success: #67c23a;
}
  • Это упрощает поддержку светлой и темной тем без перекомпиляции стилей.

Частые ошибки при миграции

  1. Попытка использовать this.$refs в <script setup> вместо ref.
  2. Использование устаревших слотов и событий Element UI.
  3. Импорт всей библиотеки вместо модульного, что увеличивает размер бандла.
  4. Игнорирование нового глобального конфиг-провайдера для настроек компонентов.
  5. Попытка использовать устаревшие CSS-классы, которые изменились в DOM Element Plus.

Рекомендации по миграции

  • Переписать компоненты с использованием Composition API и реактивных свойств.
  • Перейти на модульный импорт компонентов.
  • Проверить стили и слоты на совместимость с новой структурой DOM.
  • Использовать ElConfigProvider для глобальных настроек.
Оглавление