基底專案

目次

• 1. 使用技術
• 2. 開發環境需求
• 3. 開發環境設定
  • 3.1. 安裝 Node.js
    • 3.1.1. volta 常用指令
    • 3.1.2. npm 常用指令
• 4. 建立元件庫
• 5. i18n國際化語系
• 6. Angular響應式表單整合(@common/sdk/form)
• 7. Material Icon

1. 使用技術

• Angular - v17
  • 前端框架
• TypeScript
  • 靜態型別檢查
• RxJS - v7
  • Reactive Extensions Library
• SCSS
  • CSS Preprocessor
• Angular Material v17
  • 適用於Angular的UI套件
• Material Icon
  • google提供的icon庫

2. 開發環境需求

• 瀏覽器 : Google Chrome 或是 Microsoft Edge

• 瀏覽器擴充套件 :

  • Angular DevTools

• 編譯 : Node.js 18.12.1

  • npm v8.19.2

• 編輯器 : Visual Studio Code >= 1.74.2

  • Extension :
    • * Angular Extension Pack : Angular 開發用的 Extension 集合包
      • * Angular Language Service
      • * Angular 10 Snippets : Angular 2 ~ 10 Code Snippets
      • * Angular Snippets (Version 13) : Angular 13 Code Snippets
      • * JavaScript (ES6) code snippets : ES6 Code Snippets
      • * ESLint : 程式碼檢查
      • * Prettier - Code formatter : Prettier 程式碼格式化
      • * Nx Console : Nx UI Console
    • * Stylelint : CSS 檢查
    • Code Spell Checker : 拼字檢查
    • GitLens : git 視覺化
    • Todo Tree : 快速查看與 highlight 註解標籤

  Note : * 為必須安裝

• Nx Console

  • 已包含在 Visual Studio Code extension 提到的 Angular Extension Pack

3. 開發環境設定

3.1. 安裝 Node.js

• 建議使用 volta 來安裝，因為不同專案可能會有不同版本的需求，方便隨時切換版本。
• 輸入 node -v 指令查看當前版本號。
• 因為在 .npmrc 有設定 engine-strict = true，版本號必須符合 package.json 中的 engines 的設定，否則安裝 npm 套件會報錯。
• npm 預設是內建於 Node.js，故版本是跟著 Node.js，如無特殊需求則不需要另外安裝 npm。

Note : npm 從 v7 開始 package-lock.json 中的 lockfileVersion 已變更為 2。

如果有開發者使用舊版 npm 執行安裝指令，lockfileVersion 會變回 1，這可能會造成一直覆蓋的問題，故請確保使用正確的 Node.js 版本(請安裝 volta)。

發生此問題請先切換到正確的 Node.js 版本，然後刪除 package-lock.json 和 node_modules 資料夾，再執行 npm install 指令來重新建立 package-lock.json 即可。

Note : Windows 在 npm 安裝套件失敗時，請以 系統管理員身分 開啟 命令提示字元 輸入以下指令 : npm install --global --production windows-build-tools

3.1.1. volta 常用指令

• volta --help : 查看 volta 指令。
• volta list : 查看當前啟用的套件管理版本。
• volta list all : 查看當前所安裝的套件管理版本清單。
• volta install node[@版本號] : 安裝指定的 Node.js 版本或是變更預設版本。
• volta pin node[@version] : 設定專案 Node.js 版本的 。

3.1.2. npm 常用指令

• npm ls : 查看當前專案下安裝的 Node.js 套件清單。
• npm install(npm i) : 安裝專案下的 Node.js 套件 (無特殊情況請使用 npm ci 取代)。
  • 已有 package-lock.json 時，建議使用 npm ci 取代，避免版本可能會有些許差異。
• npm install <name> : 安裝某個 Node.js 套件。
  • -g, --global : 安裝電腦上(不分專案)
  • -D, --save-dev : 套件將會在 package.json 裡的 devDependencies。
• npm ci : 先清除 node_modules 再依照 package-lock.json 中鎖定的版號安裝專案下的套件。
• npm uninstall <name> : 解除安裝 Node.js 套件。
• npm run <name> : 執行 package.json 裡的 scripts。

4. 常用建立檔案指令

建立元件庫' ng generate library @common/sdk --standalone --project-root=libs/common/sdk

建立裝飾器 ng generate directive control --standalone --path libs/common/sdk/form/src/directives/control --project @common/sdk

5. i18n國際化語系(@common/sdk/i18n)

• i18n
  • 多語系套件

模板翻譯

使用以下功能前需先導入i18n模組TranslocoModule

管道 (Pipe)

<span>{{ 'i18nKey' | transloco }}</span>

裝飾器 (Directive)

<span transloco="i18nKey"></span>

語法糖

<ng-container *transloco="let t">
  <p>{{ t('i18nKey') }}</p>

  <example-component [title]="t('i18nKey')"></example-component>
</ng-container>

惰性載入用法(Standalone Component 開發)

  @Component({
  selector: '?????',
  standalone: true,
  ...
  providers: [
    {
      provide: TRANSLOCO_SCOPE,
      useValue: {
        scope: 'validate-messages', // 第2層資料夾
        alias: 'vm', // 使用別稱
      },
      multi: true,
    },
  ],
  ...
})
export class ????Component {
  ...
  private _translocoService = inject(TranslocoService);
  private _someText = ''
  private _sub =  this._translocoService.events$.subscribe(val => {
      // 確保翻譯檔已載入
      if (
        val.payload.scope === '????-scope' &&
        val.type === 'translationLoadSuccess'
      ) {
        this._someText = this._translocoService.translate('????-key');
      }
      this._sub.unsubscribe();
      this._sub = null;
    });
}

{{ 'vm.xxx-key' | transloco }}

6. Angular響應式表單整合(@common/sdk/form)

裝飾器 (Directive)

ControlDirective

使用 hostDirectives 綁定在表單元件

@Component({
  selector: 'app-example-input',
  ...
  standalone: true,
  imports: [ReactiveFormsModule, ControlDirective],
  hostDirectives: [ControlDirective],
})
export class ExampleInputComponent<ValueT> {}

7. Material Icon

<!-- Outlined -->
<span class="material-icons-outlined"> search </span>
<!-- Filled -->
<span class="material-icons"> search </span>
<!-- Rounded -->
<span class="material-symbols-rounded"> search </span>
<!-- Sharp -->
<span class="material-icons-sharp"> search </span>
<!-- Two tone -->
<span class="material-icons-two-tone"> search </span>