高品質TypeScript 類型定義的儲存庫。
您也可以閱讀此自述文件的西班牙語、한국어、Русский、簡體中文、葡萄牙語、義大利語、日本語和法語！
管理手冊連結
Definely Typed 最近已更改為適當的pnpm monorepo；您可能需要重新閱讀本文檔以了解此儲存庫中套件佈局的變更。
至少，您可能需要git clean -fdx儲存庫（或 Windows 上的node ./scripts/clean-node-modules.js ）來清理node_modules並執行pnpm install --filter .安裝工作區根目錄。有關pnpm install的更多信息，請參閱其他部分。
此部分追蹤儲存庫和發布過程的運作狀況。這對於遇到 PR 和套件任何問題的貢獻者可能會有所幫助。
如果這裡出現任何錯誤或上述任何內容失敗，請在 TypeScript 社群 Discord 伺服器上的 Definely Typed 頻道中告知我們。
請參閱 TypeScript 手冊。
這是首選方法。例如：
npm install --save-dev @types/node若要為作用域模組安裝類型，請刪除@並在作用域後面新增雙重底線。例如，要安裝@babel/preset-env的類型：
npm install --save-dev @types/babel__preset-env然後編譯器應該會自動包含這些類型。如果您不使用模組，您可能需要新增types引用：
/// <reference types="node" />請參閱手冊中的更多內容。
對於 npm 套件“foo”，其類型將位於“@types/foo”。
如果您的套件使用其package.json中的types或typings鍵指定了類型，則 npm 註冊表將顯示該套件具有可用的綁定，如下所示：
您可以像往常一樣克隆整個存儲庫，但它很大並且包含大量類型包目錄。這將需要一些時間來克隆，並且可能會變得不必要的笨拙。
對於僅包含與您相關的類型套件的更易於管理的克隆，您可以使用 git 的sparse-checkout和--filter功能。這將減少克隆時間並提高 git 效能。
️ 這需要最低 git 版本 2.27.0，這可能比大多數機器上的預設版本更新。舊版本中提供了更複雜的過程，但本指南未涵蓋。
git clone --sparse --filter=blob:none <forkedUrl>--sparse初始化稀疏簽出文件，以便工作目錄僅以儲存庫根目錄中的文件開始。--filter=blob:none將包含所有提交歷史記錄但排除文件，僅根據需要取得它們。git sparse-checkout add types/<type> types/<dependency-type> ...pnpm test <package to test> 。當您建立 PR 來編輯現有套件時， dt-bot應@提及該套件的所有者。如果沒有，您可以在與 PR 相關的評論中自行執行此操作。
如果您是庫作者並且您的套件是用 TypeScript 編寫的，請將生成的聲明檔案捆綁在您的套件中，而不是發佈到 Definely Typed。您也可以使用 JSDoc 進行類型註釋，從 JavaScript 檔案產生聲明檔案。
如果您要為 npm 套件新增類型，請建立一個同名的目錄。如果您要新增類型的套件不在 npm 上，請確保您為其選擇的名稱不會與 npm 上的套件名稱衝突。 （您可以使用npm info <my-package>檢查<my-package>套件是否存在。）
你的包包應該有這樣的結構：
| 文件 | 目的 |
|---|---|
index.d.ts | 這包含包的類型。 |
<my-package>-tests.ts | 這包含測試打字的範例程式碼。該程式碼不會運行，但會進行類型檢查。 |
tsconfig.json | 這允許您在包內運行tsc 。 |
.eslintrc.json | （很少）僅需要停用為 eslint 編寫的 lint 規則。 |
package.json | 包含套件的元數據，包括其名稱、版本和依賴項。 |
.npmignore | 指定要包含在套件中的檔案。 |
透過執行npx dts-gen --dt --name <my-package> --template module產生這些檔案。請參閱 dts-gen 中的所有選項。
如果除了index.d.ts之外還有.d.ts文件，請確保在index.d.ts或測試中引用它們。
Definely Typed 成員會定期監視新的 PR，但請記住，其他 PR 的數量可能會減慢速度。
有關良好的範例包，請參閱 base64-js。
當套件捆綁自己的類型時，應將類型從 Definely Typed 中刪除以避免混淆。
您可以透過執行pnpm run not-needed <typingsPackageName> <asOfVersion> [<libraryName>]來刪除它。
<typingsPackageName> ：這是要刪除的目錄的名稱。<asOfVersion> ：存根將使用此版本發佈到@types/<typingsPackageName> 。應高於目前發布的任何版本，並且應為 npm 上<libraryName>的版本。<libraryName> ：取代 Definely Typed 類型的 npm 套件的名稱。通常這與<typingsPackageName>相同，在這種情況下您可以省略它。如果套件從未出現在「Definitely Typed」上，則無需將其新增至notNeededPackages.json 。
透過執行pnpm test <package to test>來測試您的更改，其中<package to test>是您的套件的名稱。您需要從 DefinelyTyped 目錄中執行它，因為單一 package.json 不定義測試腳本。
此腳本使用 dtslint 針對您的 dts 檔案執行 TypeScript 編譯器。
準備好所有變更後，請使用pnpm run test-all來查看變更如何影響其他模組。
attw ) 檢查dtslint 包括來自 @arethetypeswrong/cli 的模組格式和package.json配置檢查。只有當可以在 npm 上找到與 SemVer 主要相容的實作套件以與 DefinelyTyped 套件進行比較時，才會執行檢查。 （將跳過在package.json中標記為nonNpm的 DefinitelyTyped 套件。）
目前，許多軟體包未通過attw檢查，需要修復。為了讓我們取得增量進展，當attw.json中的failingPackages中列出套件時，失敗的attw檢查不會使dtslint運行失敗，但它們仍將在pnpm test my-package輸出中報告。如果修復該包，請將其從failingPackages中刪除，以便attw檢查可以開始失敗的dtslint運行。
attw報告的所有問題都在輸出中連結了文件。一些有助於避免問題的經驗法則：
如果實作套件在其package.json中使用它們，DefinitelyTyped 套件中的package.json必須具有匹配的type和exports欄位。例如，如果實作package.json如下所示：
{
"name" : " my-package " ,
"version" : " 1.0.1 " ,
"type" : " module " ,
"main" : " dist/cjs/index.cjs " ,
"exports" : {
"." : {
"import" : " ./dist/esm/index.js " ,
"require" : " ./dist/cjs/index.cjs "
},
"./subpath" : {
"import" : " ./dist/esm/subpath.js " ,
"require" : " ./dist/cjs/subpath.cjs "
}
}
}那麼 DefinelyTyped package.json應該類似：
{
"name" : "@types/my-package" ,
"version" : "1.0.9999" ,
"type" : "module" ,
"types" : "index.d.ts" ,
"exports" : {
"." : {
"import" : "./index.d.ts" ,
"require" : "./index.d.cts"
} ,
"./subpath" : {
"import" : "./subpath.d.ts" ,
"require" : "./subpath.d.cts"
}
}
}請注意，每個exports路徑都會被反映，並且每個 JavaScript 文件都有一個具有匹配文件擴展名的相應聲明文件 - .d.ts文件類型為.js文件，而不是.mjs或.cjs文件！
當實作套件使用module.exports = ...時，DefinitelyTyped 套件應該使用export = ，而不是export default 。 （或者，如果module.exports只是命名屬性的對象，則 DefinelyTyped 套件可以使用一系列命名導出。）糾正此問題的最常見障礙是除了主導出之外如何導出類型的混亂。例如，假設這些類型錯誤地使用了export default ：
export interface Options {
// ...
}
export default function doSomething ( options : Options ) : void ;將export default更改為export =會產生錯誤：
export interface Options {
// ...
}
declare function doSomething ( options : Options ) : void ;
export = doSomething ;
// ^^^^^^^^^^^^^^^^^
// Error: An export assignment cannot be used in a module with other exported elements.要解決此問題，請將類型移至與函數同名的命名空間內：
declare namespace doSomething {
export interface Options {
// ...
}
}
declare function doSomething ( options : doSomething . Options ) : void ;
export = doSomething ;如果您需要協助解決問題，請在 TypeScript 社群 Discord 伺服器上的 DefinelyTyped 頻道中提問。
如果您要為 npm 套件新增類型，請建立一個同名的目錄。如果您要新增類型的套件不在 npm 上，請在package.json中設定"nonNpm": true ，並確保您為其選擇的名稱不會與 npm 上的套件名稱衝突。 （您可以使用npm info <my-package>檢查<my-package>套件是否存在。）
在極少數情況下， nonNpm可能會被設定為"conflict" ，這表示 npm 上有一個同名的包，但類型故意與該包衝突。對於定義環境（如@types/node的套件或虛擬包（如aws-lambda來說，情況可能是如此。盡可能避免使用"conflict" 。
<my-package>-tests.ts應該有一個<my-package>-tests.ts文件，它被視為您的測試文件，以及它導入的任何*.ts文件。如果您在模組的資料夾中沒有看到任何測試文件，請建立一個<my-package>-tests.ts 。這些檔案用於驗證從*.d.ts檔案匯出的 API，這些檔案是作為@types/<my-package>提供。他們自己不發貨。
對*.d.ts檔案的更改應包括相應的*.ts檔案更改，該更改顯示正在使用的 API，以便有人不會意外破壞您所依賴的程式碼。例如，對.d.ts檔案中的函數進行的變更向函數新增了參數：
index.d.ts ：
- export function twoslash(body: string): string
+ export function twoslash(body: string, config?: { version: string }): string <my-package>-tests.ts ：
import {twoslash} from "./"
// $ExpectType string
const result = twoslash("//")
+ // Handle options param
+ const resultWithOptions = twoslash("//", { version: "3.7" })
+ // When the param is incorrect
+ // @ts-expect-error
+ const resultWithOptions = twoslash("//", { })如果您想知道從哪裡開始測試程式碼，原始套件的自述文件中的範例是一個很好的起點。
您可以從該儲存庫的根目錄使用npm test <package to test>驗證您的更改，這會考慮更改的檔案。
使用$ExpectType斷言表達式屬於給定類型，使用@ts-expect-error斷言編譯錯誤。範例：
// $ExpectType void
f ( 1 ) ;
// @ts-expect-error
f ( "one" ) ;有關更多詳細信息，請參閱 dtslint 自述文件。
.eslintrc.json如果由於某種原因需要停用 lint 規則，請針對特定行停用它：
// eslint-disable-next-line no-const-enum
const enum Const {
One ,
}
const enum Enum { // eslint-disable-line no-const-enum
Two ,
}您仍然可以使用 .eslintrc.json 停用規則，但不應在新套件中停用。禁用整個包的規則會使審查變得更加困難。
tsconfig.json tsconfig.json應該將noImplicitAny 、 noImplicitThis 、 strictNullChecks和strictFunctionTypes設為true 。
您可以編輯tsconfig.json以新增新的測試檔案、新增"target": "es6" （非同步函數所需）、新增至"lib"或新增"jsx"編譯器選項。
esModuleInterop / allowSyntheticDefaultImports TL;DR： tsconfig.json中不允許使用esModuleInterop和allowSyntheticDefaultImports 。
這些選項使得為 CJS 匯出編寫預設導入成為可能，從而對 Node 和某些 JS 捆綁器中的 CJS 和 ES 模組之間的內建互通性進行建模：
// component.d.ts declare class Component { } // CJS export, modeling `module.exports = Component` in JS export = Component ; // index.d.ts // ESM default import, only allowed under 'esModuleInterop' or 'allowSyntheticDefaultExports' import Component from "./component" ;由於
index.d.ts中導入的編譯時有效性取決於特定的編譯設置，而您的類型的用戶不會繼承這些設置，因此在DefinitelyTyped中使用此模式將迫使用戶更改自己的編譯設置，這可能是不正確的為了他們的運行時間。相反，您必須為 CJS 匯出編寫 CJS 匯入，以確保廣泛的、獨立於配置的兼容性：// index.d.ts // CJS import, modeling `const Component = require("./component")` in JS import Component = require ( "./component" ) ;
package.json該文件是必需的，並且應遵循以下範本：
{
"private" : true ,
"name" : "@types/PACKAGE-NAME" ,
"version" : "1.2.9999" ,
"projects" : [
"https://aframe.io/"
] ,
"dependencies" : {
"@types/DEPENDENCY-1" : "*" ,
"@types/DEPENDENCY-2" : "*"
} ,
"devDependencies" : {
"@types/PACKAGE-NAME" : "workspace:."
} ,
"owners" : [
{
"name" : "Your Name Here" ,
"githubUsername" : "ghost"
}
]
} package.json指定所有依賴項，包括其他@types套件。
您必須將非@types依賴項新增至允許的外部相依性清單。皮卡迪就是一個很好的例子。這些添加內容得到了維護者的批准，這使我們有機會確保@types包不依賴惡意包。
如果實作套件使用 ESM 並指定"type": "module" ，那麼您應該修改 package.json 以符合：
{
"type" : " module "
}如果實作套件的 package.json 中有exports這也適用。
絕對類型化允許在package.json中使用peerDependencies 。對等依賴關係可以幫助防止套件管理器意外安裝太新的版本或同一套件的多個版本的情況。然而，對等依賴也有缺點；套件管理器在對等依賴關係的處理上有所不同（例如， yarn不會自動安裝它們， npm需要--legacy-peer-deps來處理不匹配）。因此，引入新的對等依賴項的 PR 需要維護者批准，並且應僅限於特定情況。
一般來說，如果上游套件對相同套件（或其類型）具有對等依賴關係，則類型套件僅應具有對等依賴關係。例如，React 元件的 DT 套件可以指定對@types/react@*的對等依賴，因為使用者首先需要安裝@types/react才能使用 JSX。如果使用者在其專案中安裝了@types/react@16 ，但 npm 上有更新版本的@types/react ，則對等依賴關係可能會幫助套件管理器選擇@types/react@16而不是該較新版本。類似地， chai-as-promised對chai有對等依賴，因此@types/chai-as-promised應該對@types/chai有對等依賴。
在某些情況下，上游套件對類型包沒有對等依賴關係，但對等依賴關係仍然是合適的。這些通常是上游套件擴展另一個套件並假設它存在的情況，因此應該在擴展另一個套件時聲明對等依賴關係，但沒有。例如， chai-match-pattern擴展了chai ，但沒有聲明對chai對等依賴關係，但需要它才能發揮作用。 @types/chai-match-pattern應該對@types/chai有對等依賴關係。
如果由於上游套件中的常規依賴關係，一個套件只是將另一個套件的類型公開作為其 API 的一部分，則它不應該使用對等依賴關係。例如， express的"dependencies"中有qs 。用戶安裝express時，不需要手動安裝qs 。同樣， @types/express在其"dependencies"中有@types/qs 。將@types/qs宣告為@types/express的對等依賴項是不正確的，因為這需要一些下游消費者手動安裝@types/qs 。
.npmignore該文件定義了每個@types包中要包含哪些文件。它必須採取特定的形式。對於儲存庫中只有一個版本的軟體包：
*
! ** / * .d.ts
! ** / * .d.cts
! ** / * .d.mts
! ** / * .d. * .ts這就是說「忽略所有文件，但不要忽略任何聲明文件」。對於儲存庫中具有多個版本的軟體包，「最新」版本（位於頂層）應包含類似以下內容的內容：
*
! ** / * .d.ts
! ** / * .d.cts
! ** / * .d.mts
! ** / * .d. * .ts
/ v15 /
/ v16 /
/ v17 /這與之前的.npmignore相同，但忽略每個版本化的子目錄。
如果此文件包含錯誤內容並提供預期值，CI 將失敗。無論該文件包含什麼內容，發布者都只會發布聲明文件。
pnpm dprint fmt -- 'path/to/package/**/*.ts' 。.vscode/settings.template.json （或其他編輯器的等效項）在儲存時使用 VS Code dprint 擴充功能進行格式化function sum(nums: number[]): number ：如果函數不寫入其參數，則使用ReadonlyArray 。interface Foo { new(): Foo; } ：這定義了一種可新建的物件類型。您可能想要declare class Foo { constructor(); } 。const Class: { new(): IClass; } : 更喜歡使用類別宣告class Class { constructor(); }不是新的常數。getMeAT<T>(): T ：如果型別參數沒有出現在任何參數的型別中，那麼你並沒有真正擁有泛型函數，你只是有一個偽裝的型別斷言。偏好使用真實型別斷言，例如getMeAT() as number 。可接受型別參數的範例： function id<T>(value: T): T; 。不可接受的範例： function parseJson<T>(json: string): T; 。例外： new Map<string, number>()可以。Function和Object類型幾乎從來都不是一個好主意。在 99% 的情況下，可以指定更具體的類型。例如，函數的(x: number) => number和物件的{ x: number, y: number } 。如果類型完全不確定， any是正確的選擇，而不是Object 。如果關於該類型的唯一已知事實是它是某個對象，請使用類型object ，而不是Object或{ [key: string]: any } 。var foo: string | any ：當在聯合類型中使用any時，結果類型仍然是any 。因此，雖然此類型註釋的string部分可能看起來很有用，但實際上它比簡單地使用any不提供額外的類型檢查。根據意圖，可接受的替代方案可以是any 、 string或string | object 。TL;DR：不要修改
.github/CODEOWNERS，始終修改package.json中的所有者清單。
DT 有「定義擁有者」的概念，即想要維護特定模組類型品質的人。
若要將自己新增為定義擁有者，請修改package.json中的owners陣列：
"owners" : [
{
"name" : " Some Person " ,
"githubUsername" : " somebody "
},
{
"name" : " Some Corp " ,
"url" : " https://example.org "
}
]請注意，此列表不用於提供貢獻；它僅用於管理公關評論。
定義擁有者每週一次同步到檔案 .github/CODEOWNERS，這是我們的事實來源。
Definely Typed 是 GitHub 上最活躍的儲存庫之一。您可能想知道這個項目是如何產生的。 @johnnyreilly 寫了《Definitely Typed》的歷史。它講述了 Definely Typed 早期的故事，從 @borisyankov 創建的儲存庫，到它成為 TypeScript 生態系統的關鍵部分。您可以在這裡閱讀Definitely Typed 的故事。
@types套件之間到底有什麼關係？感謝 DefinelyTyped-tools， master分支會自動發佈到 npm 上的@types範圍。
這取決於情況，但大多數拉取請求將在一周內合併。有些 PR 可以由模組所有者合併，並且合併速度更快。大致：
僅更改模組類型並具有相應測試更改的 PR 合併速度會更快
已定義的package.json中列出的所有者批准的 PR 通常合併得更快；新定義的 PR 將需要更多時間，因為它們需要維護者進行更多審查。每個 PR 在合併之前都會由 TypeScript 或 Definely Typed 團隊成員進行審核，因此請耐心等待，人為因素可能會導致延遲。檢查新拉取請求狀態板以查看維修人員處理開放 PR 時的進度。
對於非常流行的模組的更改，例如 Node/Express/Jest 在 npm 上每周有數百萬次下載，對貢獻的要求有點高。這些項目的變化可能會產生巨大的生態系統影響，因此我們非常謹慎地對待它們的變化。這些模組需要 DT 維護者的簽字和模組擁有者的熱情支持。通過這個的門檻可能相當高，而且 PR 通常會因為沒有冠軍而變得陳舊。如果您發現沒有人做出承諾，請嘗試讓您的公關焦點較小。
@types npm 包什麼時候更新？npm 包應該在一小時內更新。如果已經超過一個小時，請在 TypeScript 社群 Discord 伺服器上的 Definely Typed 頻道上提及 PR 編號，目前維護者將找到正確的團隊成員進行調查。
<reference types="" />還是導入？如果您引用的模組是一個模組（使用export ），請使用匯入。如果您引用的模組是環境模組（使用declare module ）或只是宣告全域變量，請使用<reference types="" /> 。
tsconfig.json缺少"noImplicitAny": true 、 "noImplicitThis": true或"strictNullChecks": true 。那麼他們錯了，我們還沒有註意到。您可以透過提交拉取請求來修復它們。
是的，使用 dprint。我們建議您的編輯器使用 dprint 擴充功能。
或者，您可以啟用 git hook，它會自動格式化您的程式碼。運行pnpm run setup-hooks 。然後，當您提交時， dprint fmt命令將在更改的檔案上執行。如果您利用部分克隆，請確保在執行setup-hooks腳本之前呼叫git sparse-checkout add .husky來檢查 git hooks。
拉取請求不需要合併正確的格式。任何未格式化的程式碼在合併後都會自動重新格式化。
如果您是 VS Code 用戶，我們建議將
.vscode/settings.template.json檔案複製到.vscode/settings.json。此範本將 dprint VS Code 擴充功能設定為儲存庫中的預設格式化程式。
以下是目前請求的定義。
如果類型是 Web 標準的一部分，則應將它們貢獻給 TypeScript-DOM-lib-generator，以便它們可以成為預設lib.dom.d.ts的一部分。
如果根本沒有 JavaScript 原始程式碼，例如，如果您正在編寫幫助程式類型或規範類型，則您應該自己發布類型，而不是在 Definely Typed 上發布。因為它們旨在為現有 JavaScript 程式碼提供類型，所以@types套件並不意味著直接導入。也就是說，您不應該建立一個像import type { ... } from "@types/foo"這樣使用的絕對類型包。當沒有安裝foo時，您也不應該期望編寫import type { ... } from "foo" 。
這與為僅瀏覽器的 JavaScript 程式庫提供類型或為整個環境（如 Node、Bun 等）提供類型不同。在那裡，類型要么隱式解析，要么使用/// <references types="foo" /> 。
有些套件（例如 chai-http）會匯出函數。
使用 ES6 風格導入以import * as foo from "foo";導致錯誤：
錯誤 TS2497：模組“foo”解析為非模組實體，無法使用此構造導入。
可以透過將函數宣告與同名的空命名空間合併來抑制此錯誤，但不鼓勵這種做法。這是關於這個問題的一個經常被引用的 Stack Overflow 答案。
使用import foo = require("foo");導入模組比較合適。句法。儘管如此，如果您想使用預設導入，例如import foo from "foo";你有兩個選擇：
--allowSyntheticDefaultImports編譯器選項。--esModuleInterop編譯器選項。 export = ，但我更喜歡使用預設導入。我可以將export =更改為export default嗎？與上一個問題一樣，請參閱使用--allowSyntheticDefaultImports或--esModuleInterop編譯器選項。
如果類型定義準確，請勿變更。對於 npm 包，如果node -p 'require("foo")'用於導入模組，則export =是準確的；如果node -p 'require("foo").default'用於導入模組，則export default是準確的。
然後，您將透過在package.json中指定"minimumTypeScriptVersion": "XY"來設定支援的最低版本。
但是，如果您的專案需要同時維護與 3.7 及更高版本相容的類型以及與 3.6 或更低版本相容的類型，則需要使用typesVersions功能。您可以在官方 TypeScript 文件中找到此功能的詳細說明。
這是一個幫助您入門的簡短範例：
您必須將typesVersions新增至package.json ：
{
"private" : true ,
"types" : " index " ,
"typesVersions" : {
"<=3.6" : { "*" : [ " ts3.6/* " ] }
}
}在 types 目錄中建立typesVersions欄位中提到的子目錄（本例為ts3.6/ ）。 ts3.6/將支援 TypeScript 3.6 及更低版本，因此請複製現有類型和測試。
傳回套件的根目錄，新增您要使用的 TypeScript 3.7 功能。當人們安裝該套件時，TypeScript 3.6 及更低版本將從ts3.6/index.d.ts開始，而 TypeScript 3.7 及更高版本將從index.d.ts開始。
你可以看看藍鳥的例子。
這可能屬於 TypeScript-DOM-lib-generator。請參閱那裡的指南。如果該標準仍然是草案，那麼它就屬於這裡。使用以dom-開頭的名稱，並包含指向標準的連結作為package.json中的「Project」連結。當它脫離草稿模式時，我們可能會將其從 Definely Typed 中刪除，並棄用相關的@types套件。
注意：本節的討論假設您熟悉語意版本控制
每個 Definely Typed 套件在發佈到 npm 時都會進行版本控制。 DefinitiveTyped-tools（將@types套件發佈到npm的工具）將使用package.json中列出的major.minor.9999版本號碼來設定聲明包的版本。例如，以下是撰寫本文時 Node 版本20.8.x的類型宣告的前幾行：
{
"private" : true ,
"name" : " @types/node " ,
"version" : " 20.8.9999 "
}由於版本列出為20.8.9999 ，因此@types/node套件的 npm 版本也將為20.8.x 。請注意， package.json中的版本應僅包含major.minor版本（例如10.12 ），後面接著.9999 。這是因為庫包和類型聲明包之間只有主要和次要版本號是對齊的。 （ .9999是為了確保本地開發過程中本地@types包始終是最新的。）類型聲明包的補丁版本號（例如20.8.0中的.0 ）被Definitely Typed初始化為零，並且每次都會遞增一個新的@types/node套件發佈到 npm，用於對應庫的相同主要/次要版本。
有時類型聲明包版本和庫包版本可能會不同步。以下是一些常見原因，依照給圖書館使用者帶來不便的程度排序。只有最後一種情況通常是有問題的。
@types套件之間的版本相對應，那麼npm update通常應該可以正常運作。 ❗ 如果您要更新庫的類型聲明，請務必在package.json中設定major.minor版本以符合您正在記錄的庫版本！ ❗
語意版本控制要求具有重大變更的版本必須增加主版本號。例如，在3.5.8版本之後刪除公開匯出函數的程式庫必須在下一個版本中將其版本提升到4.0.0 。此外，當庫的4.0.0版本發佈時，它的 Definely Typed 類型聲明包也應該更新到4.0.0 ，包括對庫 API 的任何重大更改。
許多庫都有大量的開發人員安裝基礎（包括使用該庫作為依賴項的其他軟體包的維護人員），他們不會立即遷移到具有重大更改的新版本，因為維護人員可能需要幾個月的時間才能重寫程式碼以適應新版本。同時，舊庫版本的使用者仍然可能希望更新舊版本的類型聲明。
如果您打算繼續更新舊版本的庫類型聲明，您可以建立以當前（即將成為「舊」）版本命名的新子資料夾（例如/v2/ ），並將現有檔案從目前版本複製到其中。
建立新版本資料夾時，請確保package.json的version欄位已更新；只要需要， pnpm就會自動解析到此版本化套件。如果儲存庫中的其他套件需要依賴這個新版本，請確保它們的package.json也被更新。
例如，如果我們建立types/history/v2 ，它的package.json將如下所示：
{
"private" : true ,
"name" : " @types/history " ,
"version" : " 2.4.9999 "
}另一個包可以透過指定來選擇此版本：
{
"private" : true ,
"name" : " @types/browser-sync " ,
"version" : " 2.26.9999 " ,
"dependencies" : {
"@types/history" : " ^2 "
}
}另外， /// <reference types=".." />不適用於路徑映射，因此依賴項必須使用import 。
@types包總是鍵入相同版本的包，因此@types/[email protected]代表[email protected] 。因此，所有更改，無論是否破壞，都會作為補丁修訂版發布，除非與主要/次要版本一起更改目標軟體包版本（無論是否巧合）。
當談到重大變更時，DT 維護者會考慮軟體包的受歡迎程度、擬議的重大變更的優點、用戶修復程式碼所需的工作量，以及變更是否可以合理地推遲到可以同步為止。重大變化。
TypeScript 手冊包含有關編寫定義的優秀一般信息，以及此範例定義文件，該文件展示瞭如何使用 ES6 樣式模組語法建立定義，同時也指定可用於全域範圍的物件。這項技術在big.js的定義中得到了實際演示，big.js 是一個可以透過網頁上的腳本標記全域載入或透過 require 或 ES6 樣式導入導入的函式庫。
若要測試您的定義在全域引用或作為匯入模組時如何使用，請建立一個test資料夾並在其中放置兩個測試檔案。將一個命名YourLibraryName-global.test.ts ，另一個命名YourLibraryName-module.test.ts 。全域測試檔案應根據在網頁上載入的腳本中的使用方式來執行定義，其中該程式庫在全域範圍內可用 - 在這種情況下，您不應指定 import 語句。模組測試檔案應根據導入時的使用方式（包括import語句）來執行定義。如果您在tsconfig.json檔案中指定files屬性，請確保包含兩個測試檔案。一個實用的例子也可以在big.js定義上取得。
請注意，不需要在每個測試檔案中充分行使定義 - 僅測試全域測試檔案上的全球可存取元素並在模組測試檔案中充分行使定義，反之亦然。
示波器軟體包的類型@foo/bar應在types/foo__bar中使用。請注意雙重底線。
該專案已獲得 MIT 許可。
定義檔上的版權分別是每個定義檔開頭列出的每個貢獻者。
