allianz/ng-aquila

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/{组件名}

Aquila 特有规则

• 绝不要在没有将 <input nxInput> 包裹在 <nx-formfield> 中的情况下使用 NxInputDirective
• 在表单域内使用 <nx-error nxFormfieldError> 显示验证消息
• 始终在 <button nxButton> 上设置 type="button" 以防止意外的表单提交
• 优先使用响应式表单与 Aquila 表单组件
• 不要使用内联 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>

最常用组件

组件	选择器
formfield	nx-formfield
input	input[nxInput]
button	button[nxButton]
icon	nx-icon
dropdown	nx-dropdown
checkbox	nx-checkbox
grid	[nxLayout]
headline	[nxHeadline]
copytext	[nxCopytext]
link	nx-link
accordion	nx-accordion
popover	[nxPopoverTriggerFor]
badge	nx-badge
datefield	input[nxDatefield]
modal	nx-modal
message	nx-message
data-display	nx-data-display
table	[nxHeaderCell]
tabs	nx-tab
list	ul[nxList]
radio-toggle	nx-radio-toggle
tooltip	[nxTooltip]
switcher	nx-switcher
spinner	nx-spinner
pagination	nx-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/{组件名}.md 或根据项目设置位于类似路径下。后备方案：使用 glob 搜索 **/mcp/generated/**/。