Skip to content

Встроенные директивы

v-text

Обновление текстового содержимого элемента.

v-html

Обновление свойства innerHTML элемента.

  • Ожидает: string

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

    Содержимое v-html вставляется как обычный HTML - синтаксис шаблонов Vue не обрабатывается. Если вы пытаетесь составить шаблоны с помощью v-html, попробуйте переосмыслить решение, используя вместо этого компоненты.

    Примечание о безопасности

    Динамический рендеринг произвольного HTML на вашем сайте может быть очень опасен, поскольку легко может привести к XSS-атакам. Используйте v-html только для доверенного содержимого и никогда для содержимого, предоставляемого пользователем.

    В однофайловых компонентах стили scoped не будут применяться к содержимому внутри v-html, поскольку этот HTML не обрабатывается компилятором шаблонов Vue. Если вы хотите использовать на содержимом v-html скопированный CSS, то вместо этого можно использовать CSS модули или дополнительный глобальный элемент <style> с ручной стратегией области применения, например BEM.

  • Пример

    template
    <div v-html="html"></div>
  • См. также Синтаксис шаблонов - Сырой HTML

v-show

Переключение видимости элемента в зависимости от истинности значения выражения.

  • Ожидает: any

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

    v-show работает, устанавливая CSS-свойство display с помощью встроенных стилей, и будет стараться соблюдать начальное значение display, когда элемент становится видимым. Также он запускает переходы анимации при изменении состояния.

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

v-if

Условное отображение элемента или фрагмента шаблона на основе истинности значения выражения.

  • Ожидает: any

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

    При переключении директивы компонента v-if, элемент и содержащиеся в нём директивы/компоненты уничтожаются и создаются заново. Если начальное условие false, то внутреннее содержимое вообще не будет выведено.

    Может использоваться на <template> для обозначения условного блока, содержащего только текст или несколько элементов.

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

    При совместном использовании v-if имеет более высокий приоритет, чем v-for. Мы не рекомендуем использовать эти две директивы вместе на одном элементе — подробнее об этом см. в руководстве по отрисовке списков.

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

v-else

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

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

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

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

    • Может использоваться на <template> для обозначения условного блока, содержащего только текст или несколько элементов.

  • Пример

    template
    <div v-if="Math.random() > 0.5">
      Сейчас ты видишь меня
    </div>
    <div v-else>
      А сейчас нет
    </div>
  • См. также Условная отрисовка - v-else

v-else-if

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

  • Ожидает: any

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

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

    • Может использоваться на <template> для обозначения условного блока, содержащего только текст или несколько элементов.

  • Пример

    template
    <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>
  • См. также Условная отрисовка - v-else-if

v-for

Многократная отрисовка элемента или блока шаблона на основе исходных данных.

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

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

    Значение директивы должно использовать специальный синтаксис alias in expression для указания псевдонима текущего итерируемого элемента:

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

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

    template
    <div v-for="(item, index) in items"></div>
    <div v-for="(value, key) in object"></div>
    <div v-for="(value, name, index) in object"></div>

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

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

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

  • См. также

v-on

Прикрепление к элементу обработчика событий.

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

  • Ожидает: Function | Inline Statement | Object (без аргументов)

  • Аргумент: event (необязательно, если используется синтаксис Object)

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

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

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

    При использовании на обычном элементе он прослушивает только нативные DOM события. При использовании на компоненте он прослушивает пользовательские события, генерируемые в дочернем компоненте.

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

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

  • Пример

    template
    <!-- метод в качестве обработчика  -->
    <button v-on:click="doThis"></button>
    
    <!-- динамическое событие -->
    <button v-on:[event]="doThis"></button>
    
    <!-- inline-выражение -->
    <button v-on:click="doThat('hello', $event)"></button>
    
    <!-- сокращённая запись -->
    <button @click="doThis"></button>
    
    <!-- окращённая запись динамического события -->
    <button @[event]="doThis"></button>
    
    <!-- stop propagation -->
    <button @click.stop="doThis"></button>
    
    <!-- prevent default -->
    <button @click.prevent="doThis"></button>
    
    <!-- prevent default без выражения -->
    <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>

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

    template
    <MyComponent @my-event="handleThis" />
    
    <!-- inline statement -->
    <MyComponent @my-event="handleThis(123, $event)" />
  • См. также

v-bind

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

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

    • : или . (при использовании модификатора .prop)
    • Пропуск значения (когда атрибут и связанное значение имеют одинаковое имя) requires 3.4+
  • Ожидает: any (если указан аргумент) | Object (без аргумента)

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

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

    • .camel - преобразование имён атрибутов из kebab-case в camelCase.
    • .prop - принудительная установить привязку в качестве свойства DOM (3.2+).
    • .attr - принудительно установить привязку в качестве атрибута DOM (3.2+).
  • Применение

    При использовании для привязки атрибутов class или style, v-bind поддерживает дополнительные типы значений, такие как Array или Objects. Более подробная информация приведена в разделе руководства по ссылкам ниже.

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

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

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

  • Пример

    template
    <!-- привязка атрибута -->
    <img v-bind:src="imageSrc" />
    
    <!-- динамическое название атрибута -->
    <button v-bind:[key]="value"></button>
    
    <!-- сокращённая запись -->
    <img :src="imageSrc" />
    
    <!-- сокращение при одинаковом названии (3.4+), расширяется до :src="src" -->
    <img :src />
    
    <!-- сокращённая запись при динамическом названии атрибута -->
    <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. -->
    <MyComponent :prop="someThing" />
    
    <!-- передача всех входных параметров родительского компонента в дочерний -->
    <MyComponent v-bind="$props" />
    
    <!-- XLink -->
    <svg><a :xlink:special="foo"></a></svg>

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

    template
    <div :someProperty.prop="someObject"></div>
    
    <!-- эквивалент -->
    <div .someProperty="someObject"></div>

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

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

    Модификатор .camel не нужен, если вы используете строковые шаблоны или предварительно компилируете шаблон на этапе сборки.

  • См. также

v-model

Создает двустороннее связывание с элементом ввода формы или с компонентом.

v-slot

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

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

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

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

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

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

    template
    <!-- Именованный слот -->
    <BaseLayout>
      <template v-slot:header>
       Содержимое для заголовка
      </template>
    
      <template v-slot:default>
        Содержимое для слота по умолчанию
      </template>
    
      <template v-slot:footer>
        Содержимое для подвала
      </template>
    </BaseLayout>
    
    <!-- Именованный слот с входными параметрами -->
    <InfiniteScroll>
      <template v-slot:item="slotProps">
        <div class="item">
          {{ slotProps.item.text }}
        </div>
      </template>
    </InfiniteScroll>
    
    <!-- Слот по умолчанию с входными параметрами и деструктуризацией -->
    <Mouse v-slot="{ x, y }">
      Mouse position: {{ x }}, {{ y }}
    </Mouse>
  • См. также

v-pre

Пропускает компиляцию для элемента и всех его потомков.

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

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

    Внутри элемента с v-pre весь синтаксис шаблона Vue будет сохранен и отображён как есть. Наиболее распространённый вариант использования этого элемента - отображение тегов фигурных скобок.

  • Пример

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

v-once

Отрисовка элемента и компонента выполняется только один раз, а последующие обновления пропускаются.

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

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

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

    template
    <!-- элемент -->
    <span v-once>Это значение никогда не изменится: {{msg}}</span>
    <!-- элемент с потомками -->
    <div v-once>
      <h1>Комментарий</h1>
      <p>{{msg}}</p>
    </div>
    <!-- компонент -->
    <MyComponent v-once :comment="msg"></MyComponent>
    <!-- директива `v-for` -->
    <ul>
      <li v-for="i in list" v-once>{{i}}</li>
    </ul>

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

  • См. также

v-memo

  • Поддерживается только в версиях 3.2+

  • Ожидает: any[]

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

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

    template
    <div v-memo="[valueA, valueB]">
      ...
    </div>

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

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

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

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

    template
    <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>

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

    Предупреждение

    При использовании v-memo с v-for убедитесь, что они используются на одном и том же элементе. v-memo не работает внутри v-for..

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

  • См. также

v-cloak

Используется для скрытия еще нескомпилированного шаблона до тех пор, пока он не будет готов.

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

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

    Данная директива нужна только для окружения без этапа сборки.

    При использовании DOM шаблонов может возникнуть "вспышка некомпилированных шаблонов": пользователь может видеть необработанные теги фигурных скобок, пока монтируемый компонент не заменит их отрисованным содержимым.

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

  • Пример

    css
    [v-cloak] {
      display: none;
    }
    template
    <div v-cloak>
      {{ message }}
    </div>

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

Встроенные директивыУже загружено