[官網](https://docs.google.com/document/d/1CZC2rcpxffTDfRDs6p1cfbmKNLA6x5O-NtkJglDaBVs/preview#heading=h.k0mh3o8u5hx)

本文件描述了 npm 上當前可用的 Angular 框架包的結構和格式。 這種格式適用於分發 Angular 元件的包（如 Angular Material）以及在@angular 名稱空間下發布的核心框架包，如@angular/core 和@angular/forms。

此處描述的格式使用獨特的檔案佈局和後設資料配置，使包能夠在使用 Angular 的大多數常見場景下無縫工作，並使其與 Angular 團隊和社群本身提供的工具相容。 出於這個原因，也強烈鼓勵第三方庫開發人員遵循相同的結構。

格式的版本控制與 Angular 本身的版本控制一致，我們希望格式以向前相容(forward-compatible)的方式發展，以支援 Angular 元件和工具生態系統的需求。

# Package format 的目的

在當今的 JavaScript 環境中，開發人員將以多種不同的方式使用包。 例如，有些可能使用 SystemJS，有些可能使用 Webpack。 儘管如此，其他人可能會在 Node 或瀏覽器中使用包作為 UMD 包或透過全域性變數訪問。

Angular 分發包支援所有常用的開發工具和工作流，並強調最佳化，從而縮小應用程式有效負載大小或加快開發迭代週期（構建時間）。

![](https://img-blog.csdnimg.cn/img_convert/7dd8c9d875c452b969319098cfb39287.png)

# Library File layout

庫一般應該使用相同的佈局，但庫中存在與 Angular 框架不同的特性。

通常，庫是在元件或功能級別拆分的。我們以 Angular 的 Material 專案為例。

Angular Material 釋出了元件集，例如 Button（單個元件）、Tabs（一組協同工作的元件）等。共同點是將這些功能區域繫結在一起的 NgModule。 Button 有一個 NgModule，Tabs 有另一個，依此類推。

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

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

![](https://img-blog.csdnimg.cn/img_convert/fed681a4123fdf8016e045d27bdf2e8f.png)

再看 Spartacus core build 出來的輸出：
![](https://img-blog.csdnimg.cn/img_convert/f2d86a4333e3db734dcd84ad566fc1b7.png)

# Primary Entry point

包的主要入口點是模組 id 與包名稱匹配的模組（例如，對於“@angular/core”包，從主要入口點匯入的內容如下： import {Component, ...} from '@ 角度/核心'）。

![](https://img-blog.csdnimg.cn/img_convert/48aea6920115531716656f38dccbf13b.png)

# Secondary Entry point

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

(1)使用者通常認為它們與主要符號組不同，並且如果它們與主要符號組相關，那麼他們就已經在那裡了。

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

輔助入口點匯入的模組 ID 將模組載入器定向到輔助入口點名稱的目錄。 例如，“@angular/core/testing”解析為一個同名的目錄，“@angular/core/testing”。 該目錄包含一個 package.json 檔案，該檔案將載入器定向到它正在尋找的正確位置。 這允許我們在單個包中建立多個入口點。

# Compilation and transpilation

為了生成所有必需的構建工件，我們強烈建議您使用 Angular 編譯器 (ngc) 使用 tsconfig.json 中的以下設定編譯您的程式碼：

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

```

# 最佳化相關

## Flattening of ES Modules

我們強烈建議您在將構建工件釋出到 npm 之前，透過扁平化 ES 模組來最佳化構建工件。這顯著減少了 Angular 應用程式的構建時間以及最終應用程式包的下載和解析時間。

Angular 編譯器支援生成索引 ES 模組檔案，然後可以使用這些檔案使用 Rollup 等工具生成扁平化模組，從而生成我們稱為扁平化 ES 模組或 FESM 的檔案格式。

FESM 是一種檔案格式，透過將所有可從入口點訪問的 ES 模組扁平化為單個 ES 模組。它是透過跟蹤包中的所有匯入並將該程式碼複製到單個檔案中而形成的，同時保留所有公共 ES 匯出並刪除所有私有匯入。

縮寫名稱“FESM”（發音為“phesom”）後面可以有一個數字，例如“FESM5”或“FESM2015”。數字是指模組內 JavaScript 的語言級別。所以 FESM5 檔案將是 ESM+ES5（匯入/匯出語句和 ES5 原始碼）。

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

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

```

一旦索引檔案（例如 my-ui-lib.js）由 ngc 生成，捆綁器和最佳化器（如 Rollup）可用於生成扁平化的 ESM 檔案。

# Inlining of templates and stylesheets

元件庫通常使用儲存在單獨檔案中的樣式表和 html 模板來實現。 雖然不是必需的，但我們建議元件作者透過將 styleUrls 和 templateUrl 分別替換為樣式和模板後設資料屬性，將模板和樣式表內聯到他們的 FESM 檔案以及 *.metadata.json 檔案中。 這簡化了應用程式開發人員對元件的使用。

從 APF v10 開始，我們建議新增 tslib 作為主要入口點的直接依賴項，這是因為 tslib 版本與用於編譯庫的 TypeScript 版本相關聯。

# 一些術語

* package: 釋出到 NPM 並安裝在一起的最小檔案集，例如 @angular/core。 該包包含一個名為 package.json 的清單、編譯後的原始碼、TypeScript files、源對映、後設資料等。該包透過 npm install @angular/core 安裝。

* Symbols:包含在模組中的類、函式、常量或變數，並可選擇透過模組匯出對外部世界可見。

* module ID: 匯入語句中使用的模組的識別符號，例如 “@spartacus/core”。 ID 通常直接對映到檔案系統上的路徑，但由於各種模組解析策略，情況並非總是如此。

* module format:模組語法規範，至少涵蓋用於從檔案匯入和匯出的語法。 常見的模組格式是 CommonJS（CJS，通常用於 Node.js 應用程式）或 ECMAScript 模組（ESM）。 模組格式僅表示單個模組的封裝，而不表示用於構成模組內容的 JavaScript 語言特性。 因此，Angular 團隊經常使用語言級別說明符作為模組格式的字尾，例如 ESM+ES5 指定模組採用 ESM 格式幷包含下級到 ES5 的程式碼。 其他常用組合：ESM+ES2015、CJS+ES5、CJS+ES2015。

* bundle: 由構建工具生成的單個 JS 檔案形式的工件，例如 WebPack 或 Rollup，包含源自一個或多個模組的符號。 捆綁包是一種特定於瀏覽器的解決方法，可減少瀏覽器開始下載數百甚至數萬個檔案時可能造成的網路壓力。 Node.js 通常不使用包。 常見的捆綁格式是 UMD 和 System.register。

* language level: 程式碼的語言（ES5 或 ES2015）。 獨立於模組格式。

* entry point: 打算由使用者匯入的模組。 它由唯一的模組 ID 引用，並匯出該模組 ID 引用的公共 API。 一個例子是@angular/core 或@angular/core/testing。 @angular/core 包中存在兩個入口點，但它們匯出不同的符號。 一個包可以有許多入口點。

* deep import: 從不是入口點的模組中檢索符號的過程。 這些模組 ID 通常被認為是私有 API，它們可以在專案的生命週期內或在建立給定包的包時更改。

* top level import: 來自入口點的匯入。 可用的頂級匯入定義了公共 API，並在“@angular/name”模組中公開，例如 @angular/core 或 @angular/common。

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

Angular Package Format (APF) v12.0 介紹

相關文章