シグナルを使ったフォーム • Angular 日本語版

シグナルフォームはAngularのシグナルを使用してフォームの状態を管理し、データモデルとUI間の自動的な同期を提供します。

このガイドでは、シグナルフォームでフォームを作成するための中心的な概念を順を追って説明します。その仕組みは次のとおりです:

最初のフォームを作成する

1. `signal()`でフォームモデルを作成する

すべてのフォームは、フォームのデータモデルを保持するシグナルを作成することから始まります:

interface LoginData {  email: string;  password: string;}const loginModel = signal<LoginData>({  email: '',  password: '',});

2. フォームモデルを`form()`に渡して`FieldTree`を作成する

次に、フォームモデルをform()関数に渡してフィールドツリーを作成します。これはモデルの形状を反映したオブジェクト構造で、ドット記法でフィールドにアクセスできます:

const loginForm = form(loginModel);// Access fields directly by property nameloginForm.emailloginForm.password

3. `[field]`ディレクティブでHTML入力をバインドする

次に、[field]ディレクティブを使用してHTMLの入力をフォームにバインドします。これにより、それらの間に双方向バインディングが作成されます:

<input type="email" [field]="loginForm.email" /><input type="password" [field]="loginForm.password" />

その結果、ユーザーによる変更（フィールドへの入力など）は自動的にフォームを更新します。

NOTE: [field]ディレクティブは、必要に応じてrequired、disabled、readonlyなどの属性のフィールドの状態も同期します。

4. `value()`でフィールドの値を読み取る

フィールドを関数として呼び出すことで、フィールドの状態にアクセスできます。これにより、フィールドの値、バリデーションステータス、インタラクションの状態に対するリアクティブなシグナルを含むFieldStateオブジェクトが返されます:

loginForm.email() // Returns FieldState with value(), valid(), touched(), etc.

フィールドの現在の値を読み取るには、value()シグナルにアクセスします:

<!-- Render form value that updates automatically as user types --><p>Email: {{ loginForm.email().value() }}</p>

// Get the current valueconst currentEmail = loginForm.email().value();

5. `set()`でフィールドの値を更新する

value.set()メソッドを使用して、プログラムからフィールドの値を更新できます。これにより、フィールドと基になるモデルシグナルの両方が更新されます:

// Update the value programmaticallyloginForm.email().value.set('[email protected]');

その結果、フィールドの値とモデルシグナルの両方が自動的に更新されます:

// The model signal is also updatedconsole.log(loginModel().email); // '[email protected]'

完全な例は次のとおりです:

基本的な使い方

[field]ディレクティブは、すべての標準的なHTMLのinputタイプで動作します。以下は、最も一般的なパターンです:

テキスト入力

テキスト入力は、さまざまなtype属性やtextareaで動作します:

<!-- Text and email --><input type="text" [field]="form.name" /><input type="email" [field]="form.email" />

数値

数値入力は、文字列と数値を自動的に変換します:

<!-- Number - automatically converts to number type --><input type="number" [field]="form.age" />

日付と時刻

日付入力は値をYYYY-MM-DD形式の文字列として保存し、時刻入力はHH:mm形式を使用します:

<!-- Date and time - stores as ISO format strings --><input type="date" [field]="form.eventDate" /><input type="time" [field]="form.eventTime" />

日付文字列をDateオブジェクトに変換する必要がある場合は、フィールドの値をDate()に渡すことで変換できます:

const dateObject = new Date(form.eventDate().value());

複数行テキスト

Textareaはテキスト入力と同じように動作します:

<!-- Textarea --><textarea [field]="form.message" rows="4"></textarea>

チェックボックス

チェックボックスはブール値にバインドされます:

<!-- Single checkbox --><label>  <input type="checkbox" [field]="form.agreeToTerms" />  I agree to the terms</label>

複数チェックボックス

複数のオプションがある場合は、それぞれに個別のブール値のfieldを作成します:

<label>  <input type="checkbox" [field]="form.emailNotifications" />  Email notifications</label><label>  <input type="checkbox" [field]="form.smsNotifications" />  SMS notifications</label>

ラジオボタン

ラジオボタンはチェックボックスと同様に動作します。ラジオボタンが同じ[field]値を使用している限り、シグナルフォームは自動的に同じname属性をすべてのラジオボタンにバインドします:

<label>  <input type="radio" value="free" [field]="form.plan" />  Free</label><label>  <input type="radio" value="premium" [field]="form.plan" />  Premium</label>

ユーザーがラジオボタンを選択すると、フォームのfieldにはそのラジオボタンのvalue属性の値が保存されます。例えば、「Premium」を選択すると、form.plan().value()は"premium"に設定されます。

selectドロップダウン

Select要素は、静的オプションと動的オプションの両方で動作します:

<!-- Static options --><select [field]="form.country">  <option value="">Select a country</option>  <option value="us">United States</option>  <option value="ca">Canada</option></select><!-- Dynamic options with @for --><select [field]="form.productId">  <option value="">Select a product</option>  @for (product of products; track product.id) {    <option [value]="product.id">{{ product.name }}</option>  }</select>

NOTE: 複数選択(<select multiple>)は、現時点では[field]ディレクティブでサポートされていません。

バリデーションと状態

シグナルフォームには、フォームフィールドに適用できる組み込みのバリデーターが用意されています。バリデーションを追加するには、form()の第2引数にスキーマ関数を渡します。この関数は、フォームモデル内のフィールドを参照できるスキーマパスパラメーターを受け取ります:

const loginForm = form(loginModel, (schemaPath) => {  debounce(schemaPath.email, 500);  required(schemaPath.email);  email(schemaPath.email);});

NOTE: スキーマパスパラメーターは、バリデーションルールを適用するためのフィールドへのパスを提供します。フィールドの値と状態にアクセスするには、フィールドツリー（loginForm.email()など）を使用してください。

一般的なバリデーターには次のものがあります:

required() - フィールドに値があることを保証します
email() - メール形式を検証します
min() / max() - 数値の範囲を検証します
minLength() / maxLength() - 文字列またはコレクションの長さを検証します
pattern() - 正規表現パターンに対して検証します

バリデーターの第2引数にオプションオブジェクトを渡すことで、エラーメッセージをカスタマイズできます:

required(schemaPath.email, { message: 'Email is required' });email(schemaPath.email, { message: 'Please enter a valid email address' });

各フォームフィールドは、シグナルを通じてそのバリデーション状態を公開します。たとえば、field().valid()をチェックしてバリデーションが成功したか、field().touched()をチェックしてユーザーが操作したかを確認し、field().errors()をチェックしてバリデーションエラーのリストを取得できます。

以下に完全な例を示します:

app.ts

import {Component, signal, ChangeDetectionStrategy} from '@angular/core';import {form, Field, required, email} from '@angular/forms/signals';interface LoginData {  email: string;  password: string;}@Component({  selector: 'app-root',  templateUrl: 'app.html',  styleUrl: 'app.css',  imports: [Field],  changeDetection: ChangeDetectionStrategy.OnPush,})export class App {  loginModel = signal<LoginData>({    email: '',    password: '',  });  loginForm = form(this.loginModel, (schemaPath) => {    required(schemaPath.email, {message: 'Email is required'});    email(schemaPath.email, {message: 'Enter a valid email address'});    required(schemaPath.password, {message: 'Password is required'});  });  onSubmit(event: Event) {    event.preventDefault();    // Perform login logic here    const credentials = this.loginModel();    console.log('Logging in with:', credentials);    // e.g., await this.authService.login(credentials);  }}

app.html

<form (submit)="onSubmit($event)">  <div>    <label>      Email:      <input type="email" [field]="loginForm.email" />    </label>    @if (loginForm.email().touched() && loginForm.email().invalid()) {      <ul class="error-list">        @for (error of loginForm.email().errors(); track error) {          <li>{{ error.message }}</li>        }      </ul>    }  </div>  <div>    <label>      Password:      <input type="password" [field]="loginForm.password" />    </label>    @if (loginForm.password().touched() && loginForm.password().invalid()) {      <div class="error">        @for (error of loginForm.password().errors(); track error) {          <p>{{ error.message }}</p>        }      </div>    }  </div>  <button type="submit">Log In</button></form>

app.css

form {  display: flex;  flex-direction: column;  gap: 1rem;  max-width: 400px;  padding: 1rem;  font-family:    Inter,    system-ui,    -apple-system,    sans-serif;}div {  display: flex;  flex-direction: column;  gap: 0.25rem;}label {  display: flex;  flex-direction: column;  gap: 0.25rem;  font-weight: 500;}input {  padding: 0.5rem;  border: 1px solid #ccc;  border-radius: 4px;  font-size: 1rem;  font-family: inherit;}input:focus {  outline: none;  border-color: #4285f4;}button {  padding: 0.75rem 1.5rem;  background-color: #4285f4;  color: white;  border: none;  border-radius: 4px;  font-size: 1rem;  font-family: inherit;  cursor: pointer;  transition: background-color 0.2s;}button:hover {  background-color: #357ae8;}button:active {  background-color: #2a65c8;}.error-list {  color: red;  font-size: 0.875rem;  margin: 0.25rem 0 0 0;  padding-left: 0;  list-style-position: inside;}.error-list p {  margin: 0;}

フィールドの状態シグナル

すべてのfield()は、これらの状態シグナルを提供します:

状態	説明
`valid()`	フィールドがすべてのバリデーションルールをパスした場合に`true`を返します
`touched()`	ユーザーがフィールドにフォーカスしてぼかした場合に`true`を返します
`dirty()`	ユーザーが値を変更した場合に`true`を返します
`disabled()`	フィールドが無効になっている場合に`true`を返します
`pending()`	非同期バリデーションが進行中の場合に`true`を返します
`errors()`	`kind`と`message`プロパティを持つバリデーションエラーの配列を返します

TIP: debounce()バリデーションルールを使用して、ユーザーが入力を停止するかフィールドを離れるまでエラー表示を遅延させます。これにより、ユーザーがまだ入力中にエラーが表示されるのを防ぎます。