如何给函数参数设置含类型键列表+任意字符串的类型并保留自动补全？

解决方案：使用函数重载实现双场景兼容 #

通过定义函数重载，可以分别处理「Settings类型键」和「任意字符串」两种场景，既保留自动补全能力，又满足参数类型的动态约束：

type Settings = {
  AddPaymentInfo?: string
  AddToCart?: number
  Lead?: boolean
  Purchase: Date
}

// 场景1：参数为Settings的键，保留原有的必填/类型约束
type TrackSettingsArgs<T extends keyof Settings> = undefined extends Settings[T]
  ? [pixelCmd: T, settings?: Settings[T]]
  : [pixelCmd: T, settings: Settings[T]]

// 场景2：参数为任意字符串，第二个参数为可选object类型
type TrackCustomArgs = [pixelCmd: string, settings?: object]

// 定义函数重载
function track<T extends keyof Settings>(...args: TrackSettingsArgs<T>): void
function track(...args: TrackCustomArgs): void
// 通用实现
function track(pixelCmd: string, settings?: unknown) {
  // 业务逻辑
}

效果验证 #

• 当输入Settings的键时，TypeScript会自动补全候选值，且第二个参数的必填性、类型完全匹配原定义：

  track("Purchase", new Date()) // 正确，第二个参数必填且为Date类型
  track("AddPaymentInfo", "test") // 正确，第二个参数可选且为string类型
  track("Lead") // 正确，第二个参数可选
  

• 当输入任意字符串时，第二个参数自动变为可选的object类型：

  track("CustomEvent", { data: "custom" }) // 正确
  track("CustomEvent") // 正确
  

原理说明 #

函数重载会让TypeScript优先匹配更具体的类型定义：当输入的字符串属于keyof Settings时，会匹配第一个重载，从而保留自动补全和原有的参数约束；当输入的字符串不在keyof Settings范围内时，会回退到第二个重载，启用任意字符串+可选object的规则。

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