Vue 泛型 props 传给 toRefs 时可能丢失类型推断(4):组件可用类型标注或 getter 暂时绕过推断错误
第 3 篇 把 TS7006 追到 toRefs(props).options.value。Vue 的宏返回类型让 options 的索引结果带着布尔键判断,ToRef 没能直接看出它是数组。组件里只要让包装 Ref 的那一步拿到数组形状,.find() 就能恢复元素推断。
项目暂时还在用受影响的 Vue 声明时,可以先在组件里把数组类型交给 TypeScript,绕过 TS7006。只在函数里查找时,直接读 props.options.find(...) 就够了。还要继续把字段作为 Ref 传递时,多个字段可以共用一份 props 类型标注,单个 options 可以用 getter。
组件的临时改法是标注 props 的读取类型
组件可以给局部 props 标注 Readonly<Props<T>>,再把它交给 toRefs()。
泛型 SFC 里可以直接标注宏的返回值。
<script setup lang="ts" generic="Value extends string | number">
import { toRefs } from 'vue';
type Option = { label: string; value: Value };
interface Props {
options: readonly Option[];
value: Value;
}
// 使用组件读取 props 时的类型。
const props: Readonly<Props> = defineProps<Props>();
const { options } = toRefs(props); // Ref<readonly Option[]>
const selected = options.value.find(item => item.value === props.value); // item 是 Option。
</script>
同样的写法放在普通 TypeScript 函数里,可以逐步检查 options 的中间类型。
import { defineProps, type Ref, toRefs } from 'vue';
type Option<T> = { value: T };
type Props<T> = { options: readonly Option<T>[]; value: T };
type IsExistingRef<T> = [T] extends [Ref] ? true : false;
function inspectAnnotated<T extends string | number>() {
const props: Readonly<Props<T>> = defineProps<Props<T>>(); // Readonly<Props<T>>
type Value = (typeof props)['value']; // T
type Options = (typeof props)['options']; // readonly Option<T>[]
type ExistingRef = IsExistingRef<Options>; // false
const { options } = toRefs(props); // Ref<readonly Option<T>[]>
const items = options.value; // readonly Option<T>[]
const selected = items.find(item => item.value === props.value); // item 是 Option<T>,selected 是 Option<T> | undefined。
}
编译器先检查宏的返回值能否赋给 Readonly<Props<T>>。赋值通过后,toRefs() 从变量声明的类型推断,按键直接取到 Props<T> 里的数组。这里的 T 出现在数组元素里,数组本身缺少 Ref 要求的字段,所以 ToRef 选中假分支,把数组包装成 Ref<readonly Option<T>[]>。父组件替换整个数组时,.value 仍会读到新数组。
如果已经有 props 变量,可以在调用处写 toRefs<Readonly<Props<T>>>(props)。satisfies 可以检查这个对象是否符合 Readonly<Props<T>>,同时保留表达式原有的交集类型。因此 toRefs(checked) 仍按原类型逐键取值,.find() 的回调也还会报错。
function inspectSatisfies<T extends string | number>() {
const props = defineProps<Props<T>>();
const checked = props satisfies Readonly<Props<T>>;
const byCheck = toRefs(checked).options.value; // any
const byAnnotation = toRefs<Readonly<Props<T>>>(props).options.value; // readonly Option<T>[]
}
标注时要匹配组件实际消费的 props 类型。组件如果依赖布尔 prop 的默认 false,或已经用 withDefaults() 补齐某个字段,把局部类型机械地写成原始的 Readonly<Props<T>> 可能会重新引入 undefined。有默认值的字段要按实际契约标注。
只需要 options 时可以用 getter 保留类型
const options = toRef(() => props.options); // Readonly<Ref<readonly Option<T>[]>>
每次读取 options.value 都会重新取当前的 props.options,父组件替换整个数组后也能跟上。
toRef(props.options) 会先读出数组,再把数组作为唯一实参。toRef(props, 'options') 传的是整个对象和键,等到读 .value 时才去取那个属性。TypeScript 匹配的两条签名各有自己的返回类型。重载用法可以先看只有一个实参与有两个实参的类型对照。
// vuejs/core/packages/reactivity/src/ref.ts:547-557
export function toRef<T>(
value: T,
): T extends () => infer R
? Readonly<Ref<R>>
: T extends Ref
? T
: Ref<UnwrapRef<T>>
export function toRef<T extends object, K extends ToRefKey<T>>(
object: T,
key: K,
): ToRef<ToRefValue<T, K>>
toRef(props.options)走第一条。传给重载的是readonly Option<T>[],符合签名的普通值分支,结果走Ref<UnwrapRef<T>>。泛型元素仍需要解包,但数组外层和.find()的签名已经确定。toRef(() => props.options)也走第一条,进入 getter 分支。infer R取出 getter 的返回类型readonly Option<T>[],重载直接返回Readonly<Ref<R>>。toRef(props, 'options')走第二条。T是整个 props 类型,K是'options'。ToRefValue<T, K>对对象已有的键返回T[K]。于是计算重新落在ToRef<P['options']>上,与toRefs(props).options一样保留前面的条件。
运行时同样有两条入口。toRef(props.options) 收到数组后交给 ref(source)。toRef(props, 'options') 收到对象和键后调用 propertyToRef(source, key)。toRefs(props) 也用 propertyToRef 为每个键创建属性 Ref。这个 Ref 的 getter 每次从对象上读当前值。toRef(() => props.options) 则由 getter Ref 在每次读取时执行传进来的函数。四条路径的实现可以对照 toRef 函数体和 propertyToRef 以及 ObjectRefImpl.value。
假设父组件起初传入数组 A,子组件用它创建 Ref。父组件后来把整个 options prop 换成数组 B,再读 .value 就能看出这个 Ref 是跟着属性走,还是留在创建时的数组上。表中的 item 是 .value.find(item => item.value === props.value) 里箭头函数的参数,对应当前被检查的数组元素。
| 创建 Ref 的写法 | TypeScript 给 item 的类型 |
父组件改传 B 后,.value 读到的数组 |
|---|---|---|
toRef(props.options) |
{ value: UnwrapRef<T> } |
A |
toRef(() => props.options) |
Option<T> |
B |
toRef(props, 'options') |
隐式 any |
B |
toRefs(props).options |
隐式 any |
B |
后两行在运行时都能读到 B,类型检查仍会报 TS7006。延迟求值影响的是 TypeScript 给属性 Ref 计算的类型,这里的数组更新照常发生。
组件要把多个字段作为 Ref 传给下游时,可以使用与实际读取契约一致的 props 标注。只需要读取一个 options 字段时,getter 同时保留推断和父组件替换数组的行为。
这两种写法都在调用端给出了数组形状。defineProps() 的声明也可以在源头提供相同的形状。第 5 篇 从原有的整对象交集出发,说明我们的 PR 怎样逐字段计算,并配套修改 withDefaults()。