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 全局变量.
动手试一试
- JSON 到 TypeScript
Generated 接口能 serve as basis for declaration files.
- Code Minifier
Declaration files 编译到 无 — observe 空输出.
常见错误
错误写法
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 等等。
动手做项目
通过引导式项目应用所学,含起始代码与解决方案。
解读错误信息
用大白话解释常见错误——什么意思、为什么发生、如何修复。