将对象传入Date.toLocaleString()时，TypeScript检查器具体要求是什么？

我碰到这个问题有段时间了，代码能正常运行，但想搞明白TypeScript检查器到底在纠结啥。下面是最简复现代码，LocaleConfig会被红色高亮：

let Today = new Date();
let LocaleConfig = {dateStyle: "full"};
console.log(Today.toLocaleString([], LocaleConfig));

我发现检查器会根据目标JS版本抛出不同错误：

默认ES3版本下的错误信息 #

No overload matches this call.
   Overload 1 of 3, '(locales?: LocalesArgument, options?: DateTimeFormatOptions | undefined): string', gave the following error.
     Argument of type '{ dateStyle: string; }' is not assignable to parameter of type 'DateTimeFormatOptions'.
       Types of property 'dateStyle' are incompatible.
         Type 'string' is not assignable to type '"full" | "long" | "medium" | "short" | undefined'.
   Overload 2 of 3, '(locales?: string | string[] | undefined, options?: DateTimeFormatOptions | undefined): string', gave the following error.
     Argument of type '{ dateStyle: string; }' is not assignable to parameter of type 'DateTimeFormatOptions'.
{source: ts, code: 2769, severity: 8}

ES6版本下的错误信息 #

Type '{ dateStyle: string; }' has no properties in common with type 'DateTimeFormatOptions'.
{source: ts, code: 2559, severity: 8}

问题原因与解决办法 #

1. 类型推断不精确：TypeScript自动把LocaleConfig.dateStyle推断为宽泛的string类型，但toLocaleString的options参数要求dateStyle是"full" | "long" | "medium" | "short"这几个字面量类型之一，导致类型不匹配。
2. ES版本差异的根源：
   • 目标设为ES3时，TypeScript的DateTimeFormatOptions类型包含dateStyle字段，但要求严格的字面量类型，因此报错类型不兼容。
   • 目标设为ES6时，TypeScript默认使用ES6标准的DateTimeFormatOptions定义，而dateStyle是ES2020才新增的API，所以类型里没有这个字段，报错“无共同属性”。

可行的解决方式：

• 显式指定类型注解：给LocaleConfig加上Intl.DateTimeFormatOptions类型（需确保tsconfig.json的lib配置包含ES2020或更高版本）：

  let LocaleConfig: Intl.DateTimeFormatOptions = {dateStyle: "full"};
  

• 使用const断言缩小类型：让TypeScript把"full"推断为字面量类型而非宽泛的string：

  let LocaleConfig = {dateStyle: "full" as const};
  

• 调整TS配置：在tsconfig.json中设置"target": "ES2020"（或更高版本），同时"lib": ["ES2020", "DOM"]，这样TypeScript会识别dateStyle是标准配置项。

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