如何为具有不同类型键的对象编写JSDoc？

Question

JSDoc API说，您可以像这样文档化对象：

请点击此处

。

{Object.<string, number>}

并记录多种类型：

{(number|boolean)}

但是，如果我尝试指定一个既可以使用字符串也可以使用数字作为键的对象，则无法使用。VSCode/JSDoc 只会报告类型为“any”的错误。

VSCode 不理解：

/**
 * Object with string or number for keys
 * @param {Object.<(string|number), any>} Container
 */

我还尝试过在@typedef中使用此方法，或者将键定义为自己的@typedef，但都没有效果。

因为我正在使用&来获取类型的交集（例如{Object.<string, any> & {'foo': number}}），所以我不想使用布尔值或者说：

/**
 * Object with string or number for keys
 * @param {(Object.<string, any>|Object.<number, any>) & {'foo': number}} Container
 */

文档中记录的类型看起来类似于：

 type Container = ({
    [x: string]: any;
  } & {
    'foo': number;
  }) | ({
    [x: number]: any;
  } & {
    'foo': number;
  })

这段文本过于啰嗦。

有没有更简洁的方式记录这个输出结果？

- AncientSwordRage

Answer 1

在JavaScript中，对象的键始终为字符串（或在数字的情况下被强制转换为字符串），因此您可能会不必要地使事情变得复杂。请参阅ECMAScript spec on Objects：

属性使用键值进行标识。属性键值是ECMAScript字符串值或Symbol值。所有String和Symbol值，包括空字符串，都可以作为属性键。属性名称是字符串值的属性键。

整数索引是一个规范的数字字符串，它是一个String类型的属性键

话虽如此，这似乎是最直接的解决方案：

// Combined
/**
 * @param {Object.<string, any> & {foo:  number}} Container
 */

// Split/reusable
/**
 * @typedef {Object.<string, any>} GenericObject
 * @param {GenericObject & {foo: number}} Container
 */

以上两种结果都会生成此类型/文档：

Container: {
    [x: string]: any;
} & {
    foo: number;
}

声明 Object.<string, any> 对我来说有点多余，因为对象键本质上是 string 类型，而值本质上是 any 类型，所以以这种方式声明并没有对开发人员提供太多价值。

- john-goldsmith