TypeScript泛型约束使用类型参数：filterByKey函数类型报错解决

问题场景 #

之前在多处重复编写类似的过滤逻辑：

let filtered = items.filter(item =>
    item.title.toLowerCase().includes(search.toLowerCase()) ||
    item.name.toLowerCase().includes(search.toLowerCase()) ||
    item.date.toLowerCase().includes(search.toLowerCase())
);

为了复用逻辑，封装了泛型函数filterByKey：

function filterByKey<T, K extends keyof T>(items: T[], keys: K[], search: string) {
    return items.filter((item) =>
        keys.some((key) => item[key].toString().toLowerCase().includes(search.toLowerCase()))
    );
}

调用方式如下：

let filtered = filterByKey(items, ['title', 'name', 'date'], search);

但TypeScript抛出错误：Property 'toString' does not exist on type 'T[K]'。尝试过无效语法function filterByKey<T, K extends keyof T, T[K] extends string>(...)，需要解决该类型报错。

解决方案 #

方案1：通过泛型约束限定属性类型 #

利用TypeScript的泛型约束特性，明确限定T中K对应的属性必须包含toString方法。

方式A：使用where子句（TypeScript 4.9+）

function filterByKey<T, K extends keyof T>(
    items: T[], 
    keys: K[], 
    search: string
): T[] where T[K] extends { toString(): string } {
    return items.filter((item) =>
        keys.some((key) => 
            item[key].toString().toLowerCase().includes(search.toLowerCase())
        )
    );
}

方式B：交叉类型约束（兼容低版本TS）

如果你的TypeScript版本低于4.9，可以用交叉类型改写约束：

function filterByKey<T extends Record<K, { toString(): string }>, K extends keyof T>(
    items: T[], 
    keys: K[], 
    search: string
): T[] {
    return items.filter((item) =>
        keys.some((key) => 
            item[key].toString().toLowerCase().includes(search.toLowerCase())
        )
    );
}

这种方式会强制要求传入的items中，指定keys对应的属性都必须有toString方法，从根源上避免类型报错。

方案2：类型断言快速消除报错 #

如果能确保传入的keys对应的属性一定可以调用toString，可以用类型断言跳过TypeScript的类型检查：

function filterByKey<T, K extends keyof T>(items: T[], keys: K[], search: string) {
    return items.filter((item) =>
        keys.some((key) => 
            (item[key] as { toString(): string }).toString().toLowerCase().includes(search.toLowerCase())
        )
    );
}

注意：这种方式会丢失类型安全性，如果后续传入的属性没有toString方法，运行时可能抛出错误。

方案3：安全处理空值并兜底 #

考虑到属性值可能为null或undefined，使用String()函数替代直接调用toString()，它能安全处理空值，同时TypeScript会识别其返回值为字符串：

function filterByKey<T, K extends keyof T>(items: T[], keys: K[], search: string) {
    const lowerSearch = search.toLowerCase();
    return items.filter((item) =>
        keys.some((key) => {
            const strValue = String(item[key]);
            return strValue.toLowerCase().includes(lowerSearch);
        })
    );
}

String()会将null转为"null"，undefined转为"undefined"，避免运行时错误，同时彻底解决类型报错问题。

内容的提问来源于stack exchange，提问作者opensas