如何让PhpStorm/WebStorm识别bind生成的函数参数为CSS选择器？

问题背景 #

我想给JavaScript的querySelector和querySelectorAll创建类jQuery风格的简写。目前已经让PhpStorm识别了函数返回值的自动补全，但CSS选择器字符串参数的补全无法触发。

现有实现代码：

/** @typedef {function (selectors:string):NodeList|null} FnQuerySelectorAll */
/** @typedef {function (selectors:string):Element      } FnQuerySelector    */

(d =>
{
  const
    /** @type FnQuerySelectorAll */ 
    $  = (Document.prototype.$  = Document.prototype.querySelectorAll).bind(d),

    /** @type FnQuerySelector    */
    $1 = (Document.prototype.$1 = Document.prototype.querySelector   ).bind(d)
  ;
  Element.prototype.$           = Element .prototype.querySelectorAll;
  Element.prototype.$1          = Element .prototype.querySelector   ;
  // ...
})(document)

当前问题：调用document.$('')时能获得选择器补全，但直接调用$('')却不行。PhpStorm无法识别bind方法生成的函数，希望通过JSDoc告知IDE该字符串参数为CSS选择器，或标记该函数为已有方法的别名。

解决方案 #

方式1：直接标注参数为CSS选择器类型 #

使用PhpStorm内置的CSSSelector类型标记参数，IDE会自动触发选择器补全：

/**
 * @param {CSSSelector} selectors 目标CSS选择器
 * @returns {NodeList|null} 匹配的元素集合
 */
const $  = (Document.prototype.$  = Document.prototype.querySelectorAll).bind(document);

/**
 * @param {CSSSelector} selectors 目标CSS选择器
 * @returns {Element} 匹配的第一个元素
 */
const $1 = (Document.prototype.$1 = Document.prototype.querySelector   ).bind(document);

Element.prototype.$  = Element.prototype.querySelectorAll;
Element.prototype.$1 = Element.prototype.querySelector;

方式2：标记为原生方法的别名 #

通过@borrows和typeof关联原生API，让IDE完全复用原生方法的类型信息：

/**
 * @borrows Document.prototype.querySelectorAll as $
 * @type {typeof Document.prototype.querySelectorAll}
 */
const $  = (Document.prototype.$  = Document.prototype.querySelectorAll).bind(document);

/**
 * @borrows Document.prototype.querySelector as $1
 * @type {typeof Document.prototype.querySelector}
 */
const $1 = (Document.prototype.$1 = Document.prototype.querySelector   ).bind(document);

Element.prototype.$  = Element.prototype.querySelectorAll;
Element.prototype.$1 = Element.prototype.querySelector;

关键说明 #

• CSSSelector是PhpStorm内置的类型别名，专门用于触发CSS选择器的自动补全逻辑。
• 第二种方式更推荐，因为它直接复用原生querySelector/querySelectorAll的完整类型定义，包括参数校验、返回值提示，无需手动维护typedef信息。
• 两种方案都能解决全局$/$1的参数补全问题，根据你的偏好选择即可。

内容的提问来源于stack exchange，提问作者Pinke Helga