ControlValueAccessorの使い方｜自作の入力部品をフォーム対応

ControlValueAccessor は、自作の入力部品（星評価・金額入力など）を、formControl や ngModel で使えるようにするための約束（インターフェース）です。 4つのメソッドを実装し、NG_VALUE_ACCESSOR という名前で自分自身を登録すると、Angular のフォームが値の読み書きをしてくれます。

providers: [
  { provide: NG_VALUE_ACCESSOR, useExisting: forwardRef(() => StarRating), multi: true },
],

確認環境：Angular 22.2.2（@angular/core・@angular/forms）、Node.js 24.15.0（Linux）。ng new のプロジェクトで、TestBed＋Vitest 5.0.4（jsdom）で部品を動かし、メソッドが呼ばれる順をログに出しました。Signal Forms の API 名は angular.dev と、@angular/forms 22.2.2 の型定義で確かめました（確認日 2026年10月12日）。

完成コード①：星評価（1〜5）

クリックで 1〜5 を選ぶ部品です。値は number、何も選んでいないときは 0 として表示します。

// star-rating.ts
import { Component, forwardRef, signal } from '@angular/core';
import { ControlValueAccessor, NG_VALUE_ACCESSOR } from '@angular/forms';

@Component({
  selector: 'app-star-rating',
  template: `
    <div role="radiogroup" aria-label="評価" (focusout)="onTouched()">
      @for (n of stars; track n) {
        <button type="button" role="radio"
          [attr.aria-checked]="n === value()"
          [disabled]="disabled()"
          [class.on]="n <= value()"
          (click)="select(n)">★</button>
      }
    </div>`,
  styles: `
    button { border: 0; background: none; font-size: 24px; color: #ccc; cursor: pointer; }
    button.on { color: #f5a623; }
    button:disabled { cursor: not-allowed; opacity: .5; }`,
  providers: [
    { provide: NG_VALUE_ACCESSOR, useExisting: forwardRef(() => StarRating), multi: true },
  ],
})
export class StarRating implements ControlValueAccessor {
  readonly stars = [1, 2, 3, 4, 5];
  protected readonly value = signal(0);
  protected readonly disabled = signal(false);
  private onChange: (v: number) => void = () => {};
  protected onTouched: () => void = () => {};

  // フォーム → 部品
  writeValue(v: number | null): void {
    this.value.set(v ?? 0);          // ngModel は最初に null を渡してくる
  }
  registerOnChange(fn: (v: number) => void): void { this.onChange = fn; }
  registerOnTouched(fn: () => void): void { this.onTouched = fn; }
  setDisabledState(isDisabled: boolean): void { this.disabled.set(isDisabled); }

  // 部品 → フォーム（ユーザーの操作のときだけ呼ぶ）
  protected select(n: number) {
    this.value.set(n);
    this.onChange(n);
  }
}

ポイントは3つです。

• useExisting で「この部品自身」を登録する。forwardRef は、クラスの定義より前で自分を参照するために使う
• multi: true を付ける。NG_VALUE_ACCESSOR は、組み込みのアクセサーと並べて探される一覧のため
• 表示用の値・無効状態を Signal で持つと、v22 の既定（OnPush）でも writeValue の変更が画面に出る

Reactive Forms で使う

@Component({
  imports: [ReactiveFormsModule, JsonPipe, StarRating],
  template: `
    <form [formGroup]="form">
      <app-star-rating formControlName="rating" />
    </form>
    <p>{{ form.value | json }}</p>`,
})
export class ReviewForm {
  form = new FormGroup({
    rating: new FormControl(3, { nonNullable: true, validators: [Validators.min(1)] }),
  });
}

ngModel（テンプレート駆動フォーム）で使う

@Component({
  imports: [FormsModule, StarRating],
  template: `<app-star-rating [(ngModel)]="rating" name="rating" />`,
})
export class ReviewPage { rating = 4; }

部品の中は、どちらで使っても同じコードです。 Reactive Forms の組み方は、関連記事「Angularリアクティブフォームの使い方｜FormGroup・バリデーション」で扱っています。ngModel の使い方は、関連記事「Angularテンプレート駆動フォーム入門｜ngModelとエラー表示」で扱っています。

4つのメソッドが呼ばれる順（ログで確認）

各メソッドの先頭でログを取り、使い方ごとに順番を比べました。

ここから分かることです。

• Reactive Forms と ngModel では、writeValue が registerOnChange より先に呼ばれた。 writeValue の中で onChange を呼ぶ作りにすると、その時点ではまだ空の関数で、後で呼ぶと別の問題が起きる（後述）
• ngModel は最初に writeValue(null) を呼び、本当の値は少し後で来た。 null を受けても壊れないように書く（上のコードの v ?? 0）
• setDisabledState(false) も初期化のときに呼ばれた。 無効でなくても呼ばれる前提で書く

操作したときのフォームの状態

new FormControl(3) につないで操作した結果です。

dirty は onChange、touched は onTouched を部品が呼んだときにだけ変わりました。 エラー表示を「touched のとき」に出すフォームでは、onTouched を呼ばない部品だと、いつまでもエラーが出ません。

完成コード②：金額入力（3桁カンマ表示・値は数値）

表示は「1,980」、フォームの値は 1980（数値）にする部品です。全角数字で入力されても数値にします。

// yen-input.ts
import { Component, forwardRef, signal } from '@angular/core';
import { ControlValueAccessor, NG_VALUE_ACCESSOR } from '@angular/forms';

const fmt = new Intl.NumberFormat('ja-JP');
const toHalf = (s: string) => s.replace(/[０-９]/g, c => String.fromCharCode(c.charCodeAt(0) - 0xfee0));

@Component({
  selector: 'app-yen-input',
  template: `
    <span class="yen">
      <input type="text" inputmode="numeric" [value]="text()" [disabled]="disabled()"
             (input)="onInput($any($event.target).value)" (blur)="onBlur()" />
      <span>円</span>
    </span>`,
  providers: [{ provide: NG_VALUE_ACCESSOR, useExisting: forwardRef(() => YenInput), multi: true }],
})
export class YenInput implements ControlValueAccessor {
  protected readonly text = signal('');
  protected readonly disabled = signal(false);
  private onChange: (v: number | null) => void = () => {};
  private onTouched: () => void = () => {};

  writeValue(v: number | null): void {
    this.text.set(v == null ? '' : fmt.format(v));
  }
  registerOnChange(fn: (v: number | null) => void): void { this.onChange = fn; }
  registerOnTouched(fn: () => void): void { this.onTouched = fn; }
  setDisabledState(d: boolean): void { this.disabled.set(d); }

  protected onInput(raw: string) {
    const digits = toHalf(raw).replace(/[^\d]/g, '');
    this.text.set(raw);                                    // 入力中は打ったまま表示
    this.onChange(digits === '' ? null : Number(digits));  // フォームには数値
  }
  protected onBlur() {
    const digits = toHalf(this.text()).replace(/[^\d]/g, '');
    this.text.set(digits === '' ? '' : fmt.format(Number(digits)));  // 離れたらカンマ付きに
    this.onTouched();
  }
}

new FormControl<number | null>(1980) につないだ結果です。

入力中にカンマを付け直すと、カーソルの位置がずれやすいので、カンマはフォーカスが外れたときに付けています。

Signal Forms（v22）で自作部品を作る：FormValueControl

v22 で安定版になった Signal Forms（@angular/forms/signals）では、ControlValueAccessor の代わりに FormValueControl<T> を実装します。 angular.dev の説明では、必須は value という model() だけで、disabled・touched・invalid・errors などは、必要なものだけ input() で受け取ります。フォーカスが外れたことは touch という output() で伝えます。

// star-signal.ts
import { Component, input, model, output } from '@angular/core';
import { FormValueControl } from '@angular/forms/signals';

@Component({
  selector: 'app-star-signal',
  template: `
    <div role="radiogroup" aria-label="評価" (focusout)="touch.emit()">
      @for (n of stars; track n) {
        <button type="button" role="radio" [attr.aria-checked]="n === value()"
          [disabled]="disabled()" [class.on]="n <= value()" (click)="value.set(n)">★</button>
      }
    </div>
    @if (touched() && invalid()) { <p class="err">評価を選んでください</p> }`,
})
export class StarSignal implements FormValueControl<number> {
  readonly stars = [1, 2, 3, 4, 5];
  readonly value = model(0);          // 必須
  readonly disabled = input(false);   // 以下は使うものだけ
  readonly touched = input(false);
  readonly invalid = input(false);
  readonly touch = output<void>();
}

// 使う側
import { form, FormField, min, disabled } from '@angular/forms/signals';

@Component({
  imports: [FormField, StarSignal],
  template: `<app-star-signal [formField]="f.rating" />`,
})
export class ReviewSignalForm {
  model = signal({ rating: 0, locked: false });
  f = form(this.model, p => {
    min(p.rating, 1);
    disabled(p.rating, ({ valueOf }) => valueOf(p.locked));
  });
}

動かした結果です。

registerOnChange などの関数を受け渡す代わりに、Signal の input・model でつながるので、コードが短くなりました。 Signal Forms 全体の書き方は、関連記事「Angular Signal Forms入門｜v22安定版のAPI早見表と完成コード」で扱っています。

既存の部品と組み合わせられるか

angular.dev には、Signal Forms 用の部品は Reactive Forms・テンプレート駆動フォームでもそのまま使える、とあります。両方向で試しました。

どちらも動いたので、既存の ControlValueAccessor 部品を残したまま、フォームを少しずつ Signal Forms に移すことができます。

touched・disabled が効かない原因表

うまく動かない部品をわざと作り、何が起きるかを確かめました。

NG01203 は、angular.dev のエラー一覧でも「自作のフォーム部品には value accessor の登録が要る」と説明されています。v22 の変更検知（OnPush が既定）については、関連記事「Angular変更検知とOnPush｜markForCheckの使い方」で扱っています。

よくある質問

Q. (blur) と (focusout) のどちらで onTouched を呼びますか。 A. 星評価のようにボタンが並ぶ部品では、中のボタン間を移動するたびに blur が出ます。今回は外側の要素で、子要素のフォーカス移動も拾える focusout を使いました。input が1つの部品なら (blur) です。

Q. 部品の中で @Input() value を作るのはどうですか。 A. ControlValueAccessor では、値は writeValue で受け取ります。value を input にもすると、フォームからの値と input からの値の2つの入口ができて、どちらが正しいか分かりにくくなります。Signal Forms の FormValueControl では、逆に value を model() で持つ決まりです。親子の受け渡しは関連記事「Angular input・output・modelの使い方｜親子の受け渡し」で扱っています。

Q. 入力チェックは部品の中に書きますか。 A. angular.dev の Signal Forms の説明では、チェックの決まりはフォーム側（スキーマ）に置き、部品は結果を表示するだけにする方針です。Reactive Forms でも、Validators.min(1) のようにフォーム側に付けると、部品を別の場面で使い回せます。独自のチェックは関連記事「Angularカスタムバリデーターの作り方｜非同期・相関チェック」で扱っています。

まとめ

• ControlValueAccessor は writeValue・registerOnChange・registerOnTouched・setDisabledState の4つ
• 登録は { provide: NG_VALUE_ACCESSOR, useExisting: forwardRef(() => 部品), multi: true }
• v22.2.2 では writeValue が registerOnChange より先。ngModel は最初に writeValue(null)
• dirty は onChange、touched は onTouched を部品が呼んだときだけ変わる
• v22 の Signal Forms では FormValueControl（value = model()）。既存の部品と 両方向で組み合わせられた

参考・出典

確認日はいずれも 2026年10月12日です。

• Angular API「ControlValueAccessor」：https://angular.dev/api/forms/ControlValueAccessor
• Angular「NG01203: Missing value accessor」：https://angular.dev/errors/NG01203
• Angular「Custom controls」（Signal Forms）：https://angular.dev/guide/forms/signals/custom-controls
• JavaScript Conference「Angular Reactive Forms: Building Custom Form Controls」：https://javascript-conference.com/blog/angular-reactive-forms-building-custom-form-controls/

株式会社RJC ― SI事業・SES事業・AI駆動開発。RJCは一緒に成長を楽しめる会社です。