ProseMirror 编辑器光标消失问题的技术解析与解决方案

问题现象

在使用 ProseMirror 编辑器时，开发者可能会遇到一个奇怪的现象：编辑器的光标和文本选择完全不可见。具体表现为：

• 光标呈现透明状态
• 文本选择时没有高亮效果
• 编辑器 DOM 元素永久带有 ProseMirror-hideselection 类名
• 调试时发现 selection.visible 属性值为 undefined 而非预期的 true

问题根源

这个问题的根源在于 TypeScript 编译器选项 useDefineForClassFields 的新特性与 ProseMirror 原有代码的交互方式。

在 ProseMirror 的源码中，Selection 类的 visible 属性是这样定义的：

export abstract class Selection {
  visible!: boolean;
}
Selection.prototype.visible = true;

这种设计原本是为了优化性能——通过在原型上定义 visible 属性而非每个实例上，可以减少内存使用。然而，当 TypeScript 配置中启用了 useDefineForClassFields: true（现代 TypeScript 版本的默认设置）时，这种模式会被破坏。

技术背景

TypeScript 的 useDefineForClassFields 选项是为了使类字段的行为与 ECMAScript 标准保持一致而引入的。当启用时：

1. 类字段会通过 Object.defineProperty 定义
2. 每个实例都会获得自己的属性描述符
3. 原型链上的赋值不会按预期影响实例属性

这就导致了 Selection.prototype.visible = true 的赋值无法按预期影响实例的 visible 属性。

解决方案

正确的做法是使用 TypeScript 的 declare 修饰符：

export abstract class Selection {
  declare visible: boolean;
}

这种修改具有以下优势：

1. 标准兼容：完全符合 ECMAScript 标准
2. 显式意图：明确表示该属性已在其他地方定义
3. 性能保持：继续利用原型链优化内存使用
4. 未来兼容：适应 TypeScript 的发展方向

深入理解

declare 关键字在 TypeScript 中用于表示"此属性已存在，不需要运行时初始化"。这与 ! 操作符（非空断言）有本质区别：

• ! 只是告诉类型检查器"相信我，这个属性不会为 null/undefined"
• declare 则表示"这个属性已经以其他方式定义，不需要生成任何运行时代码"

在类继承的场景下，declare 能完美保持原型链的工作方式，而不会像 ! 那样在 useDefineForClassFields 启用时产生意外的实例属性。

最佳实践建议

对于类似 ProseMirror 这样的库项目，建议：

1. 对于所有通过原型或其他方式初始化的属性，统一使用 declare 修饰符
2. 避免混用 ! 和原型赋值模式
3. 在文档中明确说明这些设计选择，帮助贡献者理解

总结

ProseMirror 的光标消失问题展示了现代 JavaScript/TypeScript 开发中一个典型的兼容性问题。通过理解原型继承、类字段定义方式和 TypeScript 编译器选项的交互，我们不仅能够解决眼前的问题，还能为未来的代码质量打下更好的基础。

declare 修饰符的使用既解决了当前问题，又保持了代码的优雅性和性能优势，是这类场景下的理想解决方案。