Skip to content

Declaration Files (.d.ts)

描述 JavaScript 库使用 .d.ts declaration files and declare keyword.

你将学到

  • 什么 .d.ts files 是 and 为什么它们包含否 implementation
  • Using declare keyword for ambient declarations
  • 如何 @类型包 provide 类型 for JS 库
  • 编写自定义 declarations for untyped 模块

概念讲解

Ambient Declarations

A declaration file (.d.ts) contains type declarations only — no runtime code. It describes the types of an existing JavaScript library so TypeScript can type-check code that uses it. The declare keyword tells the compiler "this exists at runtime, trust me" without generating any JavaScript. For example, declare const VERSION: string; tells TypeScript a global VERSION constant exists without emitting code for it.

@types Packages

Most popular JavaScript libraries have community-maintained type definitions published as @类型/库 packages on npm (via the DefinitelyTyped repository). You install them with npm 安装 --保存-dev @类型/lodash and TypeScript automatically finds them. If a library ships its own types (look for a 类型 or typings field in package.json), you do not need a separate @类型 package.

Writing Custom Declarations

When a library has no types and no @类型 package, you can write a custom declaration. Create a .d.ts file and declare the module: declare 模块 "my-lib" { 导出 函数 doSomething(x: 字符串): 数字; }. For global variables, use declare 全局 { 接口 Window { myVar: 字符串; } }. Custom declarations bridge the gap between typed TypeScript code and untyped JavaScript libraries.

示例代码

              // --- globals.d.ts — ambient declarations (no runtime code) ---

// Declare a global variable that exists at runtime.
declare const APP_VERSION: string;

// Declare a global function.
declare function legacyFormat(date: Date): string;

// Augment the Window interface with a custom property.
declare global {
  interface Window {
    myAnalytics: (event: string) => void;
  }
}

// Declare an untyped module.
declare module "legacy-lib" {
  export function parse(input: string): Record<string, unknown>;
  export const version: string;
}

// --- main.ts — using the declarations ---
// These exist at runtime (injected by a script tag or the environment).
console.log(APP_VERSION);
console.log(legacyFormat(new Date()));
window.myAnalytics("page_view");

// import { parse } from "legacy-lib";
// const data = parse('{"x":1}');
            

Declaration files (.d.ts) 描述类型不使用 implementation. declare keyword asserts 运行时 existence. @类型包 provide 类型 for JS 库. 自定义 declarations handle untyped 模块 and 全局变量.

动手试一试

常见错误

错误写法

Putting 运行时 code in .d.ts declaration file

正确做法

Declaration files 包含类型仅 — 否 implementations. 如果你 需要运行时 code, use regular .ts file. 编译器做 不 emit JavaScript 从 .d.ts files.

错误写法

不安装 @类型包 for JavaScript dependencies

正确做法

检查如果 @类型/包 exists for 每个 JS 库你 use. 不使用它, 库是 输入 as 任何, losing 所有类型 safety for 那个 dependency.

查阅不认识的术语

新手友好的术语表用大白话解释编程术语——变量、函数、DOM、Promise 等等。

查看术语表

动手做项目

通过引导式项目应用所学,含起始代码与解决方案。

查看项目

解读错误信息

用大白话解释常见错误——什么意思、为什么发生、如何修复。

查看错误