Vue.js

外观

本页内容

内置指令 ​

v-text ​

更新元素的文本内容。

  • 预期： string

  • 详细信息

    v-text 通过设置元素的 textContent 属性来实现，所以它会覆盖元素中现有的任何内容。如果您需要更新 textContent 的部分，应使用 mustache插值。

  • 示例

    模板
    <span v-text="msg"></span>
<!-- same as -->
<span>{{msg}}</span>

  • 另请参阅 模板语法 - 文本插值

v-html ​

更新元素的 innerHTML。

  • 预期： string

  • 详细信息

    v-html 的内容被插入为纯 HTML - Vue 模板语法不会被处理。如果您发现自己正在尝试使用 v-html 组合模板，请尝试重新思考解决方案，使用组件代替。

    安全注意事项

    在您的网站上动态渲染任意 HTML 可能非常危险，因为它很容易导致 XSS 攻击。仅在使用可信内容时使用 v-html，绝对不要 在用户提供的内容上使用。

    在 单文件组件 中，scoped 样式不会应用于 v-html 内的内容，因为该 HTML 不会被 Vue 的模板编译器处理。如果您想使用带有作用域的 CSS 样式针对 v-html 内容，您可以改用 CSS 模块 或额外的全局 <style> 元素，并使用如 BEM 之类的手动作用域策略。

  • 示例

    模板
    <div v-html="html"></div>

  • 另请参阅 模板语法 - 原始 HTML

v-show ​

根据表达式值的真伪切换元素的可见性。

  • 预期： 任何

  • 详细信息

    v-show 通过内联样式设置 display CSS 属性，并在元素可见时尝试尊重初始的 display 值。它还会在其条件改变时触发过渡。

  • 另请参阅 条件渲染 - v-show

v-if ​

根据表达式的真伪有条件地渲染元素或模板片段。

  • 预期： 任何

  • 详细信息

    当 v-if 元素切换时，元素及其包含的指令/组件将被销毁并重新构建。如果初始条件为假，则不会渲染内部内容。

    可以在 <template> 上使用，以表示仅包含文本或多个元素的条件块。

    此指令在其条件改变时触发过渡。

    当一起使用时，v-if 的优先级高于 v-for。我们不推荐在一个元素上同时使用这两个指令——有关详细信息，请参阅 列表渲染指南。

  • 另请参阅 条件渲染 - v-if

v-else ​

表示 v-if 或 v-if / v-else-if 链的 "else 块"。

  • 不期望表达式

  • 详细信息

    • 限制：前一个同级元素必须具有 v-if 或 v-else-if。

    • 可以在 <template> 上使用，以表示仅包含文本或多个元素的条件块。

  • 示例

    模板
    <div v-if="Math.random() > 0.5">
  Now you see me
</div>
<div v-else>
  Now you don't
</div>

  • 另请参阅 条件渲染 - v-else

v-else-if ​

表示 v-if 的 "else if 块"。可以链接。

  • 预期： 任何

  • 详细信息

    • 限制：前一个同级元素必须具有 v-if 或 v-else-if。

    • 可以在 <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>
  Not A/B/C
</div>

  • 另请参阅 条件渲染 - v-else-if

v-for ​

根据源数据多次渲染元素或模板块。

  • 预期： 数组 | 对象 | 数字 | 字符串 | 可迭代对象

  • 详细信息

    指令的值必须使用特殊语法 别名 in 表达式 来提供当前正在迭代的元素的别名。

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

    或者，您也可以指定对索引（或用于对象的键）的别名。

    模板
    <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 特殊属性的排序提示。

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

    v-for 也可以在实现 可迭代协议 的值上工作，包括原生的 Map 和 Set。

  • 另请参阅

v-on ​

将事件监听器附加到元素上。

  • 简写： @

  • 期望： Function | Inline Statement | Object (without argument)

  • 参数： event (如果使用对象语法，则为可选)

  • 修饰符

    • .stop - 调用 event.stopPropagation()。
    • .prevent - 调用 event.preventDefault()。
    • .capture - 在捕获模式下添加事件监听器。
    • .self - 只有当事件是从该元素派发时才触发处理器。
    • .{keyAlias} - 只在某些键上触发处理器。
    • .once - 至多触发处理器一次。
    • .left - 只有在左按钮鼠标事件上触发处理器。
    • .right - 只有在右按钮鼠标事件上触发处理器。
    • .middle - 只有在中按钮鼠标事件上触发处理器。
    • .passive - 附加一个带有 { passive: true } 的 DOM 事件。

  • 详细信息

    事件类型由参数表示。表达式可以是方法名、内联语句，或者如果存在修饰符，则省略。

    当用于普通元素时，它只监听 原生 DOM 事件。当用于自定义元素组件时，它监听该子组件发出的 自定义事件。

    当监听原生 DOM 事件时，方法接收原生事件作为唯一参数。如果使用内联语句，则语句可以访问特殊的 $event 属性：v-on:click="handle('ok', $event)"。

    v-on 还支持绑定到没有参数的事件/监听器对象。请注意，当使用对象语法时，它不支持任何修饰符。

  • 示例

    模板
    <!-- method handler -->
<button v-on:click="doThis"></button>

<!-- dynamic event -->
<button v-on:[event]="doThis"></button>

<!-- inline statement -->
<button v-on:click="doThat('hello', $event)"></button>

<!-- shorthand -->
<button @click="doThis"></button>

<!-- shorthand dynamic event -->
<button @[event]="doThis"></button>

<!-- stop propagation -->
<button @click.stop="doThis"></button>

<!-- prevent default -->
<button @click.prevent="doThis"></button>

<!-- prevent default without expression -->
<form @submit.prevent></form>

<!-- chain modifiers -->
<button @click.stop.prevent="doThis"></button>

<!-- key modifier using keyAlias -->
<input @keyup.enter="onEnter" />

<!-- the click event will be triggered at most once -->
<button v-on:click.once="doThis"></button>

<!-- object syntax -->
<button v-on="{ mousedown: doThis, mouseup: doThat }"></button>

    在子组件上监听自定义事件（当子组件上“my-event”被触发时，调用处理器）

    模板
    <MyComponent @my-event="handleThis" />

<!-- inline statement -->
<MyComponent @my-event="handleThis(123, $event)" />

  • 另请参阅

v-bind ​

将一个或多个属性，或将组件属性动态绑定到表达式。

  • 简写

    • : 或 .（当使用 .prop 修饰符时）
    • 省略值（当属性和绑定值具有相同名称时，需要 3.4+）

  • 期望： any (with argument) | Object (without argument)

  • 参数： attrOrProp (optional)

  • 修饰符

    • .camel - 将短横线分隔的属性名称转换为 camelCase。
    • .prop - 强制将绑定设置为 DOM 属性（3.2+）。
    • .attr - 强制将绑定设置为 DOM 属性（3.2+）。

  • 用法

    当用于绑定 class 或 style 属性时，v-bind 支持额外的值类型，如 Array 或 Objects。有关更多详细信息，请参阅下面的链接指南部分。

    当在元素上设置绑定时，Vue 默认会检查该元素是否使用 in 操作符定义了作为属性的键。如果属性已定义，Vue 将将值作为 DOM 属性而不是属性设置。这应该在大多数情况下都有效，但您可以通过显式使用 .prop 或 .attr 修饰符来覆盖此行为。这有时是必要的，尤其是在与 自定义元素一起工作时。

    当用于组件属性绑定时，必须在子组件中正确声明该属性。

    当没有参数时，可以用于绑定包含属性名称-值对的对象。

  • 示例

    模板
    <!-- bind an attribute -->
<img v-bind:src="imageSrc" />

<!-- dynamic attribute name -->
<button v-bind:[key]="value"></button>

<!-- shorthand -->
<img :src="imageSrc" />

<!-- same-name shorthand (3.4+), expands to :src="src" -->
<img :src />

<!-- shorthand dynamic attribute name -->
<button :[key]="value"></button>

<!-- with inline string concatenation -->
<img :src="'/path/to/images/' + fileName" />

<!-- class binding -->
<div :class="{ red: isRed }"></div>
<div :class="[classA, classB]"></div>
<div :class="[classA, { classB: isB, classC: isC }]"></div>

<!-- style binding -->
<div :style="{ fontSize: size + 'px' }"></div>
<div :style="[styleObjectA, styleObjectB]"></div>

<!-- binding an object of attributes -->
<div v-bind="{ id: someProp, 'other-attr': otherProp }"></div>

<!-- prop binding. "prop" must be declared in the child component. -->
<MyComponent :prop="someThing" />

<!-- pass down parent props in common with a child component -->
<MyComponent v-bind="$props" />

<!-- XLink -->
<svg><a :xlink:special="foo"></a></svg>

    .prop 修饰符还有一个专门的简写，即 .

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

<!-- equivalent to -->
<div .someProperty="someObject"></div>

    .camel 修饰符允许在 In-DOM 模板中使用时，将 v-bind 属性名称转换为驼峰式，例如 SVG 的 viewBox 属性。

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

    如果你使用字符串模板，或者在使用构建步骤预编译模板时，不需要 .camel。

  • 另请参阅

v-model

在表单输入元素或组件上创建双向绑定。

v-slot

表示期望接收属性的名作用域插槽或作用域插槽。

  • 简写： #

  • 期望：一个在函数参数位置有效的 JavaScript 表达式，包括对解构的支持。可选 - 只有在期望将属性传递到插槽时才需要。

  • 参数：插槽名称（可选，默认为 default）

  • 限于

    • <template>
    • 组件（用于具有属性的唯一默认插槽）

  • 示例

    模板
    <!-- Named slots -->
<BaseLayout>
  <template v-slot:header>
    Header content
  </template>

  <template v-slot:default>
    Default slot content
  </template>

  <template v-slot:footer>
    Footer content
  </template>
</BaseLayout>

<!-- Named slot that receives props -->
<InfiniteScroll>
  <template v-slot:item="slotProps">
    <div class="item">
      {{ slotProps.item.text }}
    </div>
  </template>
</InfiniteScroll>

<!-- Default slot that receive props, with destructuring -->
<Mouse v-slot="{ x, y }">
  Mouse position: {{ x }}, {{ y }}
</Mouse>

  • 另请参阅

v-pre

跳过此元素及其所有子元素的编译。

  • 不期望表达式

  • 详细信息

    在带有 v-pre 的元素内部，所有 Vue 模板语法都将保留并按原样渲染。最常见的用例是显示原始花括号标记。

  • 示例

    模板
    <span v-pre>{{ this will not be compiled }}</span>

v-once

仅渲染元素和组件一次，并跳过未来的更新。

  • 不期望表达式

  • 详细信息

    在后续的重新渲染中，元素/组件及其所有子元素将被视为静态内容并跳过。这可以用于优化更新性能。

    模板
    <!-- single element -->
<span v-once>This will never change: {{msg}}</span>
<!-- the element have children -->
<div v-once>
  <h1>Comment</h1>
  <p>{{msg}}</p>
</div>
<!-- component -->
<MyComponent v-once :comment="msg"></MyComponent>
<!-- `v-for` directive -->
<ul>
  <li v-for="i in list" v-once>{{i}}</li>
</ul>

    从 3.2 版本开始，您还可以使用 v-memo 通过无效化条件来缓存部分模板。

  • 另请参阅

v-memo

  • 仅支持 3.2+

  • 期望： any[]

  • 详细信息

    缓存模板的子树。可以在元素和组件上使用。该指令期望一个固定长度的依赖值数组，用于比较缓存。如果数组中的每个值都与上次渲染相同，则将跳过整个子树的更新。例如

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

    当组件重新渲染时，如果 valueA 和 valueB 保持不变，则将跳过此 <div> 和其所有子元素的更新。实际上，由于可以重用缓存的子树副本，甚至可以跳过 Virtual DOM VNode 的创建。

    正确指定缓存数组非常重要，否则我们可能会跳过应实际应用的更新。带有空依赖数组（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 }} - selected: {{ item.id === selected }}</p>
  <p>...more child nodes</p>
</div>

    当组件的selected状态改变时，即使大多数项目保持完全相同，也会创建大量VNodes。这里的v-memo使用本质上是在说“只有当项目从非选中状态变为选中状态，或相反时才更新此项目”。这允许每个未受影响的项重用其先前的VNode并完全跳过diff。注意，我们不需要在memo依赖数组中包含item.id，因为Vue会自动从项目的:key推断它。

    警告：

    当与v-for一起使用v-memo时，请确保它们应用于相同的元素。v-memo在v-for内部不起作用。

    v-memo也可以用于组件，以在子组件更新检查被去优化等某些边缘情况下手动防止不必要的更新。但再次强调，指定正确的依赖数组是开发者的责任，以避免跳过必要的更新。

  • 另请参阅

v-cloak ​

用于在模板准备好之前隐藏未编译的模板。

  • 不期望表达式

  • 详细信息

    此指令仅适用于无构建步骤的设置。

    当使用DOM内模板时，可能会出现“未编译模板闪现”现象：用户可能会看到直到挂载的组件用渲染内容替换之前的原始mustache标签。

    v-cloak将保留在元素上，直到关联的组件实例挂载。结合CSS规则，如[v-cloak] { display: none }，可以用来在组件准备好之前隐藏原始模板。

  • 示例

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

    在编译完成之前，<div>将不可见。

在GitHub上编辑此页面