javascript - 如何在 Visual Studio Intellisense 中记录 JavaScript 配置对象

Question

我使用 Visual Studio 的 JavaScript Intellisense 功能已经有一段时间了，并且对它为标准 API 提供建议的能力非常满意，但我发现我无法让 Visual Studio 理解配置对象（即具有多个可选的单个对象或所需的属性作为函数的参数）。

官方的JSDoc 语法建议，如果一个参数应该有属性，你可以@param为每个参数创建一个单独的行并使用点表示法：

/**
 * @param {Object} config
 * @param {String} config.name
 * @param {Number} config.gold
 */
function do_it(config) { ... }

但是，Visual Studio 无法识别这一点 - 它会将 、 和 呈现config为config.name三个config.gold单独的顶级参数。

更糟糕的是，方法主体中的 AutoComplete 功能也不识别参数，更不用说它们的类型了：

在 Visual Studio 中似乎更接近的唯一解决方案是使用适当的文档（@constructor和@property标签）编写从未调用的构造函数，这使我编写了很多死代码，也违背了 JavaScript 的无类心态（这是我首先使用配置对象的原因）。它甚至不让我写配置对象！

不仅如此，我还知道 Visual Studio 不需要它。例如，当我写出对这个库函数的调用时，它能够收集到参数对象需要名为id、source和的属性，并target在我为函数的参数创建对象文字时建议这些名称 - 并且没有一行的文档。据推测，它来自一个简单的事实，即它们被使用：

当然，如果这些属性不在对象上并且不是正确的类型，则该方法确实会引发异常，但仍然如此。 编辑：我最近能够在我自己的代码中使用对象字面量参数来复制效果——我用一个定义明确的对象调用了一个函数，当我在代码的其他地方再次调用该函数时，它给了我 Intellisense 建议。但是我仍然没有函数体内的类型信息或语义访问。

Visual Studio 显然理解配置对象的概念，并且正在做一些逻辑来提供建议的属性。那个算法是什么？以及如何在不破坏代码的情况下利用它？

Answer 1

您使用的是正确的 JSDoc 语法，但截至今天，Visual Studio 还没有为具有命名属性的参数对象构建正确的 IntelliSense。除了您引用的那个之外，目前没有其他方法可以解决这个问题，但是您可以config就地描述对象并避免编写死代码，就像您提到的那样：

/**
 * @typedef  {object} TestConfig
 * @property {string} name
 * @property {number} gold
 *//**
 * @param    {TestConfig} config 
 */
function test(config) {

}

由于我们仅将此对象用于文档和自动完成目的，因此我们不需要实际对其进行编码。这并不比原始语法更冗长，并且还具有记录配置对象的好处。

关于您的第二个问题，您可以在sigma.js库中看到的 IntelliSense 源自解析函数代码本身的主体，而不是 JSDoc 注释。这就是为什么当您将缩小的“sigma.min.js”构建添加到您的项目时仍然可以使用它，其中注释已被剥离。

您可以测试类似于库函数中的添加参数验证（尽管访问config.name或config.gold以任何其他方式也会产生相同的结果）：

function do_it(config) {
    if (Object(config) !== config || arguments.length !== 1) throw 'do_it: wrong arguments.';
    if (typeof config.name !== 'string') throw 'config must have a name string field.';
    if (typeof config.gold !== 'number') throw 'config must have a gold number field.';
    ...
}

结果是：

以类似的方式，一旦您提供了足够的信息，就会推断出正确的类型：