diff --git a/src/api/options-state.md b/src/api/options-state.md index 57fa9077a3..3dc48aead6 100644 --- a/src/api/options-state.md +++ b/src/api/options-state.md @@ -17,9 +17,9 @@ A function that returns the initial reactive state for the component instance. - **Details** - The function is expected to return a plain JavaScript object, which will be made reactive by Vue. After the instance is created, the original data object can be accessed as `this.$data`. The component instance also proxies all the properties found on the data object, so `this.a` will be equivalent to `this.$data.a`. + The function is expected to return a plain JavaScript object, which will be made reactive by Vue. After the instance is created, the reactive data object can be accessed as `this.$data`. The component instance also proxies all the properties found on the data object, so `this.a` will be equivalent to `this.$data.a`. - 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. + All top-level data properties must be included in the returned data object. Adding new properties to `this.$data` is possible, but it is **not** recommended. If the desired value of a property is not yet available then an empty value such as `undefined` or `null` should be included as a placeholder to ensure that Vue knows that the property exists. 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 `this.$data._property`. @@ -83,7 +83,7 @@ Declare the props of a component. - Simple form using an array of strings - Full form using an object where each property key is the name of the prop, and the value is the prop's type (a constructor function) or advanced options. - With object-based syntax, each prop can further defined the following options: + With object-based syntax, each prop can further define the following options: - **`type`**: Can be one of the following native constructors: `String`, `Number`, `Boolean`, `Array`, `Object`, `Date`, `Function`, `Symbol`, any custom constructor function or an array of those. In development mode, Vue will check if a prop's value matches the declared type, and will throw a warning if it doesn't. See [Prop Validation](/guide/components/props.html#prop-validation) for more details. @@ -285,7 +285,7 @@ Declare watch callbacks to be invoked on data change. The `watch` option expects an object where keys are the reactive component instance properties to watch (e.g. properties declared via `data` or `computed`) — and values are the corresponding callbacks. The callback receives the new value and the old value of the watched source. - In addition to a root-level property, The key can also be a simple dot-delimited path, e.g. `a.b.c`. Note that this usage does **not** support complex expressions - only dot-delimited paths are supported. If you need to watch complex data sources, use the imperative [`$watch()`](/api/component-instance.html#watch) API instead. + In addition to a root-level property, the key can also be a simple dot-delimited path, e.g. `a.b.c`. Note that this usage does **not** support complex expressions - only dot-delimited paths are supported. If you need to watch complex data sources, use the imperative [`$watch()`](/api/component-instance.html#watch) API instead. The value can also be a string of a method name (declared via `methods`), or an object that contains additional options. When using the object syntax, the callback should be declared under the `handler` field. Additional options include: @@ -393,7 +393,7 @@ Declare the custom events emitted by the component. The validation function will receive the additional arguments passed to the component's `$emit` call. For example, if `this.$emit('foo', 1)` is called, the corresponding validator for `foo` will receive the argument `1`. The validator function should return a boolean to indicate whether the event arguments are valid. - Note that the `emits` option affects which event listeners received by the component are considered component event listeners vs. native DOM event listeners. A declared event's listener will not be added to the component's root element, and will be removed from the component's `$attrs` object. See [Fallthrough Attributes](/guide/components/attrs.html) for more details. + Note that the `emits` option affects which event listeners are considered component event listeners, rather than native DOM event listeners. The listeners for declared events will be removed from the component's `$attrs` object, so they will not be passed through to the component's root element. See [Fallthrough Attributes](/guide/components/attrs.html) for more details. - **Example** @@ -445,7 +445,7 @@ Declare exposed public properties when the component instance is accessed by a p - **Details** - By default, a component instance exposes all instance properties to the parent when accessed via `$parent`, `$root`, or template refs. This can be undesirable since a component most likely have internal state or methods that should be kept private to avoid tight coupling. + By default, a component instance exposes all instance properties to the parent when accessed via `$parent`, `$root`, or template refs. This can be undesirable, since a component most likely has internal state or methods that should be kept private to avoid tight coupling. The `expose` option expects a list of property name strings. When `expose` is used, only the properties explicitly listed will be exposed on the component's public instance.