如何构建TypeScript类型约束数组对象键名一致？

核心解决方案 #

要实现无需提前指定键名、自动约束数组内所有单键对象键名一致的类型，可以通过泛型推断+条件类型+单键对象约束组合实现：

1. 定义单键对象基础类型 #

首先确保每个数组元素是仅含单个键的对象：

// 约束对象只能有K这一个键，额外键会触发类型冲突
type SingleKeyObject<K extends string = string> = {
  [P in K]: unknown;
} & { [key: string]: never };

2. 定义数组约束类型 #

通过泛型推断提取数组元素的键名，强制所有元素使用该键：

// 检查数组所有元素的键是否统一
type HomogeneousSingleKeyArray<T extends SingleKeyObject[]> = 
  T[number] extends SingleKeyObject<infer K>
    ? T extends SingleKeyObject<K>[]
      ? T
      : never
    : never;

3. 辅助推断函数（简化使用） #

为了避免手动传入泛型参数，用函数自动推断数组类型并应用约束：

function createHomogeneousSingleKeyArray<T extends SingleKeyObject[]>(arr: T): HomogeneousSingleKeyArray<T> {
  return arr;
}

使用示例 #

// 符合约束的情况（键名统一）
const good1 = createHomogeneousSingleKeyArray([{ id: '1' }, { id: 2 }]);
const good2 = createHomogeneousSingleKeyArray([{ name: true }, { name: null }]);

// 不符合约束的情况（键名不同，触发类型报错）
const bad = createHomogeneousSingleKeyArray([{ id: '1' }, { name: 2 }]);
// 错误提示：类型"{ id: string; }"与"{ name: number; }"的属性不兼容

原理说明 #

• SingleKeyObject<K>：通过{ [key: string]: never }覆盖所有额外键，确保对象只能有K这一个属性，多键对象会因类型冲突报错。
• HomogeneousSingleKeyArray<T>：先通过infer K提取数组元素的键名，再验证整个数组的元素是否都属于该键名的单键对象，不匹配则返回never触发错误。
• 辅助函数利用TypeScript的泛型自动推断能力，无需手动指定键名，直接约束输入数组。

通用字符串匹配约束场景 #

1. 模式匹配键名 #

约束对象键名符合特定格式（比如事件名前缀）：

// 仅允许以"on"开头且首字母大写的键名
type EventKey = `on${Capitalize<string>}`;
type EventHandlers = Record<EventKey, () => void>;

const validHandlers: EventHandlers = {
  onClick: () => {},
  onMouseOver: () => {},
};

const invalidHandlers: EventHandlers = {
  handleClick: () => {}, // 报错：键名不符合"onXXX"模式
};

2. 强制字符串完全相等 #

约束两个字符串类型必须完全一致：

type EqualStrings<S1 extends string, S2 extends string> = 
  S1 extends S2 ? S2 extends S1 ? S1 : never : never;

type ValidMatch = EqualStrings<'user_id', 'user_id'>; // 类型为'user_id'
type InvalidMatch = EqualStrings<'user_id', 'userName'>; // 类型为never

3. 数组内字符串统一 #

约束数组中所有字符串元素必须相同：

type SameStringArray<T extends string[]> = 
  T[number] extends infer S extends string
    ? T extends S[]
      ? T
      : never
    : never;

const validStrings: SameStringArray<['apple', 'apple']> = ['apple', 'apple'];
const invalidStrings: SameStringArray<['apple', 'banana']> = ['apple', 'banana']; // 报错

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