# Directivas

# v-text

# v-html

  • Espera: string

  • Detalles:

    Actualiza el innerHTML (opens new window) del elemento. Note que los contenidos son insertados como HTML plano - no serán compilados como plantillas Vue. Si usted se encuentra intentando componer plantillas utilizando v-html, intente pensar una solución utilizando componentes en su lugar.

    WARNING

    Renderizar dinámicamente HTML arbitrario en su sitio web puede ser muy peligroso porque puede conducir fácilmente a ataques XSS (opens new window). Solo utilice v-html en contenido confiable y nunca en contenido provisto por el usuario.

    En Componentes de un solo archivo, los estilos scoped no aplicarán al contenido dentro de v-html, porque el HTML no será procesado por el compilador de plantillas de Vue. Si usted quiere aplicar estilos scoped al contenido v-html, puede utilizar módulos CSS (opens new window) o un elemento <style> global adicional, con una estrategia manual como BEM por ejemplo.

  • Ejemplo:

    <div v-html="'<h1>Hola Mundo</h1>'"></div>
    
    1
  • Vea también: Sintaxis de Vinculación de Dato - Interpolaciones

# v-show

  • Espera: any

  • Uso:

    Cambia la propiedad CSS display del elemento basado en la veracidad del valor de la expresión.

    La directiva dispara transiciones cuando su condición cambie.

  • Vea también: Renderización condicional - v-show

# v-if

  • Espera: any

  • Uso:

    Renderiza condicionalmente el elemento basado en la veracidad del valor de la expresión. El elemento y sus directivas / componentes son destruidas y re-construidas al cambiar el valor de la expresión. Si el elemento es un <template>, su contenido será extraído como un bloque condicional.

    Esta directiva dispara transiciones cuando su condición cambie.

    v-if tiene una prioridad mayor que v-for cuando los dos se utilicen juntos. No recomendamos utilizarlas juntos en un elemento, vea el guía de renderizado de listas para más detalles.

  • Vea también: Renderización condicional - v-if

# v-else

  • No espera una expresión

  • Restricción: el elemento hermano previo debe tener v-if o v-else-if.

  • Uso:

    Denota el "bloque else" para v-if o una cadena v-if/v-else-if.

    <div v-if="Math.random() > 0.5">
      Ahora me ve
    </div>
    <div v-else>
      Ahora no
    </div>
    
    1
    2
    3
    4
    5
    6
  • Vea también: Renderización condicional - v-else

# v-else-if

  • Espera: any

  • Restricción: el elemento hermano previo debe tener v-if o v-else-if.

  • Uso:

    Denota el "bloque else if" para v-if . Puede ser encadenado.

    <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>
      Ninguno de ellos
    </div>
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
  • Vea también: Renderización condicional - v-else-if

# v-for

  • Espera: Array | Object | number | string | Iterable

  • Uso:

    Renderiza el elemento o plantilla múltiples veces basado en la fuente de dato. El valor de la directiva debe utilizar la sintaxis especial alias in expresión para proveer un alias para el elemento actual en el cual se está iterando:

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

    Alternativamente, usted también puede especificar un alias para el índice (o la clave si es utilizado con un objeto):

    <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>
    
    1
    2
    3

    El comportamiento por defecto de v-for intentará parchar los elementos en situ sin moverlos. Para forzar un reordenamiento de elementos, usted debe proveer una pista de ordenamiento con el atributo especial key:

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

    v-for también funciona con valores que implementan el Protocolo Iterable (opens new window), incluyendo el Map y Set nativo.

    El uso más detallado para v-for es explicado en la sección del guía referenciada abajo.

  • Vea también:

# v-on

  • Abreviación: @

  • Espera: Function | Inline Statement | Object

  • Argumento: event

  • Modificadores:

    • .stop - invoca event.stopPropagation().
    • .prevent - invoca event.preventDefault().
    • .capture - agrega escuchador de evento en modo de captura.
    • .self - invoca el manejador solo si el evento fue disparado por el elemento mísmo.
    • .{keyAlias} - invoca el manejador solo con algunas teclas.
    • .once - invoca el manejador a lo sumo una vez.
    • .left - invoca el manejador solo para eventos del botón izquierdo del ratón.
    • .right - invoca el manejador solo para eventos del botón derecho del ratón.
    • .middle - invoca el manejador solo para eventos del botón central del ratón.
    • .passive - adjunta un evento DOM con { passive: true }.
  • Uso:

    Adjunta un escuchador de evento al elemento. El tipo del evento es denotado por el argumento. La expresión puede ser el nombre de un método, una declaración en línea u omitida cuando se encuentren modificadores.

    Cuando se utilice en un elemento normal, escucha solo a evento DOM nativos (opens new window). Cuando se utilice en un componente de elemento personalizado, escucha a eventos personalizados emitidos por ese componente hijo.

    Cuando se escucha por eventos DOM nativos, el método recibe el evento nativo como único argumento. Si se utiliza una declaración en línea, la declaración tiene acceso a la propiedad especial $event: v-on:click="handle('ok', $event)".

    v-on también soporta vinculación a un objeto de pares de evento/escuchador sin argumentos. Note que cuando se utiliza la sintaxis de objeto, esta no soporta ningún modificador.

  • Ejemplo:

    <!-- método como manejador -->
    <button v-on:click="doThis"></button>
    
    <!-- evento dinámico -->
    <button v-on:[event]="doThis"></button>
    
    <!-- declaración en línea -->
    <button v-on:click="doThat('hello', $event)"></button>
    
    <!-- abreviación -->
    <button @click="doThis"></button>
    
    <!-- abreviación para evento dinámico -->
    <button @[event]="doThis"></button>
    
    <!-- detener la propagación -->
    <button @click.stop="doThis"></button>
    
    <!-- prevenir el comportamiento por defecto -->
    <button @click.prevent="doThis"></button>
    
    <!-- prevenir el comportamiento por defecto sin expresión alguna -->
    <form @submit.prevent></form>
    
    <!-- modificadores en cadena -->
    <button @click.stop.prevent="doThis"></button>
    
    <!-- modificador de tecla utilizando keyAlias -->
    <input @keyup.enter="onEnter" />
    
    <!-- el evento click será lanzado a lo sumo una vez -->
    <button v-on:click.once="doThis"></button>
    
    <!-- sintaxis de objeto -->
    <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

    Escucha a eventos personalizados en un componente hijo (el manejador es invocado cuando "my-event" es emitido en el hijo):

    <my-component @my-event="handleThis"></my-component>
    
    <!-- declaración en línea -->
    <my-component @my-event="handleThis(123, $event)"></my-component>
    
    1
    2
    3
    4
  • Vea también:

# v-bind

  • Abreviación: : o . (cuando se utilice el modificador .prop)

  • Espera: any (con argumento) | Object (sin argumento)

  • Argumento: attrOrProp (opcional)

  • Modificadores:

    • .camel - transforma el nombre del atributo de kebab-case a camelCase.
    • .prop - forzar una vinculación para establecerse como una propiedad DOM. 3.2+
    • .attr - forzar una vinculación para establecerse como un atributo DOM. 3.2+
  • Uso:

    Vincula dinámicamente uno o más atributos, o una prop de componente a una expresión.

    Cuando se utiliza para vincular el atributo class o style, soporta tipos adicionales de valor tales como Array u Object. Vea la sección del guía referenciada abajo para más detalles.

    Cuando se utiliza para vincular una prop, la prop debe ser declarada en el componente hijo de forma acorde.

    Cuando se utiliza sin argumento, puede ser utilizado para vincular un objeto que contenga pares nombre-valor de atributos. Note que en este modo los atributos class y style no soportan Array u Object.

  • Ejemplo:

    <!-- vincular un atributo -->
    <img v-bind:src="imageSrc" />
    
    <!-- nombre de atributo dinámico -->
    <button v-bind:[key]="value"></button>
    
    <!-- abreviación -->
    <img :src="imageSrc" />
    
    <!-- abreviación de nombre de atributo dinámico -->
    <button :[key]="value"></button>
    
    <!-- con concatenación en línea de cadena de caracteres -->
    <img :src="'/path/to/images/' + fileName" />
    
    <!-- vinculación del atributo class -->
    <div :class="{ red: isRed }"></div>
    <div :class="[classA, classB]"></div>
    <div :class="[classA, { classB: isB, classC: isC }]"></div>
    
    <!-- vinculación del atributo style -->
    <div :style="{ fontSize: size + 'px' }"></div>
    <div :style="[styleObjectA, styleObjectB]"></div>
    
    <!-- vincular un objeto de atributos -->
    <div v-bind="{ id: someProp, 'other-attr': otherProp }"></div>
    
    <!-- vinculación de _prop_. "prop" debe ser declarada en my-component. -->
    <my-component :prop="someThing"></my-component>
    
    <!-- pasar las props del padre al componente hijo  -->
    <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

    Cuando se establece una vinculación en un elemento, Vue por defecto comproba si el elemento tenga el clave definido como propiedad utilizando un operador in. Si la propiedad es definida, Vue establecerá el valor como propiedad DOM en vez de un atributo. Este funcionaría en la mayoría de casos, pero puede sobreescribir este comportamiento mediante explícitamente utilizar los modificadores .prop o .attr. Este es a veces necesario, especialmente cuando se trabaje con elementos personalizados.

    El modificador .prop también tiene una abreviación dedicada, .:

    <div :someProperty.prop="someObject"></div>
    
    <!-- es equivalente a -->
    <div .someProperty="someObject"></div>
    
    1
    2
    3
    4

    El modificador .camel permite transformar el nombre de un atributo de v-bind a camelCase cuando se utilice plantillas en DOM, p. ej. el atributo SVG viewBox:

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

    .camel no es necesario si usted utiliza plantillas de cadena de caracteres, o compila utilizando vue-loader/vuetify.

  • Vea también:

# v-model

# v-slot

  • Abreviación: #

  • Espera: expresión JavaScript que es válida en un posición de argumento de función (soporta desestructuración en entornos soportados). Opcional - solo requerido si se espere pasar props al slot.

  • Argumento: nombre del slot (opcional, por defecto default)

  • Limitado a:

    • <template>
    • components (para un solo slot por defecto con props)
  • Uso:

    Denota slots nombrados o slots que esperan recibir props.

  • Ejemplo:

    <!-- slots nombrados -->
    <base-layout>
      <template v-slot:header>
        Contenido del encabezado
      </template>
    
      <template v-slot:default>
        Contenido del slot por defecto
      </template>
    
      <template v-slot:footer>
        Contenido del pie de página
      </template>
    </base-layout>
    
    <!-- slot nombrado que recibe props -->
    <infinite-scroll>
      <template v-slot:item="slotProps">
        <div class="item">
          {{ slotProps.item.text }}
        </div>
      </template>
    </infinite-scroll>
    
    <!-- slot por defecto que recibe props, con desestructuración -->
    <mouse-position v-slot="{ x, y }">
      La posición del ratón: {{ 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

    Para más detalles, vea las enlaces abajo.

  • Vea también:

# v-pre

  • No espera una expresión

  • Uso:

    Saltea la compilación para este elemento y todos sus hijos. Usted puede utilizar esto para mostrar etiquetas mustache crudas. Saltear una gran cantidad de nodos sin directivas en ellos también puede acelerar el tiempo de compilación.

  • Ejemplo:

    <span v-pre>{{ esto no será compilado }}</span>
    
    1

# v-cloak

  • No espera una expresión

  • Uso:

    Esta directiva permanecerá en el elemento hasta que la instancia Vue asociada termine su compilación. Combinada con reglas de CSS tal como [v-cloak] { display: none }, esta directiva puede ser utilizada para esconder vinculaciones mustache no compiladas hasta que la instancia de Vue este lista.

  • Ejemplo:

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

    El <div> no será visible hasta que la compilación haya terminado.

# v-once

  • No espera una expresión

  • Detalles:

    Renderiza el elemento/componente solo una vez. En renderizaciones posteriores, el elemento/componente y todos sus hijos serán tratados como contenido estático, y por lo tanto, salteados. Esto puede ser utilizado para optimizar el rendimiento de actualización.

    <!-- un solo elemento -->
    <span v-once>Esto nunca cambiará: {{msg}}</span>
    <!-- n elemento con hijos -->
    <div v-once>
      <h1>comment</h1>
      <p>{{msg}}</p>
    </div>
    <!-- componente -->
    <my-component v-once :comment="msg"></my-component>
    <!-- directiva `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

    Desde la versión 3.2, puede también memorizar parte de la plantilla con condiciones de invalidación utilizando v-memo.

  • Vea también:

# v-memo 3.2+

  • Espera: Array

  • Detalles:

    Memorizar un subárbol de la plantilla. Puede ser utilizada tanto en elementos como en componentes. La directiva espera una matriz de tamaño fijo de valores de dependencia para comparar para la memorización. Si cada valor de la matriz fue el mismo como el anterior renderizado, las actualizaciones para el subárbol entero será salteado. Por ejemplo:

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

    Cuando el componente se rerenderice, si valueA y valueB siguen siendo los mismos, todas actualizaciones para este <div> y sus hijos serán salteados. De hecho, incluso la creación del VNode DOM virtual será también salteada debido a que la copia memorizada del subárbol pueda ser reutilizada.

    Es importante especificar la matriz de memorización correctmente, de lo contrario podemos saltear actualizaciones que deberían ser aplicadas. v-memo con una matriz vacía de dependencia (v-memo="[]") sería en la práctica equivalente a v-once.

    Uso con v-for

    v-memo es proporcionada solamente para optimizaciones micros en escenarios que sea crítico el rendimiento y rara vez sería necesaria. El caso má común dónde este puede ser útil es cuando se renderice listas grandes de v-for (dónde length > 1000):

    <div v-for="item in list" :key="item.id" v-memo="[item.id === selected]">
      <p>ID: {{ item.id }} - seleccionados: {{ item.id === selected }}</p>
      <p>...más nodos hijos</p>
    </div>
    
    1
    2
    3
    4

    Cuando el estado selected del componente se cambie, un gran cantidad de VNodes serán creados aunque la mayoría de los elementos siguen siendo exactamente los mismos. El uso de v-memo aquí es escencialmente decir que "solo actualiza este elemento si se haya cambiado desde el estado no seleccionado al estado seleccionado, y viceversa". Este permite que cada elemento no afecto reutilice su previo VNode y saltee el proceso "diffing" (comparar) completamente. Note que no necesitamos incluir item.id en la matriz de dependencia de memo aquí debido a que Vue le infiere automáticamente del atributo :key del elemento.

    WARNING

    Cuando se utilice v-memo con v-for, asegure que sean utilizadas en el mismo elemento. v-memo no funciona dentro de v-for.

    v-memo puede también ser utilizada en componentes para manualmente detener actualizaciones no deseadas en ciertos casos extremos dónde la comprobación de actualización del componente hijo haya sido salteada. Pero, de nuevo, es la responsabilidad del desarrollador para especificar matrices correctas de dependencias para evitar saltear actualizaciones necesarias.

  • Vea también:

# v-is deprecated

Obsoleta en 3.1.0. Utilice atributo is con el prefijo vue: en su lugar.