Sinyallerle formlar

Signal Forms, Angular Sinyalleri ile veri modeliniz ve kullanıcı arayüzü arasında otomatik senkronizasyon sağlamak için Angular sinyallerini kullanarak form durumunu yönetir.

Bu kılavuz, Signal Forms ile form oluşturmanın temel kavramlarında size yol gösterir. İşte nasıl çalıştığı:

İlk Formunuzu Oluşturma

1. signal() ile Bir Form Modeli Oluşturun

Her form, formunuzun veri modelini tutan bir sinyal oluşturarak başlar:

interface LoginData {
  email: string;
  password: string;
}

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

2. Bir FieldTree Oluşturmak İçin Form Modelini form() Fonksiyonuna Geçirin

Ardından, form modelinizi form() fonksiyonuna geçirerek bir alan ağacı (field tree) oluşturursunuz - modelinizin yapısını yansıtan ve nokta notasyonuyla alanlara erişmenizi sağlayan bir nesne yapısı:

const loginForm = form(loginModel);

// Alanlara doğrudan özellik adıyla erişin
loginForm.email;
loginForm.password;

3. HTML Girdilerini [formField] Direktifi ile Bağlayın

Ardından, HTML girdilerinizi [formField] direktifi kullanarak forma bağlarsınız; bu, aralarında iki yönlü bağlama oluşturur:

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

Sonuç olarak, kullanıcı değişiklikleri (alana yazma gibi) formu otomatik olarak günceller.

4. value() ile Alan Değerlerini Okuyun

Alanı bir fonksiyon olarak çağırarak alan durumuna erişebilirsiniz. Bu, alanın değeri, doğrulama durumu ve etkileşim durumu için reaktif sinyaller içeren bir FieldState nesnesi döndürür:

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

Alanın mevcut değerini okumak için value() sinyaline erişin:

<!-- Kullanıcı yazarken otomatik olarak güncellenen form değerini render et -->
<p>Email: {{ loginForm.email().value() }}</p>

// Mevcut değeri al
const currentEmail = loginForm.email().value();

5. set() ile Alan Değerlerini Güncelleyin

Bir alanın değerini value.set() metodunu kullanarak programatik olarak güncelleyebilirsiniz. Bu, hem alanı hem de alttaki model sinyalini günceller:

// Değeri programatik olarak güncelle
loginForm.email().value.set('alice@wonderland.com');

Sonuç olarak, hem alan değeri hem de model sinyali otomatik olarak güncellenir:

// Model sinyali de güncellenir
console.log(loginModel().email); // 'alice@wonderland.com'

İşte eksiksiz bir örnek:

import {Component, signal} from '@angular/core';
import {form, FormField} from '@angular/forms/signals';

interface LoginData {
  email: string;
  password: string;
}

@Component({
  selector: 'app-root',
  templateUrl: 'app.html',
  styleUrl: 'app.css',
  imports: [FormField],
})
export class App {
  loginModel = signal<LoginData>({
    email: '',
    password: '',
  });

  loginForm = form(this.loginModel);
}

<form>
  <label>
    Email:
    <input type="email" [formField]="loginForm.email" />
  </label>

  <label>
    Password:
    <input type="password" [formField]="loginForm.password" />
  </label>

  <p>Hello {{ loginForm.email().value() }}!</p>
  <p>Password length: {{ loginForm.password().value().length }}</p>
</form>

form {
  display: flex;
  flex-direction: column;
  gap: 1rem;
  max-width: 400px;
  padding: 1rem;
  font-family: Inter, system-ui, -apple-system, sans-serif;
}

label {
  display: flex;
  flex-direction: column;
  gap: 0.25rem;
}

input {
  padding: 0.5rem;
  border: 1px solid #ccc;
  border-radius: 4px;
  font-size: 1rem;
  font-family: inherit;
}

p {
  margin: 0.5rem 0;
  color: #666;
}

Temel Kullanım

[formField] direktifi tüm standart HTML girdi türleriyle çalışır. İşte en yaygın kullanım kalıpları:

Metin Girdileri

Metin girdileri çeşitli type öznitelikleri ve textarea'larla çalışır:

<!-- Metin ve e-posta -->
<input type="text" [formField]="form.name" />
<input type="email" [formField]="form.email" />

Sayılar

Sayı girdileri, dizeler ve sayılar arasında otomatik olarak dönüşüm yapar:

<!-- Sayı - otomatik olarak sayı türüne dönüştürür -->
<input type="number" [formField]="form.age" />

Tarih ve Saat

Tarih girdileri değerleri YYYY-MM-DD dizesi olarak saklar ve zaman girdileri HH:mm biçimini kullanır:

<!-- Tarih ve saat - ISO biçiminde dize olarak saklar -->
<input type="date" [formField]="form.eventDate" />
<input type="time" [formField]="form.eventTime" />

Tarih dizelerini Date nesnelerine dönüştürmeniz gerekiyorsa, alan değerini Date() fonksiyonuna geçirerek bunu yapabilirsiniz:

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

Çok Satırlı Metin

Textarea'lar metin girdileriyle aynı şekilde çalışır:

<!-- Metin alanı -->
<textarea [formField]="form.message" rows="4"></textarea>

Onay Kutuları

Onay kutuları boolean değerlere bağlanır:

<!-- Tekli onay kutusu -->
<label>
  <input type="checkbox" [formField]="form.agreeToTerms" />
  I agree to the terms
</label>

Çoklu Onay Kutuları

Birden fazla seçenek için her biri için ayrı bir boolean formField oluşturun:

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

Radyo Düğmeleri

Radyo düğmeleri onay kutularına benzer şekilde çalışır. Radyo düğmeleri aynı [formField] değerini kullandığı sürece, Signal Forms otomatik olarak hepsine aynı name özniteliğini bağlar:

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

Kullanıcı bir radyo düğmesi seçtiğinde, form formField o radyo düğmesinin value özniteliğindeki değeri saklar. Örneğin, "Premium" seçildiğinde form.plan().value() "premium" olarak ayarlanır.

Select Açılır Menüler

Select elementleri hem statik hem de dinamik seçeneklerle çalışır:

<!-- Statik seçenekler -->
<select [formField]="form.country">
  <option value="">Select a country</option>
  <option value="us">United States</option>
  <option value="ca">Canada</option>
</select>

<!-- @for ile dinamik seçenekler -->
<select [formField]="form.productId">
  <option value="">Select a product</option>
  @for (product of products; track product.id) {
    <option [value]="product.id">{{ product.name }}</option>
  }
</select>

Doğrulama ve Durum

Signal Forms, form alanlarınıza uygulayabileceğiniz yerleşik doğrulayıcılar sağlar. Doğrulama eklemek için form() fonksiyonuna ikinci argüman olarak bir şema fonksiyonu geçirin:

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

Şema fonksiyonu, doğrulama kurallarını yapılandırmak için alanlarınıza yollar sağlayan bir şema yolu parametresi alır.

Yaygın doğrulayıcılar şunlardır:

• required() - Alanın bir değere sahip olmasını sağlar
• email() - E-posta biçimini doğrular
• min() / max() - Sayı aralıklarını doğrular
• minLength() / maxLength() - Dize veya koleksiyon uzunluğunu doğrular
• pattern() - Bir regex kalıbına göre doğrular

Doğrulayıcıya ikinci argüman olarak bir seçenekler nesnesi geçirerek hata mesajlarını da özelleştirebilirsiniz:

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

Her form alanı, doğrulama durumunu sinyaller aracılığıyla sunar. Örneğin, doğrulamanın geçip geçmediğini görmek için field().valid(), kullanıcının etkileşimde bulunup bulunmadığını görmek için field().touched() ve doğrulama hatalarının listesini almak için field().errors() kontrol edebilirsiniz.

İşte eksiksiz bir örnek:

import {Component, signal} from '@angular/core';
import {email, form, FormField, required} from '@angular/forms/signals';

interface LoginData {
  email: string;
  password: string;
}

@Component({
  selector: 'app-root',
  templateUrl: 'app.html',
  styleUrl: 'app.css',
  imports: [FormField],
})
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);
  }
}

<form (submit)="onSubmit($event)">
  <div>
    <label>
      Email:
      <input type="email" [formField]="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" [formField]="loginForm.password" />
    </label>

    @if (loginForm.password().touched() && loginForm.password().invalid()) {
      <div class="error-list">
        @for (error of loginForm.password().errors(); track error) {
          <p>{{ error.message }}</p>
        }
      </div>
    }
  </div>

  <button type="submit">Log In</button>
</form>

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;
}

Alan Durumu Sinyalleri

Her field() şu durum sinyallerini sağlar:

Sonraki Adımlar

Signal Forms ve nasıl çalıştığı hakkında daha fazla bilgi edinmek için detaylı kılavuzlara göz atın:

• Overview - Signal Forms'a giriş ve ne zaman kullanılacağı
• Form models - Sinyallerle form verisi oluşturma ve yönetme
• Field state management - Doğrulama durumu, etkileşim takibi ve alan görünürlüğü ile çalışma
• Validation - Yerleşik doğrulayıcılar, özel doğrulama kuralları ve asenkron doğrulama