From da74edb2f47250d0f4f96a89f26fc49ba0224d53 Mon Sep 17 00:00:00 2001 From: NataliaTepluhina Date: Mon, 4 May 2020 17:07:45 +0300 Subject: [PATCH 1/4] feat: added watch --- src/.vuepress/config.js | 3 +- src/api/instance-methods.md | 121 ++++++++++++++++++++++++++++++++++++ 2 files changed, 123 insertions(+), 1 deletion(-) create mode 100644 src/api/instance-methods.md diff --git a/src/.vuepress/config.js b/src/.vuepress/config.js index 22249e30f3..321b4c64d9 100644 --- a/src/.vuepress/config.js +++ b/src/.vuepress/config.js @@ -69,7 +69,8 @@ const sidebar = { '/api/options-misc' ] }, - '/api/instance-properties.md' + '/api/instance-properties.md', + '/api/instance-methods.md' ] } diff --git a/src/api/instance-methods.md b/src/api/instance-methods.md new file mode 100644 index 0000000000..6b90cff9bc --- /dev/null +++ b/src/api/instance-methods.md @@ -0,0 +1,121 @@ +# Instance Methods + +## \$watch + +- **Arguments:** + + - `{string | Function} source` + - `{Function | Object} callback` + - `{Object} [options]` + - `{boolean} deep` + - `{boolean} immediate` + +- **Returns:** `{Function} unwatch` + +- **Usage:** + + Watch an expression or a computed function on the Vue instance for changes. The callback gets called with the new value and the old value. The expression only accepts dot-delimited paths. For more complex expressions, use a function instead. + + :::tip Note + When mutating (rather than replacing) an Object or an Array, the old value will be the same as new value because they reference the same Object/Array. Vue doesn't keep a copy of the pre-mutate value. + ::: + +- **Example:** + + ```js + const app = Vue.createApp({ + data() { + return { + a: 1, + b: 2 + } + }, + created() { + // keypath + this.$watch('a', (newVal, oldVal) => { + // do something + }) + + // function + this.$watch( + // every time the expression `this.a + this.b` yields a different result, + // the handler will be called. It's as if we were watching a computed + // property without defining the computed property itself + () => this.a + this.b, + (newVal, oldVal) => { + // do something + } + ) + } + }) + ``` + + `$watch` returns an unwatch function that stops firing the callback: + + ```js + const app = Vue.createApp({ + data() { + return { + a: 1 + } + } + }) + + const vm = app.mount('#app') + + const unwatch = vm.$watch('a', cb) + // later, teardown the watcher + unwatch() + ``` + +- **Option: deep** + + To also detect nested value changes inside Objects, you need to pass in `deep: true` in the options argument. Note that you don't need to do so to listen for Array mutations. + + ```js + vm.$watch('someObject', callback, { + deep: true + }) + vm.someObject.nestedValue = 123 + // callback is fired + ``` + +- **Option: immediate** + + Passing in `immediate: true` in the option will trigger the callback immediately with the current value of the expression: + + ```js + vm.$watch('a', callback, { + immediate: true + }) + // `callback` is fired immediately with current value of `a` + ``` + + Note that with `immediate` option you won't be able to unwatch the given property on the first callback call. + + ```js + // This will cause an error + var unwatch = vm.$watch( + 'value', + function() { + doSomething() + unwatch() + }, + { immediate: true } + ) + ``` + + If you still want to call an unwatch function inside the callback, you should check its availability first: + + ```js + const unwatch = vm.$watch( + 'value', + function() { + doSomething() + if (unwatch) { + unwatch() + } + }, + { immediate: true } + ) + ``` From 443014236ba35b4c5f6d1cb32cf73f2297bb5dc8 Mon Sep 17 00:00:00 2001 From: NataliaTepluhina Date: Mon, 4 May 2020 18:15:07 +0300 Subject: [PATCH 2/4] feat: added instance methods --- src/api/instance-methods.md | 118 +++++++++++++++++++++++++++++ src/api/options-lifecycle-hooks.md | 4 +- src/guide/component-basics.md | 2 +- src/guide/computed.md | 2 +- src/guide/instance.md | 2 +- 5 files changed, 123 insertions(+), 5 deletions(-) diff --git a/src/api/instance-methods.md b/src/api/instance-methods.md index 6b90cff9bc..dce1dde059 100644 --- a/src/api/instance-methods.md +++ b/src/api/instance-methods.md @@ -119,3 +119,121 @@ { immediate: true } ) ``` + +- **See also:** [Watchers](../guide/computed.html#watchers) + +## \$emit + +- **Arguments:** + + - `{string} eventName` + - `[...args]` + + Trigger an event on the current instance. Any additional arguments will be passed into the listener's callback function. + +- **Examples:** + + Using `$emit` with only an event name: + + ```html +
+ +
+ ``` + + ```js + const app = Vue.createApp({ + methods: { + sayHi() { + console.log('Hi!') + } + } + }) + + app.component('welcome-button', { + template: ` + + ` + }) + + app.mount('#emit-example-simple') + ``` + + Using `$emit` with additional arguments: + + ```html +
+ +
+ ``` + + ```js + const app = Vue.createApp({ + methods: { + showAdvice(advice) { + alert(advice) + } + } + }) + + app.component('advice-component', { + data() { + return { + adviceText: 'Some advice' + } + }, + template: ` +
+ + +
+ ` + }) + ``` + +- **See also:** + - [`emits` option](./options-data.html#emits) + - [Emitting a Value With an Event](../guide/component-basics.html#emitting-a-value-with-an-event) + +## \$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. + +## \$nextTick + +- **Arguments:** + + - `{Function} [callback]` + +- **Usage:** + + Defer the callback to be executed after the next DOM update cycle. Use it immediately after you've changed some data to wait for the DOM update. This is the same as the global `Vue.nextTick`, except that the callback's `this` context is automatically bound to the instance calling this method. + +- **Example:** + + ```js + Vue.createApp({ + // ... + methods: { + // ... + example() { + // modify data + this.message = 'changed' + // DOM is not updated yet + this.$nextTick(function() { + // DOM is now updated + // `this` is bound to the current instance + this.doSomethingElse() + }) + } + } + }) + ``` + +- **See also:** [Vue.nextTick](TODO) diff --git a/src/api/options-lifecycle-hooks.md b/src/api/options-lifecycle-hooks.md index 11a2bf0242..1603886de8 100644 --- a/src/api/options-lifecycle-hooks.md +++ b/src/api/options-lifecycle-hooks.md @@ -44,7 +44,7 @@ All lifecycle hooks automatically have their `this` context bound to the instanc Called after the instance has been mounted, where element, passed to `Vue.createApp({}).mount()` is replaced by the newly created `vm.$el`. If the root instance is mounted to an in-document element, `vm.$el` will also be in-document when `mounted` is called. - Note that `mounted` does **not** guarantee that all child components have also been mounted. If you want to wait until the entire view has been rendered, you can use [vm.\$nextTick](TODO) inside of `mounted`: + Note that `mounted` does **not** guarantee that all child components have also been mounted. If you want to wait until the entire view has been rendered, you can use [vm.$nextTick](../api/instance-methods.html#nexttick) inside of `mounted`: ```js mounted() { @@ -81,7 +81,7 @@ All lifecycle hooks automatically have their `this` context bound to the instanc The component's DOM will have been updated when this hook is called, so you can perform DOM-dependent operations here. However, in most cases you should avoid changing state inside the hook. To react to state changes, it's usually better to use a [computed property](./options-data.html#computed) or [watcher](./options-data.html#watch) instead. - Note that `updated` does **not** guarantee that all child components have also been re-rendered. If you want to wait until the entire view has been re-rendered, you can use [vm.\$nextTick](TODO) inside of `updated`: + Note that `updated` does **not** guarantee that all child components have also been re-rendered. If you want to wait until the entire view has been re-rendered, you can use [vm.$nextTick](../api/instance-methods.html#nexttick) inside of `updated`: ```js updated() { diff --git a/src/guide/component-basics.md b/src/guide/component-basics.md index 8d89faddb2..e013f1e5e7 100644 --- a/src/guide/component-basics.md +++ b/src/guide/component-basics.md @@ -226,7 +226,7 @@ When we click on the button, we need to communicate to the parent that it should ``` -Then the child component can emit an event on itself by calling the built-in [**`$emit`** method](TODO:../api/#vm-emit), passing the name of the event: +Then the child component can emit an event on itself by calling the built-in [**`$emit`** method](../api/instance-methods.html#emit), passing the name of the event: ```html