diff --git a/src/guide/computed.md b/src/guide/computed.md index 8ea7070a7d..79ced6d0b2 100644 --- a/src/guide/computed.md +++ b/src/guide/computed.md @@ -97,55 +97,7 @@ computed: { In comparison, a method invocation will **always** run the function whenever a re-render happens. -Why do we need caching? Imagine we have an expensive computed property **A**, which requires looping through a huge array and doing a lot of computations. Then we may have other computed properties that in turn depend on **A**. Without caching, we would be executing **A**’s getter many more times than necessary! In cases where you do not want caching, use a method instead. - -### Computed vs Watched Property - -Vue does provide a more generic way to observe and react to data changes on a Vue instance: **watch properties**. When you have some data that needs to change based on some other data, it is tempting to overuse `watch` - especially if you are coming from an AngularJS background. However, it is often a better idea to use a computed property rather than an imperative `watch` callback. Consider this example: - -```html -
{{ fullName }}
-``` - -```js -const vm = Vue.createApp({ - data() { - return { - firstName: 'Foo', - lastName: 'Bar', - fullName: 'Foo Bar' - } - }, - watch: { - firstName(val) { - this.fullName = val + ' ' + this.lastName - }, - lastName(val) { - this.fullName = this.firstName + ' ' + val - } - } -}).mount('#demo') -``` - -The above code is imperative and repetitive. Compare it with a computed property version: - -```js -const vm = Vue.createApp({ - data() { - return { - firstName: 'Foo', - lastName: 'Bar' - } - }, - computed: { - fullName() { - return this.firstName + ' ' + this.lastName - } - } -}).mount('#demo') -``` - -Much better, isn't it? +Why do we need caching? Imagine we have an expensive computed property `list`, which requires looping through a huge array and doing a lot of computations. Then we may have other computed properties that in turn depend on `list`. Without caching, we would be executing `list`’s getter many more times than necessary! In cases where you do not want caching, use a `method` instead. ### Computed Setter @@ -239,3 +191,51 @@ Result: In this case, using the `watch` option allows us to perform an asynchronous operation (accessing an API) and sets a condition for performing this operation. None of that would be possible with a computed property. In addition to the `watch` option, you can also use the imperative [vm.\$watch API](TODO:../api/#vm-watch). + +### Computed vs Watched Property + +Vue does provide a more generic way to observe and react to data changes on a Vue instance: **watch properties**. When you have some data that needs to change based on some other data, it is tempting to overuse `watch` - especially if you are coming from an AngularJS background. However, it is often a better idea to use a computed property rather than an imperative `watch` callback. Consider this example: + +```html +
{{ fullName }}
+``` + +```js +const vm = Vue.createApp({ + data() { + return { + firstName: 'Foo', + lastName: 'Bar', + fullName: 'Foo Bar' + } + }, + watch: { + firstName(val) { + this.fullName = val + ' ' + this.lastName + }, + lastName(val) { + this.fullName = this.firstName + ' ' + val + } + } +}).mount('#demo') +``` + +The above code is imperative and repetitive. Compare it with a computed property version: + +```js +const vm = Vue.createApp({ + data() { + return { + firstName: 'Foo', + lastName: 'Bar' + } + }, + computed: { + fullName() { + return this.firstName + ' ' + this.lastName + } + } +}).mount('#demo') +``` + +Much better, isn't it? diff --git a/src/guide/instance.md b/src/guide/instance.md index bd273e87f9..513abb967b 100644 --- a/src/guide/instance.md +++ b/src/guide/instance.md @@ -8,7 +8,7 @@ Every Vue application starts by creating a new **Vue instance** with the `create Vue.createApp(/* options */) ``` -After the Vue instance is created, we can _mount_ it, passing a container to `.mount` method. For example, if we want to mount a Vue application on `
`, we should pass `#app`: +After the Vue instance is created, we can _mount_ it, passing a container to `mount` method. For example, if we want to mount a Vue application on `
`, we should pass `#app`: ```js Vue.createApp(/* options */).mount('#app') diff --git a/src/guide/introduction.md b/src/guide/introduction.md index c0f1bb9743..b5b3affbb0 100644 --- a/src/guide/introduction.md +++ b/src/guide/introduction.md @@ -83,7 +83,7 @@ Vue.createApp(AttributeBindingApp).mount('#bind-attribute')

-Here we are encountering something new. The `v-bind` attribute you are seeing is called a **directive**. Directives are prefixed with `v-` to indicate that they are special attributes provided by Vue, and as you may have guessed, they apply special reactive behavior to the rendered DOM. Here, it is basically saying "keep this element's `title` attribute up-to-date with the `message` property on the Vue instance." +Here we're encountering something new. The `v-bind` attribute you're seeing is called a **directive**. Directives are prefixed with `v-` to indicate that they are special attributes provided by Vue, and as you may have guessed, they apply special reactive behavior to the rendered DOM. Here we are basically saying "_keep this element's `title` attribute up-to-date with the `message` property on the Vue instance._" ## Conditionals and Loops @@ -109,7 +109,7 @@ Vue.createApp(ConditionalRenderingApp).mount('#conditional-rendering') This example demonstrates that we can bind data to not only text and attributes, but also the **structure** of the DOM. Moreover, Vue also provides a powerful transition effect system that can automatically apply [transition effects](TODO) when elements are inserted/updated/removed by Vue. -You can change `seen` from `true` to `false` in the sandbox below to check the effect +You can change `seen` from `true` to `false` in the sandbox below to check the effect:

See the Pen @@ -118,7 +118,7 @@ You can change `seen` from `true` to `false` in the sandbox below to check the e

-There are quite a few other directives, each with its own special functionality. For example, the `v-for` directive can be used for displaying a list of items using the data from an Array: +There are quite a few other directives, each with its own special functionality. For example, the `v-for` directive can be used to display a list of items using the data from an Array: ```html
diff --git a/src/guide/template-syntax.md b/src/guide/template-syntax.md index 1d2701e646..2e6bd81a22 100644 --- a/src/guide/template-syntax.md +++ b/src/guide/template-syntax.md @@ -83,10 +83,6 @@ These expressions will be evaluated as JavaScript in the data scope of the owner {{ if (ok) { return message } }} ``` -::: tip -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.

-::: - ## Directives 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: @@ -137,31 +133,6 @@ Similarly, you can use dynamic arguments to bind a handler to a dynamic event na In this example, when `eventName`'s value is `"focus"`, `v-on:[eventName]` will be equivalent to `v-on:focus`. -#### Dynamic Argument Value Constraints - -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. - -#### Dynamic Argument Expression Constraints - -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: - -```html - - ... -``` - -The workaround is to either use expressions without spaces or quotes, or replace the complex expression with a computed property. - -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: - -```html - - ... -``` - ### Modifiers 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: @@ -203,3 +174,34 @@ The `v-` prefix serves as a visual cue for identifying Vue-specific attributes i ``` 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. + +### Caveats + +#### Dynamic Argument Value Constraints + +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. + +#### Dynamic Argument Expression Constraints + +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: + +```html + + ... +``` + +We recommend replacing any complex expressions with a [computed property](computed.html), one of the most fundamental pieces of Vue, which we'll cover shortly. + +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: + +```html + + ... +``` + +#### JavaScript Expressions + +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.