Vue 3 深入组件笔记

组件注册 | Vue.js 组件基础 | Vue.js

DOM 模板解析注意事项

大小写区分

HTML 标签和属性名称是不分大小写的，所以浏览器会把任何大写的字符解释为小写。这意味着当你使用 DOM 内的模板时，无论是 PascalCase 形式的组件名称、camelCase 形式的 prop 名称还是 v-on 的事件名称，都需要转换为相应等价的 kebab-case (短横线连字符) 形式

闭合标签

然而在 DOM 模板中，我们必须显式地写出关闭标签：

<my-component></my-component>

元素位置限制#

某些 HTML 元素对于放在其中的元素类型有限制，例如 <ul>，<ol>，<table> 和 <select>，相应的，某些元素仅在放置于特定元素中时才会显示，例如 <li>，<tr> 和 <option>。

这将导致在使用带有此类限制元素的组件时出现问题。例如：

<table>
  <blog-post-row></blog-post-row>
</table>

自定义的组件 <blog-post-row> 将作为无效的内容被忽略，因而在最终呈现的输出中造成错误。我们可以使用特殊的 is attribute 作为一种解决方案：

<table>
  <tr is="vue:blog-post-row"></tr>
</table>

组件注册

全局注册虽然很方便，但有以下几个问题：

1. 全局注册，但并没有被使用的组件无法在生产打包时被自动移除 (也叫“tree-shaking”)。如果你全局注册了一个组件，即使它并没有被实际使用，它仍然会出现在打包后的 JS 文件中。
2. 全局注册在大型项目中使项目的依赖关系变得不那么明确。在父组件中使用子组件时，不太容易定位子组件的实现。和使用过多的全局变量一样，这可能会影响应用长期的可维护性。

相比之下，局部注册的组件需要在使用它的父组件中显式导入，并且只能在该父组件中使用。它的优点是使组件之间的依赖关系更加明确，并且对 tree-shaking 更加友好。

Prop声明

对象声明式

// 使用 <script setup>
defineProps({
  title: String,
  likes: Number
})

非setup声明式

// 非 <script setup>
export default {
  props: {
    title: String,
    likes: Number
  }
}

补充细节：

• 所有 prop 默认都是可选的，除非声明了 required: true。
• 除 Boolean 外的未传递的可选 prop 将会有一个默认值 undefined。
• Boolean 类型的未传递 prop 将被转换为 false。这可以通过为它设置 default 来更改——例如：设置为 default: undefined 将与非布尔类型的 prop 的行为保持一致。
• 如果声明了 default 值，那么在 prop 的值被解析为 undefined 时，无论 prop 是未被传递还是显式指明的 undefined，都会改为 default 值。

当 prop 的校验失败后，Vue 会抛出一个控制台警告 (在开发模式下)。

如果使用了基于类型的 prop 声明 ，Vue 会尽最大努力在运行时按照 prop 的类型标注进行编译。举例来说，defineProps<{ msg: string }> 会被编译为 { msg: { type: String, required: true }}。

运行时类型检查

校验选项中的 type 可以是下列这些原生构造函数：

• String
• Number
• Boolean
• Array
• Object
• Date
• Function
• Symbol

另外，type 也可以是自定义的类或构造函数，Vue 将会通过 instanceof 来检查类型是否匹配。例如下面这个类：

class Person {
  constructor(firstName, lastName) {
    this.firstName = firstName
    this.lastName = lastName
  }
}

你可以将其作为一个 prop 的类型：

defineProps({
  author: Person
})

TS声明式

<script setup lang="ts">
defineProps<{
  title?: string
  likes?: number
}>()
</script>

参数传递

<MyComponent greeting-message="hello" />

对于组件名我们推荐使用 PascalCase，因为这提高了模板的可读性，能帮助我们区分 Vue 组件和原生 HTML 元素。然而对于传递 props 来说，使用 camelCase 并没有太多优势，因此我们推荐更贴近 HTML 的书写风格。

使用一个对象绑定多个 prop

如果你想要将一个对象的所有属性都当作 props 传入，你可以使用没有参数的 v-bind，即只使用 v-bind 而非 :prop-name，类似于对象的自动解构并声明。例如，这里有一个 post 对象：

const post = {
  id: 1,
  title: 'My Journey with Vue'
}

以及下面的模板：

<BlogPost v-bind="post" />

而这实际上等价于：

<BlogPost :id="post.id" :title="post.title" />

单向数据流

导致你想要更改一个 prop 的需求通常来源于以下两种场景：

1. prop 被用于传入初始值；而子组件想在之后将其作为一个局部数据属性。在这种情况下，最好是新定义一个局部数据属性，从 props 上获取初始值即可：

   const props = defineProps(['initialCounter'])
   
   // 计数器只是将 props.initialCounter 作为初始值
   // 像下面这样做就使 prop 和后续更新无关了
   const counter = ref(props.initialCounter)

2. 需要对传入的 prop 值做进一步的转换。在这种情况中，最好是基于该 prop 值定义一个计算属性：

   const props = defineProps(['size'])
   
   // 该 prop 变更时计算属性也会自动更新
   const normalizedSize = computed(() => props.size.trim().toLowerCase())

事件校验

和对 props 添加类型校验的方式类似，所有触发的事件也可以使用对象形式来描述。

要为事件添加校验，那么事件可以被赋值为一个函数，接受的参数就是抛出事件时传入 emit 的内容，返回一个布尔值来表明事件是否合法。

<script setup>
const emit = defineEmits({
  // 没有校验
  click: null,

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

function submitForm(email, password) {
  emit('submit', { email, password })
}
</script>

透传 Attributes

当一个组件以单个元素为根作渲染时，透传的 attribute 会自动被添加到根元素上。同时对class、style和v-on都会做合并。

深层组件继承

有些情况下一个组件会在根节点上渲染另一个组件。例如，我们重构一下 <MyButton>，让它在根节点上渲染 <BaseButton>：

<!-- <MyButton/> 的模板，只是渲染另一个组件 -->
<BaseButton />

此时 <MyButton> 接收的透传 attribute 会直接继续传给 <BaseButton>。

请注意：

1. 透传的 attribute 不会包含 <MyButton> 上声明过的 props 或是针对 emits 声明事件的 v-on 侦听函数，换句话说，声明过的 props 和侦听函数被 <MyButton>“消费”了（v-on不参与多级透传）。
2. 透传的 attribute 若符合声明，也可以作为 props 传入 <BaseButton>。

禁用 Attributes 继承 :star:

如果你不想要一个组件自动地继承 attribute，你可以在组件选项中设置 inheritAttrs: false。

如果你使用了 <script setup>，你需要一个额外的 <script> 块来书写这个选项声明：

<script>
// 使用普通的 <script> 来声明选项
export default {
  inheritAttrs: false
}
</script>

<script setup>
// ...setup 部分逻辑
</script>

最常见的需要禁用 attribute 继承的场景就是 attribute 需要应用在根节点以外的其他元素上。通过设置 inheritAttrs 选项为 false，你可以完全控制透传进来的 attribute 被如何使用。

这些透传进来的 attribute 可以在模板的表达式中直接用 $attrs 访问到。

<span>Fallthrough attribute: {{ $attrs }}</span>

这个 $attrs 对象包含了除组件所声明的 props 和 emits 之外的所有其他 attribute，例如 class，style，v-on 监听器等等。

有几点需要注意：

• 和 props 有所不同，透传 attributes 在 JavaScript 中保留了它们原始的大小写，所以像 foo-bar 这样的一个 attribute 需要通过 $attrs['foo-bar'] 来访问。
• 像 @click 这样的一个 v-on 事件监听器将在此对象下被暴露为一个函数 $attrs.onClick。

现在我们要再次使用一下之前小节中的 <MyButton> 组件例子。有时候我们可能为了样式，需要在 <button> 元素外包装一层 <div>：

<div class="btn-wrapper">
  <button class="btn">click me</button>
</div>

我们想要所有像 class 和 v-on 监听器这样的透传 attribute 都应用在内部的 <button> 上而不是外层的 <div> 上。我们可以通过设定 inheritAttrs: false 和使用 v-bind="$attrs" 来实现：

<div class="btn-wrapper">
  <button class="btn" v-bind="$attrs">click me</button>
</div>

小提示：没有参数的 v-bind 会将一个对象的所有属性都作为 attribute 应用到目标元素上。

如果 <CustomLayout> 有下面这样的多根节点模板，由于 Vue 不知道要将 attribute 透传到哪里，所以会抛出一个警告。

如果 $attrs 被显式绑定，则不会有警告：

<header>...</header>
<main v-bind="$attrs">...</main>
<footer>...</footer>

在脚本中访问 Attributes

如果需要，你可以在 <script setup> 中使用 useAttrs() API 来访问一个组件的所有透传 attribute：

<script setup>
import { useAttrs } from 'vue'

const attrs = useAttrs()
</script>

如果没有使用 <script setup>，attrs 会作为 setup() 上下文对象的一个属性暴露：

export default {
  setup(props, ctx) {
    // 透传 attribute 被暴露为 ctx.attrs
    console.log(ctx.attrs)
  }
}

需要注意的是，**虽然这里的 attrs 对象总是反映为最新的透传 attribute，但它并不是响应式的 (考虑到性能因素)。你不能通过侦听器去监听它的变化。**如果你需要响应性，可以使用 prop。或者你也可以使用 onUpdated() 使得在每次更新时结合最新的 attrs 执行副作用。

插槽 Slot

插槽内容无法访问子组件的数据。Vue 模板中的表达式只能访问其定义时所处的作用域，这和 JavaScript 的词法作用域规则是一致的。换言之：

父组件模板中的表达式只能访问父组件的作用域；子组件模板中的表达式只能访问子组件的作用域。

默认内容

在外部没有提供任何内容的情况下，可以为插槽指定默认内容。比如有这样一个 <SubmitButton> 组件：

<button type="submit">
  <slot></slot>
</button>

如果我们想在父组件没有提供任何插槽内容时在 <button> 内渲染“Submit”，只需要将“Submit”写在 <slot> 标签之间来作为默认内容：

<button type="submit">
  <slot>
    Submit <!-- 默认内容 -->
  </slot>
</button>

现在，当我们在父组件中使用 <SubmitButton> 且没有提供任何插槽内容时：

<SubmitButton />

“Submit”将会被作为默认内容渲染：

<button type="submit">Submit</button>

但如果我们提供了插槽内容：

<SubmitButton>Save</SubmitButton>

那么被显式提供的内容会取代默认内容：

<button type="submit">Save</button>

具名插槽

有时在一个组件中包含多个插槽出口是很有用的。举例来说，在一个 <BaseLayout> 组件中，有如下模板：

template

<div class="container">
  <header>
    <!-- 标题内容放这里 -->
  </header>
  <main>
    <!-- 主要内容放这里 -->
  </main>
  <footer>
    <!-- 底部内容放这里 -->
  </footer>
</div>

对于这种场景，<slot> 元素可以有一个特殊的 attribute name，用来给各个插槽分配唯一的 ID，以确定每一处要渲染的内容：

template

<div class="container">
  <header>
    <slot name="header"></slot>
  </header>
  <main>
    <slot></slot>
  </main>
  <footer>
    <slot name="footer"></slot>
  </footer>
</div>

这类带 name 的插槽被称为具名插槽 (named slots)。没有提供 name 的 <slot> 出口会隐式地命名为“default”。

在父组件中使用 <BaseLayout> 时，我们需要一种方式将多个插槽内容传入到各自目标插槽的出口。此时就需要用到具名插槽了：

要为具名插槽传入内容，我们需要使用一个含 v-slot 指令的 <template> 元素，并将目标插槽的名字传给该指令：

template

<BaseLayout>
  <template v-slot:header>
    <!-- header 插槽的内容放这里 -->
  </template>
</BaseLayout>

v-slot 有对应的简写 #，因此 <template v-slot:header> 可以简写为 <template #header>。其意思就是“将这部分模板片段传入子组件的 header 插槽中”。

下面我们给出完整的、向 <BaseLayout> 传递插槽内容的代码，指令均使用的是缩写形式：

template

<BaseLayout>
  <template #header>
    <h1>Here might be a page title</h1>
  </template>

  <template #default>
    <p>A paragraph for the main content.</p>
    <p>And another one.</p>
  </template>

  <template #footer>
    <p>Here's some contact info</p>
  </template>
</BaseLayout>

当一个组件同时接收默认插槽和具名插槽时，所有位于顶级的非 <template> 节点都被隐式地视为默认插槽的内容。所以上面也可以写成：

template

<BaseLayout>
  <template #header>
    <h1>Here might be a page title</h1>
  </template>

  <!-- 隐式的默认插槽 -->
  <p>A paragraph for the main content.</p>
  <p>And another one.</p>

  <template #footer>
    <p>Here's some contact info</p>
  </template>
</BaseLayout>

现在 <template> 元素中的所有内容都将被传递到相应的插槽。最终渲染出的 HTML 如下：

html

<div class="container">
  <header>
    <h1>Here might be a page title</h1>
  </header>
  <main>
    <p>A paragraph for the main content.</p>
    <p>And another one.</p>
  </main>
  <footer>
    <p>Here's some contact info</p>
  </footer>
</div>

在演练场中尝试一下

使用 JavaScript 函数来类比可能更有助于你来理解具名插槽：

js

// 传入不同的内容给不同名字的插槽
BaseLayout({
  header: `...`,
  default: `...`,
  footer: `...`
})

// <BaseLayout> 渲染插槽内容到对应位置
function BaseLayout(slots) {
  return `<div class="container">
      <header>${slots.header}</header>
      <main>${slots.default}</main>
      <footer>${slots.footer}</footer>
    </div>`
}

动态插槽名称

动态指令参数在 v-slot 上也是有效的，即可以定义下面这样的动态插槽名：

<base-layout>
  <template v-slot:[dynamicSlotName]>
    ...
  </template>

  <!-- 缩写为 -->
  <template #[dynamicSlotName]>
    ...
  </template>
</base-layout>

注意这里的表达式和动态指令参数受相同的语法限制。

作用域插槽

提供伏组件插槽访问子组件的能力。

<!-- <MyComponent> 的模板 -->
<div>
  <slot :text="greetingMessage" :count="1"></slot>
</div>

当需要接收插槽 props 时，默认插槽和具名插槽的使用方式有一些小区别。下面我们将先展示默认插槽如何接受 props，通过子组件标签上的 v-slot 指令，直接接收到了一个插槽 props 对象：

<MyComponent v-slot="slotProps">
  {{ slotProps.text }} {{ slotProps.count }}
</MyComponent>

可以理解为JSX内的props组件的运作方式。

具名作用域插槽

具名作用域插槽的工作方式也是类似的，插槽 props 可以作为 v-slot 指令的值被访问到：v-slot:name="slotProps"。当使用缩写时是这样：

<MyComponent>
  <template #header="headerProps">
    {{ headerProps }}
  </template>

  <template #default="defaultProps">
    {{ defaultProps }}
  </template>

  <template #footer="footerProps">
    {{ footerProps }}
  </template>
</MyComponent>

向具名插槽中传入 props：

<slot name="header" message="hello"></slot>

注意插槽上的 name 是一个 Vue 特别保留的 attribute，不会作为 props 传递给插槽。因此最终 headerProps 的结果是 { message: 'hello' }。

具名插槽与某人插槽不可嵌套混用，正确案例：

<template>
  <MyComponent>
    <!-- 使用显式的默认插槽 -->
    <template #default="{ message }">
      <p>{{ message }}</p>
    </template>

    <template #footer>
      <p>Here's some contact info</p>
    </template>
  </MyComponent>
</template>

高级组件案例

将对单个列表元素内容和样式的控制权留给使用它的父组件，即父组件负责单元插槽内的样式逻辑，子组件负责多次渲染的位置和生成方式：

<FancyList :api-url="url" :per-page="10">
  <template #item="{ body, username, likes }">
    <div class="item">
      <p>{{ body }}</p>
      <p>by {{ username }} | {{ likes }} likes</p>
    </div>
  </template>
</FancyList>

<ul>
  <li v-for="item in items">
    <slot name="item" v-bind="item"></slot>
  </li>
</ul>

无渲染组件

组件只包括了逻辑而不需要自己渲染内容，视图输出通过作用域插槽全权交给了消费者组件

<MouseTracker v-slot="{ x, y }">
  Mouse is at: {{ x }}, {{ y }}
</MouseTracker>

依赖注入方式

• prop 透传

• provide&inject

  注入默认值

  // 如果没有祖先组件提供 "message"
  // `value` 会是 "这是默认值"
  const value = inject('message', '这是默认值')

  应用层（app供应）

  import { createApp } from 'vue'
  
  const app = createApp({})
  
  app.provide(/* 注入名 */ 'message', /* 值 */ 'hello!')

和响应式数据配合使用

• 供给方组件内声明，将响应式、变更方法都内聚在供给方组件中

• 可以通过readonly() 来包装提供的值，保护不被注入方更改

  provide('read-only-count', readonly(count))

• 于是乎违背了单向数据流规则

  <!-- 在供给方组件内 -->
  <script setup>
  import { provide, ref } from 'vue'
  
  const location = ref('North Pole')
  
  function updateLocation() {
    location.value = 'South Pole'
  }
  
  provide('location', {
    location,
    updateLocation
  })
  </script>

  <!-- 在注入方组件 -->
  <script setup>
  import { inject } from 'vue'
  
  const { location, updateLocation } = inject('location')
  </script>
  
  <template>
    <button @click="updateLocation">{{ location }}</button>
  </template>

Symbol 方式冲突

我们通常推荐在一个单独的文件中导出这些注入名 Symbol：

// keys.js
export const myInjectionKey = Symbol()

// 在供给方组件中
import { provide } from 'vue'
import { myInjectionKey } from './keys.js'

provide(myInjectionKey, { /*
  要提供的数据
*/ });

// 注入方组件
import { inject } from 'vue'
import { myInjectionKey } from './keys.js'

const injected = inject(myInjectionKey)

TS 标注

import { provide, inject } from 'vue'
import type { InjectionKey } from 'vue'

const key = Symbol() as InjectionKey<string>

provide(key, 'foo') // 若提供的是非字符串值会导致错误

const foo = inject(key) // foo 的类型：string | undefined

建议将注入 key 的类型放在一个单独的文件中，这样它就可以被多个组件导入。

当使用字符串注入 key 时，注入值的类型是 unknown，需要通过泛型参数显式声明

const foo = inject<string>('foo') // 类型：string | undefined

注意注入的值仍然可以是 undefined，因为无法保证提供者一定会在运行时 provide 这个值。

当提供了一个默认值后，这个 undefined 类型就可以被移除：

const foo = inject<string>('foo', 'bar') // 类型：string

如果你确定该值将始终被提供，则还可以强制转换该值：

const foo = inject('foo') as string

异步组件 :star:

1. Promise 加载

   import { defineAsyncComponent } from 'vue'
   
   const AsyncComp = defineAsyncComponent(() => {
     return new Promise((resolve, reject) => {
       // ...从服务器获取组件
       resolve(/* 获取到的组件 */)
     })
   })
   // ... 像使用其他一般组件一样使用 `AsyncComp`

2. 通过ES模块动态导入加载（本身返回Promise，即import()加载）

   import { defineAsyncComponent } from 'vue'
   
   const AsyncComp = defineAsyncComponent(() =>
     import('./components/MyComponent.vue')
   )

3. 全局注册

   app.component('MyComponent', defineAsyncComponent(() =>
     import('./components/MyComponent.vue')
   ))

4. 局部组册

   <script setup>
   import { defineAsyncComponent } from 'vue'
   
   const AdminPage = defineAsyncComponent(() =>
     import('./components/AdminPageComponent.vue')
   )
   </script>
   
   <template>
     <AdminPage />
   </template>

加载错误状态处理

const AsyncComp = defineAsyncComponent({
  // 加载函数
  loader: () => import('./Foo.vue'),

  // 加载异步组件时使用的组件
  loadingComponent: LoadingComponent,
  // 展示加载组件前的延迟时间，默认为 200ms
  delay: 200,

  // 加载失败后展示的组件
  errorComponent: ErrorComponent,
  // 如果提供了一个 timeout 时间限制，并超时了
  // 也会显示这里配置的报错组件，默认值是：Infinity
  timeout: 3000
})

异步组件可以搭配内置的 <Suspense> 组件一起使用，若想了解 <Suspense> 和异步组件之间交互，请参阅 Suspense 章节。