如何使用 jsDoc 在自定义组件中记录此关键字？

Posted 2023-03-13

【中文标题】如何使用 jsDoc 在自定义组件中记录此关键字？

【英文标题】：how to document this keyword in custom components with jsDoc?

【发布时间】：2020-11-25 22:00:17

【问题描述】：

我正在使用 Vuejs 内联模板组件，我们在 javascript 文件中注册组件，在 html 中注册模板。

组件看起来像这样：

Vue.component('compare-benefits', 
  data() 
     // the "this" keyword in methods should refer to this object
     return 
        ...state,
        isLoading: false,
     
  ,
  methods: 
    getData() 
       // I want the "this" keyword here to reference the object return in data above 
       this.isLoading = true;
    
  
)

如果你不熟悉 Vue，这里发生的事情是 Vue 框架会将你方法中的 this 关键字绑定到你从 data() 方法返回的对象。

我如何在这里使用 jsDoc 并告诉它这里的 this 关键字实际上是在引用该对象？

编辑：使用 jsDoc 的主要原因不是创建文档，而是使用 @ts-check 在 vscode 中进行智能感知和类型检查

【问题讨论】：

我假设这段代码在一个 JS 文件中，并且您正在运行 tsc 进行类型检查。您是否尝试过将文件扩展名重命名为 TS？仅此一项就可以在 this 上为您提供 Intellisense，其中包括组件的数据道具（以及 $ 道具）。

实际上我没有运行tsc。我正在使用 vscode，它会检查我是否在文件顶部包含 @ts-check 注释。

【参考方案1】：

Vue framework 中的 this 关键字是 Vue 类型的对象。您可以通过在 getData 方法或任何其他方法中调试代码来识别它。此外，Vue data 是this 的属性。我在下面上传了一个屏幕截图，您可以从我目前正在处理的一个示例中查看它：

结果你的jsDoc使用后的代码会是这样的：

Vue.component('compare-benefits', 
    data() 
        return 
            ...state,
            isLoading: false,
        
    ,
    methods: 
        /** @this Vue */
        getData() 
            this.isLoading = true;
        
    
)

【讨论】：

这是有道理的，但是仅添加 /** @this Vue */ 并不能提供我在使用 @ts-check 时在 vscode 中寻找的智能感知和类型检查，因为在这种情况下它不知道返回data() 中的对象也属于 Vue 实例。当我将鼠标悬停在这个关键字上时，我仍然会输入“any”。在这种情况下，您将如何记录组件本身和返回的数据？

@tito.300 首先，您没有在问题中提及 VS Code。但是，Vue framework 中的data() function 的返回数据应该始终是一个对象，因为它提到了here，因此您不需要记录它。另外，如果将鼠标悬停在开头提到的Vue 上会发生什么？

当我将鼠标悬停在 Vue 上时，我看到了 (alias) const Vue: VueConstructor<Vue> 。我编辑了我的问题。

@tito.300 无论我为了让智能感知器了解this 是Vue object 所做的尝试，它根本不是。可能目前不支持它，或者它被开发期间this 位于一个函数、一个对象、另一个对象和另一个函数中这一事实感到困惑。再举一个例子，下面的/** @this Vue */ function setName(test) this.test = test; 理解this 是Vue 类型。另一方面，jsDoc 文档很清楚，对于this，您需要设置@this

【参考方案2】：

我不知道 Vue.js。但是，我对 JSDoc 的了解可能会对您有所帮助。 'this' 关键字可以记录如下

/**
 * @this Vue
 */

这里 'Vue' 应该在 JSDoc 中声明。您可能可以在 Vue.js 文档中找到它。 您可以查看this file 以获取有关创建类、枚举、函数等的示例以及它们在 JSDoc 中的用法。