Katkıda Bulun
Detaylı Rehberler
Angular Aria

Autocomplete

Genel Bakış

Kullanıcılar yazarken seçenekleri filtreleyen ve öneren, bir listeden değer bulmalarına ve seçmelerine yardımcı olan erişilebilir bir giriş alanı.

Kullanım

Otomatik tamamlama, kullanıcıların yazmanın kaydırmadan daha hızlı olduğu büyük bir seçenek kümesinden seçim yapması gerektiğinde en iyi çalışır. Şu durumlarda otomatik tamamlama kullanmayı düşünün:

  • Seçenek listesi uzun (20'den fazla öğe) - Yazmak, bir açılır menüyü kaydırmaya göre seçimleri daha hızlı daraltır
  • Kullanıcılar ne aradıklarını biliyor - Beklenen değerin bir kısmını yazabilirler (il adı, ürün veya kullanıcı adı gibi)
  • Seçenekler tahmin edilebilir kalıpları takip ediyor - Kullanıcılar kısmi eşleşmeleri tahmin edebilir (ülke kodları, e-posta alanları veya kategoriler gibi)
  • Hız önemli - Formlar kapsamlı navigasyon olmadan hızlı seçimden faydalanır

Şu durumlarda otomatik tamamlamadan kaçının:

  • Listede 10'dan az seçenek var - Düzgün bir açılır menü veya radyo grubu daha iyi görünürlük sağlar
  • Kullanıcıların seçeneklere göz atması gerekiyor - Keşfetmek önemliyse, tüm seçenekleri önceden gösterin
  • Seçenekler bilinmiyor - Kullanıcılar listede var olduğunu bilmedikleri şeyleri yazamaz

Özellikler

Angular'ın otomatik tamamlaması, tam erişilebilir bir combobox uygulaması sağlar:

  • Klavye Navigasyonu - Ok tuşlarıyla seçenekler arasında gezinin, Enter ile seçin, Escape ile kapatın
  • Ekran Okuyucu Desteği - Yardımcı teknolojiler için yerleşik ARIA nitelikleri
  • Dinamik Vurgulama Davranışı - Satır içi seçim önerileri için yerleşik destek
  • Sinyal Tabanlı Reaktivite - Angular sinyalleri kullanan reaktif durum yönetimi
  • Popover API Entegrasyonu - Optimum konumlandırma için yerel HTML Popover API'sinden yararlanır
  • Çift Yönlü Metin Desteği - Sağdan sola (RTL) dilleri otomatik olarak işler

Örnekler

Otomatik seçim modu

Kısmi metin yazan kullanıcılar, girdilerinin mevcut bir seçenekle eşleştiğine dair anında onay bekler. Otomatik seçim modu, kullanıcılar yazarken giriş değerini ilk filtrelenmiş seçenekle eşleşecek şekilde günceller, gereken tuş vuruşu sayısını azaltır ve aramalarının doğru yolda olduğuna dair anında geri bildirim sağlar.

Manuel seçim modu

Manuel seçim modu, kullanıcılar öneri listesinde gezinirken yazılan metni değiştirmeden tutar ve otomatik güncellemelerden kaynaklanan karışıklığı önler. Giriş, yalnızca kullanıcılar seçimlerini Enter veya tıklamayla açıkça onayladıklarında değişir.

Vurgulama modu

Vurgulama modu, kullanıcının Enter veya tıklama ile açıkça yeni bir seçenek seçene kadar, ok tuşlarıyla seçenekler arasında gezinirken giriş değerini değiştirmeden gezinmesine olanak tanır.

Signal Forms Entegrasyonu

Angular Aria, sinyal tabanlı Signal Forms API'siyle sorunsuz şekilde entegre olur. Karmaşık girdileri, FormValueControl uygulayan yeniden kullanılabilir özel kontrol bileşenlerinde kapsülleyebilirsiniz.

Aşağıdaki örnek, FormValueControl<string> uygulayan, [formField] ile üst forma bağlanan ve şema doğrulama kurallarıyla korunan bir ülke seçici bileşenini gösterir.

Test Etme

Otomatik tamamlama deseni, @angular/aria/combobox/testing ve @angular/aria/listbox/testing paketlerinden ComboboxHarness ve ListboxHarness birleşimiyle test edilebilir. Bir otomatik tamamlama bileşenini test etmek için harness'lerin nasıl kullanılacağına dair bir örnek:

import {ComponentFixture, TestBed} from '@angular/core/testing';
import {HarnessLoader} from '@angular/cdk/testing';
import {TestbedHarnessEnvironment} from '@angular/cdk/testing/testbed';
import {ComboboxHarness} from '@angular/aria/combobox/testing';
import {ListboxHarness} from '@angular/aria/listbox/testing';
import {MyAutocompleteComponent} from './my-autocomplete'; // Bileşeniniz

describe('MyAutocompleteComponent', () => {
  let fixture: ComponentFixture<MyAutocompleteComponent>;
  let loader: HarnessLoader;

  beforeEach(async () => {
    TestBed.configureTestingModule({
      imports: [MyAutocompleteComponent],
    });

    fixture = TestBed.createComponent(MyAutocompleteComponent);
    await fixture.whenStable();
    loader = TestbedHarnessEnvironment.loader(fixture);
  });

  it('should filter options based on input', async () => {
    const combobox = await loader.getHarness(ComboboxHarness);

    // Filtrelemeyi tetiklemek için girişe yazın
    await combobox.setValue('ap');
    expect(await combobox.isOpen()).toBe(true);

    // Açılır pencereden listbox harness'ini alın
    const listbox = await combobox.getPopupWidget(ListboxHarness);
    const options = await listbox.getOptions();

    // Seçeneklerin filtrelendiğini doğrulayın (örn. 'Apple', 'Apricot')
    expect(options.length).toBe(2);
    expect(await options[0].getText()).toBe('Apple');

    // İlk seçeneği seçin
    await options[0].click();

    // Giriş değerinin güncellendiğini ve açılır pencerenin kapandığını doğrulayın
    expect(await combobox.isOpen()).toBe(false);
    expect(await combobox.getValue()).toBe('Apple');
  });
});

API referansı

Ayrıntılı API belgeleri için aşağıdaki API referanslarını inceleyin: