React’te her ülkede çalışan bir adres formu nasıl kurulur

Önce ülke, sonra düzen

Hangi alanların var olduğuna, nasıl adlandırıldıklarına, hangilerinin zorunlu olduğuna ve hangi sırayla geldiklerine ülke karar verir. Bu yüzden önce ülkeyi sorun, müşterinin yerel ayarından ya da IP’sinden önceden seçilmiş olarak, ve geri kalanı veriden kurun.

Ne kadar şeyin değiştiğine dair birkaç örnek:

Her ülkeyi elle araştırmanız gerekmez. Google, libaddressinput kütüphanesinin arkasındaki adres meta verilerini yayınlıyor; dünyanın çoğu için alan sırası, etiketler, zorunlu alanlar ve posta kodu desenleriyle birlikte. En çok gönderim yaptığınız ülkeleri seçip onlara kesin bir biçim verin, diğer her ülkeye de sade bir yedek verin: iki adres satırı, şehir, bölge ve posta kodu; hiçbiri katı biçimde doğrulanmadan.

type Field = "address1" | "address2" | "city" | "region" | "postalCode"

type CountryFormat = {
  rows: Field[][]
  labels: Partial<Record<Field, string>>
  required: Field[]
  postalCode?: { pattern: RegExp; example: string }
  regions?: { code: string; name: string }[]
}

const countryFormats: Record<string, CountryFormat> = {
  US: {
    rows: [["address1"], ["address2"], ["city", "region", "postalCode"]],
    labels: { region: "State", postalCode: "ZIP code" },
    required: ["address1", "city", "region", "postalCode"],
    postalCode: { pattern: /^\d{5}(-\d{4})?$/, example: "94110" },
  },
  GB: {
    rows: [["address1"], ["address2"], ["city"], ["postalCode"]],
    labels: { city: "Town or city", postalCode: "Postcode" },
    required: ["address1", "city", "postalCode"],
    postalCode: {
      pattern: /^[A-Z]{1,2}\d[A-Z\d]? ?\d[A-Z]{2}$/i,
      example: "SW1A 1AA",
    },
  },
}

Form bileşeni ardından format.rows’u render eder ve hiçbir ülkenin adını anmaz.

Daha az alan

Gösterdiğiniz her alan, doldurulacak bir şey daha ve yanlış yapılacak bir şey daha demektir.

• Tek bir ad alanı. Ad ve soyad değil, "Ad soyad". Pek çok isim iki parçaya ayrılmaz ve sıralama ülkeden ülkeye değişir.
• 2. satır bir bağlantının arkasında. "Daire, kat vb. ekle" onu açar. Çoğu insanın buna ihtiyacı yoktur. Otomatik doldurma ya da adres arama onu doldurursa gösterin.
• Şirket de bir bağlantının arkasında, az sayıdaki B2B siparişi için.
• Telefon isteğe bağlı, nedeniyle birlikte. Alanın altındaki "Yalnızca teslimatla ilgili sorular için" ifadesi, zorunlu bir alanın gerçek numaralar topladığından daha fazla numara toplar.

İşin çoğunu otomatik doldurma yapar

Tarayıcının otomatik doldurması formun tamamını tek dokunuşta doldurabilir, ama yalnızca her input’un bir name’i ve doğru autocomplete token’ı varsa. Tarayıcı hangi kayıtlı adresin nereye gideceğini bilsin diye token’ların başına shipping ya da billing ekleyin:

<Input name="name" autoComplete="shipping name" />
<Input name="address1" autoComplete="shipping address-line1" />
<Input name="address2" autoComplete="shipping address-line2" />
<Input name="city" autoComplete="shipping address-level2" />
<Input name="region" autoComplete="shipping address-level1" />
<Input
  name="postalCode"
  autoComplete="shipping postal-code"
  inputMode={country === "US" ? "numeric" : "text"}
/>
<Input name="phone" type="tel" autoComplete="shipping tel" />

address-level1 eyalet, il ya da prefektörlüktür; address-level2 ise şehirdir. Fatura adresi gönderim adresinden farklı olduğunda billing token’larıyla ikinci bir form render edin; böylece tarayıcı fatura formunu gönderim adresiyle doldurmaz.

Posta kodları için type="number" kullanmayın. ZIP kodları sıfırla başlar, Birleşik Krallık ve Kanada kodlarında harf vardır ve sayı input’ları spinner’lar ve kaydırma tekerleğiyle değişimlerle gelir. inputMode="numeric" ile bir metin input’unu yalnızca kodların tamamen rakam olduğu yerlerde kullanın.

Posta kodu sorgulama

Bazı ülkelerde posta kodu size şehri ve bölgeyi zaten söyler. Japonya klasik örnektir: adresler posta koduyla başlar ve kod tek başına prefektörlüğü ve şehri belirler. Müşteri posta kodunu bitirdiğinde onu sorgulayın ve şehir ile bölgeyi doldurun, ama zaten yazdıkları bir şeyin üzerine asla yazmayın. Onların girdisi sizin verinize üstün gelir.

Adres arama

Adres arama, yani bir adresin başını yazıp bir öneri seçmek, mobilde her formdan daha hızlıdır. Google Places ve Mapbox bunu iki çağrı olarak sunar: biri yazılan şey için adres önerir, diğeri seçilen öneriyi yapılandırılmış alanlara dönüştürür.

Bağlarken birkaç kural:

• Her arama kutusunda olduğu gibi yazmada bir duraklama bekleyin ve önceki isteği iptal edin.
• Listeyi her zaman "Adresi elle gir" ile bitirin. Sokak yeni olabilir ya da öneri yanlış olabilir.
• Bir seçimden sonra alanları doldurun ve gösterin; böylece müşteri sonucu kontrol edip bir daire numarası ekleyebilir.
• Google’ın Places API’si, bir aramanın öneri ve ayrıntı çağrılarını gruplamak için oturum token’ları kullanır. Bunları kullanın, yoksa çağrılar ayrı ayrı faturalandırılabilir.

Neyin yanlış olduğunu söyleyen hatalar

Bir alanı müşteri ondan ayrıldığında doğrulayın, sonra düzeltilene kadar yazdıkça canlı olarak. Hatayı ülkeye göre yazın: ABD’de "5 haneli bir ZIP kodu girin", Birleşik Krallık’ta "SW1A 1AA gibi bir posta kodu girin". "Geçersiz posta kodu" kimseye yardımcı olmaz.

Gönderimde her sorunu formun üstündeki bir özette listeleyin, her birini kendi alanına bağlayın ve odağı özete taşıyın. Her hatayı aria-describedby ile input’una bağlayın ve aria-invalid ayarlayın; böylece ekran okuyucular mesajı alanla birlikte okur.

Doğrulamadan önce normalleştirin: boşlukları kırpın, Birleşik Krallık ve Kanada posta kodlarını büyük harfe çevirin ve boşluklu ya da boşluksuz kabul edin. Düzeltebilecekken "sw1a1aa"yı reddetmek müşterinin değil, sizin hatanızdır.

Ülke değiştirme

İnsanlar adresin yarısını yazdıktan sonra ülkeyi düşündüğünüzden daha sık değiştirir. Değiştirdiklerinde hâlâ uyanları (ad, sokak satırları, telefon) koruyun, yeni ülkenin farklı bir listesi varsa bölgeyi temizleyin ve yalnızca zaten dokundukları alanları yeniden kontrol edin. Henüz ulaşmadıkları alanlarda yeni hatalar göstermek, yapmadıkları bir şey için azarlanmak gibi hissettirir.

Metni değil, yapıyı saklayın

Adresi biçimlendirilmiş satırlar olarak değil, alanlar artı bir ISO ülke kodu olarak kaydedin. Vergi, kargo ücretleri ve kargo etiketleri için yapıya ihtiyacınız olacak ve gösterim için her zaman biçimlendirebilirsiniz. "12 Mission St, San Francisco, CA 94110" gibi tek satırlık bir özet, verinin bir görünümüdür, verinin kendisi değil.

Bir kontrol listesi

• Önce ülke, sonra ülkeye özgü bir biçimden alanlar, etiketler ve sıra.
• Ana ülkeleriniz için kesin bir biçim, geri kalanlar için hoşgörülü bir yedek.
• Tek bir ad alanı, bağlantıların arkasında 2. satır ve şirket, nedeniyle birlikte isteğe bağlı telefon.
• Her input’ta bir name ve bir shipping ya da billing autocomplete token’ı.
• Posta kodları için metin input’ları; sayısal klavyeler yalnızca kodların rakam olduğu yerlerde.
• Yazılan değerlerin üzerine asla yazmayan posta kodu sorgulama.
• Sonunda elle giriş seçeneği olan adres arama.
• Ülkeye özgü hata metinleri ve gönderimde bağlantılı bir özet.

Bunun için HextaUI bloğu

HextaUI Pro’daki Address Form bloğu bu kurallar üzerine kurulu. On altı ülkenin etiketleri, zorunlu alanları, bölge listeleri ve posta kuralları olan kendi biçimi var; diğer her ülke sade bir yedek alır. Her input’ta shipping ya da billing önekiyle doğru autocomplete token’ı var. onSearchAddress ve onResolveAddress adres aramayı bağlar; Google Places için bir örnek var ve aynı iki çağrı Mapbox’a da eşlenir. onLookupPostalCode, yazılan hiçbir şeyin üzerine yazmadan şehri ve bölgeyi doldurur, validate() ise her sorunu bağlantılı bir özette listeler. SavedAddresses ve AddressSummary, oturum açmış müşterileri ve tamamlanmış "Gönderim adresi" satırını kapsar.

Checkout bloğu bunu teslimat için kullanır. O sayfanın geri kalanını kuruyorsanız React ve Next.js’te tek sayfalık bir ödeme akışı hakkında da yazdım.

SSS

Ülke alanı önce mi gelmeli? Evet. Hangi alanların var olduğuna ve hangi sırayla geldiklerine o karar verir; bu yüzden geri kalanın anlam kazanması için önce seçilmesi gerekir.

Ad ve soyad alanları mı kullanmalıyım? Bir kargo firması ya da ödeme sağlayıcısı ayrımı şart koşmadıkça tek bir ad soyad alanı kullanın.

Posta kodu hangi input tipini kullanmalı? Bir metin input’u; inputMode="numeric" yalnızca kodları tamamen rakamdan oluşan ülkeler için.

Bir API’den adres doğrulamaya ihtiyacım var mı? Yardımcı olur ama siparişi buna bağlı olarak engellemeyin. Bir düzeltme önerin ve müşterinin yazdığını korumasına izin verin.