Vue.js

# Директивы

# 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="'<h1>Hello World</h1>'"></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

  • Сокращённая запись: : или . (при использовании модификатора .prop)

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

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

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

    • .camel — преобразование имён атрибутов из kebab-case в camelCase.
    • .prop — форсирует установку привязки как свойством DOM. 3.2+
    • .attr — форсирует установку привязки атрибутом DOM. 3.2+

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

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

    При использовании с атрибутами 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

    При установке привязки к элементу, по умолчанию Vue проверяет оператором in, был ли определён ключ в элементе как свойство. Если свойство определено, то Vue будет устанавливать значение как свойство DOM, а не как атрибут. В большинстве случаев это и ожидается, но можно изменить поведение, явно указывая модификаторы .prop или .attr. Иногда это необходимо, особенно при работе с пользовательскими элементами.

    Модификатор .prop также имеет сокращённую запись .:

    <div :someProperty.prop="someObject"></div>

<!-- сокращённая запись -->
<div .someProperty="someObject"></div>
    1
    2
    3
    4

    Модификатор .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

    Начиная с версии 3.2, можно использовать мемоизацию части шаблона, с возможностью указания условий для инвалидации, с помощью директивы v-memo.

  • См. также:

# v-memo 3.2+

  • Ожидает: Array

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

    Мемоизация части поддерева шаблона. Может использоваться как для элементов, так и для компонентов. Директива ожидает массив фиксированной длины зависимых значений, которые станут использоваться для сравнения при мемоизации. Если каждое значение массива осталось таким же, как при последней отрисовке, то обновление всего поддерева будет пропущено. Например:

    <div v-memo="[valueA, valueB]">
  ...
</div>
    1
    2
    3

    При повторной отрисовке компонента, если valueA и valueB остались неизменными, то будут пропущены все обновления этого <div> и его дочерних элементов. Фактически, будет пропущено даже создание VNode виртуального DOM, поскольку можно переиспользовать мемоизировую копию поддерева.

    Важно правильно определить массив для мемоизации, иначе можно пропустить обновления, которые действительно должны быть выполнены. v-memo с пустым массивом зависимостей (v-memo="[]") будет функционально эквивалентен v-once.

    Использование вместе с v-for

    v-memo нужна исключительно для микрооптимизации сценариев, где критически важна производительность, и должна использоваться крайне редко. Наиболее частый случай, где она может оказаться полезной — отрисовка больших списков с помощью v-for (когда length > 1000):

    <div v-for="item in list" :key="item.id" v-memo="[item.id === selected]">
  <p>ID: {{ item.id }} - выбран: {{ item.id === selected ? 'Да' : 'Нет' }}</p>
  <p>...больше дочерних элементов</p>
</div>
    1
    2
    3
    4

    При изменении состояния selected в компоненте, будет создаваться большое число VNode, даже если большинство элементов остаётся таким же. Использование v-memo здесь уточняет, что «обновляем этот элемент только в том случае, если он перешёл из состояния не выбран в состояние выбран». Это позволит всем незатронутым элементам переиспользовать свою предыдущую VNode и полностью пропустить операцию сравнения. Обратите внимание, что item.id не нужно добавлять в массив зависимостей мемоизации, поскольку Vue автоматически определяет его из :key элемента.

    ПРЕДУПРЕЖДЕНИЕ

    При использовании v-memo вместе с v-for, убедитесь, что они указываются на одном и том же элементе. v-memo ВНУТРИ v-for НЕ БУДЕТ РАБОТАТЬ.

    v-memo также можно использовать и на компонентах, чтобы вручную предотвращать нежелательные обновления в некоторых крайних случаях, когда проверка обновления дочернего компонента была де-оптимизирована. Но, повторимся, на разработчике лежит полная ответственность за указание правильного массива зависимостей, для избежания пропуска необходимых обновлений.

  • См. также:

# v-is удалено

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

← Специальные атрибуты →