|
| 1 | +# Template Syntax |
| 2 | + |
| 3 | +Vue.js uses an HTML-based template syntax that allows you to declaratively bind the rendered DOM to the underlying Vue instance's data. All Vue.js templates are valid HTML that can be parsed by spec-compliant browsers and HTML parsers. |
| 4 | + |
| 5 | +Under the hood, Vue compiles the templates into Virtual DOM render functions. Combined with the reactivity system, Vue is able to intelligently figure out the minimal number of components to re-render and apply the minimal amount of DOM manipulations when the app state changes. |
| 6 | + |
| 7 | +If you are familiar with Virtual DOM concepts and prefer the raw power of JavaScript, you can also [directly write render functions](TODO:render-function.html) instead of templates, with optional JSX support. |
| 8 | + |
| 9 | +## Interpolations |
| 10 | + |
| 11 | +### Text |
| 12 | + |
| 13 | +The most basic form of data binding is text interpolation using the "Mustache" syntax (double curly braces): |
| 14 | + |
| 15 | +``` html |
| 16 | +<span>Message: {{ msg }}</span> |
| 17 | +``` |
| 18 | + |
| 19 | +The mustache tag will be replaced with the value of the `msg` property on the corresponding data object. It will also be updated whenever the data object's `msg` property changes. |
| 20 | + |
| 21 | +You can also perform one-time interpolations that do not update on data change by using the [v-once directive](TODO:../api/#v-once), but keep in mind this will also affect any other bindings on the same node: |
| 22 | + |
| 23 | +``` html |
| 24 | +<span v-once>This will never change: {{ msg }}</span> |
| 25 | +``` |
| 26 | + |
| 27 | +### Raw HTML |
| 28 | + |
| 29 | +The double mustaches interprets the data as plain text, not HTML. In order to output real HTML, you will need to use the [`v-html` directive](TODO:../api/#v-html): |
| 30 | + |
| 31 | +``` html |
| 32 | +<p>Using mustaches: {{ rawHtml }}</p> |
| 33 | +<p>Using v-html directive: <span v-html="rawHtml"></span></p> |
| 34 | +``` |
| 35 | +<template-1/> |
| 36 | + |
| 37 | +The contents of the `span` will be replaced with the value of the `rawHtml` property, interpreted as plain HTML - data bindings are ignored. Note that you cannot use `v-html` to compose template partials, because Vue is not a string-based templating engine. Instead, components are preferred as the fundamental unit for UI reuse and composition. |
| 38 | + |
| 39 | +::: tip |
| 40 | +Dynamically rendering arbitrary HTML on your website can be very dangerous because it can easily lead to [XSS vulnerabilities](https://en.wikipedia.org/wiki/Cross-site_scripting). Only use HTML interpolation on trusted content and **never** on user-provided content |
| 41 | +::: |
| 42 | + |
| 43 | +### Attributes |
| 44 | + |
| 45 | +Mustaches cannot be used inside HTML attributes. Instead, use a [`v-bind` directive](../api/#v-bind): |
| 46 | + |
| 47 | +``` html |
| 48 | +<div v-bind:id="dynamicId"></div> |
| 49 | +``` |
| 50 | + |
| 51 | +In the case of boolean attributes, where their mere existence implies `true`, `v-bind` works a little differently. In this example: |
| 52 | + |
| 53 | +``` html |
| 54 | +<button v-bind:disabled="isButtonDisabled">Button</button> |
| 55 | +``` |
| 56 | + |
| 57 | +If `isButtonDisabled` has the value of `null`, `undefined`, or `false`, the `disabled` attribute will not even be included in the rendered `<button>` element. |
| 58 | + |
| 59 | +### Using JavaScript Expressions |
| 60 | + |
| 61 | +So far we've only been binding to simple property keys in our templates. But Vue.js actually supports the full power of JavaScript expressions inside all data bindings: |
| 62 | + |
| 63 | +``` html |
| 64 | +{{ number + 1 }} |
| 65 | + |
| 66 | +{{ ok ? 'YES' : 'NO' }} |
| 67 | + |
| 68 | +{{ message.split('').reverse().join('') }} |
| 69 | + |
| 70 | +<div v-bind:id="'list-' + id"></div> |
| 71 | +``` |
| 72 | + |
| 73 | +These expressions will be evaluated as JavaScript in the data scope of the owner Vue instance. One restriction is that each binding can only contain **one single expression**, so the following will **NOT** work: |
| 74 | + |
| 75 | +``` html |
| 76 | +<!-- this is a statement, not an expression: --> |
| 77 | +{{ var a = 1 }} |
| 78 | + |
| 79 | +<!-- flow control won't work either, use ternary expressions --> |
| 80 | +{{ if (ok) { return message } }} |
| 81 | +``` |
| 82 | + |
| 83 | +::: tip |
| 84 | +Template expressions are sandboxed and only have access to a [whitelist of globals](TODO:https://github.com/vuejs/vue/blob/v2.6.10/src/core/instance/proxy.js#L9) such as `Math` and `Date`. You should not attempt to access user defined globals in template expressions.</p> |
| 85 | +::: |
| 86 | + |
| 87 | +## Directives |
| 88 | + |
| 89 | +Directives are special attributes with the `v-` prefix. Directive attribute values are expected to be **a single JavaScript expression** (with the exception of `v-for`, which will be discussed later). A directive's job is to reactively apply side effects to the DOM when the value of its expression changes. Let's review the example we saw in the introduction: |
| 90 | + |
| 91 | +``` html |
| 92 | +<p v-if="seen">Now you see me</p> |
| 93 | +``` |
| 94 | + |
| 95 | +Here, the `v-if` directive would remove/insert the `<p>` element based on the truthiness of the value of the expression `seen`. |
| 96 | + |
| 97 | +### Arguments |
| 98 | + |
| 99 | +Some directives can take an "argument", denoted by a colon after the directive name. For example, the `v-bind` directive is used to reactively update an HTML attribute: |
| 100 | + |
| 101 | +``` html |
| 102 | +<a v-bind:href="url"> ... </a> |
| 103 | +``` |
| 104 | + |
| 105 | +Here `href` is the argument, which tells the `v-bind` directive to bind the element's `href` attribute to the value of the expression `url`. |
| 106 | + |
| 107 | +Another example is the `v-on` directive, which listens to DOM events: |
| 108 | + |
| 109 | +``` html |
| 110 | +<a v-on:click="doSomething"> ... </a> |
| 111 | +``` |
| 112 | + |
| 113 | +Here the argument is the event name to listen to. We will talk about event handling in more detail too. |
| 114 | + |
| 115 | +### Dynamic Arguments |
| 116 | + |
| 117 | +It is also possible to use a JavaScript expression in a directive argument by wrapping it with square brackets: |
| 118 | + |
| 119 | +``` html |
| 120 | +<!-- |
| 121 | +Note that there are some constraints to the argument expression, as explained |
| 122 | +in the "Dynamic Argument Expression Constraints" section below. |
| 123 | +--> |
| 124 | +<a v-bind:[attributeName]="url"> ... </a> |
| 125 | +``` |
| 126 | + |
| 127 | +Here `attributeName` will be dynamically evaluated as a JavaScript expression, and its evaluated value will be used as the final value for the argument. For example, if your Vue instance has a data property, `attributeName`, whose value is `"href"`, then this binding will be equivalent to `v-bind:href`. |
| 128 | + |
| 129 | +Similarly, you can use dynamic arguments to bind a handler to a dynamic event name: |
| 130 | + |
| 131 | +``` html |
| 132 | +<a v-on:[eventName]="doSomething"> ... </a> |
| 133 | +``` |
| 134 | + |
| 135 | +In this example, when `eventName`'s value is `"focus"`, `v-on:[eventName]` will be equivalent to `v-on:focus`. |
| 136 | + |
| 137 | +#### Dynamic Argument Value Constraints |
| 138 | + |
| 139 | +Dynamic arguments are expected to evaluate to a string, with the exception of `null`. The special value `null` can be used to explicitly remove the binding. Any other non-string value will trigger a warning. |
| 140 | + |
| 141 | +#### Dynamic Argument Expression Constraints |
| 142 | + |
| 143 | +Dynamic argument expressions have some syntax constraints because certain characters, such as spaces and quotes, are invalid inside HTML attribute names. For example, the following is invalid: |
| 144 | + |
| 145 | +``` html |
| 146 | +<!-- This will trigger a compiler warning. --> |
| 147 | +<a v-bind:['foo' + bar]="value"> ... </a> |
| 148 | +``` |
| 149 | + |
| 150 | +The workaround is to either use expressions without spaces or quotes, or replace the complex expression with a computed property. |
| 151 | + |
| 152 | +When using in-DOM templates (templates directly written in an HTML file), you should also avoid naming keys with uppercase characters, as browsers will coerce attribute names into lowercase: |
| 153 | + |
| 154 | +``` html |
| 155 | +<!-- |
| 156 | +This will be converted to v-bind:[someattr] in in-DOM templates. |
| 157 | +Unless you have a "someattr" property in your instance, your code won't work. |
| 158 | +--> |
| 159 | +<a v-bind:[someAttr]="value"> ... </a> |
| 160 | +``` |
| 161 | + |
| 162 | +### Modifiers |
| 163 | + |
| 164 | +Modifiers are special postfixes denoted by a dot, which indicate that a directive should be bound in some special way. For example, the `.prevent` modifier tells the `v-on` directive to call `event.preventDefault()` on the triggered event: |
| 165 | + |
| 166 | +``` html |
| 167 | +<form v-on:submit.prevent="onSubmit"> ... </form> |
| 168 | +``` |
| 169 | + |
| 170 | +You'll see other examples of modifiers later, [for `v-on`](TODO:events.html#Event-Modifiers) and [for `v-model`](TODO:forms.html#Modifiers), when we explore those features. |
| 171 | + |
| 172 | +## Shorthands |
| 173 | + |
| 174 | +The `v-` prefix serves as a visual cue for identifying Vue-specific attributes in your templates. This is useful when you are using Vue.js to apply dynamic behavior to some existing markup, but can feel verbose for some frequently used directives. At the same time, the need for the `v-` prefix becomes less important when you are building a [SPA](https://en.wikipedia.org/wiki/Single-page_application), where Vue manages every template. Therefore, Vue provides special shorthands for two of the most often used directives, `v-bind` and `v-on`: |
| 175 | + |
| 176 | +### `v-bind` Shorthand |
| 177 | + |
| 178 | +``` html |
| 179 | +<!-- full syntax --> |
| 180 | +<a v-bind:href="url"> ... </a> |
| 181 | + |
| 182 | +<!-- shorthand --> |
| 183 | +<a :href="url"> ... </a> |
| 184 | + |
| 185 | +<!-- shorthand with dynamic argument (2.6.0+) --> |
| 186 | +<a :[key]="url"> ... </a> |
| 187 | +``` |
| 188 | + |
| 189 | +### `v-on` Shorthand |
| 190 | + |
| 191 | +``` html |
| 192 | +<!-- full syntax --> |
| 193 | +<a v-on:click="doSomething"> ... </a> |
| 194 | + |
| 195 | +<!-- shorthand --> |
| 196 | +<a @click="doSomething"> ... </a> |
| 197 | + |
| 198 | +<!-- shorthand with dynamic argument (2.6.0+) --> |
| 199 | +<a @[event]="doSomething"> ... </a> |
| 200 | +``` |
| 201 | + |
| 202 | +They may look a bit different from normal HTML, but `:` and `@` are valid characters for attribute names and all Vue-supported browsers can parse it correctly. In addition, they do not appear in the final rendered markup. The shorthand syntax is totally optional, but you will likely appreciate it when you learn more about its usage later. |
0 commit comments