Angular 創(chuàng)作原理圖

創(chuàng)作原理圖

你可以創(chuàng)建自己的原理圖來對 Angular 項(xiàng)目進(jìn)行操作。庫開發(fā)人員通常會(huì)把這些原理圖與他們的庫打包在一起，以便把它們與 Angular CLI 集成在一起。你也可以創(chuàng)建獨(dú)立的原理圖來操作 Angular 應(yīng)用中的文件和目錄結(jié)構(gòu)，以便為你的開發(fā)環(huán)境定制它們，并讓它們符合你的標(biāo)準(zhǔn)和約束。多個(gè)原理圖還可以串聯(lián)起來，通過運(yùn)行其它原理圖來完成復(fù)雜的操作。

在應(yīng)用程序中操作代碼可能既強(qiáng)大又危險(xiǎn)。比如，創(chuàng)建一個(gè)已存在的文件會(huì)出錯(cuò)，如果出現(xiàn)這種情況，就應(yīng)該放棄已應(yīng)用的所有其它更改。Angular 原理圖工具通過創(chuàng)建虛擬文件系統(tǒng)來防止副作用和錯(cuò)誤。原理圖描述了一個(gè)可應(yīng)用于虛擬文件系統(tǒng)的轉(zhuǎn)換管道。當(dāng)原理圖運(yùn)行時(shí)，轉(zhuǎn)換就會(huì)被記錄在內(nèi)存中，只有當(dāng)這些更改被確認(rèn)有效時(shí)，才會(huì)應(yīng)用到實(shí)際的文件系統(tǒng)中。

原理圖的概念

原理圖的公共 API 定義了表達(dá)其基本概念的類。

• 虛擬文件系統(tǒng)用 ?Tree?（樹）表示。?Tree ?數(shù)據(jù)結(jié)構(gòu)包含一個(gè)基礎(chǔ)狀態(tài) base（一組已經(jīng)存在的文件）和一個(gè) 暫存區(qū) staging（需要應(yīng)用到 base 的更改列表）。在進(jìn)行修改的過程中，你并沒有真正改變它的 base，而是把那些修改添加到了暫存區(qū)。
• ?Rule?（規(guī)則）對象定義了一個(gè)函數(shù)，它接受 ?Tree?，進(jìn)行轉(zhuǎn)換，并返回一個(gè)新的 ?Tree?。原理圖的主文件 ?index.ts? 定義了一組實(shí)現(xiàn)原理圖邏輯的規(guī)則。
• 轉(zhuǎn)換由 ?Action?（動(dòng)作）表示。有四種動(dòng)作類型：?Create?、?Rename?、?Overwrite ?和 ?Delete?。
• 每個(gè)原理圖都在一個(gè)上下文中運(yùn)行，上下文由一個(gè) ?SchematicContext ?對象表示。

傳給規(guī)則的上下文對象可以訪問該原理圖可能會(huì)用到的工具函數(shù)和元數(shù)據(jù)，包括一個(gè)幫助調(diào)試的日志 API。上下文還定義了一個(gè)合并策略，用于確定如何將這些更改從暫存樹合并到基礎(chǔ)樹中?？梢越邮芑蚝雎阅硞€(gè)更改，也可以拋出異常。

定義規(guī)則和動(dòng)作

當(dāng)你使用 Schematics CLI 創(chuàng)建一個(gè)新的空白原理圖時(shí)，它所生成的入口函數(shù)就是一個(gè)規(guī)則工廠。?RuleFactory ?對象定義了一個(gè)用于創(chuàng)建 ?Rule ?的高階函數(shù)。

import { Rule, SchematicContext, Tree } from '@angular-devkit/schematics';

// You don't have to export the function as default.
// You can also have more than one rule factory per file.
export function helloWorld(_options: any): Rule {
 return (tree: Tree, _context: SchematicContext) => {
   return tree;
 };
}

你的這些規(guī)則可以通過調(diào)用外部工具和實(shí)現(xiàn)邏輯來修改你的項(xiàng)目。比如，你需要一個(gè)規(guī)則來定義如何將原理圖中的模板合并到宿主項(xiàng)目中。

規(guī)則可以利用 ?@schematics/angular? 包提供的實(shí)用工具。尋求輔助函數(shù)來處理模塊、依賴、TypeScript、AST、JSON、Angular CLI 工作區(qū)和項(xiàng)目等等。

import {
  JsonAstObject,
  JsonObject,
  JsonValue,
  Path,
  normalize,
  parseJsonAst,
  strings,
} from '@angular-devkit/core';

利用模式和接口來定義輸入選項(xiàng)

規(guī)則可以從調(diào)用者那里收集選項(xiàng)值，并把它們注入到模板中。規(guī)則可用的選項(xiàng)及其允許的值和默認(rèn)值是在原理圖的 JSON 模式文件 ?<schematic>/schema.json? 中定義的。可以用 TypeScript 接口來為這個(gè)模式定義變量或枚舉的數(shù)據(jù)類型。

該模式定義了原理圖中使用的變量的類型和默認(rèn)值。比如，假設(shè)的 “Hello World” 原理圖可能具有以下模式定義（schema）。

{
    "properties": {
        "name": {
            "type": "string",
            "minLength": 1,
            "default": "world"
        },
        "useColor": {
            "type": "boolean"
        }
    }
}

可以在 @schematics/angular 中看到 Angular CLI 命令原理圖的模式文件范例。

原理圖提示

原理圖提示能將用戶交互引入到原理圖執(zhí)行過程中?？梢耘渲迷韴D選項(xiàng)，以向用戶顯示可自定義的問題。在執(zhí)行原理圖之前會(huì)顯示提示，然后將用戶的響應(yīng)用作選項(xiàng)的值。這使得用戶可以指導(dǎo)原理圖的操作，而無需深入了解可用選項(xiàng)的全部范圍。

比如，這個(gè) “Hello World” 原理圖可能會(huì)要求用戶提供他的名字，并顯示該名字以代替默認(rèn)名字 “world”。要定義這樣的提示，請將 ?x-prompt? 屬性添加到 ?name ?變量的模式中。

類似地，你可以添加一個(gè)提示，以允許用戶確定原理圖在執(zhí)行其 hello 操作時(shí)是否將使用顏色。帶有兩個(gè)提示的模式如下。

{
    "properties": {
        "name": {
            "type": "string",
            "minLength": 1,
            "default": "world",
            "x-prompt": "What is your name?"
        },
        "useColor": {
            "type": "boolean",
            "x-prompt": "Would you like the response in color?"
        }
    }
}

提示的簡寫語法

這些范例使用提示語法的簡寫形式，僅提供問題的文本。在大多數(shù)情況下，這就是所需要的。但是請注意，這兩個(gè)提示要求使用不同類型的輸入。使用簡寫形式時(shí)，將根據(jù)屬性的模式自動(dòng)選擇最合適的類型。在該范例中，?name ?提示使用 ?input ?類型，因?yàn)樗且粋€(gè)字符串屬性。?useColor ?提示使用 ?confirmation ?類型，因?yàn)樗遣紶枌傩浴Ｔ谶@種情況下，“是” 對應(yīng)于 ?true ?而 “否” 對應(yīng)于 ?false?。

支持三種輸入類型。

簡而言之，類型是根據(jù)屬性的類型和約束來推斷的。

在以下范例中，該屬性采用枚舉值，因此原理圖將自動(dòng)選擇列表類型，并根據(jù)可能的值創(chuàng)建菜單。

"style": {
  "description": "The file extension or preprocessor to use for style files.",
  "type": "string",
  "default": "css",
  "enum": [
    "css",
    "scss",
    "sass",
    "less",
    "styl"
  ],
  "x-prompt": "Which stylesheet format would you like to use?"
}

提示運(yùn)行時(shí)會(huì)根據(jù) JSON 模式中提供的約束條件自動(dòng)驗(yàn)證提供的響應(yīng)。如果該值不可接受，則提示用戶輸入新值。這樣可以確保傳遞到原理圖的任何值都符合原理圖實(shí)現(xiàn)的期望，因此你無需在原理圖的代碼中添加其它檢查。

提示的長格式語法

在需要對提示進(jìn)行其它自定義和控制情況下，?x-prompt? 字段也支持長格式語法。在這種形式下，?x-prompt? 字段值是帶有子字段的 JSON 對象，這些子字段可自定義提示的行為。

下面的長格式范例來自 CLI 用來生成應(yīng)用程序的原理圖的 JSON 模式。它定義提示，允許用戶選擇要用于正在創(chuàng)建的應(yīng)用程序的樣式預(yù)處理器。通過使用長格式，原理圖可以為菜單選項(xiàng)提供更明確的格式。

"style": {
  "description": "The file extension or preprocessor to use for style files.",
  "type": "string",
  "default": "css",
  "enum": [
    "css",
    "scss",
    "sass",
    "less"
  ],
  "x-prompt": {
    "message": "Which stylesheet format would you like to use?",
    "type": "list",
    "items": [
      { "value": "css",  "label": "CSS" },
      { "value": "scss", "label": "SCSS   [ https://sass-lang.com/documentation/syntax#scss                ]" },
      { "value": "sass", "label": "Sass   [ https://sass-lang.com/documentation/syntax#the-indented-syntax ]" },
      { "value": "less", "label": "Less   [ http://lesscss.org/                                            ]" }
    ]
  },
},

x-prompt 模式

定義原理圖選項(xiàng)的 JSON 模式支持?jǐn)U展，以允許對提示及其相應(yīng)行為進(jìn)行聲明式定義。無需其它邏輯或更改原理圖代碼即可支持提示。以下 JSON 模式是 ?x-prompt? 字段的長格式語法的完整描述。

{
    "oneOf": [
        { "type": "string" },
        {
            "type": "object",
            "properties": {
                "type": { "type": "string" },
                "message": { "type": "string" },
                "items": {
                    "type": "array",
                    "items": {
                        "oneOf": [
                            { "type": "string" },
                            {
                                "type": "object",
                                "properties": {
                                    "label": { "type": "string" },
                                    "value": { }
                                },
                                "required": [ "value" ]
                            }
                        ]
                    }
                }
            },
            "required": [ "message" ]
        }
    ]
}

原理圖 CLI

原理圖有自己的命令行工具。使用 Node 6.9 或以上版本，全局安裝 Schematics 命令行工具：

npm install -g @angular-devkit/schematics-cli

這將安裝可執(zhí)行文件 ?schematics?，你可以用它在自己的項(xiàng)目文件夾中創(chuàng)建一個(gè)新的原理圖集合、把一個(gè)新的原理圖添加到一個(gè)現(xiàn)有的集合中，或者擴(kuò)展一個(gè)現(xiàn)有的原理圖。

在下面的章節(jié)中，我們將使用 CLI 創(chuàng)建一個(gè)新的原理圖集合，以介紹文件和目錄結(jié)構(gòu)，以及一些基本概念。

但是，原理圖的最常見用途是將 Angular 庫與 Angular CLI 集成在一起?？梢灾苯釉?nbsp;Angular 工作區(qū)的庫項(xiàng)目中創(chuàng)建原理圖文件，而無需使用 Schematics CLI。

創(chuàng)建一個(gè)原理圖的集合

下列命令用來在同名的新項(xiàng)目文件夾中創(chuàng)建一個(gè)名為 ?hello-world? 的新原理圖。

schematics blank --name=hello-world

?blank ?原理圖是由 Schematics CLI 提供的。該命令用于創(chuàng)建一個(gè)新的項(xiàng)目文件夾（該集合的根文件夾），并在該集合中創(chuàng)建一個(gè)最初的命名原理圖。

轉(zhuǎn)到 collection 文件夾，安裝你的 npm 依賴，然后在常用的編輯器中打開這個(gè)新集合，看看所生成的文件。比如，如果你正在使用 VSCode：

cd hello-world
npm install
npm run build
code .

最初的原理圖與項(xiàng)目文件夾的名字相同，是在 ?src/hello-world? 中生成的?？梢园严嚓P(guān)的原理圖添加到這個(gè)集合中，并修改所生成的骨架代碼來定義原理圖的功能。每個(gè)原理圖的名稱在集合中都必須是唯一的。

運(yùn)行原理圖

使用 ?schematics ?命令運(yùn)行一個(gè)命名原理圖。按以下格式提供項(xiàng)目文件夾的路徑、原理圖名稱和所有必選項(xiàng)。

schematics <path-to-schematics-project>:<schematics-name> --<required-option>=<value>

該路徑可以是絕對路徑，也可以是執(zhí)行該命令的當(dāng)前工作目錄的相對路徑。比如，要運(yùn)行剛生成的原理圖（它沒有必選項(xiàng)），請使用下面的命令。

schematics .:hello-world

把原理圖添加到集合中

要把一個(gè)原理圖添加到現(xiàn)有的集合中，請使用和新建原理圖項(xiàng)目相同的命令，不過要改為在該項(xiàng)目的文件夾下運(yùn)行該命令。

cd hello-world
schematics blank --name=goodbye-world

該命令會(huì)在你的集合中生成一個(gè)新的命名原理圖，它包含一個(gè)主文件 ?index.ts? 及其相關(guān)的測試規(guī)約。它還會(huì)把這個(gè)新原理圖的名字（name），說明（description）和工廠函數(shù)（factory function）添加到 ?collection.json? 文件中此集合的 JSON 模式中。

集合的內(nèi)容

集合的根文件夾中包含一些配置文件、?node_modules ?文件夾和 ?src/? 文件夾。?src/? 文件夾包含該集合中各個(gè)命名原理圖的子文件夾，以及一個(gè)模式文件（?collection.json?），它是集合中各個(gè)原理圖的模式定義。每個(gè)原理圖都是用名稱，描述和工廠函數(shù)創(chuàng)建的。

{
  "$schema":
     "../node_modules/@angular-devkit/schematics/collection-schema.json",
  "schematics": {
    "hello-world": {
      "description": "A blank schematic.",
      "factory": "./hello-world/index#helloWorld"
    }
  }
}

• ?$schema? 屬性指定了 CLI 進(jìn)行驗(yàn)證時(shí)所用的模式。
• ?schematics ?屬性列出了屬于這個(gè)集合的各個(gè)命名原理圖。每個(gè)原理圖都有一個(gè)純文本格式的描述，以及指向主文件中自動(dòng)生成的那個(gè)入口函數(shù)。
• ?factory ?屬性指向自動(dòng)生成的那個(gè)入口函數(shù)。在這個(gè)例子中，你會(huì)通過調(diào)用 ?helloWorld()? 工廠函數(shù)來調(diào)用 ?hello-world? 原理圖。
• 可選屬性 ?schema ?是一個(gè) JSON 模式文件，它定義了本原理圖中可用的命令行參數(shù)。
• 可選數(shù)組屬性 ?aliases ?指定了一個(gè)或多個(gè)可用來調(diào)用此原理圖的字符串。比如，Angular CLI “generate” 命令的原理圖有一個(gè)別名 “g”，這就可以讓你使用命令 ?ng g?。

命名原理圖

當(dāng)你使用 Schematics CLI 創(chuàng)建空白原理圖項(xiàng)目時(shí)，該集合的第一個(gè)成員是一張與該集合同名的空白原理圖。當(dāng)你把這個(gè)新的命名原理圖添加到本集合中時(shí)，它會(huì)自動(dòng)添加到 ?collection.json? 模式中。

除了名稱和描述外，每個(gè)原理圖還有一個(gè) ?factory ?屬性，用于標(biāo)識此原理圖的入口點(diǎn)。在本例中，你通過在主文件 ?hello-world/index.ts? 中調(diào)用 ?helloWorld()? 函數(shù)來調(diào)用此原理圖中定義的功能。

該集合中每個(gè)命名原理圖都有以下主要部分。

原理圖可以在 ?index.ts? 文件中提供它全部的邏輯，不需要額外的模板。你也可以在 ?files/? 文件夾中提供組件和模板來為 Angular 創(chuàng)建動(dòng)態(tài)原理圖，比如那些獨(dú)立的 Angular 項(xiàng)目。這個(gè) index 文件中的邏輯會(huì)通過定義一些用來注入數(shù)據(jù)和修改變量的規(guī)則來配置這些模板。