Merge remote-tracking branch 'upstream/master' into dev

Author: GuiDevloper

src/.vuepress/config.js

@@ -15,6 +15,7 @@ const sidebar = {
         '/guide/introduction',
         '/guide/instance',
         '/guide/template-syntax',
+        '/guide/data-methods',
         '/guide/computed',
         '/guide/class-and-style',
         '/guide/conditional',

src/api/composition-api.md

@@ -158,3 +158,58 @@ const foo = inject<string>('foo') // string | undefined
 - **See also**:
   - [Provide / Inject](../guide/component-provide-inject.html)
   - [Composition API Provide / Inject](../guide/composition-api-provide-inject.html)
+
+## `getCurrentInstance`
+
+`getCurrentInstance` enables access to an internal component instance useful for advanced usages or for library creators.
+
+```ts
+import { getCurrentIntance } from 'vue'
+
+const MyComponent = {
+  setup() {
+    const internalIntance = getCurrentInstance()
+
+    internalInstance.appContext.config.globalProperties // access to globalProperties
+  }
+}
+```
+
+`getCurrentInstance` **only** works during [setup](#setup) or [Lifecycle Hooks](#lifecycle-hooks)
+
+> When using outside of [setup](#setup) or [Lifecycle Hooks](#lifecycle-hooks), please call `getCurrentInstance()` on `setup` and use the instance instead.
+
+```ts
+const MyComponent = {
+  setup() {
+    const internalIntance = getCurrentInstance() // works
+
+    const id = useComponentId() // works
+
+    const handleClick = () => {
+      getCurrentInstance() // doesn't work
+      useComponentId() // doesn't work
+
+      internalIntance // works
+    }
+
+    onMounted(() => {
+      getCurrentInstance() // works
+    })
+
+    return () =>
+      h(
+        'button',
+        {
+          onClick: handleClick
+        },
+        `uid: ${id}`
+      )
+  }
+}
+
+// also works if called on a composable
+function useComponentId() {
+  return getCurrentInstance().uid
+}
+```

src/api/directives.md

@@ -197,7 +197,7 @@
   <!-- shorthand -->
   <button @click="doThis"></button>
 
-  <!-- shorthand dynamic event (2.6.0+) -->
+  <!-- shorthand dynamic event -->
   <button @[event]="doThis"></button>
 
   <!-- stop propagation -->

src/api/instance-methods.md

@@ -158,7 +158,9 @@
   If you still want to call an unwatch function inside the callback, you should check its availability first:
 
   ```js
-  const unwatch = vm.$watch(
+  let unwatch = null
+  
+  unwatch = vm.$watch(
     'value',
     function() {
       doSomething()

src/api/options-data.md

@@ -92,7 +92,7 @@
 
 - **Details:**
 
-  Computed properties to be mixed into the Vcomponent instance. All getters and setters have their `this` context automatically bound to the component instance.
+  Computed properties to be mixed into the component 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:
 

src/guide/component-basics.md

@@ -234,7 +234,7 @@ Então, o componente filho pode emitir um evento por si próprio chamando o [mé
 </button>
 ```
 
-Graças à escuta `v-on:enlarge-text="postFontSize += 0.1"`, o componente pai receberá o evento e atualizará o valor de `postFontSize`.
+Graças à escuta `@enlarge-text="postFontSize += 0.1"`, o componente pai receberá o evento e atualizará o valor de `postFontSize`.
 
 <p class="codepen" data-height="300" data-theme-id="39028" data-default-tab="html,result" data-user="Vue" data-slug-hash="KKpGyrp" data-editable="true" style="height: 300px; box-sizing: border-box; display: flex; align-items: center; justify-content: center; border: 2px solid; margin: 1em 0; padding: 1em;" data-pen-title="Básico sobre Componentes: Emitindo Eventos">
   <span>Veja o exemplo <a href="https://codepen.io/vuejs-br/pen/jOqXJEv">

src/guide/component-slots.md

@@ -48,7 +48,7 @@ Or even other components:
 <todo-button>
   <!-- Use a component to add an icon -->
   <font-awesome-icon name="plus"></font-awesome-icon>
-  Your Profile
+  Add todo
 </todo-button>
 ```
 
@@ -263,7 +263,7 @@ To make `item` available to the slot content provided by the parent, we can add
 ```html
 <ul>
   <li v-for="( item, index ) in items">
-    <slot v-bind:item="item"></slot>
+    <slot :item="item"></slot>
   </li>
 </ul>
 ```
@@ -330,7 +330,7 @@ Whenever there are multiple slots, use the full `<template>` based syntax for _a
   <template v-slot:other="otherSlotProps">
     ...
   </template>
-</current-user>
+</todo-list>
 ```
 
 ### Destructuring Slot Props

src/guide/composition-api-provide-inject.md

@@ -36,7 +36,7 @@ export default {
 <!-- src/components/MyMarker.vue -->
 <script>
 export default {
-  inject: ['location', 'longitude', 'latitude']
+  inject: ['location', 'geolocation']
 }
 </script>
 ```

src/guide/data-methods.md

@@ -0,0 +1,125 @@
+# Data Properties and Methods
+
+## Data Properties
+
+The `data` option for a component is a function. Vue calls this function as part of creating a new component instance. It should return an object, which Vue will then wrap in its reactivity system and store on the component instance as `$data`. For convenience, any top-level properties of that object are also exposed directly via the component instance:
+
+```js
+const app = Vue.createApp({
+  data() {
+    return { count: 4 }
+  }
+})
+
+const vm = app.mount('#app')
+
+console.log(vm.$data.count) // => 4
+console.log(vm.count)       // => 4
+
+// Assigning a value to vm.count will also update $data.count
+vm.count = 5
+console.log(vm.$data.count) // => 5
+
+// ... and vice-versa
+vm.$data.count = 6
+console.log(vm.count) // => 6
+```
+
+These instance properties are only added when the instance is first created, so you need to ensure they are all present in the object returned by the `data` function. Where necessary, use `null`, `undefined` or some other placeholder value for properties where the desired value isn't yet available.
+
+It is possible to add a new property directly to the component instance without including it in `data`. However, because this property isn't backed by the reactive `$data` object, it won't automatically be tracked by [Vue's reactivity system](reactivity.html).
+
+Vue uses a `$` prefix when exposing its own built-in APIs via the component instance. It also reserves the prefix `_` for internal properties. You should avoid using names for top-level `data` properties that start with either of these characters.
+
+## Methods
+
+To add methods to a component instance we use the `methods` option. This should be an object containing the desired methods:
+
+```js
+const app = Vue.createApp({
+  data() {
+    return { count: 4 }
+  },
+  methods: {
+    increment() {
+      // `this` will refer to the component instance
+      this.count++
+    }
+  }
+})
+
+const vm = app.mount('#app')
+
+console.log(vm.count) // => 4
+
+vm.increment()
+
+console.log(vm.count) // => 5
+```
+
+Vue automatically binds the `this` value for `methods` so that it always refers to the component instance. This ensures that a method retains the correct `this` value if it's used as an event listener or callback. You should avoid using arrow functions when defining `methods`, as that prevents Vue from binding the appropriate `this` value.
+
+Just like all other properties of the component instance, the `methods` are accessible from within the component's template. Inside a template they are most commonly used as event listeners:
+
+```html
+<button @click="increment">Up vote</button>
+```
+
+In the example above, the method `increment` will be called when the `<button>` is clicked.
+
+It is also possible to call a method directly from a template. As we'll see shortly, it's usually better to use a [computed property](computed.html) instead. However, using a method can be useful in scenarios where computed properties aren't a viable option. You can call a method anywhere that a template supports JavaScript expressions:
+
+```html
+<span :title="toTitleDate(date)">
+  {{ formatDate(date) }}
+</span>
+```
+
+If the methods `toTitleDate` or `formatDate` access any reactive data then it will be tracked as a rendering dependency, just as if it had been used in the template directly.
+
+Methods called from a template should not have any side effects, such as changing data or triggering asynchronous processes. If you find yourself tempted to do that you should probably use a [lifecycle hook](instance.html#lifecycle-hooks) instead.
+
+### Debouncing and Throttling
+
+Vue doesn't include built-in support for debouncing or throttling but it can be implemented using libraries such as [Lodash](https://lodash.com/).
+
+In cases where a component is only used once, the debouncing can be applied directly within `methods`:
+
+```html
+<script src="https://unpkg.com/[email protected]/lodash.min.js"></script>
+<script>
+  Vue.createApp({
+    methods: {
+      // Debouncing with Lodash
+      click: _.debounce(function() {
+        // ... respond to click ...
+      }, 500)
+    }
+  }).mount('#app')
+</script>
+```
+
+However, this approach is potentially problematic for components that are reused because they'll all share the same debounced function. To keep the component instances independent from each other, we can add the debounced function in the `created` lifecycle hook:
+
+```js
+app.component('save-button', {
+  created() {
+    // Debouncing with Lodash
+    this.debouncedClick = _.debounce(this.click, 500)
+  },
+  unmounted() {
+    // Cancel the timer when the component is removed
+    this.debouncedClick.cancel()
+  },
+  methods: {
+    click() {
+      // ... respond to click ...
+    }
+  },
+  template: `
+    <button @click="debouncedClick">
+      Save
+    </button>
+  `
+})
+```