介绍

声明文件部分旨在教你如何编写高质量的 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.

发布到 npm

¥Publish to npm

发布 部分解释了如何将声明文件发布到 npm 包,并展示了如何管理依赖包。

¥The Publishing section explains how to publish your declaration files to an npm package, and shows how to manage your dependent packages.

查找并安装声明文件

¥Find and Install Declaration Files

对于 JavaScript 库用户,引用 部分提供了几个简单的步骤来定位和安装相应的声明文件。

¥For JavaScript library users, the Consumption section offers a few simple steps to locate and install corresponding declaration files.