Skip to content

Reword Vue instance/application parameters mentions #355

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 6 commits into from
Aug 1, 2020
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 1 addition & 39 deletions src/api/application-api.md
Original file line number Diff line number Diff line change
Expand Up @@ -158,7 +158,7 @@ Apart from `el`, you should treat these arguments as read-only and never modify

- **Usage:**

Apply a mixin in the whole application scope, which will affect **every** Vue instance created afterwards in the given app (for example, child components). This can be used by plugin authors to inject custom behavior into components. **Not recommended in application code**.
Apply a mixin in the whole application scope. Once registered they can be used in the template of any component within the current application. This can be used by plugin authors to inject custom behavior into components. **Not recommended in application code**.

- **See also:** [Global Mixin](../guide/mixins.html#global-mixin)

Expand Down Expand Up @@ -192,44 +192,6 @@ app.mount('#my-app')
- **See also:**
- [Lifecycle Diagram](../guide/instance.html#lifecycle-diagram)

## provide

- **Type:**

- `Object | () => Object`

- **Details:**

This option is [used together with `inject`](../api/options-composition.html#provide-inject) to allow an ancestor component to serve as a dependency injector for all its descendants, regardless of how deep the component hierarchy is, as long as they are in the same parent chain.

The `provide` option should be an object or a function that returns an object. This object contains the properties that are available for injection into its descendants. You can use ES2015 Symbols as keys in this object, but only in environments that natively support `Symbol` and `Reflect.ownKeys`.

> Note: the `provide` and `inject` bindings are NOT reactive. This is intentional. However, if you pass down an observed object, properties on that object do remain reactive.

- **Example:**

```js
import { createApp } from 'vue'

const app = createApp({
provide: {
user: 'John Doe'
}
})

app.component('user-card', {
inject: ['user'],
template: `
<div>
{{ user }}
</div>
`
})
```

- **See also:**
- [Provide / Inject](../guide/component-provide-inject.md)

## unmount

- **Arguments:**
Expand Down
4 changes: 2 additions & 2 deletions src/api/application-config.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@ app.config.errorHandler = (err, vm, info) => {
}
```

Assign a handler for uncaught errors during component render function and watchers. The handler gets called with the error and the Vue instance.
Assign a handler for uncaught errors during component render function and watchers. The handler gets called with the error and the application instance.

> Error tracking services [Sentry](https://sentry.io/for/vue/) and [Bugsnag](https://docs.bugsnag.com/platforms/browsers/vue/) provide official integrations using this option.

Expand Down Expand Up @@ -134,7 +134,7 @@ app.mixin({

Define merging strategies for custom options.

The merge strategy receives the value of that option defined on the parent and child instances as the first and second arguments, respectively. The context Vue instance is passed as the third argument.
The merge strategy receives the value of that option defined on the parent and child instances as the first and second arguments, respectively. The context application instance is passed as the third argument.

- **See also:** [Custom Option Merging Strategies](../guide/mixins.html#custom-option-merge-strategies)

Expand Down
2 changes: 1 addition & 1 deletion src/api/directives.md
Original file line number Diff line number Diff line change
Expand Up @@ -409,7 +409,7 @@

- **Usage:**

This directive will remain on the element until the associated Vue instance finishes compilation. Combined with CSS rules such as `[v-cloak] { display: none }`, this directive can be used to hide un-compiled mustache bindings until the Vue instance is ready.
This directive will remain on the element until the associated component instance finishes compilation. Combined with CSS rules such as `[v-cloak] { display: none }`, this directive can be used to hide un-compiled mustache bindings until the component instance is ready.

- **Example:**

Expand Down
12 changes: 6 additions & 6 deletions src/api/instance-methods.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Instance Methods

## $watch
## \$watch

- **Arguments:**

Expand All @@ -14,7 +14,7 @@

- **Usage:**

Watch a reactive property or a computed function on the Vue instance for changes. The callback gets called with the new value and the old value for the given property. We can only pass top-level `data`, `prop`, or `computed` property name as a string. For more complex expressions or nested properties, use a function instead.
Watch a reactive property or a computed function on the component instance for changes. The callback gets called with the new value and the old value for the given property. We can only pass top-level `data`, `prop`, or `computed` property name as a string. For more complex expressions or nested properties, use a function instead.

- **Example:**

Expand Down Expand Up @@ -172,7 +172,7 @@

- **See also:** [Watchers](../guide/computed.html#watchers)

## $emit
## \$emit

- **Arguments:**

Expand Down Expand Up @@ -249,13 +249,13 @@
- [`emits` option](./options-data.html#emits)
- [Emitting a Value With an Event](../guide/component-basics.html#emitting-a-value-with-an-event)

## $forceUpdate
## \$forceUpdate

- **Usage:**

Force the Vue instance to re-render. Note it does not affect all child components, only the instance itself and child components with inserted slot content.
Force the component instance to re-render. Note it does not affect all child components, only the instance itself and child components with inserted slot content.

## $nextTick
## \$nextTick

- **Arguments:**

Expand Down
14 changes: 7 additions & 7 deletions src/api/instance-properties.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@

- **Details:**

The data object that the Vue instance is observing. The Vue instance proxies access to the properties on its data object.
The data object that the component instance is observing. The component instance proxies access to the properties on its data object.

- **See also:** [Options / Data - data](./options-data.html#data-2)

Expand All @@ -16,7 +16,7 @@

- **Details:**

An object representing the current props a component has received. The Vue instance proxies access to the properties on its props object.
An object representing the current props a component has received. The component instance proxies access to the properties on its props object.

## $el

Expand All @@ -26,7 +26,7 @@

- **Details:**

The root DOM element that the Vue instance is managing.
The root DOM element that the component instance is managing.

## $options

Expand All @@ -36,7 +36,7 @@

- **Details:**

The instantiation options used for the current Vue instance. This is useful when you want to include custom properties in the options:
The instantiation options used for the current component instance. This is useful when you want to include custom properties in the options:

```js
const app = Vue.createApp({
Expand All @@ -49,7 +49,7 @@

## $parent

- **Type:** `Vue instance`
- **Type:** `Component instance`

- **Read only**

Expand All @@ -59,13 +59,13 @@

## $root

- **Type:** `Vue instance`
- **Type:** `Component instance`

- **Read only**

- **Details:**

The root Vue instance of the current component tree. If the current instance has no parents this value will be itself.
The root component instance of the current component tree. If the current instance has no parents this value will be itself.

## $slots

Expand Down
4 changes: 2 additions & 2 deletions src/api/options-assets.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@

- **Details:**

A hash of directives to be made available to the Vue instance.
A hash of directives to be made available to the component instance.

- **See also:** [Custom Directives](../guide/custom-directive.html)

Expand All @@ -16,6 +16,6 @@

- **Details:**

A hash of components to be made available to the Vue instance.
A hash of components to be made available to the component instance.

- **See also:** [Components](../guide/component-basics.html)
23 changes: 11 additions & 12 deletions src/api/options-data.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,21 +6,21 @@

- **Details:**

The function that returns a data object for the Vue instance. In `data`, we don't recommend to observe objects with their own stateful behavior like browser API objects and prototype properties. A good idea would be to have here just a plain object that represents component data.
The function that returns a data object for the component instance. In `data`, we don't recommend to observe objects with their own stateful behavior like browser API objects and prototype properties. A good idea would be to have here just a plain object that represents component data.

Once observed, you can no longer add reactive properties to the root data object. It is therefore recommended to declare all root-level reactive properties upfront, before creating the instance.

After the instance is created, the original data object can be accessed as `vm.$data`. The Vue instance also proxies all the properties found on the data object, so `vm.a` will be equivalent to `vm.$data.a`.
After the instance is created, the original data object can be accessed as `vm.$data`. The component instance also proxies all the properties found on the data object, so `vm.a` will be equivalent to `vm.$data.a`.

Properties that start with `_` or `$` will **not** be proxied on the Vue instance because they may conflict with Vue's internal properties and API methods. You will have to access them as `vm.$data._property`.
Properties that start with `_` or `$` will **not** be proxied on the component instance because they may conflict with Vue's internal properties and API methods. You will have to access them as `vm.$data._property`.

- **Example:**

```js
// direct instance creation
const data = { a: 1 }

// The object is added to a Vue instance
// The object is added to a component instance
const vm = Vue.createApp({
data() {
return data
Expand Down Expand Up @@ -92,7 +92,7 @@

- **Details:**

Computed properties to be mixed into the Vue instance. All getters and setters have their `this` context automatically bound to the Vue instance.
Computed properties to be mixed into the Vcomponent instance. All getters and setters have their `this` context automatically bound to the component instance.

Note that if you use an arrow function with a computed property, `this` won't be the component's instance, but you can still access the instance as the function's first argument:

Expand Down Expand Up @@ -143,10 +143,10 @@

- **Details:**

Methods to be mixed into the Vue instance. You can access these methods directly on the VM instance, or use them in directive expressions. All methods will have their `this` context automatically bound to the Vue instance.
Methods to be mixed into the component instance. You can access these methods directly on the VM instance, or use them in directive expressions. All methods will have their `this` context automatically bound to the component instance.

:::tip Note
Note that **you should not use an arrow function to define a method** (e.g. `plus: () => this.a++`). The reason is arrow functions bind the parent context, so `this` will not be the Vue instance as you expect and `this.a` will be undefined.
Note that **you should not use an arrow function to define a method** (e.g. `plus: () => this.a++`). The reason is arrow functions bind the parent context, so `this` will not be the component instance as you expect and `this.a` will be undefined.
:::

- **Example:**
Expand Down Expand Up @@ -177,7 +177,7 @@

- **Details:**

An object where keys are expressions to watch and values are the corresponding callbacks. The value can also be a string of a method name, or an Object that contains additional options. The Vue instance will call `$watch()` for each entry in the object at instantiation.
An object where keys are expressions to watch and values are the corresponding callbacks. The value can also be a string of a method name, or an Object that contains additional options. The component instance will call `$watch()` for each entry in the object at instantiation.

- **Example:**

Expand Down Expand Up @@ -244,7 +244,7 @@
```

::: tip Note
Note that _you should not use an arrow function to define a watcher_ (e.g. `searchQuery: newValue => this.updateAutocomplete(newValue)`). The reason is arrow functions bind the parent context, so `this` will not be the Vue instance as you expect and `this.updateAutocomplete` will be undefined.
Note that _you should not use an arrow function to define a watcher_ (e.g. `searchQuery: newValue => this.updateAutocomplete(newValue)`). The reason is arrow functions bind the parent context, so `this` will not be the component instance as you expect and `this.updateAutocomplete` will be undefined.
:::

- **See also:** [Watchers](../guide/computed.html#watchers)
Expand Down Expand Up @@ -290,10 +290,9 @@
}
})
```

::: tip Note
Events listed in the `emits` option **will not** be inherited by the root element of the component and also will be excluded from the `$attrs` property.
:::


- **See also:** [Attribute Inheritance](../guide/component-props.html#non-prop-attributes)
* **See also:** [Attribute Inheritance](../guide/component-props.html#non-prop-attributes)
2 changes: 1 addition & 1 deletion src/api/options-dom.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@

- **Details:**

A string template to be used as the markup for the Vue instance. The template will **replace** the mounted element. Any existing markup inside the mounted element will be ignored, unless content distribution slots are present in the template.
A string template to be used as the markup for the component instance. The template will **replace** the mounted element. Any existing markup inside the mounted element will be ignored, unless content distribution slots are present in the template.

If the string starts with `#` it will be used as a `querySelector` and use the selected element's innerHTML as the template string. This allows the use of the common `<script type="x-template">` trick to include templates.

Expand Down
6 changes: 3 additions & 3 deletions src/api/options-lifecycle-hooks.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# Lifecycle hooks

:::tip Note
All lifecycle hooks automatically have their `this` context bound to the instance, so that you can access data, computed properties, and methods. This means **you should not use an arrow function to define a lifecycle method** (e.g. `created: () => this.fetchTodos()`). The reason is arrow functions bind the parent context, so `this` will not be the Vue instance as you expect and `this.fetchTodos` will be undefined.
All lifecycle hooks automatically have their `this` context bound to the instance, so that you can access data, computed properties, and methods. This means **you should not use an arrow function to define a lifecycle method** (e.g. `created: () => this.fetchTodos()`). The reason is arrow functions bind the parent context, so `this` will not be the component instance as you expect and `this.fetchTodos` will be undefined.
:::

## beforeCreate
Expand Down Expand Up @@ -128,7 +128,7 @@ All lifecycle hooks automatically have their `this` context bound to the instanc

- **Details:**

Called right before a Vue instance is unmounted. At this stage the instance is still fully functional.
Called right before a component instance is unmounted. At this stage the instance is still fully functional.

**This hook is not called during server-side rendering.**

Expand All @@ -140,7 +140,7 @@ All lifecycle hooks automatically have their `this` context bound to the instanc

- **Details:**

Called after a Vue instance has been unmounted. When this hook is called, all directives of the Vue instance have been unbound, all event listeners have been removed, and all child Vue instances have also been unmounted.
Called after a component instance has been unmounted. When this hook is called, all directives of the component instance have been unbound, all event listeners have been removed, and all child component instance have also been unmounted.

**This hook is not called during server-side rendering.**

Expand Down
6 changes: 3 additions & 3 deletions src/guide/change-detection.md
Original file line number Diff line number Diff line change
Expand Up @@ -84,7 +84,7 @@ vm.items.splice(newLength)

## Declaring Reactive Properties

Since Vue doesn't allow dynamically adding root-level reactive properties, you have to initialize Vue instances by declaring all root-level reactive data properties upfront, even with an empty value:
Since Vue doesn't allow dynamically adding root-level reactive properties, you have to initialize component instances by declaring all root-level reactive data properties upfront, even with an empty value:

```js
var vm = new Vue({
Expand All @@ -100,7 +100,7 @@ vm.message = 'Hello!'

If you don't declare `message` in the data option, Vue will warn you that the render function is trying to access a property that doesn't exist.

There are technical reasons behind this restriction - it eliminates a class of edge cases in the dependency tracking system, and also makes Vue instances play nicer with type checking systems. But there is also an important consideration in terms of code maintainability: the `data` object is like the schema for your component's state. Declaring all reactive properties upfront makes the component code easier to understand when revisited later or read by another developer.
There are technical reasons behind this restriction - it eliminates a class of edge cases in the dependency tracking system, and also makes component instances play nicer with type checking systems. But there is also an important consideration in terms of code maintainability: the `data` object is like the schema for your component's state. Declaring all reactive properties upfront makes the component code easier to understand when revisited later or read by another developer.

## Async Update Queue

Expand All @@ -126,7 +126,7 @@ Vue.nextTick(function() {
})
```

There is also the `vm.$nextTick()` instance method, which is especially handy inside components, because it doesn't need global `Vue` and its callback's `this` context will be automatically bound to the current Vue instance:
There is also the `vm.$nextTick()` instance method, which is especially handy inside components, because it doesn't need global `Vue` and its callback's `this` context will be automatically bound to the current component instance:

```js
Vue.component('example', {
Expand Down
4 changes: 2 additions & 2 deletions src/guide/class-and-style.md
Original file line number Diff line number Diff line change
Expand Up @@ -128,7 +128,7 @@ When you use the `class` attribute on a custom component with a single root elem
For example, if you declare this component:

```js
const app = Vue.createApp()
const app = Vue.createApp({})

app.component('my-component', {
template: `<p class="foo bar">Hi!</p>`
Expand Down Expand Up @@ -170,7 +170,7 @@ If your component has multiple root elements, you would need to define which com
```

```js
const app = Vue.createApp()
const app = Vue.createApp({})

app.component('my-component', {
template: `
Expand Down
Loading