Posta kodundan adres

Adres, select'lerden seçilmek yerine posta kodundan da doldurulabilir. Posta kodu input'u ekleyin; kod yazılınca select'ler kendiliğinden dolar. Mahalle seçilince de aynı input türetilen kodu gösterir, iki yön birlikte çalışır.

Posta kodu input'u

{
  "provinceCode": null,
  "province": null,
  "district": null,
  "neighbourhood": null,
  "postalCode": null,
  "postalCodes": []
}

"use client"
 
import { useViraAddress } from "@virastack/address"
 
export function AddressFields() {
  const {
    getProvinceProps,
    getDistrictProps,
    getNeighbourhoodProps,
    getPostalCodeInputProps,
    postalCodeStatus,
  } = useViraAddress()
 
  return (
    <>
      <input {...getPostalCodeInputProps()} />
      {postalCodeStatus === "unknown" && <p>Bu posta kodu bulunamadı.</p>}
 
      <select {...getProvinceProps()} />
      <select {...getDistrictProps()} />
      <select {...getNeighbourhoodProps()} />
    </>
  )
}

getPostalCodeInputProps() düz bir <input>'a yayılır: inputMode="numeric", autoComplete="postal-code", maxLength 5, value ve onChange. Rakam olmayan her şey atılır; arama beş rakam girilince yapılır. Daha az rakamla düzenlerken adres yerinde kalır.

names.postalCode verdiyseniz input o adı taşır. Aynı formda gizli getPostalCodeProps() input'unu ayrıca kullanmayın; ikisi aynı alanı gönderir.

Ne kadar kesin?

Her posta kodu tek bir ilçeye aittir ve ilk iki hanesi ilin plaka kodudur. Ama bir kod çoğu zaman birden çok mahalleyi kapsar: 2.777 kodun yalnızca 205'inin altında tek mahalle vardır, Sakarya'da 54100 ise 81 mahallenin ortak kodudur. Bu yüzden arama kodun kesin söyleyebildiği kadarını doldurur ve postalCodeStatus neyin bulunduğunu söyler:

Veri derlenirken her kodun tek ilçede kaldığı ve plaka koduyla başladığı kontrol edilir; bir güncelleme bunu bozarsa yayınlanmaz.

Davranış

• İl veya ilçe elle seçilince arama bırakılır: mahalle listesi yeniden tamamlanır, input seçimden türetilen kodu gösterir.
• Daraltılmış listeden mahalle seçmek aramayı korur. Birden çok kodu olan bir mahallede value.postalCode kullanıcının yazdığı koddur, ilki değil.
• Kod yüklenirken başka bir seçim yapılırsa ya da yeni bir kod yazılırsa eski yanıt yenisinin üstüne yazılmaz.
• İl seçim için zaten yüklendiyse tekrar indirilmez; arama aynı veriyi kullanır.
• form verildiyse dolan her seviye forma shouldDirty ile yazılır; "partial" durumda mahalle boş, posta kodu dolu olur. form.reset() aramayı da bırakır.

setPostalCode()

Input kullanmadan, örneğin kayıtlı bir adresten ya da konumdan gelen kodla aramayı kendiniz başlatın. Promise, bulunan durumla çözülür:

const { setPostalCode, value } = useViraAddress()
 
await setPostalCode("34710") // "exact"
value
// { province: "İSTANBUL", district: "KADIKÖY",
//   neighbourhood: "CAFERAĞA MAH.", postalCode: "34710", ... }
 
await setPostalCode("34096") // "partial"
value
// { province: "İSTANBUL", district: "FATİH",
//   neighbourhood: null, postalCode: "34096", ... }
 
await setPostalCode("34999") // "unknown": adres değişmez
await setPostalCode(null)    // null: arama bırakılır, adres kalır

Kodu metin olarak verin: 01040 sayı olarak 1040 olur ve baştaki sıfır geri getirilemez. Boşluklar atılır, "34 710" çalışır.

UI kütüphaneleri

Prop'lar standart input prop'larıdır; onChange hem olayı hem düz değeri alır. shadcn/ui ve Ant Design'ın Input'u olduğu gibi kabul eder:

import { Input } from "@/components/ui/input"
 
<Input
  {...address.getPostalCodeInputProps({ placeholder: "34710" })}
  aria-describedby="postal-code-hint"
/>

Sunucuda

Aynı arama sunucuda resolvePostalCode ile yapılır; gönderilen posta kodu da resolveAddress ile mahalleye karşı kontrol edilir. Bkz. sunucu doğrulaması. React olmadan ham sonuç için veri setindeki findPostalCode kullanılır.