挑战：扩展原生DOM类型与类型不一致性
在web开发中，我们经常需要对dom元素执行重复操作，例如添加/移除css类、查找子元素等。为了提高代码复用性和可读性，开发者倾向于为dom元素添加自定义方法，使其行为更像一个功能丰富的对象。然而，在typescript环境中，直接扩展原生dom类型（如 element 和 nodelist）会面临几个挑战：
-
querySelector 与 querySelectorAll 的返回类型差异： document.querySelector() 返回单个 Element 或 null，而 document.querySelectorAll() 返回 NodeListOf
。这导致在编写统一的自定义选择器函数时，需要处理两种不同的返回类型。 - 类型安全问题： 直接对原生接口进行全局修改（如 interface Element { ... }）可能会导致类型污染，尤其是在处理 NodeList 时，如果将其强行声明为 Element 的子类型，将引入不准确的类型信息。
- 原型链修改的TypeScript最佳实践： 如何在不破坏现有类型系统的前提下，为 Element.prototype 添加新方法，并让TypeScript正确识别这些扩展。
开发者最初尝试通过将 NodeList 接口扩展为 Element 来统一类型，并为 Element 添加 forEach 方法。虽然这在运行时可能“奏效”，但从TypeScript的角度来看，这是一种不恰当的类型处理，因为它错误地暗示一个 NodeList 实例同时也是一个 Element 实例，这与DOM的实际结构不符，可能导致未来的类型错误或混淆。
解决方案：利用交叉类型和原型扩展
为了优雅地解决上述问题，我们可以采用一种结合TypeScript交叉类型和原型链修改的策略。核心思想是定义一个新的类型，它在原有 Element 类型的基础上，增加了我们自定义的方法，然后将这些方法实际添加到 Element.prototype 上。
1. 定义扩展类型
首先，我们定义一个包含自定义方法的函数，并创建一个交叉类型 ElementExtended，它将原生 Element 类型与我们自定义方法的类型签名结合起来。
// util.ts
/**
* classAdd 函数：用于向元素添加一个或多个CSS类。
* 使用 'this: Element' 明确指定函数执行时的上下文类型。
*/
function classAdd(this: Element, ...tokens: string[]) {
this.classList.add(...tokens);
}
/**
* ElementExtended 类型：
* 它是原生 Element 类型与 classAdd 方法类型签名的交叉。
* 这样，任何被声明为 ElementExtended 的对象都将拥有 Element 的所有属性和 classAdd 方法。
*/
type ElementExtended = Element & {
classAdd: typeof classAdd;
};在这里，typeof classAdd 用于获取 classAdd 函数的类型签名，确保 ElementExtended 中的 classAdd 属性与实际的函数实现类型一致。
2. 扩展 Element.prototype
接下来，我们将 classAdd 函数实际添加到 Element.prototype 上。由于 Element.prototype 的类型默认是 Element，我们需要使用类型断言 as ElementExtended 来告诉TypeScript，我们正在向其添加一个 ElementExtended 类型才有的属性。
// util.ts (接上文) // 将 classAdd 方法添加到 Element 的原型链上 // 使用类型断言告知 TypeScript，Element.prototype 将拥有 classAdd 方法 (Element.prototype as ElementExtended).classAdd = classAdd;
通过这种方式，所有 Element 实例（包括通过 document.querySelector 获取的单个元素）都将拥有 classAdd 方法。
3. 创建自定义选择器函数
为了统一处理 querySelector 和 querySelectorAll 的返回类型，并确保它们返回的元素是 ElementExtended 类型，我们可以创建自定义的选择器函数。
// util.ts (接上文) /** * query 函数：封装 document.querySelectorAll，返回 NodeListOf。 * 这样，即使选择器匹配到多个元素，我们也可以安全地对它们进行操作。 */ function query(selector: string): NodeListOf { // querySelectorAll 默认返回 NodeListOf ， // 我们将其断言为 NodeListOf ，因为我们已经扩展了 Element.prototype return document.querySelectorAll(selector) as NodeListOf ; } /** * queryArray 函数：将 query 函数的结果转换为 ElementExtended 数组。 * 这在需要使用数组方法（如 map, filter, reduce）时非常有用。 */ function queryArray(selector: string): ElementExtended[] { return Array.from(query(selector)); } // 导出自定义选择器函数 export { query, queryArray, };
在这里，document.querySelectorAll(selector) as NodeListOf
4. 使用示例
现在，我们可以在其他模块中导入并使用这些自定义函数和扩展方法。
// test.ts (或 test.js，如果编译为JS)
import { query, queryArray } from './util';
// 示例1：选择单个元素并使用 classAdd 方法
// query('foo') 返回 NodeListOf
// [0] 获取第一个元素，类型为 ElementExtended 或 undefined
// ?.classAdd('bar') 安全地调用 classAdd 方法
query('foo')[0]?.classAdd('bar');
// 示例2：选择多个元素并遍历使用 classAdd
queryArray('.my-item').forEach(item => {
item.classAdd('active', 'highlight'); // 可以添加多个类
});
// 示例3：直接对单个元素使用 classAdd (假设元素已经存在)
const myDiv = document.getElementById('myDiv') as ElementExtended;
if (myDiv) {
myDiv.classAdd('new-style');
}
// 示例4：链式调用（如果方法返回 this）
// 假设 ElementExtended 上有其他方法，如 removeClass
// myDiv.classAdd('a').removeClass('b'); 注意事项与最佳实践
- 原型污染的考量： 直接修改 Element.prototype 是一种全局性的操作。虽然对于添加自定义方法通常是可接受的，但如果你的项目需要严格控制全局作用域，或者与可能修改相同原型的第三方库发生冲突，则需要谨慎。在这种情况下，可以考虑使用纯粹的工具函数，例如 addClass(element: Element, className: string)，而不是作为元素的方法。
-
类型断言的合理性： as NodeListOf
的使用是基于我们已经修改了 Element.prototype 的事实。如果 Element.prototype 没有被修改，这个断言将是不安全的，因为它会欺骗TypeScript，导致运行时错误。 - this 关键字的类型： 在 classAdd 函数中使用 this: Element 是非常重要的。它告诉TypeScript，当 classAdd 被调用时，this 上下文将是一个 Element 实例，从而确保在函数内部可以安全地访问 this.classList 等属性。
- 模块化： 将这些扩展逻辑封装在单独的工具文件（如 util.ts）中，并通过 export 导出，可以提高代码的组织性和可维护性。
- 替代方案： 对于更复杂的DOM操作或需要跨浏览器兼容性的场景，使用成熟的DOM操作库（如jQuery、Lodash/Underscore的DOM工具函数子集，或者更现代的Web组件/框架）可能是更优的选择。这些库通常提供了更健壮、更全面的API，并且已经处理了大量的类型和兼容性问题。
总结
通过上述方法，我们成功地在TypeScript中为原生DOM Element 类型添加了自定义方法，并通过自定义选择器函数统一了 querySelector 和 querySelectorAll 的返回类型，使其始终返回具有扩展能力的元素集合。这种方法利用了TypeScript的类型系统特性，提供了类型安全的同时，也保持了代码的简洁和可读性。在进行此类原型扩展时，理解其对全局作用域的影响并遵循TypeScript的最佳实践至关重要。
