如何建立高質量的TypeScript宣告檔案(一)
庫結構
“庫結構”可幫助您瞭解常用庫格式以及如何為每種格式編寫正確的宣告檔案。 如果您正在編輯現有檔案,則可能不需要閱讀這篇文章。 新宣告檔案的作者必須閱讀本篇文章以正確理解庫的格式如何影響宣告檔案的寫入。
介紹
從廣義上講,構造宣告檔案的方式取決於庫的使用方式。 有許多方法可以在JavaScript中提供供消費的庫,你需要編寫你的宣告檔案來匹配它。 本篇文章介紹瞭如何識別公共庫模式,以及如何編寫與該模式對應的宣告檔案。
每種型別的主要庫結構模式在“模板”部分中都有相應的檔案。 您可以從這些模板開始,以幫助您更快地前進。
識別各種庫的型別
首先,我們將回顧TypeScript宣告檔案可以表示的庫型別。 我們將簡要介紹如何使用各種庫,如何編寫,以及列出現實世界中的一些示例庫。
識別庫的結構是編寫其宣告檔案的第一步。 我們將根據其用法和程式碼給出關於如何識別結構的提示。 根據圖書館的文件和組織,一個可能比另一個更容易。 我們建議您使用哪種方式更舒適。
全域性庫
全域性庫是可以從全域性範圍訪問的庫(即不使用任何形式的匯入)。 許多庫只是公開一個或多個全域性變數以供使用。 例如,如果您使用的是jQuery,只需引用它就可以使用$變數:
您通常會在全域性庫的文件中看到如何在HTML指令碼標記中使用庫的指導:
<script src="http://a.great.cdn.for/someLib.js"></script>
今天,大多數流行的全球可訪問庫實際上都是作為UMD庫編寫的(見下文)。 UMD庫文件很難與全域性庫文件區分開來。 在編寫全域性宣告檔案之前,請確保該庫實際上不是UMD。
從程式碼中識別全域性庫
全域性庫程式碼通常非常簡單。 全域性“Hello,world”庫可能如下所示:
function createGreeting(s) { return "Hello, " + s; }
或者像這樣:
window.createGreeting = function(s) { return "Hello, " + s; }
檢視全域性庫的程式碼時,您通常會看到:
- 頂級var語句或函式宣告
- window.someName的一個或多個賦值
- 存在DOM原語(如文件或視窗)的假設
你不會看到:
- 檢查或使用模組載入器,如require或define
- CommonJS/Node.js樣式匯入形式var fs = require("fs");
- 呼叫define(...)
- 描述如何require或import庫的文件
全域性庫的例子
因為將全域性庫轉換為UMD庫通常很容易,所以很少有流行的庫仍然以全域性風格編寫。 但是,小而且需要DOM(或沒有依賴關係)的庫可能仍然是全域性的。
全域性庫模板
模板檔案global.d.ts定義了一個示例庫myLib。 請務必閱讀"防止名稱衝突"腳註。
未完待續...