使用TypeScript为DOM元素创建可扩展的自定义选择器与方法

背景与挑战

在前端开发中，我们经常需要对dom元素进行操作。虽然原生的queryselector和queryselectorall方法功能强大，但在某些场景下，我们可能希望创建更具语义化或更便捷的自定义选择器，并为选中的元素或元素集合添加自定义方法（例如，批量添加css类）。

然而，在使用TypeScript时，这会带来一个类型挑战：querySelector返回一个Element类型，而querySelectorAll返回一个NodeList类型。如果一个自定义的find函数可能返回单个元素也可能返回元素列表，TypeScript的类型系统会对此感到困惑。此外，如何优雅地为这两种不同类型的返回值都添加自定义方法（例如，addClass或forEach）而不破坏类型安全，是我们需要解决的核心问题。

最初的尝试可能包括为Element接口添加forEach方法，并让NodeList继承Element接口，但这通常被认为不是最佳实践，因为它混淆了单个元素和元素集合的语义，并且可能导致类型判断上的混乱。

解决方案：类型扩展与原型修改

为了在TypeScript中实现类型安全且可扩展的自定义DOM操作，一个推荐的方法是结合TypeScript的声明合并（Declaration Merging）和JavaScript的原型链修改。

1. 定义扩展类型

首先，我们定义一个扩展类型ElementExtended，它在原生Element的基础上，增加了我们自定义的方法。

// util.ts
type ElementExtended = Element & {
  classAdd: typeof classAdd; // 声明classAdd方法，其类型与classAdd函数相同
};

这里，ElementExtended是一个交叉类型（Intersection Type），它表示一个既是Element又是拥有classAdd方法的对象。typeof classAdd用于获取classAdd函数的类型签名。

2. 实现自定义方法

接下来，我们实现自定义的DOM操作方法，例如classAdd。注意，我们在这里明确指定了this的类型为Element，这对于确保方法的正确上下文至关重要。

// util.ts
function classAdd(this: Element, ...tokens: string[]) {
  this.classList.add(...tokens);
}

通过this: Element，TypeScript知道在调用classAdd时，this上下文将是一个Element实例，从而允许我们安全地访问this.classList。

3. 扩展Element原型

这是实现自定义方法能在DOM元素上直接调用的关键一步。我们需要在运行时将classAdd函数添加到Element.prototype上。为了让TypeScript知道Element.prototype现在有了这个新方法，我们需要进行类型断言。

// util.ts
(Element.prototype as ElementExtended).classAdd = classAdd;

这行代码告诉TypeScript编译器，我们正在将classAdd函数赋值给Element.prototype上的classAdd属性，并且我们断言Element.prototype现在拥有ElementExtended类型所定义的classAdd方法。

4. 创建自定义选择器函数

现在，我们可以创建自定义的选择器函数，例如query和queryArray。这些函数将利用原生的querySelectorAll，但会将其返回值类型声明为包含我们扩展方法的类型。

// util.ts
function query(selector: string): NodeListOf<ElementExtended> {
  // querySelectorAll返回NodeListOf<Element>，我们将其断言为NodeListOf<ElementExtended>
  // 这是安全的，因为我们已经通过Element.prototype扩展了Element的实例
  return document.querySelectorAll(selector) as NodeListOf<ElementExtended>;
}

function queryArray(selector: string): ElementExtended[] {
  // 如果需要一个真正的数组而不是NodeList，可以使用Array.from
  return Array.from(query(selector));
}

export {
  query,
  queryArray,
};

这里，document.querySelectorAll(selector)返回一个NodeListOf。通过as NodeListOf，我们告诉TypeScript，虽然运行时它仍然是NodeListOf，但由于我们已经在Element.prototype上添加了classAdd方法，因此其内部的每个Element实例都将具备classAdd方法，从而可以安全地将其视为NodeListOf。

使用示例

一旦上述util.ts模块被引入，我们就可以像这样使用自定义的选择器和方法：

// test.ts (或 test.js 编译后)
import { query } from './util';

// 选中所有class为'foo'的元素，并为第一个元素添加'bar'类
query('.foo')[0]?.classAdd('bar');

// 选中所有class为'item'的元素，并为它们批量添加'active'类
query('.item').forEach(el => el.classAdd('active'));

// 如果需要一个数组进行其他数组操作
const elementsArray = queryArray('.my-div');
elementsArray.filter(el => el.textContent?.includes('important')).forEach(el => el.classAdd('highlight'));

注意事项与最佳实践

1. 全局原型修改的考量： 直接修改Element.prototype是一种全局性的操作。这意味着所有Element实例（包括第三方库创建的）都将拥有这些新方法。在大型项目或与多个库集成时，这可能会导致命名冲突或意外行为。如果这是一个主要关注点，可以考虑以下替代方案：
   • 包装模式： 创建一个自定义的包装类，将原生Element实例封装起来，并在包装类上定义所有自定义方法。这样可以避免全局污染，但每次操作都需要通过包装器。
   • 工具函数： 保持自定义方法为独立的工具函数，接受Element或NodeList作为参数，而不是作为原型方法。例如：addClass(element, 'className')。
2. TypeScript的运行时与编译时： TypeScript的类型系统主要在编译时提供类型检查。原型修改是JavaScript的运行时行为。as NodeListOf这样的类型断言是告诉TypeScript：“我知道我在做什么，请相信我这个类型是正确的。” 这种断言是基于你已在运行时执行了Element.prototype修改的前提。如果忘记修改原型，TypeScript在编译时不会报错，但运行时会抛出“方法不存在”的错误。
3. 方法命名： 尽量使用清晰、不易冲突的名称（例如，classAdd而不是add），以降低与未来浏览器原生API或第三方库方法冲突的风险。
4. 链式调用： 如果自定义方法返回this（如本例中的classAdd），则可以实现链式调用，进一步提升代码的可读性。

总结

通过结合TypeScript的类型声明合并和JavaScript的原型链修改，我们能够优雅且类型安全地为DOM元素添加自定义方法，并创建能够处理Element和NodeList两种返回类型的自定义选择器。这种方法提供了一种强大的机制来扩展DOM的功能，使代码更具表现力，并减少了重复代码。虽然全局原型修改需要谨慎，但在适当的场景下，它能显著提高开发效率和代码质量。

以上就是使用TypeScript为DOM元素创建可扩展的自定义选择器与方法的详细内容，更多请关注php中文网其它相关文章！