JSDoc 中定义包含固定属性和可变额外属性的对象类型

本教程探讨在 jsdoc 中定义具有固定必选属性和任意可选额外属性的对象类型。我们将介绍两种主要策略：使用通配符属性实现高度灵活性，以及结合交叉类型与字典类型实现更强的类型约束，以确保类型定义的准确性和避免因额外属性导致的类型检查错误。

在 JavaScript 项目中，JSDoc 是一种强大的工具，用于为代码添加类型注解，从而提升开发效率和代码可维护性。然而，在某些场景下，我们需要定义一种对象类型，它既包含一组固定的、明确定义的属性，又允许开发者自由添加任意数量的额外属性。例如，一个 User 对象可能需要强制包含 name 和 age 属性，同时又允许添加 from、to 等动态属性。本文将详细介绍如何在 JSDoc 中实现这种灵活的对象类型定义。

1. 场景需求分析

假设我们有一个 User 类型，要求：

• 必须包含 name (字符串) 和 age (数字) 属性。
• 可以包含任意数量的其他属性，这些属性的键和值类型可以是任意的，或者有特定的约束。

以下是一个初始的 JSDoc 定义，它会在添加额外属性时引发类型错误：

/**
 * @typedef {object} User
 * @property {string} name - 用户名
 * @property {number} age - 用户年龄
 */

/**
 * @type {User}
 */
const tom = {
  name: 'cx',
  age: 25,
  from: 'sh', // 预期会报错
  to: 'bj',   // 预期会报错
};

为了解决这个问题，我们可以采用以下两种 JSDoc 定义策略。

2. 方法一：使用通配符属性 (*) 允许任意额外属性

最直接且最灵活的方法是使用 JSDoc 的通配符属性 (*) 来指示对象可以拥有除明确定义属性之外的任何其他属性。这种方法不对额外属性的键或值进行类型限制。

/**
 * @typedef {Object} User
 * @property {string} name - 用户名 (必填)
 * @property {number} age - 用户年龄 (必填)
 * @property {*} [key: value] - 允许用户添加的任意额外属性 (可选)
 */

/**
 * @type {User}
 */
const tom = {
  name: 'cx',
  age: 25,
  from: 'sh', // 不再报错
  to: 'bj',   // 不再报错
  isActive: true, // 同样不会报错
};

说明：

• @property {*} [key: value] 告诉 JSDoc，除了 name 和 age 之外，该对象可以包含任何键 (key) 和任何值 (value) 的属性。
• [key: value] 是一个占位符，表示任意键值对。
• * 表示这些额外属性的值可以是任何类型。

优点：

• 高度灵活： 允许添加任何类型的额外属性，无需提前声明。
• 简单易懂： 定义直观，易于理解。

缺点：

稿定AI绘图

稿定推出的AI绘画工具

36

查看详情

• 类型安全性低： 对额外属性的类型没有任何约束，可能导致潜在的运行时错误，因为类型检查器不会对这些属性的值进行验证。

3. 方法二：结合交叉类型 (&) 与字典类型 (Object.<string, Type>) 实现类型约束

当我们需要对额外属性的类型进行更具体的约束时（例如，所有额外属性的值都必须是字符串），可以使用 JSDoc 的交叉类型 (&) 结合字典类型 Object.<string, Type>。这种方法允许我们定义一个具有特定类型签名的额外属性集合，并将其与固定属性合并。

/**
 * @typedef {object} UserBase
 * @property {string} name - 用户名
 * @property {number} age - 用户年龄
 */

/**
 * @typedef {Object.<string, string>} AdditionalProperties - 额外属性，键为字符串，值为字符串
 */

/**
 * @typedef {UserBase & AdditionalProperties} User - 包含固定属性和额外字符串属性的用户类型
 */

/**
 * @type {User}
 */
const tom = {
  name: "cx",
  age: 25,
  from: "sh", // 不再报错
  to: "bj",   // 不再报错
  // isActive: true, // 如果这里尝试添加非字符串值，将引发类型错误
};

/**
 * 尝试添加一个不符合类型约束的属性
 * @type {User}
 */
const invalidTom = {
  name: "john",
  age: 30,
  country: "USA",
  // isVerified: true, // 错误：'true' 不是 string 类型
};

说明：

• 我们首先定义了 UserBase，它包含所有固定的必选属性。
• @typedef {Object.<string, string>} AdditionalProperties 定义了一个字典类型，其中所有的键都是 string，所有的值也都是 string。你可以根据需要将 string 替换为其他类型（例如 number、boolean 或 any）。
• @typedef {UserBase & AdditionalProperties} User 使用交叉类型 (&) 将 UserBase 和 AdditionalProperties 合并。这意味着 User 类型必须满足 UserBase 的所有要求，同时其所有未明确定义的属性都必须符合 AdditionalProperties 的类型签名。

优点：

• 类型安全性高： 对额外属性的键和值类型有明确的约束，有助于在开发阶段捕获类型错误。
• 结构清晰： 将固定属性和额外属性的类型定义分离，提高了可读性。

缺点：

• 略复杂： 需要定义多个 typedef 来组合类型。
• 约束性强： 如果额外属性的类型非常多样，可能需要更复杂的 Object.<string, Type> 定义，甚至可能需要回退到 Object.<string, *>。

总结与建议

在 JSDoc 中定义同时包含固定属性和可变额外属性的对象类型时，选择哪种方法取决于你对类型安全性和灵活性的具体需求：

1. 当额外属性的类型完全不可预测，且你更看重灵活性和简洁性时，请使用 @property {*} [key: value]。这种方法最简单，但牺牲了额外属性的类型检查。
2. 当需要对额外属性的类型进行约束，以提高代码的健壮性和可维护性时，请使用交叉类型结合 Object.<string, Type>。这种方法提供了更强的类型保证，尤其适用于所有额外属性都遵循相似类型模式的场景。

通过合理运用这些 JSDoc 策略，你可以为复杂的 JavaScript 对象提供清晰、准确的类型定义，从而提升项目的整体质量和开发体验。

以上就是JSDoc 中定义包含固定属性和可变额外属性的对象类型的详细内容，更多请关注php中文网其它相关文章！