官網(wǎng)

本文檔描述了 npm 上當前可用的 Angular 框架包的結(jié)構(gòu)和格式。 這種格式適用于分發(fā) Angular 組件的包（如 Angular Material）以及在@angular 命名空間下發(fā)布的核心框架包，如@angular/core 和@angular/forms。

此處描述的格式使用獨特的文件布局和元數(shù)據(jù)配置，使包能夠在使用 Angular 的大多數(shù)常見場景下無縫工作，并使其與 Angular 團隊和社區(qū)本身提供的工具兼容。 出于這個原因，也強烈鼓勵第三方庫開發(fā)人員遵循相同的結(jié)構(gòu)。

格式的版本控制與 Angular 本身的版本控制一致，我們希望格式以向前兼容(forward-compatible)的方式發(fā)展，以支持 Angular 組件和工具生態(tài)系統(tǒng)的需求。

Package format 的目的

在當今的 JavaScript 環(huán)境中，開發(fā)人員將以多種不同的方式使用包。 例如，有些可能使用 SystemJS，有些可能使用 Webpack。 盡管如此，其他人可能會在 Node 或瀏覽器中使用包作為 UMD 包或通過全局變量訪問。

Angular 分發(fā)包支持所有常用的開發(fā)工具和工作流，并強調(diào)優(yōu)化，從而縮小應(yīng)用程序有效負載大小或加快開發(fā)迭代周期（構(gòu)建時間）。

Library File layout

庫一般應(yīng)該使用相同的布局，但庫中存在與 Angular 框架不同的特性。

通常，庫是在組件或功能級別拆分的。我們以 Angular 的 Material 項目為例。

Angular Material 發(fā)布了組件集，例如 Button（單個組件）、Tabs（一組協(xié)同工作的組件）等。共同點是將這些功能區(qū)域綁定在一起的 NgModule。 Button 有一個 NgModule，Tabs 有另一個，依此類推。

Angular Package Format 的一般規(guī)則是為最小的邏輯連接代碼集生成 FESM 文件。例如，Angular 包有一個用于@angular/core 的 FESM。當開發(fā)人員使用來自@angular/core 的 Component 符號時，他們很可能也會直接或間接使用諸如 Injectable、Directive、NgModule 等符號。因此，所有這些部分都應(yīng)該捆綁在一起形成一個 FESM。對于大多數(shù)庫情況，應(yīng)該將單個邏輯組組合到一個 NgModule 中，并且所有這些文件應(yīng)該捆綁在一起作為包中的單個 FESM 文件，代表 npm 包中的單個入口點。

以下是 Angular Material 項目在這種格式下的外觀示例：

再看 Spartacus core build 出來的輸出：

Primary Entry point

包的主要入口點是模塊 id 與包名稱匹配的模塊（例如，對于“@angular/core”包，從主要入口點導(dǎo)入的內(nèi)容如下： import {Component, …} from ‘@angular/core’）。

Secondary Entry point

除了主要入口點，包可以包含零個或多個次要入口點（例如@angular/common/http）。 這些包含我們不想與主入口點中的符號組合在一起的符號，原因有兩個：

(1)用戶通常認為它們與主要符號組不同，并且如果它們與主要符號組相關(guān)，那么他們就已經(jīng)在那里了。

(2)次要組中的符號通常僅用于特定場景（例如，在編寫和運行測試時）。 可能不會在主入口點中包含這些符號，因此我們減少了它們被意外錯誤使用的機會（例如，在@angular/core/testing 中使用的生產(chǎn)代碼中使用測試模擬）。

輔助入口點導(dǎo)入的模塊 ID 將模塊加載器定向到輔助入口點名稱的目錄。 例如，“@angular/core/testing”解析為一個同名的目錄，“@angular/core/testing”。 該目錄包含一個 package.json 文件，該文件將加載器定向到它正在尋找的正確位置。 這允許我們在單個包中創(chuàng)建多個入口點。

Compilation and transpilation

為了生成所有必需的構(gòu)建工件，我們強烈建議您使用 Angular 編譯器 (ngc) 使用 tsconfig.json 中的以下設(shè)置編譯您的代碼：

{"compilerOptions": {..."declaration": true,"module": "es2015","target": "es2015"},"angularCompilerOptions": {"strictMetadataEmit": true,"skipTemplateCodegen": true,"flatModuleOutFile": "my-ui-lib.js","flatModuleId": "my-ui-lib",} }

優(yōu)化相關(guān)

Flattening of ES Modules

我們強烈建議您在將構(gòu)建工件發(fā)布到 npm 之前，通過扁平化 ES 模塊來優(yōu)化構(gòu)建工件。這顯著減少了 Angular 應(yīng)用程序的構(gòu)建時間以及最終應(yīng)用程序包的下載和解析時間。

Angular 編譯器支持生成索引 ES 模塊文件，然后可以使用這些文件使用 Rollup 等工具生成扁平化模塊，從而生成我們稱為扁平化 ES 模塊或 FESM 的文件格式。

FESM 是一種文件格式，通過將所有可從入口點訪問的 ES 模塊扁平化為單個 ES 模塊。它是通過跟蹤包中的所有導(dǎo)入并將該代碼復(fù)制到單個文件中而形成的，同時保留所有公共 ES 導(dǎo)出并刪除所有私有導(dǎo)入。

縮寫名稱“FESM”（發(fā)音為“phesom”）后面可以有一個數(shù)字，例如“FESM5”或“FESM2015”。數(shù)字是指模塊內(nèi) JavaScript 的語言級別。所以 FESM5 文件將是 ESM+ES5（導(dǎo)入/導(dǎo)出語句和 ES5 源代碼）。

要生成扁平化的 ES 模塊索引文件，請在 tsconfig.json 文件中使用以下配置選項：

{"compilerOptions": {..."module": "es2015","target": "es2015",...},"angularCompilerOptions": {..."flatModuleOutFile": "my-ui-lib.js","flatModuleId": "my-ui-lib"} }

一旦索引文件（例如 my-ui-lib.js）由 ngc 生成，捆綁器和優(yōu)化器（如 Rollup）可用于生成扁平化的 ESM 文件。

Inlining of templates and stylesheets

組件庫通常使用存儲在單獨文件中的樣式表和 html 模板來實現(xiàn)。 雖然不是必需的，但我們建議組件作者通過將 styleUrls 和 templateUrl 分別替換為樣式和模板元數(shù)據(jù)屬性，將模板和樣式表內(nèi)聯(lián)到他們的 FESM 文件以及 *.metadata.json 文件中。 這簡化了應(yīng)用程序開發(fā)人員對組件的使用。

從 APF v10 開始，我們建議添加 tslib 作為主要入口點的直接依賴項，這是因為 tslib 版本與用于編譯庫的 TypeScript 版本相關(guān)聯(lián)。

一些術(shù)語

• package: 發(fā)布到 NPM 并安裝在一起的最小文件集，例如 @angular/core。 該包包含一個名為 package.json 的清單、編譯后的源代碼、TypeScript files、源映射、元數(shù)據(jù)等。該包通過 npm install @angular/core 安裝。

• Symbols:包含在模塊中的類、函數(shù)、常量或變量，并可選擇通過模塊導(dǎo)出對外部世界可見。

• module ID: 導(dǎo)入語句中使用的模塊的標識符，例如 “@spartacus/core”。 ID 通常直接映射到文件系統(tǒng)上的路徑，但由于各種模塊解析策略，情況并非總是如此。

• module format:模塊語法規(guī)范，至少涵蓋用于從文件導(dǎo)入和導(dǎo)出的語法。 常見的模塊格式是 CommonJS（CJS，通常用于 Node.js 應(yīng)用程序）或 ECMAScript 模塊（ESM）。 模塊格式僅表示單個模塊的封裝，而不表示用于構(gòu)成模塊內(nèi)容的 JavaScript 語言特性。 因此，Angular 團隊經(jīng)常使用語言級別說明符作為模塊格式的后綴，例如 ESM+ES5 指定模塊采用 ESM 格式并包含下級到 ES5 的代碼。 其他常用組合：ESM+ES2015、CJS+ES5、CJS+ES2015。

• bundle: 由構(gòu)建工具生成的單個 JS 文件形式的工件，例如 WebPack 或 Rollup，包含源自一個或多個模塊的符號。 捆綁包是一種特定于瀏覽器的解決方法，可減少瀏覽器開始下載數(shù)百甚至數(shù)萬個文件時可能造成的網(wǎng)絡(luò)壓力。 Node.js 通常不使用包。 常見的捆綁格式是 UMD 和 System.register。

• language level: 代碼的語言（ES5 或 ES2015）。 獨立于模塊格式。

• entry point: 打算由用戶導(dǎo)入的模塊。 它由唯一的模塊 ID 引用，并導(dǎo)出該模塊 ID 引用的公共 API。 一個例子是@angular/core 或@angular/core/testing。 @angular/core 包中存在兩個入口點，但它們導(dǎo)出不同的符號。 一個包可以有許多入口點。

• deep import: 從不是入口點的模塊中檢索符號的過程。 這些模塊 ID 通常被認為是私有 API，它們可以在項目的生命周期內(nèi)或在創(chuàng)建給定包的包時更改。

• top level import: 來自入口點的導(dǎo)入。 可用的頂級導(dǎo)入定義了公共 API，并在“@angular/name”模塊中公開，例如 @angular/core 或 @angular/common。

• tree shaking: 識別和刪除應(yīng)用程序未使用的代碼的過程 - 也稱為死代碼消除。 這是使用 Rollup、Closure Compiler 或 Uglify 等工具在應(yīng)用程序級進行操作。

更多Jerry的原創(chuàng)文章，盡在：“汪子熙”:

總結(jié)

以上是生活随笔為你收集整理的Angular Package Format (APF) v12.0 介绍的全部內(nèi)容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網(wǎng)站內(nèi)容還不錯，歡迎將生活随笔推薦給好友。