callback-this-type

如果这是其 API 的一部分，就为回调中的 this 指定类型

概述

当库调用用户提供的回调，并为其指定特定的 this 上下文时，该上下文就是 API 的一部分。TypeScript 允许将 this 声明为函数的第一个参数，尽管它并不是真正的参数。这样可以记录并强制要求使用预期的上下文。

何时使用此技能

• 回调使用 this
• API 提供 this 上下文
• 为事件处理程序指定类型
• 库在回调中设置 this
• 记录回调上下文

铁律

如果 this 是回调 API 的一部分，就将其指定为第一个参数的类型。这样可以记录预期的上下文，并启用自动补全。

示例

// BAD: this is untyped
interface EventEmitter {
  on(event: string, handler: (data: any) => void): void;
}

// User doesn't know what 'this' is:
emitter.on('click', function(data) {
  this.something; // What properties does this have?
});

// GOOD: this is typed
interface EventEmitter {
  on(
    event: string,
    handler: (this: EventContext, data: any) => void
  ): void;
}

interface EventContext {
  target: Element;
  timestamp: number;
  preventDefault(): void;
}

// User now gets autocompletion for 'this'
emitter.on('click', function(data) {
  this.target; // Autocomplete works!
  this.timestamp; // Typed as number
});

参考资料

• Dan Vanderkam 著，《Effective TypeScript》第 2 版
• 第 69 条：如果 this 是 API 的一部分，就为回调中的 this 指定类型