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

原创
2023/09/15 16:22
阅读数 1.6K
AI总结

本文由郭凯南同学分享,主要是基于组件库开发的场景,介绍了 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(): 在组件渲染过程中追踪到响应式依赖时调用,仅在开发模式下可用,用于调试响应式系统。

在实际的开发过程中,我们最常用到的声明周期钩子是 onMountedonBeforeUnmountonUnmounted——它们具有最强的泛用性,在实际开发过程中占据了 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>
  • 在对组件进行二次封装时,用户可以引入 PropsEmits 接口,通过继承在原组件的基础上继续拓展属性与事件的定义。
<!-- 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社区,B站/抖音/小红书/视频号。

展开阅读全文
加载中
点击引领话题📣 发布并加入讨论🔥
0 评论
1 收藏
0
分享
AI总结
返回顶部
顶部