您现在的位置是：首页 > 文章详情

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

日期：2023-09-15点击：78收藏

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

前言

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

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

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

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

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

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

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

我们在举例时，会尽量贴近当下环境中较新的实践——使用 Vue 的最新版本与 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，可以进一步参考官方文档：

组件的生命周期

每个 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 开源社区贡献，你将收获：

直接的价值：

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

长远的价值：

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

关于 OpenTiny

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

核心亮点：

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

联系我们：