如何在JSDoc中扩展typedef类型定义的属性？

问题描述 #

我有如下JSDoc的typedef类型定义：

/**
 * @typedef {Object} obj1
 * @property {boolean} a - Property 1
 * @property {boolean} b - Property 2
 */

我想要创建一个新的typedef，除包含obj1的a、b属性外，还添加以下属性：

* @property {boolean} c - Property 3
* @property {boolean} d - Property 4

就像JavaScript里用扩展运算符...obj1复用对象属性那样，不想重复定义a、b。请问能不能用类似下面的JSDoc写法实现？

/**
 * @typedef {Object} obj1
 * @property {boolean} a - Property 1
 * @property {boolean} b - Property 2
 */

/**
 * @typedef {Object} obj2
 * @property {...obj1}
 * @property {boolean} c - Property 3
 * @property {boolean} d - Property 4
 */

解答 #

你尝试的@property {...obj1}写法不被标准JSDoc支持，但有两种标准方式可以实现类型扩展：

方式一：类型交集（最推荐） #

直接通过obj1 & { ... }的语法合并类型，这是最简洁且兼容性最好的方式：

/**
 * @typedef {Object} obj1
 * @property {boolean} a - Property 1
 * @property {boolean} b - Property 2
 */

/**
 * @typedef {obj1 & {
 *   c: boolean;
 *   d: boolean;
 * }} obj2
 */

obj2会自动继承obj1的所有属性，同时新增c和d，和JS的对象扩展逻辑一致。

方式二：使用@augments标签 #

如果你习惯类继承的写法，可以用@augments（或别名@extends）来扩展已有typedef：

/**
 * @typedef {Object} obj1
 * @property {boolean} a - Property 1
 * @property {boolean} b - Property 2
 */

/**
 * @typedef {Object} obj2
 * @augments obj1
 * @property {boolean} c - Property 3
 * @property {boolean} d - Property 4
 */

这种方式需要你的JSDoc解析器支持（比如VS Code的TS服务、ESLint的JSDoc插件等），主流工具基本都兼容。

注意 #

• 不要用你最初尝试的@property {...obj1}语法，它不属于标准规范，解析器识别不了。
• 类型交集的方式兼容性最优，优先推荐。

内容的提问来源于stack exchange，提问作者Islam Y-