![]()
在 Vue 3 的 Composition API 中，采用了 setup() 作为组件的入口函数。
在结合了 TypeScript 的情况下，传统的 Vue.extend 等定义方法无法对此类组件给出正确的参数类型推断，这就需要引入 defineComponent() 组件包装函数，其在 rfc 文档中的说明为：
https://composition-api.vuejs.org/api.html#setup
interface Data {
[key: string]: unknown
}
interface SetupContext {
attrs: Data
slots: Slots
emit: (event: string, ...args: unknown[]) => void
}
function setup(props: Data, context: SetupContext): Data
To get type inference for the arguments passed to setup(), the use of defineComponent is needed.
文档中说得相当简略，实际写起来难免还是有丈二和尚摸不着头脑的时候。
本文将采用与本系列之前两篇相同的做法，从单元测试入手，结合 ts 类型定义，尝试弄懂 defineComponent() 的明确用法。
考虑到篇幅和相似性，本文只采用 vue 2.x + @vue/composition-api 的组合进行说明，vue 3 中的签名方式稍有不同，读者可以自行参考并尝试。
I. 测试用例
在 @vue/composition-api 项目中，test/types/defineComponent.spec.ts 中的几个测试用例非常直观的展示了几种“合法”的 TS 组件方式 （顺序和原文件中有调整）：
[test case 1] 无 props
it('no props', () => {
const App = defineComponent({
setup(props, ctx) {
//...
return () => null
},
})
new Vue(App)
//...
})
[test case 2] 数组形式的 props
it('should accept tuple props', () => {
const App = defineComponent({
props: ['p1', 'p2'],
setup(props) {
//...
},
})
new Vue(App)
//...
})
[test case 3] 自动推断 props
it('should infer props type', () => {
const App = defineComponent({
props: {
a: {
type: Number,
default: 0,
},
b: String, // 只简写类型
},
setup(props, ctx) {
//...
return () => null
},
})
new Vue(App)
//...
})
[test case 4] 推断是否必须
组件选项中的 props 类型将被推断为 { readonly foo: string; readonly bar: string; readonly zoo?: string }
it('infer the required prop', () => {
const App = defineComponent({
props: {
foo: {
type: String,
required: true,
},
bar: {
type: String,
default: 'default',
},
zoo: {
type: String,
required: false,
},
},
propsData: {
foo: 'foo',
},
setup(props) {
//...
return () => null
},
})
new Vue(App)
//...
})
[test case 5] 显式自定义 props 接口
it('custom props interface', () => {
interface IPropsType {
b: string
}
const App = defineComponent<IPropsType>({ // 写明接口
props: {
b: {}, // 只简写空对象
},
setup(props, ctx) {
//...
return () => null
},
})
new Vue(App)
//...
})
[test case 6] 显式接口和显式类型
it('custom props type function', () => {
interface IPropsTypeFunction {
fn: (arg: boolean) => void
}
const App = defineComponent<IPropsTypeFunction>({ // 写明接口
props: {
fn: Function as PropType<(arg: boolean) => void>, // 写明类型
},
setup(props, ctx) {
//...
return () => null
},
})
new Vue(App)
//...
})
[test case 7] 从显式类型推断 props
it('custom props type inferred from PropType', () => {
interface User {
name: string
}
const App = defineComponent({
props: {
user: Object as PropType<User>,
func: Function as PropType<() => boolean>,
userFunc: Function as PropType<(u: User) => User>,
},
setup(props) {
//...
return () => null
},
})
new Vue(App)
//...
})
II. 一些基础类型定义
在阅读 defineComponent 函数的签名形式之前，为了便于解释，先来看看其关联的几个基础类型定义，大致理解其作用即可，毋需深究：
引自 vue 2.x 中的 options 基础类型接口
此类型没太多好说的，就是我们熟悉的 Vue 2.x 组件 options 的定义：
// vue 2.x 项目中的 types/options.d.ts
export interface ComponentOptions<
V extends Vue,
Data=DefaultData<V>,
Methods=DefaultMethods<V>,
Computed=DefaultComputed,
PropsDef=PropsDefinition<DefaultProps>,
Props=DefaultProps> {
data?: Data;
props?: PropsDef;
propsData?: object;
computed?: Accessors<Computed>;
methods?: Methods;
watch?: Record<string, WatchOptionsWithHandler<any> | WatchHandler<any>>;
el?: Element | string;
template?: string;
// hack is for functional component type inference, should not be used in user code
render?(createElement: CreateElement, hack: RenderContext<Props>): VNode;
renderError?(createElement: CreateElement, err: Error): VNode;
staticRenderFns?: ((createElement: CreateElement) => VNode)[];
beforeCreate?(this: V): void;
created?(): void;
beforeDestroy?(): void;
destroyed?(): void;
beforeMount?(): void;
mounted?(): void;
beforeUpdate?(): void;
updated?(): void;
activated?(): void;
deactivated?(): void;
errorCaptured?(err: Error, vm: Vue, info: string): boolean | void;
serverPrefetch?(this: V): Promise<void>;
directives?: { [key: string]: DirectiveFunction | DirectiveOptions };
components?: { [key: string]: Component<any, any, any, any> | AsyncComponent<any, any, any, any> };
transitions?: { [key: string]: object };
filters?: { [key: string]: Function };
provide?: object | (() => object);
inject?: InjectOptions;
model?: {
prop?: string;
event?: string;
};
parent?: Vue;
mixins?: (ComponentOptions<Vue> | typeof Vue)[];
name?: string;
// TODO: support properly inferred 'extends'
extends?: ComponentOptions<Vue> | typeof Vue;
delimiters?: [string, string];
comments?: boolean;
inheritAttrs?: boolean;
}
在后面的定义中可以看到，该类型被 @vue/composition-api 引用后一般取别名为 Vue2ComponentOptions 。
composition 式组件 options 类型基础接口
继承自符合当前泛型约束的 Vue2ComponentOptions，并重写了自己的几个可选属性：
interface ComponentOptionsBase<
Props,
D = Data,
C extends ComputedOptions = {},
M extends MethodOptions = {}
>
extends Omit<
Vue2ComponentOptions<Vue, D, M, C, Props>,
'data' | 'computed' | 'method' | 'setup' | 'props'
> {
data?: (this: Props, vm: Props) => D
computed?: C
methods?: M
}
setup 函数上下文类型接口
顾名思义，这就是 setup() 函数中第二个参数 context 的类型：
export interface SetupContext {
readonly attrs: Record<string, string>
readonly slots: { [key: string]: (...args: any[]) => VNode[] }
readonly parent: ComponentInstance | null
readonly root: ComponentInstance
readonly listeners: { [key: string]: Function }
emit(event: string, ...args: any[]): void
}
普通键值数据
export type Data = { [key: string]: unknown }
计算值选项类型
也是我们熟悉的 computed 选项键值对，值为普通的函数（即单个 getter）或 { getter, setter } 的写法：
export type ComputedOptions = Record<
string,
ComputedGetter<any> | WritableComputedOptions<any>
>
方法选项类型
export interface MethodOptions {
[key: string]: Function
}
Vue 组件代理
基本就是为了能同时适配 options api 和类组件两种定义，弄出来的一个类型壳子：
// src/component/componentProxy.ts
// for Vetur and TSX support
type VueConstructorProxy<PropsOptions, RawBindings> = VueConstructor & {
new (...args: any[]): ComponentRenderProxy<
ExtractPropTypes<PropsOptions>,
ShallowUnwrapRef<RawBindings>,
ExtractPropTypes<PropsOptions, false>
>
}
type DefaultData<V> = object | ((this: V) => object)
type DefaultMethods<V> = { [key: string]: (this: V, ...args: any[]) => any }
type DefaultComputed = { [key: string]: any }
export type VueProxy<
PropsOptions,
RawBindings,
Data = DefaultData<Vue>,
Computed = DefaultComputed,
Methods = DefaultMethods<Vue>
> = Vue2ComponentOptions<
Vue,
ShallowUnwrapRef<RawBindings> & Data,
Methods,
Computed,
PropsOptions,
ExtractPropTypes<PropsOptions, false>
> &
VueConstructorProxy<PropsOptions, RawBindings>
组件渲染代理
代理上的公开属性，被用作模版中的渲染上下文（相当于 render 中的 this）:
// src/component/componentProxy.ts
export type ComponentRenderProxy<
P = {}, // 从 props 选项中提取的类型
B = {}, // 从 setup() 中返回的被称作 RawBindings 的绑定值类型
D = {}, // data() 中返回的值类型
C extends ComputedOptions = {},
M extends MethodOptions = {},
PublicProps = P
> = {
$data: D
$props: Readonly<P & PublicProps>
$attrs: Data
} & Readonly<P> &
ShallowUnwrapRef<B> &
D &
M &
ExtractComputedReturns<C> &
Omit<Vue, '$data' | '$props' | '$attrs'>
属性类型定义
也就是 String、String[] 等：
export type PropType<T> = PropConstructor<T> | PropConstructor<T>[]
type PropConstructor<T> =
| { new (...args: any[]): T & object }
| { (): T }
| { new (...args: string[]): Function }
属性验证类型定义
export interface PropOptions<T = any> {
type?: PropType<T> | true | null
required?: boolean
default?: T | DefaultFactory<T> | null | undefined
validator?(value: unknown): boolean
}
兼容字符串和验证对象的 props 类型定义
export type ComponentPropsOptions<P = Data> =
| ComponentObjectPropsOptions<P>
| string[]
export type ComponentObjectPropsOptions<P = Data> = {
[K in keyof P]: Prop<P[K]> | null
}
export type Prop<T> = PropOptions<T> | PropType<T>
III. 官网文档中的 props
因为 defineComponent 的几种签名定义主要就是围绕 props 进行的，那么就先回顾一下官网文档中的几度说明：
https://cn.vuejs.org/v2/guide/components.html#%E9%80%9A%E8%BF%87-Prop-%E5%90%91%E5%AD%90%E7%BB%84%E4%BB%B6%E4%BC%A0%E9%80%92%E6%95%B0%E6%8D%AE
Prop 是你可以在组件上注册的一些自定义 attribute。当一个值传递给一个 prop attribute 的时候，它就变成了那个组件实例的一个 property。为了给博文组件传递一个标题，我们可以用一个 props 选项将其包含在该组件可接受的 prop 列表中：
Vue.component('blog-post', {
props: ['title'],
template: '<h3>{{ title }}</h3>'
})
https://cn.vuejs.org/v2/guide/components-props.html#Prop-%E7%B1%BB%E5%9E%8B
...到这里，我们只看到了以字符串数组形式列出的 prop：
props: ['title', 'likes', 'isPublished', 'commentIds', 'author']
但是，通常你希望每个 prop 都有指定的值类型。这时，你可以以对象形式列出 prop，这些 property 的名称和值分别是 prop 各自的名称和类型：
props: {
title: String,
likes: Number,
isPublished: Boolean,
commentIds: Array,
author: Object,
callback: Function,
contactsPromise: Promise // or any other constructor
}
https://cn.vuejs.org/v2/guide/components-props.html#Prop-%E9%AA%8C%E8%AF%81
为了定制 prop 的验证方式，你可以为 props 中的值提供一个带有验证需求的对象，而不是一个字符串数组。例如：
Vue.component('my-component', {
props: {
// 基础的类型检查 (`null` 和 `undefined` 会通过任何类型验证)
propA: Number,
// 多个可能的类型
propB: [String, Number],
// 必填的字符串
propC: {
type: String,
required: true
},
// 带有默认值的数字
propD: {
type: Number,
default: 100
},
// 带有默认值的对象
propE: {
type: Object,
// 对象或数组默认值必须从一个工厂函数获取
default: function () {
return { message: 'hello' }
}
},
// 自定义验证函数
propF: {
validator: function (value) {
// 这个值必须匹配下列字符串中的一个
return ['success', 'warning', 'danger'].indexOf(value) !== -1
}
}
}
})
IV. defineComponent 函数签名
有了上面这些印象和准备，正式来看看 defineComponent() 函数的几种签名：
签名 1：无 props
这种签名的 defineComponent 函数，将适配一个没有 props 定义的 options 对象参数，
// overload 1: object format with no props
export function defineComponent<
RawBindings,
D = Data,
C extends ComputedOptions = {},
M extends MethodOptions = {}
>(
options: ComponentOptionsWithoutProps<unknown, RawBindings, D, C, M>
): VueProxy<unknown, RawBindings, D, C, M>
也就是其对应的 VueProxy 类型之 PropsOptions 定义部分为 unknown :
// src/component/componentOptions.ts
export type ComponentOptionsWithoutProps<
Props = unknown,
RawBindings = Data,
D = Data,
C extends ComputedOptions = {},
M extends MethodOptions = {}
> = ComponentOptionsBase<Props, D, C, M> & {
props?: undefined
emits?: string[] | Record<string, null | ((emitData: any) => boolean)>
setup?: SetupFunction<Props, RawBindings>
} & ThisType<ComponentRenderProxy<Props, RawBindings, D, C, M>>
在上面的测试用例中就是 [test case 1] 的情况。
签名 2：数组形式的 props
props 将被推断为 { [key in PropNames]?: any } 类型：
// overload 2: object format with array props declaration
// props inferred as { [key in PropNames]?: any }
// return type is for Vetur and TSX support
export function defineComponent<
PropNames extends string,
RawBindings = Data,
D = Data,
C extends ComputedOptions = {},
M extends MethodOptions = {},
PropsOptions extends ComponentPropsOptions = ComponentPropsOptions
>(
options: ComponentOptionsWithArrayProps<PropNames, RawBindings, D, C, M>
): VueProxy<Readonly<{ [key in PropNames]?: any }>, RawBindings, D, C, M>
将 props 匹配为属性名组成的字符串数组：
// src/component/componentOptions.ts
export type ComponentOptionsWithArrayProps<
PropNames extends string = string,
RawBindings = Data,
D = Data,
C extends ComputedOptions = {},
M extends MethodOptions = {},
Props = Readonly<{ [key in PropNames]?: any }>
> = ComponentOptionsBase<Props, D, C, M> & {
props?: PropNames[]
emits?: string[] | Record<string, null | ((emitData: any) => boolean)>
setup?: SetupFunction<Props, RawBindings>
} & ThisType<ComponentRenderProxy<Props, RawBindings, D, C, M>>
在上面的测试用例中就是 [test case 2] 的情况。
签名3：非数组 props
// overload 3: object format with object props declaration
// see `ExtractPropTypes` in ./componentProps.ts
export function defineComponent<
Props,
RawBindings = Data,
D = Data,
C extends ComputedOptions = {},
M extends MethodOptions = {},
PropsOptions extends ComponentPropsOptions = ComponentPropsOptions
>(
options: HasDefined<Props> extends true
? ComponentOptionsWithProps<PropsOptions, RawBindings, D, C, M, Props>
: ComponentOptionsWithProps<PropsOptions, RawBindings, D, C, M>
): VueProxy<PropsOptions, RawBindings, D, C, M>
这里要注意的是，如果没有明确指定（[test case 5、6]） Props 泛型，那么就利用 ExtractPropTypes 从 props 中每项的 PropType 类型定义自动推断（[test case 7]） 。
// src/component/componentOptions.ts
export type ComponentOptionsWithProps<
PropsOptions = ComponentPropsOptions,
RawBindings = Data,
D = Data,
C extends ComputedOptions = {},
M extends MethodOptions = {},
Props = ExtractPropTypes<PropsOptions>
> = ComponentOptionsBase<Props, D, C, M> & {
props?: PropsOptions
emits?: string[] | Record<string, null | ((emitData: any) => boolean) >
setup?: SetupFunction<Props, RawBindings>
} & ThisType<ComponentRenderProxy<Props, RawBindings, D, C, M>>
// src/component/componentProps.ts
export type ExtractPropTypes<
O,
MakeDefaultRequired extends boolean = true
> = O extends object
? { [K in RequiredKeys<O, MakeDefaultRequired>]: InferPropType<O[K]> } &
{ [K in OptionalKeys<O, MakeDefaultRequired>]?: InferPropType<O[K]> }
: { [K in string]: any }
// prettier-ignore
type InferPropType<T> = T extends null
? any // null & true would fail to infer
: T extends { type: null | true }
? any // As TS issue https://github.com/Microsoft/TypeScript/issues/14829 // somehow `ObjectConstructor` when inferred from { (): T } becomes `any` // `BooleanConstructor` when inferred from PropConstructor(with PropMethod) becomes `Boolean`
: T extends ObjectConstructor | { type: ObjectConstructor }
? { [key: string]: any }
: T extends BooleanConstructor | { type: BooleanConstructor }
? boolean
: T extends FunctionConstructor
? Function
: T extends Prop<infer V>
? ExtractCorrectPropType<V> : T;
V. 开发实践
除去单元测试中几种基本的用法，在以下的 ParentDialog 组件中，主要有这几个实际开发中要注意的点：
-
-
-
-
tsx 中 v-model 和 scopedSlots 的写法
ParentDialog.vue
<script lang="tsx">
import { noop, trim } from 'lodash';
import {
inject, Ref, defineComponent, getCurrentInstance, ref
} from '@vue/composition-api';
import filters from '@/filters';
import CommonDialog from '@/components/CommonDialog';
import ChildTable, { getEmptyModelRow } from './ChildTable.vue';
export interface IParentDialog {
show: boolean;
specFn: (component_id: HostComponent['id']) => Promise<{ data: DictSpecs }>;
}
export default defineComponent<IParentDialog>({
// tsx 中自定义组件依然要注册
components: {
ChildTable
},
props: {
show: {
type: Boolean,
default: false
},
specFn: {
type: Function,
default: noop
}
},
// note: setup 须用箭头函数
setup: (props, context) => {
// 修正 tsx 中无法自动注入 'h' 函数的问题
// eslint-disable-next-line no-unused-vars
const h = getCurrentInstance()!.$createElement;
const { emit } = context;
const { specFn, show } = props;
// filter 的用法
const { withColon } = filters;
// inject 的用法
const pageType = inject<CompSpecType>('pageType', 'foo');
const dictComponents = inject<Ref<DictComp[]>>('dictComponents', ref([]));
// ref的类型约束
const dictSpecs = ref<DictSpecs>([]);
const loading = ref(false);
const _lookupSpecs = async (component_id: HostComponent['id']) => {
loading.value = true;
try {
const json = await specFn(component_id);
dictSpecs.value = json.data;
} finally {
loading.value = false;
}
};
const formdata = ref<Spec>({
component_id: '',
specs_id: '',
model: [getEmptyModelRow()]
});
const err1 = ref('');
const err2 = ref('');
const _doCheck = () => {
err1.value = '';
err2.value = '';
const { component_id, specs_id, model } = formdata.value;
if (!component_id) {
err1.value = '请选择部件';
return false;
}
for (let i = 0; i < model.length; i++) {
const { brand_id, data } = model[i];
if (!brand_id) {
err2.value = '请选择品牌';
return false;
}
if (
formdata.value.model.some(
(m, midx) => midx !== i && String(m.brand_id) === String(brand_id)
)
) {
err2.value = '品牌重复';
return false;
}
}
return true;
};
const onClose = () => {
emit('update:show', false);
};
const onSubmit = async () => {
const bool = _doCheck();
if (!bool) return;
const params = formdata.value;
emit('submit', params);
onClose();
};
// note: 在 tsx 中，element-ui 等全局注册的组件依然要用 kebab-case 形式 🤦
return () => (
<CommonDialog
class="comp"
title="新建"
width="1000px"
labelCancel="取消"
labelSubmit="确定"
vLoading={loading.value}
show={show}
onClose={onClose}
onSubmit={onSubmit}
>
<el-form labelWidth="140px" class="create-page">
<el-form-item label={withColon('部件类型')} required={true} error={err1.value}>
<el-select
class="full-width"
model={{
value: formdata.value.component_id,
callback: (v: string) => {
formdata.value.component_id = v;
_lookupSpecs(v);
}
}}
>
{dictComponents.value.map((dictComp: DictComp) => (
<el-option key={dictComp.id} label={dictComp.component_name} value={dictComp.id} />
))}
</el-select>
</el-form-item>
{formdata.value.component_id ? (
<el-form-item labelWidth="0" label="" required={true} error={err2.value}>
<child-table
list={formdata.value.model}
onChange={(v: Spec['model']) => {
formdata.value.model = v;
}}
onError={(err: string) => {
err3.value = err;
}}
scopedSlots={{
default: (scope: any) => (
<p>{ scope.foo }</p>
)
}}
/>
</el-form-item>
) : null}
</el-form>
</CommonDialog>
);
}
});
</script>
<style lang="scss" scoped>
</style>
