fine tune attrs

Author: yyx990803

src/guide/components/attrs.md

@@ -6,54 +6,10 @@ aside: deep
 
 > This page assumes you've already read the [Components Basics](/guide/essentials/component-basics). Read that first if you are new to components.
 
-A component non-prop attribute is an attribute or event listener that is passed to a component, but is not explicitly declared in [props](./props) or [emits](./events.html#defining-custom-events). Common examples of this include `class`, `style`, and `id` attributes.
-
-These fallthrough attributes can be accessed directly in template expressions as `$attrs`:
-
-```vue-html
-<span>Fallthrough attributes: {{ $attrs }}</span>
-```
-
-<div class="composition-api">
-
-You can also access them in `<script setup>` using the `useAttrs()` API:
-
-```vue
-<script setup>
-import { useAttrs } from 'vue'
-
-const attrs = useAttrs()
-</script>
-```
-
-If not using `<script setup>`, `attrs` will be exposed as a property of the `setup()` context:
-
-```js
-export default {
-  setup(props, ctx) {
-    // fallthrough attributes are exposed as ctx.attrs
-  }
-}
-```
-
-</div>
-
-<div class="options-api">
-
-You can also access them in JavaScript via the `$attrs` instance property:
-
-```js
-export default {
-  created() {
-    console.log(this.$attrs)
-  }
-}
-```
-
-</div>
-
 ## Attribute Inheritance
 
+A "fallthrough attribute" is an attribute or `v-on` event listener that is passed to a component, but is not explicitly declared in the receiving component's [props](./props) or [emits](./events.html#defining-custom-events). Common examples of this include `class`, `style`, and `id` attributes.
+
 When a component renders a single root element, fallthrough attributes will be automatically added to the root element's attributes. For example, given a `<MyButton>` component with the following template:
 
 ```vue-html
@@ -90,14 +46,31 @@ Then the final rendered DOM would now become:
 
 ### `v-on` Listener Inheritance
 
-Same rule applies to the event listeners:
+Same rule applies to `v-on` event listeners:
 
 ```vue-html
 <MyButton @click="onClick" />
 ```
 
 The `click` listener will be added to the root element of `<MyButton>`, i.e. the native `<button>` element. When the native `<button>` is clicked, it will trigger the `onClick` method of the parent component. If the native `<button>` already has a `click` listener bound with `v-on`, then both listeners will trigger.
 
+### Nested Component Inheritance
+
+If a component renders another component as its root node, for example, we refactored `<MyButton>` to render a `<BaseButton>` as its root:
+
+```vue-html
+<!-- template of <MyButton/> that simply renders another component -->
+<BaseButton />
+```
+
+Then the fallthrough attributes received by `<MyButton>` will be automatically forwarded to `<BaseButton>`.
+
+Note that:
+
+1. Forwarded attributes do not include any attributes that are declared as props by `<MyButton>` - in other words, the declared props have been "consumed" by `<MyButton>`.
+
+2. Forwarded attributes may be accepted as props by `<BaseButton>`, if declared by it.
+
 ## Disabling Attribute Inheritance
 
 If you do **not** want a component to automatically inherit attributes, you can set `inheritAttrs: false` in the component's options.
@@ -121,9 +94,15 @@ export default {
 
 </div>
 
-The common scenario for disabling an attribute inheritance is when attributes need to be applied to other elements besides the root node.
+The common scenario for disabling an attribute inheritance is when attributes need to be applied to other elements besides the root node. By setting the `inheritAttrs` option to `false`, you can take full control over where the fallthrough attributes should be applied to.
+
+These fallthrough attributes can be accessed directly in template expressions as `$attrs`:
+
+```vue-html
+<span>Fallthrough attributes: {{ $attrs }}</span>
+```
 
-By setting the `inheritAttrs` option to `false`, you can take full control over where the fallthrough attributes should be applied to. The `$attrs` object includes all attributes not included to component `props` and `emits` properties (e.g., `class`, `style`, `v-on` listeners, etc.).
+The `$attrs` object includes all attributes not included to component `props` and `emits` properties (e.g., `class`, `style`, `v-on` listeners, etc.).
 
 Using our `<MyButton>` component example from the [previous section](#attribute-inheritance) - sometimes we may need to wrap the actual `<button>` element with an extra `<div>` for styling purposes:
 
@@ -141,6 +120,8 @@ We want all fallthrough attributes like `class` and `v-on` listeners to be appli
 </div>
 ```
 
+Remember that [`v-bind` without argument](/guide/essentials/template-syntax.html#dynamically-binding-multiple-attributes) binds every property of an object as attributes to the target element.
+
 ## Attribute Inheritance on Multiple Root Nodes
 
 Unlike single root node components, components with multiple root nodes do not have an automatic attribute fallthrough behavior. If `$attrs` are not bound explicitly, a runtime warning will be issued.
@@ -164,3 +145,44 @@ The warning will be suppressed if `$attrs` is explicitly bound:
 <main v-bind="$attrs">...</main>
 <footer>...</footer>
 ```
+
+## Accessing Fallthrough Attributes in JavaScript
+
+<div class="composition-api">
+
+You can access a component's fallthrough attributes in `<script setup>` using the `useAttrs()` API:
+
+```vue
+<script setup>
+import { useAttrs } from 'vue'
+
+const attrs = useAttrs()
+</script>
+```
+
+If not using `<script setup>`, `attrs` will be exposed as a property of the `setup()` context:
+
+```js
+export default {
+  setup(props, ctx) {
+    // fallthrough attributes are exposed as ctx.attrs
+    console.log(ctx.attrs)
+  }
+}
+```
+
+</div>
+
+<div class="options-api">
+
+You can access a component's fallthrough attributes via the `$attrs` instance property:
+
+```js
+export default {
+  created() {
+    console.log(this.$attrs)
+  }
+}
+```
+
+</div>

src/guide/components/events.md

@@ -2,7 +2,7 @@
 
 > This page assumes you've already read the [Components Basics](/guide/essentials/component-basics). Read that first if you are new to components.
 
-## Event Names
+## Event Name Casing
 
 Like components and props, event names provide an automatic case transformation. If you emit an event from the child component in camel case, you will be able to add a kebab-cased listener in the parent:
 

src/guide/components/props.md

@@ -205,7 +205,7 @@ In the two examples above, we happen to pass string values, but _any_ type of va
 
 ### Binding Multiple Properties Using an Object
 
-If you want to pass all the properties of an object as props, you can use `v-bind` without an argument (`v-bind` instead of `:prop-name`). For example, given a `post` object:
+If you want to pass all the properties of an object as props, you can use [`v-bind` without an argument](/guide/essentials/template-syntax.html#dynamically-binding-multiple-attributes) (`v-bind` instead of `:prop-name`). For example, given a `post` object:
 
 <div class="options-api">