Vue3 深入组件

组件基础

基本示例

JavaScript

// 创建一个 Vue 应用
const app = Vue.createApp({})

// 定义一个名为 button-counter 的新全局组件
app.component('button-counter', {
  data() {
    return {
      count: 0
    }
  },
  template: `
    <button @click="count++">
      You clicked me {{ count }} times.
    </button>`
})

信息

在这里演示的是一个简单的示例，但是在典型的 Vue 应用中，我们使用单文件组件而不是字符串模板。

组件是带有名称的可复用实例，在这个例子中是 <button-counter>。我们可以把这个组件作为一个根实例中的自定义元素来使用：

HTML

<div id="components-demo">
  <button-counter></button-counter>
</div>

JavaScript

app.mount('#components-demo')

因为组件是可复用的实例，所以它们与根实例接收相同的选项，例如 data、computed、watch、methods 以及生命周期钩子等。

组件的复用

可以将组件进行任意次数的复用：

HTML

<div id="components-demo">
  <button-counter></button-counter>
  <button-counter></button-counter>
  <button-counter></button-counter>
</div>

注意当点击按钮时，每个组件都会各自独立维护它的 count。因为每用一次组件，就会有一个它的新实例被创建。

通过 Prop 向子组件传递数据

JavaScript

const app = Vue.createApp({})

app.component('blog-post', {
  props: ['title'],
  template: `<h4>{{ title }}</h4>`
})

app.mount('#blog-post-demo')

HTML

<div id="blog-post-demo" class="demo">
  <blog-post title="My journey with Vue"></blog-post>
  <blog-post title="Blogging with Vue"></blog-post>
  <blog-post title="Why Vue is so fun"></blog-post>
</div>

使用 v-for 渲染组件：

HTML

<div id="blog-posts-demo">
  <blog-post v-for="post in posts" :key="post.id" :title="post.title"></blog-post>
</div>

JavaScript

const App = {
  data() {
    return {
      posts: [
        { id: 1, title: 'My journey with Vue' },
        { id: 2, title: 'Blogging with Vue' },
        { id: 3, title: 'Why Vue is so fun' }
      ]
    }
  }
}

const app = Vue.createApp(App)

app.component('blog-post', {
  props: ['title'],
  template: `<h4>{{ title }}</h4>`
})

app.mount('#blog-posts-demo')

监听子组件事件

HTML

<div id="blog-posts-events-demo" class="demo">
  <div :style="{ fontSize: postFontSize + 'em' }">
    <blog-post
      v-for="post in posts"
      :key="post.id"
      :title="post.title"
      @enlarge-text="postFontSize += 0.1"
    ></blog-post>
  </div>
</div>

JavaScript

const app = Vue.createApp({
  data() {
    return {
      posts: [
        { id: 1, title: 'My journey with Vue'},
        { id: 2, title: 'Blogging with Vue'},
        { id: 3, title: 'Why Vue is so fun'}
      ],
      postFontSize: 1
    }
  }
})

app.component('blog-post', {
  props: ['title'],
  emits: ['enlargeText'],
  template: `
    <div class="blog-post">
      <h4>{{ title }}</h4>
      <button @click="$emit('enlargeText')">
        Enlarge text
      </button>
    </div>
  `
})

app.mount('#blog-posts-events-demo')

父级组件可以像处理原生 DOM 事件一样通过 v-on 或 @ 监听子组件实例的任意事件：

HTML

<blog-post ... @enlarge-text="postFontSize += 0.1"></blog-post>

同时子组件可以通过调用内建的 $emit 方法并传入事件名称来触发一个事件：

HTML

<button @click="$emit('enlargeText')">Enlarge text</button>

最后可以在组件的 emits 选项中列出已抛出的事件（这将允许我们检查组件抛出的所有事件，还可以选择验证它们）：

JavaScript

app.component('blog-post', {
  props: ['title'],
  emits: ['enlargeText']
})

使用事件抛出一个值

如果我们想让 <blog-post> 组件决定它的文本要放大多少。这时可以使用 $emit 的第二个参数来提供这个值：

HTML

<button @click="$emit('enlargeText', 0.1)">
  Enlarge text
</button>

然后当在父级组件监听这个事件的时候，我们可以通过 $event 访问到被抛出的这个值：

HTML

<blog-post ... @enlarge-text="postFontSize += $event"></blog-post>

或者，如果这个事件处理函数是一个方法：

HTML

<blog-post ... @enlarge-text="onEnlargeText"></blog-post>

那么这个值将会作为第一个参数传入这个方法：

JavaScript

methods: {
  onEnlargeText(enlargeAmount) {
    this.postFontSize += enlargeAmount
  }
}

在组件上使用 v-model

v-model 本质上不过是语法糖，在自定义组件中：

HTML

<component v-model="searchText"></component>

以上写法相当于：

HTML

<component :model-value="searchText" @update:model-value="searchText = $event"></component>

从上面也可以看出，在自定义组件中 v-model 默认绑定的是 modelValue 属性，监听的是 update:modelValue 事件。

JavaScript

app.component('custom-input', {
  props: ['modelValue'],
  emits: ['update:modelValue'],
  template: `
    <input :value="modelValue" @input="$emit('update:modelValue', $event.target.value)">
  `
})

HTML

<custom-input v-model="searchText"></custom-input>

实际上我们还可以给 v-model 指定一个参数，来明确指出其双向绑定的属性：

JavaScript

app.component('custom-input', {
  props: ['context'],
  emits: ['update:context'],
  template: `<input :value="context" @input="$emit('update:context', $event.target.value)">`
})

HTML

<custom-input v-model:context="searchText"></custom-input>

也可以结合使用计算属性，并在 set 方法中调用 $emit：

JavaScript

app.component('custom-input', {
  props: ['context'],
  emits: ['update:context'],
  template: `<input v-model="contextProp">`,
  computed: {
    contextProp: {
      get() {
        return this.context
      },
      set(value) {
        this.$emit('update:context', value)
      }
    }
  }
})

也可以在单个组件实例上创建多个 v-model 绑定：

HTML

<user-name
  v-model:first-name="firstName"
  v-model:last-name="lastName"
></user-name>

JavaScript

app.component('user-name', {
  props: {
    firstName: String,
    lastName: String
  },
  emits: ['update:firstName', 'update:lastName'],
  template: `
    <input 
      type="text"
      :value="firstName"
      @input="$emit('update:firstName', $event.target.value)">

    <input
      type="text"
      :value="lastName"
      @input="$emit('update:lastName', $event.target.value)">
  `
})

通过插槽分发内容

和 HTML 元素一样，我们经常需要向一个组件传递内容，像这样：

HTML

<alert-box>
  Something bad happened.
</alert-box>

可能会渲染出这样的东西：

Error! Something bad happened.

这可以通过使用 Vue 的自定义 <slot> 元素来实现：

JavaScript

app.component('alert-box', {
  template: `
    <div class="demo-alert-box">
      <strong>Error!</strong>
      <slot></slot>
    </div>
  `
})

动态组件

CSS

.demo {
  font-family: sans-serif;
  border: 1px solid #eee;
  border-radius: 2px;
  padding: 20px 30px;
  margin-top: 1em;
  margin-bottom: 40px;
  user-select: none;
  overflow-x: auto;
}

.tab-button {
  padding: 6px 10px;
  border-top-left-radius: 3px;
  border-top-right-radius: 3px;
  border: 1px solid #ccc;
  cursor: pointer;
  background: #f0f0f0;
  margin-bottom: -1px;
  margin-right: -1px;
}

.tab-button:hover {
  background: #e0e0e0;
}

.tab-button.active {
  background: #e0e0e0;
}

.demo-tab {
  border: 1px solid #ccc;
  padding: 10px;
}

HTML

<div id="dynamic-component-demo" class="demo">
  <button
     v-for="tab in tabs"
     v-bind:key="tab"
     v-bind:class="['tab-button', { active: currentTab === tab }]"
     v-on:click="currentTab = tab"
   >
    {{ tab }}
  </button>
  <component v-bind:is="currentTabComponent" class="tab"></component>
</div>

JavaScript

const app = Vue.createApp({
  data() {
    return {
      currentTab: 'Home',
      tabs: ['Home', 'Posts', 'Archive']
    }
  },
  computed: {
    currentTabComponent() {
      return 'tab-' + this.currentTab.toLowerCase()
    }
  }
})

app.component('tab-home', {
  template: `<div class="demo-tab">Home component</div>`
})

app.component('tab-posts', {
  template: `<div class="demo-tab">Posts component</div>`
})

app.component('tab-archive', {
  template: `<div class="demo-tab">Archive component</div>`
})

app.mount('#dynamic-component-demo')

上述例子是通过 Vue 的 <component> 元素加一个特殊的 is attribute 实现的：

HTML

<!-- component 会在 `currentTabComponent` 改变时被替换为对应的组件 -->
<component :is="currentTabComponent"></component>

组件注册

组件名

强烈推荐遵循 W3C 规范来给自定义标签命名：

全部小写
包含连字符 (及：即有多个单词与连字符符号连接)

组件名大小写

在字符串模板或单文件组件中定义组件时，定义组件名的方式有两种：

使用 kebab-case：

JavaScript

app.component('my-component-name', {
  /* ... */
})

当使用 kebab-case (短横线分隔命名) 定义一个组件时，你在引用这个自定义元素时也必须使用 kebab-case，例如 <my-component-name>。

使用 PascalCase：

JavaScript

app.component('MyComponentName', {
  /* ... */
})

当使用 PascalCase (首字母大写命名) 定义一个组件时，你在引用这个自定义元素时两种命名法都可以使用。也就是说 <my-component-name> 和 <MyComponentName> 都是可接受的。注意，尽管如此，直接在 DOM (即非字符串的模板) 中使用时只有 kebab-case 是有效的。

全局注册

用 app.component 来创建组件：

JavaScript

Vue.createApp({...}).component('my-component-name', {
  // ... 选项 ...
})

这些组件是全局注册的。也就是说它们在注册之后可以用在任何新创建的组件实例的模板中。比如：

JavaScript

const app = Vue.createApp({})

app.component('component-a', {
  /* ... */
})
app.component('component-b', {
  /* ... */
})
app.component('component-c', {
  /* ... */
})

app.mount('#app')

HTML

<div id="app">
  <component-a></component-a>
  <component-b></component-b>
  <component-c></component-c>
</div>

在所有子组件中也是如此，也就是说这三个组件在各自内部也都可以相互使用。

局部注册

全局注册往往是不够理想的。比如，如果你使用一个像 webpack 这样的构建系统，全局注册所有的组件意味着即便你已经不再使用其中一个组件了，它仍然会被包含在最终的构建结果中。这造成了用户下载的 JavaScript 的无谓的增加。

在这些情况下，你可以通过一个普通的 JavaScript 对象来定义组件：

JavaScript

const ComponentA = {
  /* ... */
}
const ComponentB = {
  /* ... */
}
const ComponentC = {
  /* ... */
}

然后在 components 选项中定义你想要使用的组件：

JavaScript

const app = Vue.createApp({
  components: {
    'component-a': ComponentA,
    'component-b': ComponentB
  }
})

对于 components 对象中的每个 property 来说，其 property 名就是自定义元素的名字，其 property 值就是这个组件的选项对象。

注意局部注册的组件在其子组件中不可用。例如，如果你希望 ComponentA 在 ComponentB 中可用，则你需要这样写：

JavaScript

const ComponentA = {
  /* ... */
}

const ComponentB = {
  components: {
    'component-a': ComponentA
  }
  // ...
}

或者如果你通过 Babel 和 webpack 使用 ES2015 模块，那么代码看起来像这样：

JavaScript

import ComponentA from './ComponentA.vue'

export default {
  components: {
    ComponentA
  }
  // ...
}

注意在 ES2015+ 中，在对象中放一个类似 ComponentA 的变量名其实是 ComponentA: ComponentA 的缩写，即这个变量名同时是：

用在模板中的自定义元素的名称
包含了这个组件选项的变量名

模块系统

如果你没有通过 import/require 使用一个模块系统，也许可以暂且跳过这个章节。如果你使用了，那么我们会为你提供一些特殊的使用说明和注意事项。

在模块系统中局部注册

如果你还在阅读，说明你使用了诸如 Babel 和 webpack 的模块系统。在这些情况下，我们推荐创建一个 components 目录，并将每个组件放置在其各自的文件中。

然后你需要在局部注册之前导入每个你想使用的组件。例如，假设在 ComponentB.js 或 ComponentB.vue 文件中：

JavaScript

import ComponentA from './ComponentA'
import ComponentC from './ComponentC'

export default {
  components: {
    ComponentA,
    ComponentC
  }
  // ...
}

现在 ComponentA 和 ComponentC 都可以在 ComponentB 的模板中使用了。

Props

Prop 类型

可以以字符串数组形式列出的 prop：

JavaScript

props: ['title', 'likes', 'isPublished', 'commentIds', 'author']

还可以以对象形式列出 prop，这些 property 的名称和值分别是 prop 各自的名称和类型：

JavaScript

props: {
  title: String,
  likes: Number,
  isPublished: Boolean,
  commentIds: Array,
  author: Object,
  callback: Function,
  contactsPromise: Promise // 或任何其他构造函数
}

类型可以是下列原生构造函数中的一个：

String
Number
Boolean
Array
Object
Date
Function
Symbol

此外，还可以是一个自定义的构造函数，并且通过 instanceof 来进行检查确认。例如，给定下列现成的构造函数：

JavaScript

function Person(firstName, lastName) {
  this.firstName = firstName
  this.lastName = lastName
}

可以使用：

JavaScript

app.component('blog-post', {
  props: {
    author: Person
  }
})

来验证 author prop 的值是否是通过 new Person 创建的。

单向数据流

所有的 prop 都使得其父子 prop 之间形成了一个单向下行绑定：父级 prop 的更新会向下流动到子组件中，但是反过来则不行。

提示

在 JavaScript 中对象和数组是通过引用传入的，所以对于一个数组或对象类型的 prop 来说，在子组件中改变这个对象或数组本身将会影响到父组件的状态，且 Vue 无法为此向你发出警告。作为一个通用规则，应该避免修改任何 prop，包括对象和数组，因为这种做法无视了单向数据绑定，且可能会导致意料之外的结果。

Prop 验证

JavaScript

app.component('my-component', {
  props: {
    // 基础的类型检查 (`null` 和 `undefined` 值会通过任何类型验证)
    propA: Number,
    // 多个可能的类型
    propB: [String, Number],
    // 必填的字符串
    propC: {
      type: String,
      required: true
    },
    // 带有默认值的数字
    propD: {
      type: Number,
      default: 100
    },
    // 带有默认值的对象
    propE: {
      type: Object,
      // 对象或数组的默认值必须从一个工厂函数返回
      default() {
        return { message: 'hello' }
      }
    },
    // 自定义验证函数
    propF: {
      validator(value) {
        // 这个值必须与下列字符串中的其中一个相匹配
        return ['success', 'warning', 'danger'].includes(value)
      }
    },
    // 具有默认值的函数
    propG: {
      type: Function,
      // 与对象或数组的默认值不同，这不是一个工厂函数——这是一个用作默认值的函数
      default() {
        return 'Default function'
      }
    }
  }
})

当 prop 验证失败的时候，(开发环境构建版本的) Vue 将会产生一个控制台的警告。

注意 prop 会在一个组件实例创建之前进行验证，所以实例的 property (如 data、computed 等) 在 default 或 validator 函数中是不可用的。

Prop 的大小写命名

HTML 中的 attribute 名是大小写不敏感的，所以浏览器会把所有大写字符解释为小写字符。这意味着当你使用 DOM 中的模板时，camelCase (驼峰命名法) 的 prop 名需要使用其等价的 kebab-case (短横线分隔命名) 命名。

JavaScript

const app = Vue.createApp({})

app.component('blog-post', {
  // 在 JavaScript 中使用 camelCase
  props: ['postTitle'],
  template: '<h3>{{ postTitle }}</h3>'
})

HTML

<!-- 在 HTML 中使用 kebab-case -->
<blog-post post-title="hello!"></blog-post>

非 Prop 的 Attribute

一个非 prop 的 attribute 是指传向一个组件，但是该组件并没有相应 props 或 emits 定义的 attribute。常见的示例包括 class、style 和 id attribute。可以通过 $attrs property 访问那些 attribute。

Attribute 继承

当组件返回单个根节点时，非 prop 的 attribute 将自动添加到根节点的 attribute 中。例如，在 date-picker 组件的实例中：

JavaScript

app.component('date-picker', {
  template: `
    <div class="date-picker">
      <input type="datetime-local" />
    </div>
  `
})

如果我们需要通过 data-status attribute 定义 <date-picker> 组件的状态，它将应用于根节点 (即 div.date-picker)。

HTML

<!-- 具有非 prop 的 attribute 的 date-picker 组件-->
<date-picker data-status="activated"></date-picker>

<!-- 渲染后的 date-picker 组件 -->
<div class="date-picker" data-status="activated">
  <input type="datetime-local" />
</div>

同样的规则也适用于事件监听器：

HTML

<date-picker @change="submitChange"></date-picker>

JavaScript

app.component('date-picker', {
  created() {
    console.log(this.$attrs) // { onChange: () => {}  }
  }
})

当一个具有 change 事件的 HTML 元素作为 date-picker 的根元素时，这可能会有帮助。

JavaScript

app.component('date-picker', {
  template: `
    <select>
      <option value="1">Yesterday</option>
      <option value="2">Today</option>
      <option value="3">Tomorrow</option>
    </select>
  `
})

在这种情况下，change 事件监听器将从父组件传递到子组件，它将在原生 <select> 的 change 事件上触发。我们不需要显式地从 date-picker 发出事件：

HTML

<div id="date-picker" class="demo">
  <date-picker @change="showChange"></date-picker>
</div>

JavaScript

const app = Vue.createApp({
  methods: {
    showChange(event) {
      console.log(event.target.value) // 将打印所选选项的值
    }
  }
})

禁用 Attribute 继承

如果你不希望组件的根元素继承 attribute，可以在组件的选项中设置 inheritAttrs: false。

禁用 attribute 继承的常见场景是需要将 attribute 应用于根节点之外的其他元素。

通过将 inheritAttrs 选项设置为 false，你可以使用组件的 $attrs property 将 attribute 应用到其它元素上，该 property 包括组件 props 和 emits property 中未包含的所有属性 (例如，class、style、v-on 监听器等)。

使用上一节中的 date-picker 组件示例，如果需要将所有非 prop 的 attribute 应用于 input 元素而不是根 div 元素，可以使用 v-bind 缩写来完成。

JavaScript

app.component('date-picker', {
  inheritAttrs: false,
  template: `
    <div class="date-picker">
      <input type="datetime-local" v-bind="$attrs" />
    </div>
  `
})

有了这个新配置，data-status attribute 将应用于 input 元素！

HTML

<!-- date-picker 组件使用非 prop 的 attribute -->
<date-picker data-status="activated"></date-picker>

<!-- 渲染后的 date-picker 组件 -->
<div class="date-picker">
  <input type="datetime-local" data-status="activated" />
</div>

多个根节点上的 Attribute 继承

与单个根节点组件不同，具有多个根节点的组件不具有自动 attribute fallthrough（隐式贯穿）行为。如果未显式绑定 $attrs，将发出运行时警告。

HTML

<custom-layout id="custom-layout" @click="changeValue"></custom-layout>

JavaScript

// 这将发出警告
app.component('custom-layout', {
  template: `
    <header>...</header>
    <main>...</main>
    <footer>...</footer>
  `
})

// 没有警告，$attrs 被传递到 <main> 元素
app.component('custom-layout', {
  template: `
    <header>...</header>
    <main v-bind="$attrs">...</main>
    <footer>...</footer>
  `
})

自定义事件

事件名

与组件和 prop 一样，事件名提供了自动的大小写转换。如果在子组件中触发一个以 camelCase (驼峰式命名) 命名的事件，你将可以在父组件中添加一个 kebab-case (短横线分隔命名) 的监听器。

JavaScript

this.$emit('myEvent')

HTML

<my-component @my-event="doSomething"></my-component>

定义自定义事件

可以通过 emits 选项在组件上定义发出的事件。

JavaScript

app.component('custom-form', {
  emits: ['inFocus', 'submit']
})

当在 emits 选项中定义了原生事件 (如 click) 时，将使用组件中的事件替代原生事件侦听器。

信息

建议定义所有发出的事件，以便更好地记录组件应该如何工作。

验证抛出的事件

要添加验证，请为事件分配一个函数，该函数接收传递给 $emit 调用的参数，并返回一个布尔值以指示事件是否有效。

JavaScript

app.component('custom-form', {
  emits: {
    // 没有验证
    click: null,

    // 验证 submit 事件
    submit: ({ email, password }) => {
      if (email && password) {
        return true
      } else {
        console.warn('Invalid submit event payload!')
        return false
      }
    }
  },
  methods: {
    submitForm(email, password) {
      this.$emit('submit', { email, password })
    }
  }
})

处理 `v-model` 修饰符

v-model 的修饰符默认通过 modelModifiers prop 提供给组件实例。

HTML

<my-component v-model.upper-case="myText"></my-component>

JavaScript

app.component('my-component', {
  props: {
    modelValue: String,
    modelModifiers: { default: () => ({}) }
  },
  emits: ['update:modelValue'],
  template: `
    <input type="text"
      :value="modelValue"
      @input="$emit('update:modelValue', $event.target.value)">
  `,
  created() {
    console.log(this.modelModifiers) // {upper-case: true}
  }
})

在以上示例中，我们为 modelModifiers prop 指定了一个空对象作为默认值，否则在未指定修饰符的情况下 modelModifiers 将为 undefined。

在组件的 created 生命周期钩子触发时，modelModifiers prop 会包含所有已指定的修饰符，并且 modelModifiers prop 的顺序将保持与修饰符申明的顺序一致。

对于带参数的 v-model 绑定，生成的 prop 名称将为 arg + "Modifiers"：

HTML

<my-component v-model:description.capitalize="myText"></my-component>

JavaScript

app.component('my-component', {
  props: ['description', 'descriptionModifiers'],
  emits: ['update:description'],
  template: `
    <input type="text"
      :value="description"
      @input="$emit('update:description', $event.target.value)">
  `,
  created() {
    console.log(this.descriptionModifiers) // { capitalize: true }
  }
})

Vue3 深入组件 ​

组件基础 ​

基本示例 ​

组件的复用 ​

通过 Prop 向子组件传递数据 ​

监听子组件事件 ​

使用事件抛出一个值 ​

在组件上使用 v-model ​

通过插槽分发内容 ​

动态组件 ​

组件注册 ​

组件名 ​

组件名大小写 ​

全局注册 ​

局部注册 ​

模块系统 ​

在模块系统中局部注册 ​

Props ​

Prop 类型 ​

单向数据流 ​

Prop 验证 ​

Prop 的大小写命名 ​

非 Prop 的 Attribute ​

Attribute 继承 ​

禁用 Attribute 继承 ​

多个根节点上的 Attribute 继承 ​

自定义事件 ​

事件名 ​

定义自定义事件 ​

验证抛出的事件 ​

处理 v-model 修饰符 ​

Vue3 深入组件

组件基础

基本示例

组件的复用

通过 Prop 向子组件传递数据

监听子组件事件

使用事件抛出一个值

在组件上使用 v-model

通过插槽分发内容

动态组件

组件注册

组件名

组件名大小写

全局注册

局部注册

模块系统

在模块系统中局部注册

Props

Prop 类型

单向数据流

Prop 验证

Prop 的大小写命名

非 Prop 的 Attribute

Attribute 继承

禁用 Attribute 继承

多个根节点上的 Attribute 继承

自定义事件

事件名

定义自定义事件

验证抛出的事件

处理 `v-model` 修饰符