Vue3 的父子组件传值、绑定表单数据、UI库的二次封装、防抖等,想来大家都很熟悉了,本篇介绍一种使用 Typescript 的方式进行统一的封装的方法。
基础使用方法
Vue3对于表单的绑定提供了一种简单的方式:v-model。对于使用者来说非常方便,v-model="name" 就可以了。
自己做组件
但是当我们要自己做一个组件的时候,就有一点麻烦:
https://staging-cn.vuejs.org/guide/components/events.html#usage-with-v-model
<script setup> defineProps(['modelValue']) defineEmits(['update:modelValue']) </script> <template> <input :value="modelValue" @input="$emit('update:modelValue', $event.target.value)" /> </template>
需要我们定义 props、emit、input 事件等。
对UI库的组件进行二次封装
如果我们想对UI库进行封装的话,就又麻烦了一点点:
https://staging-cn.vuejs.org/guide/components/events.html#usage-with-v-model
// <script setup> import { computed } from 'vue' const props = defineProps(['modelValue']) const emit = defineEmits(['update:modelValue']) const value = computed({ get() { return props.modelValue }, set(value) { emit('update:modelValue', value) } }) // </script> <template> <el-input v-model="value" /> </template>
由于 v-model 不可以直接用组件的 props,而 el-input 又把原生的 value 变成了 v-model 的形式,所以需要使用 computed 做中转,这样代码就显得有点繁琐。
如果考虑防抖功能的话,代码会更复杂一些。
代码为啥会越写越乱?因为没有及时进行重构和必要的封装!
建立 vue3 项目
情况讲述完毕,我们开始介绍解决方案。
首先采用 vue3 的最新工具链:create-vue, 建立一个支持 Typescript 的项目。
https://staging-cn.vuejs.org/guide/typescript/overview.html
先用 Typescript 的方式封装一下 v-model,然后再采用一种更方便的方式实现需求,二者可以对照看看哪种更适合。
v-model 的封装
我们先对 v-model、emit 做一个简单的封装,然后再加上防抖的功能。
基本封装方式
ref-emit.ts
import { customRef } from 'vue' /** * 控件的直接输入,不需要防抖。负责父子组件交互表单值 * @param props 组件的 props * @param emit 组件的 emit * @param key v-model 的名称,用于 emit */ export default function emitRef<T, K extends keyof T & string> ( props: T, emit: (event: any, ...args: any[]) => void, key: K ) { return customRef<T[K]>((track: () => void, trigger: () => void) => { return { get(): T[K] { track() return props[key] // 返回 modelValue 的值 }, set(val: T[K]) { trigger() // 通过 emit 设置 modelValue 的值 emit(`update:${key.toString()}`, val) } } }) }
K keyof T
因为属性名称应该在 props 里面,所以使用 keyof T 的方式进行约束。
T[K]
可以使用 T[K] 作为返回类型。
key 的默认值
尝试了各种方式,虽然可以运行,但是TS会报错。可能是我打开的方式不对吧。
customRef
为啥没有用 computed?因为后续要增加防抖功能。
在 set 里面使用 emit 进行提交,在 get 里面获取 props 里的属性值。
emit 的 type
emit: (event: any, ...args: any[]) => void,各种尝试,最后还是用了any。
这样简单的封装就完成了。
支持防抖的方式
官网提供的防抖代码,对应原生 input 是好用的,但是用在 el-input 上面就出了一点小问题,所以只好修改一下:
ref-emit-debounce.ts import { customRef, watch } from 'vue' /** * 控件的防抖输入,emit的方式 * @param props 组件的 props * @param emit 组件的 emit * @param key v-model的名称,默认 modelValue,用于emit * @param delay 延迟时间,默认500毫秒 */ export default function debounceRef<T, K extends keyof T> ( props: T, emit: (name: any, ...args: any[]) => void, key: K, delay = 500 ) { // 计时器 let timeout: NodeJS.Timeout // 初始化设置属性值 let _value = props[key] return customRef<T[K]>((track: () => void, trigger: () => void) => { // 监听父组件的属性变化,然后赋值,确保响应父组件设置属性 watch(() => props[key], (v1) => { _value = v1 trigger() }) return { get(): T[K] { track() return _value }, set(val: T[K]) { _value = val // 绑定值 trigger() // 输入内容绑定到控件,但是不提交 clearTimeout(timeout) // 清掉上一次的计时 // 设置新的计时 timeout = setTimeout(() => { emit(`update:${key.toString()}`, val) // 提交 }, delay) } } }) }
timeout = setTimeout(() => {})
实现防抖功能,延迟提交数据。
let _value = props[key]
定义一个内部变量,在用户输入字符的时候保存数据,用于绑定组件,等延迟后再提交给父组件。
watch(() => props[key], (v1) => {})
监听属性值的变化,在父组件修改值的时候,可以更新子组件的显示内容。
因为子组件的值对应的是内部变量 _value,并没有直接对应props的属性值。
这样就实现了防抖的功能。
直接传递 model 的方法。
一个表单里面往往涉及多个字段,如果每个字段都使用 v-model 的方式传递的话,就会出现“中转”的情况,这里的“中转”指的是 emit,其内部代码比较复杂。
如果组件嵌套比较深的话,就会多次“中转”,这样不够直接,也比较繁琐。
另外如果需要 v-for 遍历表单子控件的话,也不方便处理多 v-model 的情况。
所以为什么不把一个表单的 model 对象直接传入子组件呢?这样不管嵌套多少层组件,都是直接对地址进行操作,另外也方便处理一个组件对应多个字段的情况。
当然,也有一点麻烦的地方,需要多传入一个属性,记录组件要操作的字段名称。
组件的 props 的类型是 shallowReadonly,即根级只读,所以我们可以修改传入的对象的属性。
基础封装方式
ref-model.ts import { computed } from 'vue' /** * 控件的直接输入,不需要防抖。负责父子组件交互表单值。 * @param model 组件的 props 的 model * @param colName 需要使用的属性名称 */ export default function modelRef<T, K extends keyof T> (model: T, colName: K) { return computed<T[K]>({ get(): T[K] { // 返回 model 里面指定属性的值 return model[colName] }, set(val: T[K]) { // 给 model 里面指定属性赋值 model[colName] = val } }) }
我们也可以使用 computed 来做中转,还是用 K extends keyof T做一下约束。
防抖的实现方式
ref-model-debounce.ts import { customRef, watch } from 'vue' import type { IEventDebounce } from '../types/20-form-item' /** * 直接修改 model 的防抖 * @param model 组件的 props 的 model * @param colName 需要使用的属性名称 * @param events 事件集合,run:立即提交;clear:清空计时,用于汉字输入 * @param delay 延迟时间,默认 500 毫秒 */ export default function debounceRef<T, K extends keyof T> ( model: T, colName: K, events: IEventDebounce, delay = 500 ) { // 计时器 let timeout: NodeJS.Timeout // 初始化设置属性值 let _value: T[K] = model[colName] return customRef<T[K]>((track: () => void, trigger: () => void) => { // 监听父组件的属性变化,然后赋值,确保响应父组件设置属性 watch(() => model[colName], (v1) => { _value = v1 trigger() }) return { get(): T[K] { track() return _value }, set(val: T[K]) { _value = val // 绑定值 trigger() // 输入内容绑定到控件,但是不提交 clearTimeout(timeout) // 清掉上一次的计时 // 设置新的计时 timeout = setTimeout(() => { model[colName] = _value // 提交 }, delay) } } }) }
对比一下就会发现,代码基本一样,只是取值、赋值的地方不同,一个使用 emit,一个直接给model的属性赋值。
那么能不能合并为一个函数呢?当然可以,只是参数不好起名,另外需要做判断,这样看起来就有点不易读,所以还是做两个函数直接一点。
我比较喜欢直接传入 model 对象,非常简洁。
范围取值(多字段)的封装方式
开始日期、结束日期,可以分为两个控件,也可以用一个控件,如果使用一个控件的话,就涉及到类型转换,字段对应的问题。
所以我们可以再封装一个函数。
ref-model-range.ts import { customRef } from 'vue' interface IModel { [key: string]: any } /** * 一个控件对应多个字段的情况,不支持 emit * @param model 表单的 model * @param arrColName 使用多个属性,数组 */ export default function range2Ref<T extends IModel, K extends keyof T> ( model: T, ...arrColName: K[] ) { return customRef<Array<any>>((track: () => void, trigger: () => void) => { return { get(): Array<any> { track() // 多个字段,需要拼接属性值 const tmp: Array<any> = [] arrColName.forEach((col: K) => { // 获取 model 里面指定的属性值,组成数组的形式 tmp.push(model[col]) }) return tmp }, set(arrVal: Array<any>) { trigger() if (arrVal) { arrColName.forEach((col: K, i: number) => { // 拆分属性赋值,值的数量可能少于字段数量 if (i < arrVal.length) { model[col] = arrVal[i] } else { model[col] = '' } }) } else { // 清空选择 arrColName.forEach((col: K) => { model[col] = '' // undefined }) } } } }) }
IModel
定义一个接口,用于约束泛型 T,这样 model[col] 就不会报错了。
这里就不考虑防抖的问题了,因为大部分情况都不需要防抖。
使用方法
封装完毕,在组件里面使用就非常方便了,只需要一行即可。
先做一个父组件,加载各种子组件做一下演示。
js // v-model 、 emit 的封装 const emitVal = ref('') // 传递 对象 const person = reactive({name: '测试', age: 111}) // 范围,分为两个属性 const date = reactive({d1: '2012-10-11', d2: '2012-11-11'}) template emit 的封装 <input-emit v-model="emitVal"/> <input-emit v-model="person.name"/> model的封装 <input-model :model="person" colName="name"/> <input-model :model="person" colName="age"/> model 的范围取值 <input-range :model="date" colName="d1_d2"/> emit
我们做一个子组件:
10-emit.vue // <template> <!--测试 emitRef--> <el-input v-model="val"></el-input> // /template> // <script lang="ts"> import { defineComponent } from 'vue' import emitRef from '../../../../lib/base/ref-emit' export default defineComponent({ name: 'nf-demo-base-emit', props: { modelValue: { type: [String, Number, Boolean, Date] } }, emits: ['update:modelValue'], setup(props, context) { const val = emitRef(props, context.emit, 'modelValue') return { val } } }) // </script>
定义一下 props 和 emit,然后调用函数即可。
也支持 script setup 的方式:
12-emit-ss.vue <template> <el-input v-model="val" ></el-input> </template> <script setup lang="ts"> import emitRef from '../../../../lib/base/ref-emit' const props = defineProps<{ modelValue: string }>() const emit = defineEmits<{ (e: 'update:modelValue', value: string): void }>() const val = emitRef(props, emit, 'modelValue') </script>
定义props,定义emit,然后调用 emitRef。
model
我们做一个子组件
20-model.vue
<template> <el-input v-model="val2"></el-input> </template> <script lang="ts"> import { defineComponent } from 'vue' import type { PropType } from 'vue' import modelRef from '../../../../lib/base/ref-model' interface Person { name: string, age: 12 } export default defineComponent({ name: 'nf-base-model', props: { model: { type: Object as PropType<Person> }, colName: { type: String }, setup(props, context) { const val2 = modelRef(props.model, 'name') return { val2 } } }) </script>
定义 props,然后调用即可。
虽然多了一个描述字段名称的参数,但是不用定义和传递 emit 了。
<template> <el-date-picker v-model="val2" type="daterange" value-format="YYYY-MM-DD" range-separator="-" start-placeholder="开始日期" end-placeholder="结束日期" /> </template> <script lang="ts"> import { defineComponent } from 'vue' import type { PropType } from 'vue' import rangeRef from '../../../../lib/base/ref-model-range2' interface DateRange { d1: string, d2: string } export default defineComponent({ name: 'nf-base-range', props: { model: { type: Object as PropType<DateRange> }, colName: { type: [String] } }, setup(props, context) { const val2 = rangeRef<DateRange>(props.model, 'd1', 'd2') return { val2 } } }) </script>
范围取值
el-date-picker 组件在 type="daterange" 的时候,v-model 是一个数组,而后端数据库的设置,一般是两个字段,比如 startDate、endDate,需要提交的也是对象形式,这样就需要在数组和对象之间做转换。
而我们封装的 rangeRef 就可以做这样的转换。
TS 的尴尬
可能你会注意到,上面的例子没有使用 colName 属性,而是直接传递字符层的参数。
因为 TS 只能做静态检查,不能做动态检查,直接写字符串是静态的方式,TS可以检查。
但是使用 colName 属性的话,是动态的方式,TS的检查不支持动态,然后直接给出错误提示。
虽然可以正常运行,但是看着红线,还是很烦的,所以最后封装了个寂寞。
对比一下
对比项目 | emit | model |
类型明确 | 困难 | 很明确 |
参数(使用) | 一个 | 两个 |
效率 | emit内部需要中转 | 直接使用对象地址修改 |
封装难度 | 有点麻烦 | 轻松 |
组件里使用 |
需要定义emit | 不需要定义emit |
多字段(封装) | 无需单独封装 | 需要单独封装 |
多字段(使用) | 需要写多个v-model | 不需要增加参数的数量 |
多字段(表单v-for) | 不好处理 | 容易 |
如果表单里的子组件,想采用 v-for 的方式遍历出来的话,显然 model 的方式更容易实现,因为不用考虑一个组件需要写几个 v-model。