TypeScript 中文网: 文档

声明文件部分旨在教你如何编写高质量的 TypeScript 声明文件。我们需要假设基本熟悉 TypeScript 语言才能开始。

¥The Declaration Files section is designed to teach you how to write a high-quality TypeScript Declaration File. We need to assume basic familiarity with the TypeScript language in order to get started.

如果你还没有，你应该阅读 TypeScript 手册以熟悉基本概念，尤其是类型和模块。

¥If you haven’t already, you should read the TypeScript Handbook to familiarize yourself with basic concepts, especially types and modules.

了解 .d.ts 文件如何工作的最常见情况是你正在键入一个没有类型的 npm 包。在这种情况下，你可以直接跳转到模块 .d.ts。

¥The most common case for learning how .d.ts files work is that you’re typing an npm package with no types. In that case, you can jump straight to Modules .d.ts.

声明文件部分分为以下部分。

¥The Declaration Files section is broken down into the following sections.

声明参考手册

¥Declaration Reference

当我们只有底层库的示例来指导我们时，我们经常面临编写声明文件的问题。声明参考手册部分展示了许多常见的 API 模式以及如何为每个模式编写声明。本指南针对的是 TypeScript 新手，他们可能还不熟悉 TypeScript 中的每一种语言结构。

¥We are often faced with writing a declaration file when we only have examples of the underlying library to guide us. The Declaration Reference section shows many common API patterns and how to write declarations for each of them. This guide is aimed at the TypeScript novice who may not yet be familiar with every language construct in TypeScript.

库结构

¥Library Structures

库结构指南可帮助你了解常见的库格式以及如何为每种格式编写正确的声明文件。如果你正在编辑现有文件，你可能不需要阅读本节。强烈建议新声明文件的作者阅读本节，以正确理解库的格式如何影响声明文件的编写。

¥The Library Structures guide helps you understand common library formats and how to write a proper declaration file for each format. If you’re editing an existing file, you probably don’t need to read this section. Authors of new declaration files are strongly encouraged to read this section to properly understand how the format of the library influences the writing of the declaration file.

在模板部分，你会发现许多声明文件，它们可作为编写新文件时的有用起点。如果你已经知道你的结构是什么，请参阅边栏中的 d.ts 模板部分。

¥In the Template section you’ll find a number of declaration files that serve as a useful starting point when writing a new file. If you already know what your structure is, see the d.ts Template section in the sidebar.

该做什么和不该做什么

¥Do’s and Don’ts

可以轻松避免声明文件中的许多常见错误。该做什么和不该做什么部分标识了常见错误，描述了如何检测它们以及如何修复它们。每个人都应该阅读本节以帮助自己避免常见错误。

¥Many common mistakes in declaration files can be easily avoided. The Do’s and Don’ts section identifies common errors, describes how to detect them, and how to fix them. Everyone should read this section to help themselves avoid common mistakes.

深入探讨

¥Deep Dive

对于对声明文件的工作原理感兴趣的经验丰富的作者，深入探讨部分解释了声明编写中的许多高级概念，并展示了如何利用这些概念来创建更清晰、更直观的声明文件。

¥For seasoned authors interested in the underlying mechanics of how declaration files work, the Deep Dive section explains many advanced concepts in declaration writing, and shows how to leverage these concepts to create cleaner and more intuitive declaration files.