如何在TypeScript .d.ts声明文件中正确声明Countly.q.push方法

你之前编写的声明无法生效，核心是两个语法和类型定义的错误：

• 语法层面：TS不支持export function q.push()这类带点的函数名声明，点代表对象的嵌套属性，必须逐层声明对象结构后再定义内层方法
• 类型层面：没有将push方法的参数定义为固定顺序的元组类型，TS无法识别数组不同位置的参数类型约束，自然不会生效。

可直接使用的声明代码 #

将以下内容写入你的.d.ts类型声明文件即可：

declare module 'countly-sdk-web' {
  // Countly事件标准结构，除必填key外其余均为可选字段
  interface CountlyEvent {
    key: string;
    count?: number;
    sum?: number;
    dur?: number;
    segmentation?: Record<string, string | number | boolean>;
  }

  // Countly异步队列支持的所有调用格式，以元组联合类型定义
  type CountlyQueueTask = 
    | ['add_event', CountlyEvent]
    // 后续需要支持其他q.push调用时，按相同格式追加即可，例如：
    // | ['track_pageview', pageUrl: string]
    // | ['track_sessions']

  interface CountlyStatic {
    q: {
      push: (task: CountlyQueueTask) => void;
    };
  }

  const Countly: CountlyStatic;
  export default Countly;
}

类型校验效果 #

声明完成后，业务代码中的调用会自动获得精准的类型提示和校验：

• 符合规则的调用可正常通过校验：

import Countly from 'countly-sdk-web';

Countly.q.push(['add_event', {
  key: "action_open_web"
}]);

• 不符合规则的调用会被TS直接标记错误，包括但不限于：
  • 第一个方法名字面量拼写错误
  • 事件对象漏填必填的key字段
  • 传入字段的值类型不符合Countly要求

内容的提问来源于stack exchange，提问作者Akhmad Zaki