通过 JSDoc 的条件映射类型（Conditional Mapped Types），可为 getPageObjectProxy 函数自动推导字符串属性的返回类型，从而省去每个字段手动添加 @type 注解的冗余操作。
通过 jsdoc 的条件映射类型（conditional mapped types），可为 `getpageobjectproxy` 函数自动推导字符串属性的返回类型，从而省去每个字段手动添加 `@type` 注解的冗余操作。
在基于 Cypress + Page Object Model（POM）的测试框架中，我们常借助 Proxy 将字符串选择器（如 'input'、'[data-testid=logout-button]'）动态转换为 Cypress.Chainable<JQuery<HTMLElement>> 类型的 DOM 元素链式调用对象。这种方式显著提升代码可读性与 IDE 智能提示体验，但原始实现需为每个字符串属性重复书写：
/** @type {Cypress.Chainable<JQuery<HTMLElement>>} */
searchField: 'input',这不仅冗长易错，还违背 DRY（Don’t Repeat Yourself）原则。
✅ 解决方案：利用 JSDoc 支持的泛型 + 条件映射类型
JSDoc 虽不支持 TypeScript 全功能，但在主流编辑器（VS Code、WebStorm）及 @typescript-eslint 等工具链中，已良好支持 keyof、extends 和映射类型语法。只需在 getPageObjectProxy 的函数签名中精准声明返回类型，即可让整个对象字面量的类型自动推导：
/**
* @template T
* @param {T} pageObject a page object with string selectors
* @returns {{[key in keyof T]: T[key] extends string ? Cypress.Chainable<JQuery<HTMLElement>> : T[key]}}
* A proxied page object where string-valued properties are auto-converted to Cypress chainables;
* non-string properties (e.g., methods) retain their original types.
*/
export const getPageObjectProxy = pageObject => new Proxy(pageObject, {
get(target, prop) {
if (typeof target[prop] === 'string') {
return cy.get(target[prop]);
}
return target[prop];
}
});? 关键点解析：
- T[key] extends string ? ... : ... 是条件类型，判断原对象 T 中每个属性值是否为 string；
- 若是，则映射为 Cypress.Chainable<JQuery<HTMLElement>>；否则保留原类型（如方法函数保持 Function 类型）；
- [key in keyof T] 实现对所有键的遍历映射，等效于 TypeScript 中的 { [K in keyof T]: ... }。
? 使用时无需任何 JSDoc 类型注释：
export const homePage = getPageObjectProxy({
searchField: 'input',
logOutButton: '[data-testid=logout-button]',
modeDropdown: '[data-testid=mode-dropdown]',
setMode(name) {
// ✅ 此处直接使用 homePage（而非 this），避免 this 绑定问题
homePage.modeDropdown.click();
homePage.modeDropdown.children().contains(name).click();
}
});⚠️ 注意事项：
- 方法内部应引用 homePage（即代理后对象）而非 this，因 Proxy 不改变 this 指向，而 this 在箭头函数或严格模式下可能为 undefined；
- 若需在方法中访问原始选择器（如日志调试），可通过 Reflect.get(homePage, 'modeDropdown', homePage) 获取原始值（需额外封装），但通常不推荐破坏类型一致性；
- 此方案完全兼容 JavaScript 项目（无需 .ts 文件），仅依赖 JSDoc 类型标注与现代编辑器支持。
✅ 效果验证：
- VS Code 中将鼠标悬停在 homePage.searchField 上，显示类型为 Cypress.Chainable<JQuery<HTMLElement>>；
- 调用 .click()、.type() 等方法时获得完整智能补全与类型检查；
- 新增字段无需维护类型注释，修改选择器字符串即自动生效。
这一模式不仅适用于 Cypress POM，也可推广至 Playwright、WebDriverIO 等任意基于字符串选择器 + Proxy 封装的自动化测试架构，是提升类型安全与开发效率的轻量级最佳实践。
