# Директивы

# v-text

# v-html

  • Ожидает: string

  • Подробности:

    Обновляет свойство элемента innerHTML (opens new window). Учтите, что содержимое будет вставляться как обычный HTML и не будет компилироваться или обрабатываться как шаблоны Vue. Если понимаете, что пытаетесь организовать составление шаблона с помощью v-html, то попробуйте переосмыслить реализацию с использованием компонентов.

    ВНИМАНИЕ

    Динамическая отрисовка произвольного HTML-кода на сайте — опасная практика, которая приводит к XSS-уязвимостям (opens new window). Передавайте в v-html содержимое, которому можно доверять, и НИКОГДА не передавайте содержимое, которое предоставляется пользователем.

    Локальные стили (scoped) в однофайловых компонентах также не будут применяться к содержимому v-html, потому что этот HTML никак не обрабатывается компилятором шаблонов Vue. При необходимости стилизовать содержимое в v-html вместо локального CSS можно использовать CSS-модули (opens new window) или указать дополнительный глобальный элемент <style> с собственной стратегией модульности, такой как БЭМ.

  • Пример:

    <div v-html="html"></div>
    
    1
  • См. также: Синтаксис шаблонов — Интерполяции

# v-show

  • Ожидает: any

  • Использование:

    Отображает элемент по условию, выполняя переключение у элемента CSS-свойства display в зависимости от истинности указанного выражения.

    Директива запускает анимации перехода при изменении состояния.

  • См. также: Условная отрисовка — v-show

# v-if

  • Ожидает: any

  • Использование:

    Отрисовывает элемент по условию, в зависимости от истинности указанного выражения. При переключении элемент и все содержащиеся в нём директивы / компоненты будут уничтожены и созданы заново. Для <template> будет отрисовываться его содержимое.

    Директива запускает анимации перехода при изменении состояния.

    Будет иметь больший приоритет, при совместном использовании с v-for на элементе, но не рекомендуется использовать эти две директивы одновременно — подробнее в разделе отрисовки списков.

  • См. также: Условная отрисовка — v-if

# v-else

  • Не ожидает выражения

  • Ограничение: предыдущий элемент должен иметь директиву v-if или v-else-if.

  • Использование:

    Обозначает «блок else» для v-if или цепочки v-if/v-else-if.

    <div v-if="Math.random() > 0.5">
      Сейчас меня видно
    </div>
    <div v-else>
      А сейчас — нет
    </div>
    
    1
    2
    3
    4
    5
    6
  • См. также: Условная отрисовка — v-else

# v-else-if

  • Ожидает: any

  • Ограничение: предыдущий элемент должен иметь директиву v-if или v-else-if.

  • Использование:

    Обозначает «блок else if» для v-if. Можно использовать для создания цепочек условий.

    <div v-if="type === 'A'">
      A
    </div>
    <div v-else-if="type === 'B'">
      B
    </div>
    <div v-else-if="type === 'C'">
      C
    </div>
    <div v-else>
      Не A/B/C
    </div>
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
  • См. также: Условная отрисовка — v-else-if

# v-for

  • Ожидает: Array | Object | number | string | Iterable

  • Использование:

    Многократно отрисовывает элемент или блок шаблона на основании исходных данных. Значение директивы должно использовать специальный синтаксис alias in expression, чтобы объявить переменную для текущего элемента итерации:

    <div v-for="item in items">
      {{ item.text }}
    </div>
    
    1
    2
    3

    Также можно объявить переменную для индекса (или ключа, при работе с объектом):

    <div v-for="(item, index) in items"></div>
    <div v-for="(value, name) in object"></div>
    <div v-for="(value, name, index) in object"></div>
    
    1
    2
    3

    По умолчанию v-for будет обновлять элементы «на месте», не перемещая их. Если необходимо переупорядочивать элементы при изменениях, то потребуется указывать специальный атрибут key:

    <div v-for="item in items" :key="item.id">
      {{ item.text }}
    </div>
    
    1
    2
    3

    Кроме того, v-for может работать со значениями, реализующими протокол Iterable (opens new window), включая нативные Map и Set.

    Подробная информация об использовании v-for описана в разделе руководства по ссылке ниже.

  • См. также: Отрисовка списков

# v-on

  • Сокращённая запись: @

  • Ожидает: Function | Инлайн-выражение | Object

  • Аргумент: event

  • Модификаторы:

    • .stop — вызывает event.stopPropagation().
    • .prevent — вызывает event.preventDefault().
    • .capture — отслеживает событие в режиме capture.
    • .self — вызывает обработчик только если событие произошло именно на этом элементе.
    • .{keyAlias} — вызывает обработчик только при нажатии определённой клавиши.
    • .once — вызывает обработчик события только один раз.
    • .left — вызывает обработчик только по нажатию левой кнопки мыши.
    • .right — вызывает обработчик только по нажатию правой кнопки мыши.
    • .middle — вызывает обработчик только по нажатию средней кнопки мыши.
    • .passive — добавляет обработчик события DOM с опцией { passive: true }.
  • Использование:

    Прикрепляет обработчик события к элементу. Тип события определяется аргументом. Выражение может быть именем метода, инлайн-выражением или даже не указываться, при использовании модификаторов.

    При использовании на обычном элементе отслеживает только нативные события DOM (opens new window). При использовании на компонентах отслеживает пользовательские события, которые были сгенерированы в нём.

    При отслеживании нативных событий DOM в метод аргументом будет передаваться объект события. При указании инлайн-выражения, к объекту события можно получить доступ через специальное свойство $event: v-on:click="handle('ok', $event)".

    Также v-on поддерживает привязку объекта из пар событие/обработчик без аргумента. Обратите внимание, что при использовании объектного синтаксиса модификаторы не поддерживаются.

  • Пример:

    <!-- использование метода в качестве обработчика -->
    <button v-on:click="doThis"></button>
    
    <!-- динамическое имя события -->
    <button v-on:[event]="doThis"></button>
    
    <!-- инлайн-выражение -->
    <button v-on:click="doThat('hello', $event)"></button>
    
    <!-- сокращённая запись -->
    <button @click="doThis"></button>
    
    <!-- сокращённая запись при динамическом имени события -->
    <button @[event]="doThis"></button>
    
    <!-- остановка всплытия события -->
    <button @click.stop="doThis"></button>
    
    <!-- остановка поведения по умолчанию -->
    <button @click.prevent="doThis"></button>
    
    <!-- остановка поведения по умолчанию без выражения -->
    <form @submit.prevent></form>
    
    <!-- цепочка модификаторов -->
    <button @click.stop.prevent="doThis"></button>
    
    <!-- модификатор клавиши с использованием keyAlias -->
    <input @keyup.enter="onEnter" />
    
    <!-- обработчик события будет вызван не больше одного раза -->
    <button v-on:click.once="doThis"></button>
    
    <!-- объектный синтаксис -->
    <button v-on="{ mousedown: doThis, mouseup: doThat }"></button>
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35

    Отслеживание пользовательских событий на компоненте (обработчик вызывается, когда в дочернем компоненте будет сгенерировано событие my-event):

    <my-component @my-event="handleThis"></my-component>
    
    <!-- инлайн-выражение -->
    <my-component @my-event="handleThis(123, $event)"></my-component>
    
    1
    2
    3
    4
  • См. также:

# v-bind

  • Сокращённая запись: :

  • Ожидает: any (если указан аргумент) | Object (без аргумента)

  • Аргумент: attrOrProp (опционально)

  • Модификаторы:

    • .camel — преобразование имён атрибутов из kebab-case в camelCase.
  • Использование:

    Динамически привязывает один или несколько атрибутов или входных параметров компонента к выражению.

    При использовании с атрибутами class или style в качестве значений допускаются массивы и объекты. Подробнее можно узнать в разделе руководства по ссылкам ниже.

    При привязке входных параметров к дочернему компоненту необходимо также объявлять их внутри него.

    При использовании без аргумента можно привязать объект из пар имя-значение. Обратите внимание, в этом режиме не поддерживаются массивы или объекты для class и style.

  • Пример:

    <!-- привязка к атрибуту -->
    <img v-bind:src="imageSrc" />
    
    <!-- динамическое имя атрибута -->
    <button v-bind:[key]="value"></button>
    
    <!-- сокращённая запись -->
    <img :src="imageSrc" />
    
    <!-- сокращённая запись при динамическом имени атрибута -->
    <button :[key]="value"></button>
    
    <!-- инлайн-выражение с конкатенацией строк -->
    <img :src="'/path/to/images/' + fileName" />
    
    <!-- привязка классов -->
    <div :class="{ red: isRed }"></div>
    <div :class="[classA, classB]"></div>
    <div :class="[classA, { classB: isB, classC: isC }]"></div>
    
    <!-- привязка стилей -->
    <div :style="{ fontSize: size + 'px' }"></div>
    <div :style="[styleObjectA, styleObjectB]"></div>
    
    <!-- привязка объекта с несколькими атрибутами -->
    <div v-bind="{ id: someProp, 'other-attr': otherProp }"></div>
    
    <!-- привязка входного параметра / "prop" должен быть объявлен в my-component -->
    <my-component :prop="someThing"></my-component>
    
    <!-- передача всех входных параметров родительского компонента в дочерний -->
    <child-component v-bind="$props"></child-component>
    
    <!-- XLink -->
    <svg><a :xlink:special="foo"></a></svg>
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35

    Модификатор .camel позволяет приводить имя атрибута v-bind в camelCase при использовании DOM-шаблонов, например для атрибута viewBox в SVG:

    <svg :view-box.camel="viewBox"></svg>
    
    1

    Указывать .camel при использовании строковых шаблонов или компиляции шаблонов с помощью vue-loader/vueify не нужно.

  • См. также:

# v-model

  • Ожидает: варьируется в зависимости от элемента формы или работы компонента

  • Использование ограничено:

    • <input>
    • <select>
    • <textarea>
    • компоненты
  • Модификаторы:

    • .lazy — отслеживание события change вместо input
    • .number — приведение корректной строки со значением к числу
    • .trim — удаление пробелов в начале и в конце строки
  • Использование:

    Создаёт двухстороннюю привязку к элементу ввода формы или к компоненту. Подробнее об использовании в разделах документации по ссылкам ниже.

  • См. также:

# v-slot

  • Сокращённая запись: #

  • Ожидает: JavaScript выражение, допустимое в позиции аргумента функции (можно использовать деструктуризацию в поддерживаемых окружениях). Опционально — требуется только в случае ожидания входных параметров, передаваемых в слот.

  • Аргумент: имя слота (опционально, по умолчанию default)

  • Использование ограничено:

    • <template>
    • компонентами (для единственного слота по умолчанию с входными параметрами)
  • Использование:

    Обозначение именованного слота или слота, который получает входные параметры.

  • Пример:

    <!-- Именованный слот -->
    <base-layout>
      <template v-slot:header>
        Содержимое для заголовка
      </template>
    
      <template v-slot:default>
        Содержимое для слота по умолчанию
      </template>
    
      <template v-slot:footer>
        Содержимое для подвала
      </template>
    </base-layout>
    
    <!-- Именованный слот с входными параметрами -->
    <infinite-scroll>
      <template v-slot:item="slotProps">
        <div class="item">
          {{ slotProps.item.text }}
        </div>
      </template>
    </infinite-scroll>
    
    <!-- Слот по умолчанию с входными параметрами и деструктуризацией -->
    <mouse-position v-slot="{ x, y }">
      Mouse position: {{ x }}, {{ y }}
    </mouse-position>
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28

    Дополнительную информацию можно получить по ссылкам ниже.

  • См. также:

# v-pre

  • Не ожидает выражения

  • Использование:

    Пропускает компиляцию для элемента и всех его потомков. Можно использовать для отображения необработанных тегов фигурных скобок. Пропуск большого количества элементов без директив на них также может ускорить компиляцию.

  • Пример:

    <span v-pre>{{ это не будет скомпилировано }}</span>
    
    1

# v-cloak

  • Не ожидает выражения

  • Использование:

    Директива остаётся на элементе, пока связанный с ним экземпляр компонента не завершит компиляцию. В сочетании с CSS-правилом [v-cloak] { display: none } позволяет скрывать нескомпилированные шаблоны до тех пор, пока не будет готов экземпляр компонента.

  • Пример:

    [v-cloak] {
      display: none;
    }
    
    1
    2
    3
    <div v-cloak>
      {{ message }}
    </div>
    
    1
    2
    3

    Элемента <div> не будет видно до завершения компиляции.

# v-once

  • Не ожидает выражения

  • Подробности:

    Отрисовывает один раз элемент или компонент. При последующих обновлениях данных и перерисовках элемент/компонент и все его потомки будут считаться статичными и пропускаться. Может использоваться для оптимизации производительности обновлений.

    <!-- элемент -->
    <span v-once>Это значение никогда не изменится: {{ msg }}</span>
    
    <!-- элемент с потомками -->
    <div v-once>
      <h1>Комментарий</h1>
      <p>{{ msg }}</p>
    </div>
    
    <!-- компонент -->
    <my-component v-once :comment="msg"></my-component>
    
    <!-- директива `v-for` -->
    <ul>
      <li v-for="i in list" v-once>{{ i }}</li>
    </ul>
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
  • См. также: Синтаксис шаблонов — Интерполяции

# v-is удалено

Удалено в версии 3.1.0. Вместо неё используйте атрибут is с префиксом vue:.