必不可少的UI组件一——组件的基础知识

本文由郭凯南同学分享，主要是基于组件库开发的场景，介绍了 Vue 组件开发的基础知识与优秀实践。

前言

很多同学随着自己前端技能的增长，不满足于常规的业务开发，开始想着做一些自己的技术积累。例如学会了 Vue 框架的使用以及如何封装组件之后，想要自己试着开发一套组件库引入到项目中，甚至共享给更多的人使用。但是在这个过程中，往往会遇到许多的问题：

• 组件库工程需要的基础设施改如何搭建，如何实现组件库的构建、提交门禁、测试、文档、发布？
• 对于复杂一些的组件，我在实现的过程中感觉逻辑越来越混乱，代码越来越难以维护，最终难以持续迭代下去。
• 有些组件交互复杂，甚至由多个子组件构成(例如 Form 和 FormItem)，它们之间的通信和状态共享如何处理？感觉缺少思路，无从下手。

磨刀不误砍柴工，对于正处于经验积累阶段的前端同学，或许需要先重温一些基础知识，夯实内功，才能更好地实践。

实践 Vue 组件库的搭建，我们是需要掌握一些前置知识的：

• 一方面是前端工程化相关内容，它们是组件库的地基、脚手架般重要的存在，是整个组件库工程的基础；
• 另一方面是 Vue 组件开发的技巧与优秀实践，它们在实现组件库主体部分时发挥作用，决定了我们的能否实现、能否做好每一个组件。

本章分享的内容侧重于后者，我们将基于组件库开发的场景，介绍一些高频使用的 Vue 框架基础知识与实战技巧，主要内容如下：

• 组件的基本概念；
• 官方主推的组件开发范式：单文件组件与组合式 API；
• 深入组合式 API：响应式 API；
• 深入组合式 API：组件的生命周期；
• 深入组合式 API：组件之间的通信方式；
• 组件开发的优秀实践介绍。

我们在举例时，会尽量贴近当下环境中较新的实践——使用 Vue 的最新版本与 TypeScript。如果读者在阅读过程中对代码示例中的内容感到困惑，可以前往以下文档补充学习：

• Vue 官方文档
• TypeScript 官方文档
• TypeScript 学习指南

组件的基本概念

对于组件库而言，组件的概念是用户界面 UI 中独立的、可重用的部分，用户倾向于多次复用组件，像搭积木一样，将多个组件组合为完整的用户界面。

不过，站在 Vue 框架层面来看，我们先前提到的“组件”的概念其实是 Vue 框架中“组件”概念的子集。对于 Vue 框架而言，万物都是组件——无论是大的用户界面，还是小的功能模块。

任何一个 Vue 应用都可以看做是以 App.vue(入口组件可以叫其他名称) 为根节点的组件树。

既然我们的目标是编写组件库，那么下文将要讲解的基础知识将围绕着以下三个问题展开：

• 应该采用什么样的范式编写 Vue 组件？
• 如何编写组件的内部运行逻辑？
• 如何定义组件的外部交互接口？即处理组件之间的通信问题。

单文件组件与组合式 api

目前，Vue 官方主推的组件实现范式是 单文件组件 与 组合式 API 的结合。下面给出一个典型案例：

<script lang="ts" setup>
import { ref, onMounted } from 'vue'

// 响应式状态
const count = ref(0)

// 更改状态、触发更新的函数
function increment() {
  count.value++
}

// 生命周期钩子
onMounted(() => {
  console.log(`计数器初始值为 ${count.value}。`)
})
</script>

<template>
  <button class="btn" @click="increment">点击了：{{ count }} 次</button>
</template>

<style>
.btn {
  background-color: #c7000b;
}
</style>

如你所见，Vue 的单文件组件是网页开发中 HTML、CSS 和 JavaScript 三种语言经典组合的自然延伸。<template>、<script> 和 <style> 三个块在同一个文件中封装、组合了组件的视图、逻辑和样式。

关于单文件组件的优势与选型理由，Vue 官网给出了非常充分清晰的理由：为什么要使用 SFC。

而 组合式 API 则体现在单文件组件的逻辑部分(<script></script>)，它要求我们使用函数语句而不是声明选项的方式书写 Vue 组件的逻辑部分。在 Vue 3 中，组合式 API 经常配合 <script setup> 语法出现在单文件组件中。

Vue 官网对于组合式 API 的优势也有着充分的说明：为什么要有组合式 API？。

组合式 API 的相比选项式 API 的一大优势，在于可以将相同逻辑关注点的代码聚合为一组，而不用为了同一个逻辑关注点在不同的选项之间来回切换。

我们分享中的演示案例都将采用“单文件模板和组合式 API 结合”的形式，同样推荐大家编写自己的组件库时采纳这种实践。这主要基于以下理由：

• 单文件模板和组合式 API 各自的优势。(参考官方文档中的描述)
• Vue 官方已经针对这样的范式此做了足够的优化，目前足以满足绝大多数应用场景。
• 作为官方主推的一种实践方案，未来也将得到社区最大力度的支持。

组合式 API 和单文件组件并不能天然被浏览器所支持，需要提供额外的编译支持，因此必须搭配构建工具使用。  我们可以参考 Vite 搭建第一个 Vite 项目，基于 Vite，通过简单的命令快速生成这样的模板。

npm create vite@latest

其中的 src/components/HelloWorld.vue 就是符合“单文件组件和组合式 API”实践的典型组件，我们可以参考它并尝试编写我们自己的组件。

响应式 API

明确了编写组件的范式之后，下一步我们需要掌握如何编写组件的内部运行逻辑。这就需要我们对组合式 API 涵盖的内容——响应式 API、生命周期钩子、依赖注入进行了解，这里我们先来看响应式 API。

我建议大家仔细阅读官方文档中的 深入响应式系统，它有助于我们更好地理解和运用响应式 API。

本文由于篇幅限制，不倾向于花篇幅分析响应式 API 的原理，这里给出一个简单的说明：响应式 API 用于创建响应式变量，响应式变量的改变可以触发 <template> 模板渲染内容的改变，或者触发一些关联的事件。下面的例子对刚才的说明进行了解释：

<script setup lang="ts">
import { ref, watch } from 'vue'

const a = ref('Hello');

// 响应式变量 a 发生修改，关联事件(alert) 会被触发
watch(a, () => {
  alert(a.value)
})


// 5 秒后，修改响应式变量 a
setTimeout(() => {
  a.value = 'Hello World!'
}, 5000)
</script>

<template>
  <div>
    <!-- 响应式变量 a 发生修改，模板渲染内容也会及时跟进 -->
    <p>{{ a }}</p>
  </div>
</template>

我们来简单回顾开发过程中最常用的响应式 API：

ref 和 reactive

ref 和 reactive 是响应式 API 的基础，它们能够将普通 JavaScript 变量变成响应式变量：

• reactive 方法接收一个对象，将其变成响应式。
• ref 可以让基本类型(字符串、数字、布尔)变量也能够变成响应式。
• ref 创建的响应式数据需要通过 .value 属性进行访问和修改；而 reactive 创建的响应式对象可以直接访问和修改其属性。
• 从表面上看 ref 更适合于处理基本类型，而 reactive 更适合于处理对象。(不过这不代表 ref 不可以处理对象，许多实践甚至推荐尽可能使用 ref 代替 reactive，参考：VueUse Guidelines)。

<script setup lang="ts">
import { ref, reactive } from 'vue'

const refState = ref(0);
console.log(refState) // Ref 对象
console.log(refState.value) // 0

const reactiveState = reactive({ state: 0 })
console.log(reactiveState.state) // 0

function clickHandler() {
  // ref 对象的设置也需要 .value
  refState.value++;
  reactiveState.state++;
}
</script>

<template>
  <div>
    <!-- 注意在模板中访问 ref 变量不需要 value  -->
    <p>{{ refState }}</p>
    <p>{{ reactiveState.state }}</p>
    <button @click="clickHandler">+1</button>
  </div>
</template>

computed

computed 用于创建一个响应式的计算属性。

<script setup lang="ts">
import { ref, reactive, computed } from 'vue'

const a = ref(1);
const b = reactive({ count: 2 })

// 函数内部无论是 a 还是 b 发生变化，都会自动触发响应式变量 sum 的重新计算，永远保持 sum = a + b.count
const sum = computed(() => a.value + b.count)

setTimeout(() => {
  a.value = 2;
  b.count = 3;
  // 注意访问 computed 创建的响应式变量时也要加上 .value
  console.log(sum.value) // 5
}, 5000)
</script>

<template>
  <div>
    <!-- 注意在模板中访问 ref 变量不需要 value  -->
    <p>a = {{ a }}</p>
    <p>b.count = {{ b.count }}</p>
    <p>sum = a + b.count = {{ sum }}</p>
  </div>
</template>

watch

watch 用于观察一个或多个响应式对象，并在观察对象发生变化时，执行与其相关联的方法。

import { ref, reactive, watch } from 'vue'

const count = ref(0)
const data = reactive({
  count: 0
})

watch(count, (newVal, oldVal) => {
  // count changed from 0 to 1
  console.log(`count changed from ${oldVal} to ${newVal}`)
})

watch(data, (newVal, oldVal) => {
  // { count: 2 }
  console.log(oldVal)

  // { count: 2 }
  console.log(newVal)
})

// 检测 reactive 对象内部属性时，需要写成函数返回的形式
watch(() => data.count, (newVal, oldVal) => {
  // data.count changed from 0 to 2
  console.log(`data.count changed from ${oldVal} to ${newVal}`)
})

// 观测多个 响应式对象/属性 的变化
watch([
  count,
  () => data.count
], ([newCount, newDataCount], [oldCount, oldDataCount]) => {
  // count changed from 0 to 1
  // data.count changed from 0 to 2
  console.log(`count changed from ${oldCount} to ${newCount}`)
  console.log(`data.count changed from ${oldDataCount} to ${newDataCount}`)
})

setTimeout(() => {
  count.value = 1
  data.count = 2
}, 5000)

上述提到的响应式 API 具有最强的泛用性，涵盖了 90% 甚至更多的应用场景。需要更加深入的了解响应式 API，可以进一步参考官方文档：

• 响应式 API：核心
• 响应式 API：工具函数
• 响应式 API：进阶

组件的生命周期

每个 Vue 组件实例在创建时都需要经历一系列的初始化步骤，比如设置好数据侦听，编译模板，挂载实例到 DOM，以及在数据改变时更新 DOM。在此过程中，它也会运行被称为生命周期钩子的函数，让开发者有机会在特定阶段运行自己的代码。

• onBeforeMount(): 在组件被挂载之前调用，此时组件已经完成了响应式状态的设置，但还没有创建 DOM 节点。
• onMounted(): 在组件被挂载之后调用，此时组件已经创建了 DOM 节点，并插入了父容器中。可以在这个钩子中访问或操作 DOM 元素。
• onBeforeUpdate(): 在组件即将因为响应式状态变更而更新其 DOM 树之前调用，可以在这个钩子中访问更新前的 DOM 状态。
• onUpdated(): 在组件因为响应式状态变更而更新其 DOM 树之后调用，可以在这个钩子中访问更新后的 DOM 状态。
• onBeforeUnmount(): 在组件实例被卸载之前调用，此时组件实例依然还保有全部的功能。
• onUnmounted(): 在组件实例被卸载之后调用，此时组件实例已经失去了全部的功能。可以在这个钩子中清理一些副作用，如计时器、事件监听器等。
• onErrorCaptured(): 在捕获了后代组件传递的错误时调用，可以在这个钩子中处理错误或阻止错误继续向上传递。
• onRenderTracked(): 在组件渲染过程中追踪到响应式依赖时调用，仅在开发模式下可用，用于调试响应式系统。

在实际的开发过程中，我们最常用到的声明周期钩子是 onMounted、onBeforeUnmount、onUnmounted——它们具有最强的泛用性，在实际开发过程中占据了 90% 的出场率。

<script setup lang="ts">
import { ref, onMounted, onBeforeUnmount } from 'vue'

const el = ref<HTMLDivElement>()
console.log(el.value) // undefined
onMounted(() => {
  // 通常在 onMounted 中获取 DOM
  console.log(el.value) // HTMLDivElement
})

const timer = setTimeout(function() {
  // 定时器任务
}, 5000)
onBeforeUnmount(() => {
  // 在 onBeforeUnmount 中注销定时器、绑定事件等
  clearTimeout(timer)
})

</script>

<template>
  <div ref="el"></div>
</template>

曾经的选项式 API 中，全局只有一个 mounted 钩子，所有的 DOM 初始化相关逻辑都要写进去。不同的是，组合式 API 中的生命周期钩子是可以多次调用的，这一特点使得组合式 API 更加擅于“按逻辑关系组织代码"。

<script setup lang="ts">
import { ref, onMounted, onBeforeUnmount } from 'vue'

const a = ref<HTMLDivElement>()
onMounted(() => {
  console.log(a.value) // HTMLDivElement
  console.log(a.value.innerText) // aaa
})

const b = ref<HTMLDivElement>()
onMounted(() => {
  console.log(b.value) // HTMLDivElement
  console.log(b.value.innerText) // bbb
})

const c = ref<HTMLDivElement>()
onMounted(() => {
  console.log(c.value) // HTMLDivElement
  console.log(c.value.innerText) // ccc
})

</script>

<template>
  <div>
    <div ref="a">aaa</div>
    <div ref="b">bbb</div>
    <div ref="c">ccc</div>
  </div>
</template>

组件之间的通信方式

接下来还有一个问题，就是组件如何与外部进行交互，即如何与其他组件通信？对于组件库的开发而言，我们推荐使用以下通信机制，对于每种通信机制都给出了示例代码，大家可以在自己创建的示例工程中，或者在 Vue SFC Playground 尝试运行示例，查看效果。

props / v-bind

参考：Vue 官方文档：Props

• 这是 Vue 中父子组件最基础的通信方式。子组件声明自身的属性 props，父组件调用子组件时通过 v-bind 绑定属性。
• 结合使用 withDefaults 和 defineProps，可以完整地设置组件属性的类型与默认值。
• 组件的属性可以是任何类型，包括复杂对象、函数等。
• 组件原则上不允许修改 props，因此 props 是一种从父到子的单向通信机制。但是子组件可以利用函数类型的 props，将内部的状态通过函数参数告知父组件实现反向通信。

<!-- 子组件 child.vue -->
<script setup lang="ts">
import { reactive } from 'vue'

const props = withDefaults(defineProps<{
  // props 的类型
  text?: string;
  data?: Record<string, any>;
  clickCallback?: (data: Record<string, any>) => void
}>(), {
  // props 的默认值
  text: 'Button',
  data: () => ({}),
  clickCallback: () => {}
})

const childData = reactive({
  ...props.data,
  count: 0,
})

function clickHandler() {
  childData.count++
  props.clickCallback(childData)
}
</script>

<template>
  <button @click="clickHandler">
    {{ text }}
  </button>
</template>

---

<!-- 父组件中使用子组件 child.vue -->
<script setup lang="ts">
import Child from './child.vue'

function clickHandler(data: Record<string, any>) {
  console.log('子组件的数据对象：', data); // 子组件的数据对象：{ message: 'parent', count: 1 }
}
</script>

<template>
  <Child 
    text="Hello World" 
    :data="{ message: 'parent' }" 
    :clickCallback="clickHandler" />
</template>

本案例的代码演示：props / v-bind

emit / v-on

参考：Vue 官方文档：事件

• 组件之间从子到父的单向通信机制。组件通过 defineEmits 声明事件。
• 父组件通过 v-on 监听子组件事件，当子组件内部调用 emit() 触发事件时，会执行 v-on 绑定的方法。
• 因为 emit() 可以携带参数，因此子组件可以向父组件传递自身的状态。

<!-- 子组件 child.vue -->
<script setup lang="ts">
import { reactive } from 'vue'

const emit = defineEmits<{
  (event: 'add', val: string, list: string[]): void;
}>();

const list: string[] = reactive([])

function clickHandler() {
  const value = `第${String(list.length + 1)}项`
  list.push(value)
  emit('add', value, list);
}
</script>

<template>
  <div>
    <ul>
      <li v-for="(item, index) in list" :key="index">{{ item }}</li>
    </ul>
    <button @click="clickHandler">Add</button>
  </div>
</template>

---

<!-- 父组件中使用子组件 child.vue -->
<script setup lang="ts">
import Child from './child.vue'

function addHandler(value: string, list: string[]) {
  console.log('向子组件列表添加项：', value)
  console.log('子组件当前列表：', list)
}
</script>

<template>
  <Child @add="addHandler" />
</template>

本案例的代码演示：emit / v-on

v-model

参考：Vue 官方文档：组件 v-model

• v-model 机制是 vue 提供的一个语法糖，它能够使一个响应式变量在父子组件之间始终保持同步，实现双向绑定。
• 实现组件的 v-model 机制需要综合使用上述的 props 和 emit。子组件通过 emit() 方法触发一个携带了新值的 update:xxx 自定义事件，就能使父组件绑定到子组件 props 上的 xxx 属性同步为对应的新值。
• 下面的例子以一个 input 输入框组件为例子，通过 watch 方法实现 v-model 机制。无论父组件从外部修改，还是子组件在内部修改，v-model 绑定的 value 属性始终双向同步。

<!-- 子组件 child.vue -->
<script setup lang="ts">
import { ref, watch } from 'vue'

const props = withDefaults(defineProps<{
  value?: string;
}>(), {
  value: ''
})

const emit = defineEmits<{
  (event: 'update:value', val: string): void;
}>();

const valueModel = ref(props.value);

watch(() => props.value, (val) => {
  valueModel.value = val
})

watch(valueModel, (val) => {
  emit('update:value', val)
})

function inputHandler(event: Event) {
  const { value } = event.target as HTMLInputElement
  valueModel.value = value
}

function clickHandler() {
  valueModel.value += 'Hello World!'
}
</script>

<template>
  <div>
    <input :value="valueModel" @input="inputHandler" />
    <button @click="clickHandler">子组件内部修改 value</button>
  </div>
</template>

---

<!-- 父组件中使用子组件 child.vue -->
<script setup lang="ts">
import Child from './child.vue'
import { ref, watch } from 'vue'

const msg = ref('')
</script>

<template>
  <div>
    <Child v-model:value="msg" />
    <p>{{ msg }}</p>
  </div>
</template>

本案例的代码演示：v-model

defineExpose / ref

参考：Vue 官方文档：模板引用

• 子组件使用 defineExpose 向外暴露自身的属性与方法。
• 父组件通过 ref 获取子组件的实例对象，访问与调用子组件暴露的属性与方法。

<!-- 子组件 child.vue -->
<script setup lang="ts">
import { ref } from 'vue'

const isVisible = ref(false);

function open() {
  isVisible.value = true;
}

function close() {
  isVisible.value = false;
}

defineExpose({
  isVisible,
  open,
  close
})
</script>

<template>
  <div v-if="isVisible">Child</div>
</template>

---

<!-- 父组件中使用子组件 child.vue -->
<script setup lang="ts">
import Child from './child.vue'
import { ref, computed } from 'vue'

const childInstance = ref<InstanceType<typeof Child>>()

const showState = computed(() => `${childInstance.value?.isVisible ? '显示' : '隐藏'}`)

function showHandler() {
  childInstance.value?.open()
  console.log('当前组件的状态：', showState.value)
}

function hideHandler() {
  childInstance.value?.close();
  console.log('当前组件的状态：', showState.value)
}

</script>

<template>
  <div>
    <button @click="showHandler">显示 Child</button>
    <button @click="hideHandler">隐藏 Child</button>
    <p>当前组件的状态：{{ showState }}</p>
    <Child ref="childInstance" />
  </div>
</template>

本案例的代码演示：defineExpose / ref

provide / inject

参考：Vue 官方文档：依赖注入

provide / inject 是 vue 中的依赖注入 API，可用于在组件树中传值。凡是在上层组件中通过 provide 注册的值，都可以在下层组件中使用 inject 获取。

我们通过 单选框组 RadioGroup 的场景来演示 provide / inject 的典型使用，radio-group 组件可以将包括选中值在内的自身状态包装为上下文对象，通过 provide 向下传递，内部的 radio 组件中通过 inject 方法获取上下文对象，从而可以根据自身属性更新 select 组件的状态。

这样的传值方式，使得子组件之间只要处在同一个父组件之下，也得以共享状态，实现同级组件之间的通信。

<!-- radio-group.vue -->
<script setup lang="ts">
import { ref, watch, provide, Ref } from 'vue'

const props = withDefaults(defineProps<{
  modelValue?: any;
}>(), {
  modelValue: ''
})

const emit = defineEmits<{
  (event: 'update:modelValue', val: any): void;
}>();

// 实现选中项 v-model 双向绑定
const model = ref(props.modelValue)
watch(() => props.modelValue, (val) => { model.value = val })
watch(model, (val) => { emit('update:modelValue', val) })

// 将组件的上下文对象向下传递
const context = {
  radioGroupSelected: model,
  selections: <Ref<boolean>[]>[]
};

export type RadioGroupContext = typeof context

provide('radio-group', context)
</script>

<template>
  <ul class="radio-group">
    <slot />
  </ul>
</template>

---

<!-- radio.vue -->
<script setup lang="ts">
import { ref, watch, inject, Ref } from 'vue'
import type { RadioGroupContext } from './radio-group.vue'

const props = withDefaults(defineProps<{
  /** 单个 radio 的选中状态 */
  modelValue?: boolean;

  /** radio 的绑定值 */
  value?: any;
}>(), {
  modelValue: false,
  value: ''
})

const emit = defineEmits<{
  (event: 'update:modelValue', val: boolean): void;
}>();

// 获取 radio-group 组件的上下文对象
const radioGroupContext = inject<RadioGroupContext>('radio-group')

// 实现选中状态 v-model 双向绑定
const model = ref(props.modelValue)
watch(() => props.modelValue, (val) => { model.value = val })
watch(model, (val) => { emit('update:modelValue', val) })

if (radioGroupContext) {
  // 若检测到父级 radio-group 组件，将自身状态推入上下文对象
  radioGroupContext.selections.push(model);
}

function changeHandler(event: Event) {
  const { checked } = event.target as HTMLInputElement
  model.value = checked

  if (checked && radioGroupContext) {
    // 子组件被选中时，根据子组件绑定的 value，控制父组件的 v-model 绑定值
    radioGroupContext.radioGroupSelected.value = props.value

    // 取消其他同级 radio 的选中状态
    radioGroupContext.selections.forEach((selection) => {
      if (selection !== model) {
        selection.value = false
      }
    })
  }
}
</script>

<template>
  <li class="radio">
    <input type="radio" :checked="model" @change="changeHandler" />
    <slot />
  </li>
</template>

---

<!-- 父组件中使用子组件 radio-group.vue -->
<script setup lang="ts">
import { ref } from 'vue'
import RadioGroup from './radio-group.vue'
import Radio  from './radio.vue'

const value = ref('')
</script>

<template>
  <div>
    <RadioGroup v-model="value">
      <Radio value="11111">选项 1</Radio>
      <Radio value="22222">选项 2</Radio>
      <Radio value="33333">选项 3</Radio>
    </RadioGroup>
    <p>当前选中的值：{{ value }}</p>
  </div>
</template>

本案例的代码演示：provide / inject

插槽 slot

参考：Vue 官方文档：插槽

• 插槽功能允许我们将自定义模板内容渲染到组件的特定位置，也算作一种父组件向子组件通信的方式。
• 通过 作用域插槽 功能，组件可以向一个插槽的出口上传递属性，而父组件使用插槽时通过 v-slot 指令就能接收到子组件所传递的内容。

<!-- 子组件 child.vue -->
<script setup lang="ts">
import { reactive } from 'vue'

const data = reactive({
  default: 0,
  special: 0
})
</script>

<template>
  <div>
    <p>defaultCount：{{ data.default }}</p>
    <slot :data="data" />
    <p>specialCount：{{ data.special }}</p>
    <slot name="special" :data="data" />
  </div>
</template>

---

<!-- 父组件中使用子组件 child.vue -->
<script setup lang="ts">
import Child from './child.vue'
</script>

<template>
  <Child>
    <template #default="{ data }">
      <button @click="data.default++">Click</button>
    </template>
      <template #special="{ data }">
      <button @click="data.special++">Click</button>
    </template>
  </Child>
</template>

本案例的代码演示：插槽 slot

封装组件的优秀实践

了解了 Vue 框架的基础知识和组件开发技巧后，我们给大家分享一些优秀的实践，可以改善编码体验，更好地组织组件的逻辑模块，促进代码质量的提升。

安装并设置配套的 IDE 插件

许多小伙伴还在使用 Vetur 作为 Vue 开发的辅助插件，虽然 Vetur 的下载量压倒性得高，但它代表的是 Vue2 时代的历史，目前已经不再得到持续维护。

我们应该卸载 Vetur，改为安装 Volar 和 TypeScript Vue Plugin。前者支持 Vue3 的语法特性，后者提供了对 .vue 单文件模板的 TypeScript 支持。

如果想要更进一步加强 TypeScript 支持，我们应当参照 Vue 官方文档：Volar Takeover 模式 对编辑器进行配置，使得 TypeScript Vue Plugin 也能接管普通的 .ts 文件，进而支持对 Vue 组件实例类型的推断。

单组件的文件结构

我们推荐大家在开发单个组件时，尝试用以下文件结构来组织代码：

📦comp
 ┣ 📜comp.vue
 ┣ 📜composables.ts
 ┣ 📜index.ts
 ┗ 📜props.ts

概述和介绍

• props.ts - 集中定义组件的属性 props、事件 emits 相关的接口。
• composables.ts - 使用组合式 API，按照逻辑关注点的不同，将组件逻辑封装为多个组合式函数。
• comp.vue - 组件的单文件模板。
• index.ts - 组件的出口，导出其他文件中的内容，参考内容如下：

// index.ts
import Comp from './comp.vue';

export { Comp }
export * from './composables';
export * from './props';

规范组件的定义

我们推荐在 props.ts 中集中定义组件的属性 props、事件 emits 相关的接口，供组件的逻辑实现 composables.ts 以及单文件模板 .vue 文件使用。这里以 input 输入框组件的属性定义为例子，在 props.ts 中应当定义以下内容：

• 组件的属性 props 接口以及默认值。
• 组件的事件 emits 接口。
• 组件的实例类型。

// props.ts
import { InferVueDefaults } from '@/utils';
import type Input from './Input.vue';

export interface InputProps {
  /** 原生 input 类型 */
  type?: string;

  /** 绑定值 */
  modelValue?: string;

  /** 输入框占位文本 */
  placeholder?: string;

  /** 是否显示清楚按钮 */
  clearable?: boolean;
}

export type RequiredInputProps = Required<InputProps>

export function defaultInputProps(): Required<InferVueDefaults<InputProps>> {
  return {
    type: 'text',
    modelValue: '',
    placeholder: '',
    clearable: false
  };
}

export interface InputEmits {
  (event: 'update:modelValue', val: string): void;
  (event: 'input', val: string): void;
  (event: 'clear'): void;
  (event: 'focus'): void;
  (event: 'blur'): void;
}

export type InputInstance = InstanceType<typeof Input>

关于 InferVueDefaults，这个是 Vue 中推断默认 props 类型的类型工具，我们可以自己实现它：

type NativeType = null | number | string | boolean | symbol | Function;
type InferDefault<P, T> = ((props: P) => T & {}) | (T extends NativeType ? T : never);

/** 推断出 props 默认值的类型 */
export type InferVueDefaults<T> = {
  [K in keyof T]?: InferDefault<T, T[K]>;
};

在组件的单文件模板实现 input.vue 中，我们可以引入 props.ts 中的接口与类型，使用 Vue 官方文档：编译器宏 规范清晰地定义组件。

<!-- Input.vue -->
<script setup lang="ts">
import { 
  defaultInputProps, 
  InputProps,
  InputEmits
} from './props';

// 声明自定义选项，如组件名称 name
defineOptions({
  // ...
})

// 定义属性 props
const props = withDefaults(
  defineProps<InputProps>(),
  defaultInputProps(),
);

// 定义事件 emits
const emit = defineEmits<InputEmits>();

// 组件实现逻辑


// 向外暴露属性与方法
defineExpose({
  // ...
})
</script>

<template>
  <!-- ... -->
</template>

除了使组件本身的实现代码更具条理性，在 props.ts 中规范声明的类型与接口带来的另一大好处是：当用户希望对组件进行使用和拓展时，可以得到强大、完善、贴心的类型支持。

• 通过 ref 获取组件实例时，用户可以直接使用 Instance 类型，无需自己实现类型推断。

<script setup lang="ts">
import { InputInstance } from './input'
import { ref } from 'vue'

const input = ref<InputInstance>()

</script>

<template>
  <Input ref="input" />
</template>

• 在对组件进行二次封装时，用户可以引入 Props、Emits 接口，通过继承在原组件的基础上继续拓展属性与事件的定义。

<!-- MyInput.vue -->
<script setup lang="ts">
import { 
  defaultInputProps, 
  InputProps,
  InputEmits
} from './input';

interface MyInputProps extends InputProps {
  // ...
}

const props = withDefaults(
  defineProps<MyInputProps>(),
  {
    ...defaultInputProps(),
    // 更多属性的默认值
  },
);

interface MyInputEmits extends InputEmits {
  // ...
}

const emit = defineEmits<MyInputEmits>();
</script>

封装组合式函数

参考：Vue 官方文档：组合式函数

Vue 官方推荐我们按照类似下面的实践，通过抽取组合式函数改善代码结构。

<script setup>
import { useFeatureA } from './featureA.js'
import { useFeatureB } from './featureB.js'
import { useFeatureC } from './featureC.js'

const { foo, bar } = useFeatureA()
const { baz } = useFeatureB(foo)
const { qux } = useFeatureC(baz)
</script>

遵循官方的建议，我们建议大家在 composables.ts 中，将组件的功能拆分为多个逻辑关注点，将每一个逻辑关注点封装为一个组合式函数。

继续以之前的 input 输入框为例子，我们可以简单划分出三个逻辑点：

• 输入框内容的双向绑定，通过 useInputModelValue 实现。
• 输入框的聚焦、失焦等各种事件的处理，通过 useInputEvents 实现。
• 输入框的清空逻辑，通过 useInputClearable 实现。

// composables.ts
import { 
  ref, 
  watch, 
  onMounted, 
  onBeforeUnmount 
} from 'vue';
import {
  RequiredInputProps,
  InputEmits
} from './props'

export function useInputModelValue(
  props: RequiredInputProps,
  emit: InputEmits
) {
  const model = ref(props.modelValue);

  watch(() => props.modelValue, (val) => {
    model.value = val
  })

  watch(model, (val) => {
    emit('update:modelValue', val)
  })

  return { model }
}

export function useInputEvents(
  emit: InputEmits,
  modelValueContext: ReturnType<typeof useInputModelValue>
) {
  const inputEl = ref<HTMLInputElement>()
  const { model } = modelValueContext

  function focus() {
    inputEl.value?.focus()
  }

  function blur() {
    inputEl.value?.blur()
  }

  function focusHandler () {
    emit('focus')
  }

  function blurHandler () {
    emit('blur')
  }

  function inputHandler(e: Event) {
    const { value } = e.target as HTMLInputElement
    model.value = value
    emit('input', value)
  }

  // 组件挂载后获取 dom
  onMounted(() => {
    inputEl.value?.addEventListener('focus', focusHandler)
    inputEl.value?.addEventListener('blur', blurHandler)
    inputEl.value?.addEventListener('input', inputHandler)
  })

  // 组件注销前及时解绑事件
  onBeforeUnmount(() => {
    inputEl.value?.removeEventListener('focus', focusHandler)
    inputEl.value?.removeEventListener('blur', blurHandler)
    inputEl.value?.removeEventListener('input', inputHandler)
  })

  return { 
    inputEl,
    focus,
    blur
  }
}

export function useInputClearable(
  emit: InputEmits,
  modelValueContext: ReturnType<typeof useInputModelValue>
) {
  const { model } = modelValueContext

  function clearHandler() {
    model.value = ''
    emit('clear')
  }

  return { clearHandler }
}

最后，在 input.vue 单文件模板中，我们引入 composables.ts 中的函数进行组合。

<!-- input.vue -->
<script setup lang="ts">
import { 
  defaultInputProps, 
  InputProps,
  InputEmits
} from './props';
import {
  useInputModelValue,
  useInputClearable,
  useInputEvents
} from './composables'

defineOptions({
  // 自定义选项
})

const props = withDefaults(
  defineProps<InputProps>(),
  defaultInputProps(),
)

const emit = defineEmits<InputEmits>()

// 组件实现逻辑
const modelValueContext = useInputModelValue(props, emit)
const { model } = modelValueContext

const { inputEl, focus, blur } = useInputEvents(emit, modelValueContext)

const { clearHandler } = useInputClearable(emit, modelValueContext)

defineExpose({
  clear: clearHandler,
  focus,
  blur,
})
</script>

<template>
  <div>
    <input 
      ref="inputEl" 
      :type="type" 
      :value="model"
      :placeholder="placeholder" />
    <button v-if="clearable" @click="clearHandler">清除</button>
  </div>
</template>

完整的案例代码演示：单组件封装实践

虽然组件的代码经过分离逻辑关注点后变得更加清晰，但是我们例子中的组合函数还是有很大的提升空间——composables.ts 中函数需要的参数被限定为 input 组件的 props 和 emits，这就使得我们的组合函数只能用于特定的组件，而缺乏通用性，这些逻辑很难被其他的组件复用。

如果希望更进一步了解组件封装的技巧，可以持续关注后续的内容，本文的分享就到这里。

OpenTiny 社区招募贡献者啦

OpenTiny Vue 正在招募社区贡献者，欢迎加入我们🎉

你可以通过以下方式参与贡献：

• 在 issue 列表中选择自己喜欢的任务
• 阅读贡献者指南，开始参与贡献

你可以根据自己的喜好认领以下类型的任务：

• 编写单元测试
• 修复组件缺陷
• 为组件添加新特性
• 完善组件的文档

如何贡献单元测试：

• 在packages/vue目录下搜索it.todo关键字，找到待补充的单元测试
• 按照以上指南编写组件单元测试
• 执行单个组件的单元测试：pnpm test:unit3 button

如果你是一位经验丰富的开发者，想接受一些有挑战的任务，可以考虑以下任务：

• ✨ [Feature]: 希望提供 Skeleton 骨架屏组件
• ✨ [Feature]: 希望提供 Divider 分割线组件
• ✨ [Feature]: tree树形控件能增加虚拟滚动功能
• ✨ [Feature]: 增加视频播放组件
• ✨ [Feature]: 增加思维导图组件
• ✨ [Feature]: 添加类似飞书的多维表格组件
• ✨ [Feature]: 添加到 unplugin-vue-components
• ✨ [Feature]: 兼容formily

参与 OpenTiny 开源社区贡献，你将收获：

直接的价值：

1. 通过参与一个实际的跨端、跨框架组件库项目，学习最新的Vite+Vue3+TypeScript+Vitest技术
2. 学习从 0 到 1 搭建一个自己的组件库的整套流程和方法论，包括组件库工程化、组件的设计和开发等
3. 为自己的简历和职业生涯添彩，参与过优秀的开源项目，这本身就是受面试官青睐的亮点
4. 结识一群优秀的、热爱学习、热爱开源的小伙伴，大家一起打造一个伟大的产品

长远的价值：

1. 打造个人品牌，提升个人影响力
2. 培养良好的编码习惯
3. 获得华为云 OpenTiny 团队的荣誉和定制小礼物
4. 受邀参加各类技术大会
5. 成为 PMC 和 Committer 之后还能参与 OpenTiny 整个开源生态的决策和长远规划，培养自己的管理和规划能力
6. 未来有更多机会和可能

关于 OpenTiny

OpenTiny 是一套企业级组件库解决方案，适配 PC 端 / 移动端等多端，涵盖 Vue2 / Vue3 / Angular 多技术栈，拥有主题配置系统 / 中后台模板 / CLI 命令行等效率提升工具，可帮助开发者高效开发 Web 应用。

核心亮点：

1. 跨端跨框架：使用 Renderless 无渲染组件设计架构，实现了一套代码同时支持 Vue2 / Vue3，PC / Mobile 端，并支持函数级别的逻辑定制和全模板替换，灵活性好、二次开发能力强。
2. 组件丰富：PC 端有100+组件，移动端有30+组件，包含高频组件 Table、Tree、Select 等，内置虚拟滚动，保证大数据场景下的流畅体验，除了业界常见组件之外，我们还提供了一些独有的特色组件，如：Split 面板分割器、IpAddress IP地址输入框、Calendar 日历、Crop 图片裁切等
3. 配置式组件：组件支持模板式和配置式两种使用方式，适合低代码平台，目前团队已经将 OpenTiny 集成到内部的低代码平台，针对低码平台做了大量优化
4. 周边生态齐全：提供了基于 Angular + TypeScript 的 TinyNG 组件库，提供包含 10+ 实用功能、20+ 典型页面的 TinyPro 中后台模板，提供覆盖前端开发全流程的 TinyCLI 工程化工具，提供强大的在线主题配置平台 TinyTheme

联系我们：

• 官方公众号：OpenTiny
• OpenTiny 官网：opentiny.design/
• OpenTiny 代码仓库：github.com/opentiny/
• Vue 组件库：github.com/opentiny/ti… （欢迎 Star）
• Angluar组件库：github.com/opentiny/ng （欢迎 Star）
• CLI工具：github.com/opentiny/ti… （欢迎 Star）

更多视频内容也可以关注OpenTiny社区，B站/抖音/小红书/视频号。