Directives

Formları, listeleri, stilleri ve kullanıcıların gördüklerini yönetmek için Angular’ın yerleşik yönergelerini kullanın.

Farklı Angular yönerge türleri aşağıdaki gibidir:

Yerleşik öznitelik yönergeleri #

Öznitelik yönergeleri diğer HTML öğelerinin, özniteliklerinin, özelliklerinin ve bileşenlerinin davranışlarını dinler ve değiştirir.

The most common attribute directives are as follows:

YARDIMCI: Yerleşik yönergeler yalnızca genel API’leri kullanır. Diğer yönergelerin erişemediği herhangi bir özel API’ye özel erişimleri yoktur.

NgClass ile sınıf ekleme ve kaldırma #

ngClass ile aynı anda birden fazla CSS sınıfı ekleyin veya kaldırın.

YARARLI: Tek bir sınıf eklemek veya kaldırmak için NgClass yerine class binding kullanın.

Bileşende NgClass’ı içe aktarma #

NgClass‘ı kullanmak için bileşenin imports listesine ekleyin.

import {NgClass} from '@angular/common';
...
@Component({
  standalone: true,
...
    NgClass, // <-- import into the component
...
  ],
})
export class AppComponent implements OnInit {
...
}

NgClass’ı bir ifade ile kullanma #

Stil vermek istediğiniz öğeye [ngClass] ekleyin ve bunu bir ifadeye eşit olarak ayarlayın. Bu durumda isSpecial, app.component.ts dosyasında true olarak ayarlanmış bir boolean’dır. isSpecial true olduğu için ngClass, <div> öğesine special sınıfını uygular.

<!-- toggle the "special" class on/off with a property -->
<div [ngClass]="isSpecial ? 'special' : ''">This div is special</div>

NgClass’ı bir yöntemle kullanma #

1-NgClass‘ı bir yöntemle kullanmak için yöntemi bileşen sınıfına ekleyin. Aşağıdaki örnekte setCurrentClasses(), currentClasses özelliğini, diğer üç bileşen özelliğinin true veya false durumuna göre üç sınıf ekleyen veya kaldıran bir nesneyle ayarlar.

Nesnenin her bir anahtarı bir CSS sınıf adıdır. Eğer bir anahtar true ise, ngClass sınıfı ekler. Bir anahtar false ise, ngClass sınıfı kaldırır.

currentClasses: Record<string, boolean> = {};
...
  setCurrentClasses() {
    // CSS classes: added/removed per current state of component properties
    this.currentClasses = {
      saveable: this.canSave,
      modified: !this.isUnchanged,
      special: this.isSpecial,
    };
  }

2-Şablonda, öğenin sınıflarını ayarlamak için currentClasses‘a bağlanan ngClass özelliğini ekleyin:

<div [ngClass]="currentClasses">This div is initially saveable, unchanged, and special.</div>

Bu kullanım durumu için Angular, sınıfları başlatma sırasında ve değişiklik durumunda uygular. Tam örnek, başlangıçta ngOnInit() ile ve bağımlı özellikler bir düğme tıklamasıyla değiştiğinde setCurrentClasses() işlevini çağırır. Bu adımlar ngClass‘ı uygulamak için gerekli değildir.

NgStyle ile satır içi stilleri ayarlama #

Bileşende NgStyle’ı içe aktarma

NgStyle’ı kullanmak için bileşenin içe aktarılanlar listesine ekleyin.

import {NgStyle} from '@angular/common';
...
@Component({
  standalone: true,
...
    NgStyle, // <-- import into the component
...
  ],
})
export class AppComponent implements OnInit {
...
}

Bileşenin durumuna bağlı olarak birden fazla satır içi stili aynı anda ayarlamak için NgStyle’ı kullanın.

1-NgStyle‘ı kullanmak için bileşen sınıfına bir yöntem ekleyin.

Aşağıdaki örnekte, setCurrentStyles() işlevi currentStyles özelliğini, diğer üç bileşen özelliğinin durumuna bağlı olarak üç stil tanımlayan bir nesneyle ayarlar.

currentStyles: Record<string, string> = {};
...
  setCurrentStyles() {
    // CSS styles: set per current state of component properties
    this.currentStyles = {
      'font-style': this.canSave ? 'italic' : 'normal',
      'font-weight': !this.isUnchanged ? 'bold' : 'normal',
      'font-size': this.isSpecial ? '24px' : '12px',
    };
  }

2-Öğenin stillerini ayarlamak için currentStyles öğesine bağlanan bir ngStyle özelliği ekleyin.

<div [ngStyle]="currentStyles">
  This div is initially italic, normal weight, and extra large (24px).
</div>

Bu kullanım durumu için Angular, stilleri başlatma sırasında ve değişiklik durumunda uygular. Bunu yapmak için, tam örnek setCurrentStyles() işlevini başlangıçta ngOnInit() ile ve bağımlı özellikler bir düğme tıklamasıyla değiştiğinde çağırır. Ancak, ngStyle‘ı tek başına uygulamak için bu adımlar gerekli değildir.

ngModel ile özellikleri görüntüleme ve güncelleme #

Bir veri özelliğini görüntülemek ve kullanıcı değişiklik yaptığında bu özelliği güncellemek için NgModel yönergesini kullanın.

1-FormsModule‘ü içe aktarın ve AppComponent’in imports listesine ekleyin.

import {FormsModule} from '@angular/forms';
...
@Component({
  standalone: true,
...
    FormsModule, // <--- import into the component
...
  ],
})
export class AppComponent implements OnInit {
...
}

2-HTML <form> öğesine bir [(ngModel)] bağlayıcısı ekleyin ve bunu burada name verilen özelliğe eşit olarak ayarlayın.

<label for="example-ngModel">[(ngModel)]:</label>
    <input [(ngModel)]="currentItem.name" id="example-ngModel">

Bu [(ngModel)] sözdizimi yalnızca veriye bağlı bir özelliği ayarlayabilir.

Yapılandırmanızı özelleştirmek için, özellik ve olay bağlamayı ayıran genişletilmiş formu yazın. Özelliği ayarlamak için property binding ve değişikliklere yanıt vermek için event binding  kullanın. Aşağıdaki örnek <input>  değerini büyük harf olarak değiştirir:

<input [ngModel]="currentItem.name" (ngModelChange)="setUppercaseName($event)" id="example-uppercase">

İşte büyük harf versiyonu da dahil olmak üzere tüm varyasyonlar:

NgModel ve değer erişimcileri #

NgModel direktifi bir ControlValueAccessor tarafından desteklenen bir eleman için çalışır. Angular, tüm temel HTML form elemanları için değer erişimcileri sağlar. Daha fazla bilgi için Forms bölümüne bakınız.

Form olmayan yerleşik bir öğeye veya üçüncü taraf bir özel bileşene [(ngModel)] uygulamak için bir değer erişimcisi yazmanız gerekir. Daha fazla bilgi için  DefaultValueAccessor hakkındaki API belgelerine bakın.

YARARLI: Bir Angular bileşeni yazarken, değer ve olay özelliklerini Angular’ın two-way binding syntax göre adlandırırsanız, bir değer erişimcisine veya NgModel‘e ihtiyacınız olmaz.

Yerleşik yapısal direktifler #

Yapısal direktifler HTML düzeninden sorumludur. Genellikle bağlı oldukları ana öğeleri ekleyerek, kaldırarak ve manipüle ederek DOM’un yapısını şekillendirir veya yeniden şekillendirirler.

Bu bölümde en yaygın yerleşik yapısal yönergeler tanıtılmaktadır:

NgIf ile bir öğe ekleme veya kaldırma #

Bir ana öğeye NgIf yönergesi uygulayarak bir öğe ekleyin veya kaldırın.

NgIf false olduğunda, Angular bir öğeyi ve onun soyundan gelenleri DOM’dan kaldırır. Angular daha sonra bunların bileşenlerini atarak bellek ve kaynakları serbest bırakır.

Bileşende NgIf’i içe aktarma #

NgIf‘i kullanmak için bileşenin imports listesine ekleyin.

import {NgIf} from '@angular/common';
...
@Component({
  standalone: true,
...
    NgIf, // <-- import into the component
...
  ],
})
export class AppComponent implements OnInit {
...
}

NgIf Kullanımı #

Bir öğe eklemek veya kaldırmak için, *ngIf öğesini aşağıdaki örnekte isActive gibi bir koşul ifadesine bağlayın.

<app-item-detail *ngIf="isActive" [item]="item"></app-item-detail>

isActive ifadesi doğru bir değer döndürdüğünde, NgIf, ItemDetailComponent öğesini DOM’a ekler. İfade hatalı olduğunda, NgIf ItemDetailComponent öğesini DOM’dan kaldırır ve bileşen ile tüm alt bileşenlerini atar.

NgIf ve NgIfElse hakkında daha fazla bilgi için  NgIf API documentation bakın.

Boş değerlere karşı koruma #

Varsayılan olarak NgIf, null değere bağlı bir öğenin görüntülenmesini engeller.

Bir <div>‘i korumak için NgIf kullanmak üzere, <div>’e *ngIf=”yourProperty” ekleyin. Aşağıdaki örnekte, currentCustomer adı görünür çünkü bir currentCustomer vardır.

<div *ngIf="currentCustomer">Hello, {{ currentCustomer.name }}</div>

Ancak, özellik null ise, Angular <div> öğesini görüntülemez. Bu örnekte, Angular nullCustomer özelliğini null olduğu için görüntülemez.

<div *ngIf="nullCustomer">Hello, <span>{{ nullCustomer }}</span></div>

NgFor ile öğeleri listeleme #

Bir öğe listesi sunmak için NgFor yönergesini kullanın.

Bileşende NgFor’u içe aktarma #

NgFor‘u kullanmak için bileşenin imports listesine ekleyin.

import {NgFor} from '@angular/common';
...
@Component({
  standalone: true,
...
    NgFor, // <-- import into the component
...
  ],
})
export class AppComponent implements OnInit {
...
}

NgFor Kullanımı #

NgFor’u kullanmak için yapmanız gerekenler:

1. Angular’ın tek bir öğeyi nasıl işleyeceğini belirleyen bir HTML bloğu tanımlayın.
2. Öğelerinizi listelemek için *ngFor öğesine let item of items kısaltmasını atayın.

<div *ngFor="let item of items">{{ item.name }}</div>

“let item of items” dizesi Angular’a aşağıdakileri yapmasını söyler:

• Items dizisindeki her item yerel öğe döngü değişkeninde saklayın
• Her öğeyi her yineleme için şablon HTML’de kullanılabilir hale getirin
• “let item of items” ifadesini ana öğenin etrafında bir <ng-template>‘e çevirin
• <ng-template>’i listedeki her item için tekrarlayın

Bileşen görünümünü tekrarlama #

Bir bileşen öğesini tekrarlamak için seçiciye *ngFor uygulayın. Aşağıdaki örnekte, seçici <app-item-detail> şeklindedir.

<app-item-detail *ngFor="let item of items" [item]="item"></app-item-detail>

Aşağıdaki konumlarda item gibi bir şablon girdi değişkenine referans verin:

• ngFor ana bilgisayar öğesi içinde
• Öğenin özelliklerine erişmek için ana öğe soyundan gelenler içinde

Aşağıdaki örnek, bir enterpolasyonda önce item öğesine başvurur ve ardından <app-item-detail> bileşeninin item özelliğine bir bağlama geçirir.

<div *ngFor="let item of items">{{ item.name }}</div>
...
  <app-item-detail *ngFor="let item of items" [item]="item"></app-item-detail>

Şablon girdi değişkenleri hakkında daha fazla bilgi için  Structural directive shorthand bakınız.

ngFor’un dizinini alma #

Şablon girdi değişkenindeki *ngFor‘un indeksini alın ve şablonda kullanın.

*ngFor içinde, bir noktalı virgül ekleyin ve let i=index‘i kısaltmaya izin verin. Aşağıdaki örnek, index‘i i adında bir değişkende alır ve öğe adıyla birlikte görüntüler.

<div *ngFor="let item of items; let i=index">{{ i + 1 }} - {{ item.name }}</div>

NgFor yönerge bağlamının index özelliği, her yinelemede öğenin sıfır tabanlı indeksini döndürür.

Angular bu talimatı ana öğenin etrafında bir <ng-template>‘e çevirir, ardından listedeki her öğe için yeni bir öğe ve bağlama kümesi oluşturmak için bu şablonu tekrar tekrar kullanır. Shorthand hakkında daha fazla bilgi için  Structural Directives kılavuzuna bakın.

Bir koşul doğru olduğunda öğeleri tekrarlama #

Belirli bir koşul doğru olduğunda bir HTML bloğunu tekrarlamak için, *ngIf öğesini bir *ngFor öğesini saran bir kapsayıcı öğeye yerleştirin.

Öğeleri *ngFor ile izleme #

Bir öğe listesindeki değişiklikleri izleyerek uygulamanızın sunucuya yaptığı çağrı sayısını azaltın. Angular, *ngFor trackBy özelliği ile tüm öğe listesini yeniden yüklemek yerine yalnızca değişen öğeleri değiştirebilir ve yeniden işleyebilir.

• Bileşene NgFor‘un izlemesi gereken değeri döndüren bir yöntem ekleyin. Bu örnekte, izlenecek değer öğenin id‘sidir. Tarayıcı zaten id‘yi oluşturmuşsa, Angular bunu takip eder ve aynı id için sunucuyu yeniden sorgulamaz.

trackByItems(index: number, item: Item): number {
    return item.id;
  }

• Kısaltılmış ifadede trackBy öğesini trackByItems() yöntemine ayarlayın.

<div *ngFor="let item of items; trackBy: trackByItems">
    ({{ item.id }}) {{ item.name }}
  </div>

Change ids yeni item.ids ile yeni öğeler oluşturur. TrackBy efektinin aşağıdaki gösteriminde, Öğeleri sıfırla aynı item.id‘lere sahip yeni öğeler oluşturur.

• TrackBy olmadığında, her iki düğme de DOM öğesinin tamamen değiştirilmesini tetikler.
• trackBy ile, yalnızca id‘nin değiştirilmesi öğe değişimini tetikler.

DOM öğesi olmayan bir yönerge barındırma #

Angular <ng-container> , Angular onu DOM’a koymadığı için stillere veya düzene müdahale etmeyen bir gruplama öğesidir.

Yönergeyi barındıracak tek bir eleman olmadığında <ng-container> kullanın.

İşte <ng-container> kullanan koşullu bir paragraf.

<p>
  I turned the corner
  @if (hero) {
    and saw {{ hero.name }}. I waved
  }
  and continued on my way.
</p>

1. ngModel yönergesini FormsModule‘den içe aktarın.
2. İlgili Angular modülünün imports bölümüne FormsModule ekleyin.
3. Bir <option>ı koşullu olarak hariç tutmak için, <option>ı bir <ng-container> içine sarın.

<div>
  Pick your favorite hero
  (<label for="showSad"><input id="showSad" type="checkbox" checked (change)="showSad = !showSad">show sad</label>)
</div>
<select [(ngModel)]="hero">
  @for (h of heroes; track h) {
    @if (showSad || h.emotion !== 'sad') {
      <option [ngValue]="h">{{ h.name }} ({{ h.emotion }})</option>
    }
  }
</select>

NgSwitch ile dosyaları değiştirme #

JavaScript switch deyimi gibi, NgSwitch de bir switch koşuluna bağlı olarak birkaç olası öğe arasından bir öğeyi görüntüler. Angular, DOM’a yalnızca seçilen öğeyi yerleştirir.

NgSwitch üç yönergeden oluşan bir kümedir:

Yönergeleri kullanmak için bileşenin imports listesine NgSwitch, NgSwitchCase ve NgSwitchDefault ekleyin.

import {NgSwitch, NgSwitchCase, NgSwitchDefault} from '@angular/common';
...
@Component({
  standalone: true,
...
    NgSwitch, // <-- import into the component
    NgSwitchCase,
    NgSwitchDefault,
...
  ],
})
export class AppComponent implements OnInit {
...
}

NgSwitch’i Kullanma #

• <div> gibi bir öğede, feature gibi switch değerini döndüren bir ifadeye bağlı [ngSwitch] ekleyin. Bu örnekteki feature değeri bir dize olsa da, switch değeri herhangi bir türde olabilir.
• Durumlar için öğeler üzerinde *ngSwitchCase ve *ngSwitchDefault öğelerine bağlayın.

<div [ngSwitch]="currentItem.feature">
  <app-stout-item    *ngSwitchCase="'stout'"    [item]="currentItem"></app-stout-item>
  <app-device-item   *ngSwitchCase="'slim'"     [item]="currentItem"></app-device-item>
  <app-lost-item     *ngSwitchCase="'vintage'"  [item]="currentItem"></app-lost-item>
  <app-best-item     *ngSwitchCase="'bright'"   [item]="currentItem"></app-best-item>
...
  <app-unknown-item  *ngSwitchDefault           [item]="currentItem"></app-unknown-item>
</div>

• Ana bileşende, [ngSwitch] ifadesinde kullanmak için currentItem öğesini tanımlayın.

currentItem!: Item;

• Her bir alt bileşene, üst bileşenin currentItem öğesine bağlı bir item input property ekleyin. Aşağıdaki iki kod parçacığı ana bileşeni ve alt bileşenlerden birini göstermektedir. Diğer alt bileşenler StoutItemComponent ile aynıdır.

export class StoutItemComponent {
  @Input() item!: Item;
}

Switch yönergeleri yerleşik HTML öğeleri ve web bileşenleriyle de çalışır. Örneğin,<app-best-item> anahtar durumunu aşağıdaki gibi bir <div> ile değiştirebilirsiniz.

<div *ngSwitchCase="'bright'">Are you as bright as {{ currentItem.name }}?</div>