Communitygithub.com

allianz/ng-aquila

在使用 Aquila / Angular Brand Kit(原 Angular NDBX)中的 @allianz/ng-aquila 组件时使用。涵盖导入、使用模式、表单处理、网格布局和组件 API。

ng-aquila 是什麼?

此工具技能旨在協助開發者使用 Allianz 設計系統的 Angular 組件庫 Aquila(亦稱 Angular Brand Kit,前身為 Angular NDBX)。它專注於現代 Angular (v19+) 的開發模式,包括獨立組件、信號(Signals)、新的控制流語法(`@if`、`@for`)以及 `inject()` 函數。技能提供了從正確的導入路徑(如 `@allianz/ng-aquila/button`)到常見 UI 模式(如表單驗證、下拉選單、模態對話框和 12 欄響應式網格)的詳細指引。它還強調了特定於 Aquila 的規則,例如必須在 `<nx-formfield>` 內包裝 `<input nxInput>`,以及為按鈕設定 `type="button"` 以防止意外提交表單。此外,技能包含一個全面的組件使用案例對照表,以及如何查閱完整組件 API 文件的說明,使其成為任何在 Angular 專案中整合 Aquila 的開發者的必備參考。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/allianz/ng-aquila/tree/HEAD/skills/aquila

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

Aquila – Angular Brand Kit 組件庫

Aquila(開源)/ Angular Brand Kit(原名 NDBX)是 Allianz 設計系統的 Angular 組件庫。請使用現代 Angular(v19+)模式: 獨立組件、信號(Signals)、新的控制流(@if、@for)、inject() 等。

導入規則

Aquila 組件是獨立的。直接導入組件:

import { NxButtonComponent } from '@allianz/ng-aquila/button';
import { NxFormfieldComponent } from '@allianz/ng-aquila/formfield';
import { NxInputDirective } from '@allianz/ng-aquila/input';

@Component({
  imports: [NxButtonComponent, NxFormfieldComponent, NxInputDirective],
})

導入路徑模式:@allianz/ng-aquila/{component-name}

Aquila 特定規則

  • 切勿在不使用 <nx-formfield> 包裹 <input nxInput> 的情況下使用 NxInputDirective
  • 在表單欄位內使用 <nx-error nxFormfieldError> 顯示驗證訊息
  • 務必在 <button nxButton> 上設定 type="button",以防止意外的表單提交
  • 建議搭配 Aquila 表單組件使用響應式表單(Reactive Forms)
  • 不要使用內聯 CSS 樣式;請依賴 Aquila 的內建樣式

帶驗證的表單欄位(響應式表單)

<form [formGroup]="form">
  <nx-formfield label="電子郵件">
    <input nxInput formControlName="email" type="email" />
    @if (form.controls.email.errors) {
      <nx-error nxFormfieldError>請輸入有效的電子郵件</nx-error>
    }
  </nx-formfield>
</form>

下拉選單

<nx-formfield label="國家">
  <nx-dropdown formControlName="country">
    <nx-dropdown-item value="DE">德國</nx-dropdown-item>
    <nx-dropdown-item value="CH">瑞士</nx-dropdown-item>
    <nx-dropdown-item value="AT">奧地利</nx-dropdown-item>
  </nx-dropdown>
</nx-formfield>

模態對話框

import { NxDialogService } from '@allianz/ng-aquila/modal';

const modalRef = inject(NxDialogService).open(MyDialogComponent);
modalRef.afterClosed().subscribe(result => { /* 處理結果 */ });

網格系統

12 欄響應式網格。nxCol 最多可接受 7 個以逗號分隔的斷點值, 順序為:tiny, small, medium, large, xlarge, 2xlarge, 3xlarge。 如果提供的值少於 7 個,最後一個值會重複用於其餘斷點 (例如 nxCol="12,8" → 12,8,8,8,8,8,8)。

<div nxLayout="grid">
  <div nxRow>
    <div nxCol="12,12,6">左側</div>
    <div nxCol="12,12,6">右側</div>
  </div>
</div>

最常使用的組件

組件選擇器
formfieldnx-formfield
inputinput[nxInput]
buttonbutton[nxButton]
iconnx-icon
dropdownnx-dropdown
checkboxnx-checkbox
grid[nxLayout]
headline[nxHeadline]
copytext[nxCopytext]
linknx-link
accordionnx-accordion
popover[nxPopoverTriggerFor]
badgenx-badge
datefieldinput[nxDatefield]
modalnx-modal
messagenx-message
data-displaynx-data-display
table[nxHeaderCell]
tabsnx-tab
listul[nxList]
radio-togglenx-radio-toggle
tooltip[nxTooltip]
switchernx-switcher
spinnernx-spinner
paginationnx-pagination

按使用案例查找組件

  • 表單:autocomplete, checkbox, circle-toggle, code-input, datefield, dropdown, file-uploader, formfield, input, natural-language-form, phone-input, radio-toggle, rating, slider, switcher, timefield
  • 導航:breadcrumb, header, menu, tabs, pagination
  • 表格:comparison-table, dynamic-table, table
  • 反饋:badge, indicator, message, modal, notification-panel, progress-stepper, progressbar, spinner, tooltip
  • 佈局:accordion, card, footer, grid, sidepanel, small-stage, toolbar
  • 覆蓋層:modal, overlay, popover
  • 媒體:avatar, icon, image, video
  • 互動:action, button, link, page-search, signal-button
  • 選擇:checkbox, circle-toggle, dropdown, radio-toggle, taglist

詳細 API

如需完整的組件 API(輸入、輸出、方法),請閱讀專案中已安裝套件的組件文檔: 通常位於 node_modules/@allianz/ng-aquila/mcp/generated/components/{component-name}.md 或類似路徑,具體取決於專案設定。 備用方案:使用 glob 搜尋 **/mcp/generated/**/。

相關技能