iT邦幫忙

第 11 屆 iT 邦幫忙鐵人賽

DAY 4
1
Modern Web

高效 Coding 術:Angular Schematics 實戰三十天系列 第 4

[高效 Coding 術:Angular Schematics 實戰三十天] Day03 - 第一個 Schematic

環境安裝

Angular 開發團隊非常地貼心,為了讓大家能夠更方便地去開發與學習 Schematics ,還特地開發了 Schematics CLI 給大家使用。因此,第一步當然是先安裝 Schematics CLI 囉!而且安裝的方法也非常簡單,只要在終端機輸入以下指令即可安裝完成:

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

請使用 Node 6.9 以上的版本進行此安裝。

建立專案

安裝完成後,我們就能夠在終端機裡輸入以下指令來建立一個空白的 Schematics 專案:

schematics blank --name=hello-world

接著我們進到該資料夾內,輸入以下指令讓它把 .ts 檔編譯成 .js 檔:

npm run build

最後再輸入以下指令讓 Schematics 運作起來:

schematics .:hello-world

輸入上述指令後,應該會看到如下圖所示之畫面,代表我們的專案跟環境都沒有問題:

Imgur

而這個剛建立的專案組成非常簡單,除了剛剛 npm run build 的時候所產生的檔案外,只有以下幾個檔案:

Imgur

而這些檔案除了筆者用紅色虛線框起來的部分與 .npmignore 之外,相信大多數讀者應該都知道其作用,在此筆者就不多加解釋了。

接下來就讓筆者來跟大家說明紅色虛線框起來的檔案用途吧!

Collections

首先我們先來看看 collection.json

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

collection.json 這個 JSON 檔是整個 Schematics 的進入點,其中 schematics 這個欄位則定義了這個專案內的所有的 Schematic ,所以我們又稱它為 Collection

schematics 裡的 hello-world 指的是 Schematic 的名稱,也是日後在使用時的指令名稱; description 定義的是 hello-world 這個 Schematic 的描述;最後 factory 則是實際觸發的程式碼所在位置(語法為:相對路徑#函式名稱)。

想當然耳, schematics 的定義絕不只這些,容我暫且賣個關子,後續再隨著各種應用逐漸補充給大家。

index.ts

接著我們來看 index.ts

export function helloWorld(_options: any): Rule {
  return (tree: Tree, _context: SchematicContext) => {
    return tree;
  };
}

helloWorld 這個與指令同名的函式一般我們稱之 RuleFactory , Schematics 透過解析 collection.json 拿到這個檔案的位置與函式名稱後,使用這個函式來產出 Rule

這個函式有個 _options 參數,它是一個物件,除了代表我們所下的參數指令如: --name=hello 之外,也可以是別的 Schematics 所傳入的參數。而這個參數可以使用 JSON Schema 進行驗證,以確保它具有適當的預設值與類型。

雖然這邊只有短短四行程式碼,但有幾個型別需要特別跟大家說明:

  • Rule: 它是 Schematics 的核心,是一個接收 Tree 並回傳一個包含改變規則的 Tree
  • Tree: 它是檔案系統的結構描述,包含檔案狀態與改變檔案的規則。
  • Source: 用來建立新的 Tree

這三個型別是 Schematics 用來操作檔案系統的三大型別,只要熟悉了它們的操作方式,之後在撰寫自己的 Schematics 的時候會輕鬆很多。

範例練習

說了這麼多,相信大家一定等不及要開始來實作我們的第一個 Schematic 了!既然是第一個,不免俗地先從 Hello World 開始。

先在 index.ts 加點料:

export function helloWorld(_options: any): Rule {
  return (tree: Tree, _context: SchematicContext) => {
    
    // 產生一個檔案名稱為使用者所輸入的 --name 參數的值,沒輸入則為 'hello' 的檔案
    // 檔案內容為 'world'
    tree.create(_options.name || 'hello', 'world');

    return tree;
  };
}

存檔後,先在終端機中輸入以下指令編譯:

npm run build

再輸入以下指令讓 Schematics 運作:

schematics .:hello-world --name=leo

成功的話,應該會看到終端機有類似下圖的回應:

Imgur

雖然終端機有回應,但因為 Schematics 知道你是在開發,所以不會真的幫你建立此檔案。如果你想要 Schematics 真的幫你建立檔案的話,可以加上 --dry-run=false 的參數,像是:

schematics .:hello-world --name=leo --dry-run=false

如此一來,就會看到你的資料夾裡多了一個名為 leo 的檔案,其內容則為 world

Imgur

到此就完成我們第一個 Schematic 囉!

本日結語

雖然今天的範例程式碼非常簡單,但筆者還是會將其上傳的 Github 上供大家參考,希望大家今天都有成功安裝好開發環境並實作自己的第一個 Schematic 。

明天筆者將會教大家如何撰寫 Schematic 的測試,敬請期待。

參考資料


上一篇
[高效 Coding 術:Angular Schematics 實戰三十天] Day02 - 要學打人,先學挨打
下一篇
[高效 Coding 術:Angular Schematics 實戰三十天] Day04 - 為你的 Schematics 撰寫測試程式
系列文
高效 Coding 術:Angular Schematics 實戰三十天32

尚未有邦友留言

立即登入留言