1. 背景与挑战
在Web开发中，我们经常需要通过CSS选择器来获取DOM元素，通常使用document.querySelector()获取单个元素，或document.querySelectorAll()获取元素集合（NodeList）。然而，这两种方法的返回类型不同，导致在TypeScript中处理时可能遇到类型不兼容的问题。
例如，如果我们想为获取到的元素添加一个自定义方法（如addClass），并期望这个方法既能作用于单个Element，也能作用于NodeList中的每个元素，传统的做法会显得笨拙且缺乏类型安全。直接扩展Element和NodeList的接口，并试图让一个函数返回Element | NodeList，会使得后续操作的类型推断变得复杂，难以优雅地链式调用自定义方法。
2. 核心思路：统一类型与原型扩展
为了解决上述挑战，我们采取以下核心策略：
-
统一返回类型： 我们的自定义选择器函数将始终返回一个NodeListOf
类型，其中T是我们扩展后的Element类型。即使只匹配到一个元素，它也会被封装在一个长度为1的NodeList中。这样，所有后续操作都可以基于NodeList的特性进行，简化了类型处理。 - 原型链增强： 通过修改Element.prototype，为所有Element实例添加自定义方法。TypeScript通过声明合并（Declaration Merging）机制，允许我们为内置接口（如Element）添加新的成员，从而提供类型安全。
- 类型定义： 定义一个包含我们自定义方法的扩展Element类型，确保TypeScript能够识别这些新添加的方法。
3. 实现步骤
3.1 定义扩展元素类型
首先，我们需要定义一个继承自原生Element类型，并包含我们自定义方法的接口或类型别名。这里我们以添加一个classAdd方法为例。
// util.ts
type ElementExtended = Element & {
classAdd: typeof classAdd;
// 可以添加更多自定义方法，例如：
// customFind: typeof customFind;
};这里classAdd的类型使用了typeof classAdd，这是一种获取函数类型的好方法，确保了类型的一致性。
3.2 实现自定义方法
接下来，我们实现classAdd方法。这个方法将被添加到Element的原型上，因此它内部的this上下文将指向当前的Element实例。
// util.ts (接上)
function classAdd(this: Element, ...tokens: string[]) {
this.classList.add(...tokens);
}注意this: Element的类型注解，它明确了函数被调用时this的预期类型，这对于原型方法至关重要。
3.3 增强Element原型
这是实现自定义方法可在所有Element实例上调用的关键步骤。我们将classAdd函数赋值给Element.prototype上的一个新属性。
// util.ts (接上) (Element.prototype as ElementExtended).classAdd = classAdd;
这里使用了类型断言(Element.prototype as ElementExtended)，告诉TypeScript我们正在向Element.prototype添加一个属于ElementExtended类型的方法。这是在运行时修改原型并同时保持TypeScript类型安全性的常见模式。
自定义设置的程度更高可以满足大部分中小型企业的建站需求，同时修正了上一版中发现的BUG，优化了核心的代码占用的服务器资源更少，执行速度比上一版更快 主要的特色功能如下： 1）特色的菜单设置功能，菜单设置分为顶部菜单和底部菜单，每一项都可以进行更名、选择是否隐 藏，排序等。 2）增加企业基本信息设置功能，输入的企业信息可以在网页底部的醒目位置看到。 3）增加了在线编辑功能，输入产品信息，企业介绍等栏
3.4 创建自定义选择器函数
现在，我们创建主要的自定义选择器函数query。它将使用document.querySelectorAll获取元素，并确保返回的NodeList中的每个元素都被视为ElementExtended类型。
// util.ts (接上) function query(selector: string): NodeListOf{ return document.querySelectorAll(selector) as NodeListOf ; }
同样，我们使用了类型断言as NodeListOf
3.5 辅助函数（可选）
有时，你可能更倾向于处理数组而不是NodeList，因为数组提供了更多的便利方法（如map, filter等）。我们可以提供一个辅助函数将NodeList转换为ElementExtended数组。
// util.ts (接上)
function queryArray(selector: string): ElementExtended[] {
return Array.from(query(selector));
}3.6 导出模块
最后，导出我们的自定义选择器函数，以便在其他文件中使用。
// util.ts (接上)
export {
query,
queryArray,
};4. 完整示例代码
util.ts
// 定义扩展的Element类型，包含自定义方法
type ElementExtended = Element & {
classAdd: typeof classAdd;
// 如果需要，可以在这里添加更多自定义方法，例如：
// customFind: typeof customFind;
};
// 实现自定义方法：classAdd
// this: Element 明确了函数执行时的上下文类型
function classAdd(this: Element, ...tokens: string[]) {
this.classList.add(...tokens);
}
// 自定义DOM选择器函数
// 始终返回 NodeListOf，即使只有一个元素
function query(selector: string): NodeListOf {
// querySelectorAll 默认返回 NodeListOf
// 我们断言其结果为 NodeListOf，以便TypeScript识别我们添加的方法
return document.querySelectorAll(selector) as NodeListOf;
}
// 辅助函数：将 NodeList 转换为 ElementExtended 数组
function queryArray(selector: string): ElementExtended[] {
return Array.from(query(selector));
}
// 运行时增强 Element.prototype
// 将 classAdd 方法添加到所有 Element 实例的原型链上
(Element.prototype as ElementExtended).classAdd = classAdd;
// 导出我们的自定义选择器函数
export {
query,
queryArray,
}; test.ts (或 test.js)
import { query } from './util';
// 示例用法
// 假设HTML中有一个
const myDivs = query('#myDiv'); // 返回 NodeListOf
myDivs[0]?.classAdd('highlight', 'active'); // 安全地调用 classAdd
// 假设HTML中有一个
query('.text').forEach(p => p.classAdd('blue')); // 在 NodeList 上使用 forEach，并对每个元素调用 classAdd
// 使用 queryArray 获取数组
const elementsArray = queryArray('.item');
elementsArray.forEach(el => el.classAdd('processed')); 5. 优势与注意事项
5.1 优势
- 类型安全： TypeScript能够准确地识别query函数返回的NodeList中的每个元素都具有classAdd方法，从而提供强大的类型检查和智能提示。
-
统一操作： 无论选择器匹配到单个元素还是多个元素，返回类型都是NodeListOf
，使得后续操作（如forEach、自定义方法调用）可以统一进行，无需复杂的类型判断。 - 链式调用： 如果自定义方法（如classAdd）返回this（即当前的Element实例），则可以实现方法的链式调用，提高代码可读性。
- 代码可维护性： 将DOM操作封装到自定义函数中，使得业务逻辑与DOM操作分离，提高了代码的可维护性和复用性。
5.2 注意事项
- 全局原型修改： 这种方法会修改全局的Element.prototype。虽然在多数现代前端框架（如React, Vue）中直接操作DOM较少，但在原生JS或特定场景下，需要注意可能与其他库或脚本产生的冲突。谨慎命名自定义方法以避免冲突。
- TypeScript配置： 确保你的tsconfig.json配置正确，允许模块导入和导出。
- 非空断言： 在访问NodeList的元素时，如myDivs[0]，如果该索引可能不存在，最好使用可选链操作符?.或进行空值检查，以防止运行时错误。
- 方法返回类型： 如果你的自定义方法需要支持链式调用，请确保它们返回this（即当前的Element实例），或者返回一个ElementExtended类型。
6. 总结
通过上述方法，我们成功地在TypeScript中创建了一个类型安全、功能强大的自定义DOM选择器。这种模式通过统一返回类型和原型链增强，极大地提升了处理DOM元素的开发体验，使得代码更加简洁、可读且易于维护。在构建复杂的前端应用时，采用这种策略能够有效利用TypeScript的优势，提升开发效率和代码质量。
