PAYATHON 2026

Angular 中如何创建可复用的嵌套 FormGroup 组件

数据小陈

结论

可以按你期望的写法来做。做法是利用 Angular 的 formGroupName 指令,在组件宿主元素上提供 ControlContainer。父表单里要先有 address 这个 FormGroup,子组件模板里的 formControlName 就会注册到父表单的 address 组。子组件不要再创建自己的 FormGroup,否则会出现两套独立表单。

如果希望组件边界更清晰、测试和维护更方便,也可以让父组件创建 address 组,子组件通过输入属性接收 FormGroup,再在模板里绑定 [formGroup]。两种方式下面都会给出。

方式一:在宿主元素上使用 formGroupName

父组件负责创建完整表单模型:

import { Component, inject } from '@angular/core';
import { FormBuilder, ReactiveFormsModule, Validators } from '@angular/forms';
import { AddressInput } from './address-input';

@Component({
  selector: 'app-parent',
  imports: [ReactiveFormsModule, AddressInput],
  templateUrl: './parent.html',
})
export class ParentComponent {
  private formBuilder = inject(FormBuilder);

  defaultCountry: string =
    new Intl.Locale(navigator.language).region ?? 'TR';

  parentForm = this.formBuilder.group({
    name: ['', Validators.required],
    address: this.formBuilder.group({
      addressLine: ['', Validators.required],
      zipCode: ['', Validators.required],
      district: ['', Validators.required],
      city: ['', Validators.required],
      state: [''],
      country: [this.defaultCountry, Validators.required],
    }),
  });
}

父模板:

<form [formGroup]="parentForm">
  <input formControlName="name" placeholder="Name">

  <app-address-input formGroupName="address"></app-address-input>
</form>

子组件不再创建 FormGroup:

import { Component, Input } from '@angular/core';
import { ReactiveFormsModule } from '@angular/forms';
import { CountrySelectBox } from '../country-select-box/country-select-box';

@Component({
  selector: 'app-address-input',
  imports: [ReactiveFormsModule, CountrySelectBox],
  templateUrl: './address-input.html',
})
export class AddressInput {
  @Input() defaultCountry: string =
    new Intl.Locale(navigator.language).region ?? 'TR';
}

子模板直接使用 formControlName,不要再包一层 [formGroup]="form":

<input formControlName="addressLine" placeholder="Address Line">
<input formControlName="zipCode" placeholder="Zip Code">
<input formControlName="district" placeholder="District">
<input formControlName="city" placeholder="City">
<input formControlName="state" placeholder="State">

<app-country-select-box
  [default]="defaultCountry"
  formControlName="country">
</app-country-select-box>

这里的机制是:<app-address-input formGroupName="address"> 上的 formGroupName 会从父级 FormGroupDirective 中取出名为 address 的 FormGroup,并在宿主元素上提供 ControlContainer。子组件模板里的 formControlName 会向上查找这个 ControlContainer,因此注册进父表单的 address 组。

如果子组件内部需要访问这个组,例如显示整体校验状态,可以注入 ControlContainer:

import { Component, Input } from '@angular/core';
import { ControlContainer, FormGroup } from '@angular/forms';

@Component({
  selector: 'app-address-input',
  templateUrl: './address-input.html',
})
export class AddressInput {
  @Input() defaultCountry: string =
    new Intl.Locale(navigator.language).region ?? 'TR';

  constructor(private controlContainer: ControlContainer) {}

  get addressForm(): FormGroup {
    return this.controlContainer.control as FormGroup;
  }
}

这种写法依赖宿主元素上存在 formGroupName。如果组件可能被单独使用,可以用 @Optional() 注入,并处理空值情况。

方式二:显式传入 FormGroup(更推荐)

显式传组的数据流更清楚,也不依赖宿主元素上的指令,所以很多项目更愿意用这种方式。父组件仍然负责创建 address 组:

addressForm = this.formBuilder.group({
  addressLine: ['', Validators.required],
  zipCode: ['', Validators.required],
  district: ['', Validators.required],
  city: ['', Validators.required],
  state: [''],
  country: [this.defaultCountry, Validators.required],
});

parentForm = this.formBuilder.group({
  name: ['', Validators.required],
  address: this.addressForm,
});

父模板:

<form [formGroup]="parentForm">
  <input formControlName="name">

  <app-address-input [form]="addressForm"></app-address-input>
</form>

子组件:

import { Component, Input } from '@angular/core';
import { FormGroup, ReactiveFormsModule } from '@angular/forms';
import { CountrySelectBox } from '../country-select-box/country-select-box';

@Component({
  selector: 'app-address-input',
  imports: [ReactiveFormsModule, CountrySelectBox],
  templateUrl: './address-input.html',
})
export class AddressInput {
  @Input({ required: true }) form!: FormGroup;
  @Input() defaultCountry: string =
    new Intl.Locale(navigator.language).region ?? 'TR';
}

子模板:

<div [formGroup]="form">
  <input formControlName="addressLine" placeholder="Address Line">
  <input formControlName="zipCode" placeholder="Zip Code">
  <input formControlName="district" placeholder="District">
  <input formControlName="city" placeholder="City">
  <input formControlName="state" placeholder="State">

  <app-country-select-box
    [default]="defaultCountry"
    formControlName="country">
  </app-country-select-box>
</div>

这样父表单的最终值仍然是:

{
  name: 'John',
  address: {
    addressLine: '...',
    zipCode: '...',
    district: '...',
    city: '...',
    state: '...',
    country: 'TR'
  }
}

注意事项

  • address 在父表单中必须已经是 FormGroup,不能是 null 或未定义,否则 formGroupName 会找不到对应控件。
  • 子组件不要同时保留自己的 form 和父级的 formGroupName。两套 FormGroup 会导致值不联动,父表单也拿不到子组件内部控件的值。
  • ControlValueAccessor 主要解决单个自定义控件如何接入 formControlName 的问题,并不负责让一个组件充当 FormGroup。地址这种多字段组,优先用父子 FormGroup 组合。
  • 如果子组件模板里用了 <form> 标签,注意不要形成嵌套 <form>。在这种复用场景里,子组件模板通常用 <div> 或 <ng-container> 就够。
  • 校验逻辑应放在父表单创建的 address 组上,例如 parentForm.get('address')?.valid,不要依赖子组件内部另建的组。

备注:内容仅供参考。