Особенность работы v-model в Vue3 с обычными HTML-элементами и компонентами библиотеки ant-design-vue

v-model — это директива в Vue.js, которая обеспечивает двустороннюю привязку данных между моделью и элементами пользовательского интерфейса. Это значит, что любые изменения в пользовательском интерфейсе автоматически обновляют значения в модели данных и наоборот.

Как работает v-model с обычными HTML-элементами

Когда вы используете обычный HTML-элемент, такой как <input>, с v-model в Vue, оно автоматически связывает значение текстового поля с переменной searchTerm.

Двусторонняя связь

v-model обеспечивает двустороннюю привязку. Это значит, что изменения в поле ввода обновляют searchTerm и наоборот.

Как это реализовано

• Пропс value: Vue использует пропс value для получения текущего значения.
• Событие input: Vue перехватывает событие input и обновляет searchTerm с новым значением.

Пример работы

<template>
  <div>
    <input
      v-model="searchTerm"
      placeholder="Введите текст для поиска"
    />
    <p>Вы ввели: {{ searchTerm }}</p>
  </div>
</template>

<script setup>
import { ref } from 'vue';
const searchTerm = ref('');
</script>

В этом примере, при вводе текста в поле ввода, значение searchTerm автоматически обновляется.

Почему с компонентами ant-design-vue всё иначе?

При использовании компонентов из библиотек, таких как <a-input>, требуется немного другой синтаксис.

<a-input
  v-model:value="searchTerm"
  placeholder="Введите текст для поиска"
/>

Использование custom prop

Компоненты ant-design-vue используют modelValue как пропс для получения значения.

Событие обновления

Вместо события input используется update:modelValue для обновления значения.

Явность

Синтаксис v-model:value добавляет уровень явности, что полезно в сложных компонентах.

Что такое modelValue?

modelValue — это название пропса, который используется в компонентах для получения значения, связанного с v-model. Это значение, которое компоненты должны использовать для передачи данных.

Пример использования v-model с компонентом

<a-input v-model:value="email" placeholder="Введите вашу электронную почту" />

В этом примере v-model:value говорит Vue: "Я хочу, чтобы этот компонент использовал пропс modelValue для передачи данных".

Значение переменной email будет связано с содержимым поля ввода (a-input), и любые изменения в этом поле автоматически обновят значение email.

В самом компоненте, куда передаются данные, обновление и передача данных обратно (родителю) осуществляются с помощью $emit:

<template>
  <input
    :value="modelValue"  <!-- Здесь modelValue будет получать значение из v-model:value -->
    @input="$emit('update:modelValue', $event.target.value)" <!-- Изменения отправляются родителю -->
  />
</template>

<script setup>
import { defineProps, defineEmits } from 'vue';

// Определяем пропсы
const props = defineProps({
  modelValue: String, <!-- Здесь мы объявляем пропс modelValue -->
});

// Определяем события
const emit = defineEmits(['update:modelValue']);
</script>

Когда использовать v-model, а когда v-model:value?

v-model используется в основном с стандартными HTML-элементами, например, с полями ввода, так как они уже имеют интегрированную логику обработки:

<input v-model="text" />

Здесь Vue автоматически связывает текстовое поле (input) с переменной text.

Однако, когда вы работаете с компонентами библиотеки, такими как ant-design-vue, вам может потребоваться использовать другое имя пропса для передачи данных. В большинстве случаев это будет modelValue:

<a-input v-model:value="searchTerm" placeholder="Введите текст для поиска" />

Здесь v-model:value указывает, что нужно использовать пропс modelValue для связывания с переменной searchTerm.

Пример использования

Рассмотрим пример, как использовать оба варианта:

Простой input с v-model:

<template>
  <input v-model="name" placeholder="Введите ваше имя" />
  <p>Ваше имя: {{ name }}</p>
</template>

<script setup>
import { ref } from 'vue';
const name = ref(''); // Создаем реактивную переменную
</script>

Компонент a-input с v-model:value:

<template>
  <a-input
    v-model:value="email"
    placeholder="Введите вашу электронную почту"
  />
  <p>Ваша почта: {{ email }}</p>
</template>

<script setup>
import { ref } from 'vue';
const email = ref(''); // Создаем реактивную переменную
</script>

Понимание, когда использовать v-model или v-model:value, помогает правильно настраивать привязку данных и использовать компоненты библиотек эффективно.