Number Input elementi, kullanıcıların uygulama içerisinde sayısal değerler girmesini sağlayan temel bir input elementidir. Tam sayılar, ondalık değerler ve negatif sayılar gibi farklı veri türlerini destekleyerek geniş kullanım senaryolarına hitap eder. Sayısal girişleri kontrol altına alan yapısı sayesinde veri doğruluğunu artırır ve hatalı girişlerin önüne geçilmesine yardımcı olur.
Number Input elementi hem web hem de mobil uygulamalarda desteklenmektedir.
1.1. Sık Kullanım Senaryoları
Adet, miktar veya sayı girişi gereken alanlar
Yaş, puan, skor veya değerlendirme alanları
Yüzde, oran veya katsayı girişleri
Minimum–maksimum değer aralığı olan form alanları
Negatif değer içerebilen sayısal girişler (ör. fark, değişim oranı)
Filtreleme ve raporlama amaçlı sayısal aralık girişleri
2. Temel Özellikler
Tam sayı ve ondalık sayı desteği: Kullanım senaryosuna bağlı olarak yalnızca tam sayı veya ondalık sayı girişine izin verilebilir.
Negatif değer girişi desteği: İhtiyaca göre negatif sayı girişleri aktif veya pasif hale getirilebilir.
Minimum ve maksimum değer sınırlandırması: Girilebilecek sayısal değerler belirli bir aralıkla sınırlandırılabilir. Bu sayede geçersiz veya mantıksız girişler engellenir.
Sayısal veri doğrulama: Harf, özel karakter ve geçersiz girişlerin yapılmasını otomatik olarak engeller.
Form ve aksiyonlarla uyumlu yapı: Number Input; form submit, state güncelleme, hesaplama ve validasyon senaryolarında sorunsuz şekilde çalışır.
2.1. Number Input Elementi Özellikleri
Properties panelinden aşağıdaki ayarları yapılandırabilirsiniz:
Value: Sayısal giriş alanında varsayılan olarak gösterilecek sayıdır. Statik veya dinamik bir değer olabilir.
Decimal Separator: Ondalık kısmı ayırmak için kullanılan karakterdir (örn. nokta "." veya virgül ",").
Decimal Scale: Sayının ondalık kısmında gösterilecek basamak sayısını belirler (örn. 2 ayarlandığında, 0.00 formatı kullanılır).
Placeholder: Alan boşken görüntülenen yer tutucu metindir.
Fixed Decimal Scale: Sayının ondalık kısmının her zaman belirli bir basamakta gösterilmesini sağlar.
Allow Negative: Kullanıcıların negatif sayılar girmesine izin verir.
Allow Empty Formatting: Kullanıcıların alanı boş bırakmasına izin verir.
Format: Sayının görüntüleneceği formatı belirler (örn. para birimi veya yüzde).
Mask: Belirli bir formatta veri girişi sağlamak için kullanılır (örn. "XXX-XXX-XXXX" telefon numarası formatı).
Thousand Separator: Binlik basamakların ayrılması için kullanılan karakterdir (örn. 1,000 veya 1.000).
Max: Kullanıcının girebileceği en yüksek sayıdır.
Min: Kullanıcının girebileceği en düşük sayıdır.
Bu kılavuzu takip ederek Number Input elementini uygulamanızda etkili bir şekilde kullanabilirsiniz.
2.2. Elemente Eklenebilen Aksiyonlar
Number Input elementi, kullanıcı etkileşimlerine bağlı olarak olay (event) bazlı aksiyonlar tanımlanmasına olanak tanır. Aksiyonlar, elementin kendisine değil; belirli kullanıcı davranışları gerçekleştiğinde tetiklenen event’lere bağlanır.
Number Input elementi için aksiyonlar, Properties > Add Action alanı üzerinden aşağıdaki event’ler aracılığıyla eklenebilir.
Desteklenen Aksiyon Tetikleyicileri
onChange: Kullanıcı Number Input alanındaki değeri her değiştirdiğinde tetiklenir.
Kullanım amaçları:
Girilen değere bağlı anlık hesaplamalar yapmak
State veya değişken güncellemek
Diğer alanların değerlerini dinamik olarak değiştirmek
Canlı validasyon veya uyarı mesajları göstermek
Örnek senaryo: Kullanıcı adet bilgisini değiştirdiğinde toplam tutar otomatik olarak yeniden hesaplanır.
onPressEnter: Kullanıcı Number Input alanındayken Enter tuşuna bastığında tetiklenir.
Kullanım amaçları:
Form submit işlemi başlatmak
Bir sonraki adıma geçmek
Navigasyon aksiyonu çalıştırmak
Kaydetme veya onay işlemlerini tetiklemek
Örnek senaryo: Kullanıcı yaş bilgisini girip Enter’a bastığında form gönderilir.
onBlur: Kullanıcı Number Input alanından odak çıktığında (input alanını terk ettiğinde) tetiklenir.
Kullanım amaçları:
Giriş tamamlandıktan sonra validasyon çalıştırmak
Minimum–maksimum değer kontrolleri yapmak
Alan dışına çıkıldığında hesaplama veya state güncellemek
Örnek senaryo: Kullanıcı alanı terk ettiğinde girilen değerin izin verilen aralıkta olup olmadığı kontrol edilir.
Aksiyonlara İlişkin Temel Esaslar
Number Input elementi event bazlı çalışır; aksiyonlar yalnızca tanımlandıkları event gerçekleştiğinde tetiklenir.
Aynı event için birden fazla aksiyon tanımlanabilir.
Navigation, State Update, API Call, Workflow tetikleme gibi birçok aksiyon tipi desteklenir.
Performans gerektiren senaryolarda onChange yerine onBlur veya onPressEnter kullanılması önerilir.
Number Input elementi, özellikle hesaplama, validasyon ve form tabanlı senaryolarda aksiyonlarla birlikte kullanıldığında güçlü ve esnek bir yapı sunar.
3. Number Input Elementi Nasıl Kullanılır?
Bu bölümde Number Input elementinin uçtan uca kullanımını, bir ürün ekleme ekranı üzerinden ele alacağız.
Senaryo: Ürün Sipariş Girişi
Bir sipariş veya stok yönetimi uygulamasında, kullanıcıların bir üründen kaç adet sipariş vereceğini doğru ve kontrollü şekilde girmesi gerekir. Serbest metin alanları kullanıldığında harf, özel karakter veya geçersiz değer girişleri veri hatalarına yol açabilir.
Bu senaryoda, sipariş miktarı girişi Number Input elementi ile yapılır. Böylece kullanıcı yalnızca sayısal değer girebilir ve sistem dışı girişler otomatik olarak engellenir.
Senaryoda:
Sipariş miktarı kullanıcıdan Number Input ile alınır.
Harf ve özel karakter girişleri engellenir.
Ondalık ve negatif değer girişine izin verilmez.
Minimum ve maksimum değer sınırları tanımlanarak kontrol sağlanır.
Adım 1 - Veri Kaynağı Oluşturma
DataSources modülünde tablo oluşturma:
Datasources modülüne gidin.
Ardından Tables sekmesine gidin.
“UserContacts” adında yeni tablo oluşturun.
Kurulması gereken tablo yapısı aşağıdaki gibidir:
Önemli Alan adları:
ProductName: Siparişe eklenen ürünün ad bilgisini tutar ve kullanıcıya görüntülenen ürünü ifade eder.
Quantity: Number Input elementi üzerinden girilen sipariş adet bilgisini tutar ve yalnızca tam sayı değerler kabul edilir.
Adım 2 – Ana Sayfa Element Ekleme
UI Design modülünü açın.
Sayfaya Elements > Display > Label elementini sürükleyip bırakın.
Sayfaya Elements > Numeric Input > NumberInput elementini sürükleyip bırakın.
Başlangıçta hazır tanımlı miktarı NumberInput > Properties > Value > 1 olarak güncelleyin.
Ön yazı miktarını NumberInput > Properties > Placeholder > “1” olarak güncelleyin.
Ölçeği NumberInput > Properties > DecimalScale > 0 olarak ayarlayın.
Negatif sayı girişini engellemek için NumberInput > Properties > AllowNegative > Kapalı olarak ayarlayın.
Net miktarda ayrım olmaması için NumberInput > Properties > ThousendSeperator > Kapalı olarak ayarlayın.
Maksimum miktarı NumberInput > Properties > Max > 50 olarak ayarlayın. Böylelikle 50’den büyük değer girildiğinde otomatik maksimum değer eklenir.
Sayfaya fiyat kaydetmek için Elements > Navigation > Button elementini sürükleyip bırakın.
Buton yazısını Button > Properties > Label > Fixed Value > “Ürün Ekle” olarak ayarlayın.
Button elementine aksiyon ekleyin. Add Action > onClick > Managed DB > Save Record aksiyonunu ekleyin.
Aksiyonda tablo seçimini OrderItems olarak ayarlayın ve açılan sütünlar alanında tüm sütunları seçin.
CreatedDate alanına Default > Now tanımlaması yapın.
ProductName alanını Components > TextInput > value olarak tanımlayın.
Quantity alanına Components > NumberInput > value tanımlaması yapın.
Id alanına Default > New Guid tanımlamasını yapın.
Preview
Uygulama test edildiğinde, kullanıcıya ürün ekleme işlemleri için Ürün Adı ve Ürün Adedi alanlarının yer aldığı sade bir form ekranı sunulur. Ürün Adedi alanı, Numeric Input elementi ile yapılandırılmıştır.
Form ilk açıldığında Ürün Adedi alanı varsayılan olarak 1 değeri ile gelir. Kullanıcı, bu alan üzerinden yalnızca sayısal değer girişi yapabilir. Negatif sayılara ve ondalık değerlere izin verilmez. Ayrıca, ürün adedi için maksimum 50 olacak şekilde giriş limiti tanımlanmıştır.
Kullanıcı ürün adını ve adet bilgisini girdikten sonra Ürün Ekle butonuna tıkladığında, girilen bilgiler sistem tarafından işlenir ve ürün sipariş listesine eklenir. Aynı ürün farklı adet değerleriyle tekrar eklenebilir ve her ekleme işleminde Numeric Input kuralları geçerli olmaya devam eder.
4. Ortak Özellikler (Properties)
Number Input elementi üzerinde yer alan bazı alanlar tüm UI elementlerinde ortak olarak kullanılır. Bu nedenle, aşağıdaki özelliklerin detaylı açıklamaları ilgili genel kılavuz sayfalarında yer almaktadır:
Minimum ve maksimum değer sınırları tanımlayın. Mantıksız veya geçersiz değer girişlerini engellemek için min–max validasyonları ekleyin.
onChange Event’ini performans açısından dikkatli kullanın. Her tuş vuruşunda tetiklenen aksiyonlar yoğun işlemler için uygun olmayabilir. Bu tür senaryolarda onBlur veya onPressEnter tercih edilmelidir.
Placeholder ve etiketleri açıklayıcı kullanın. Kullanıcının hangi tür sayısal değeri girmesi gerektiği açıkça anlaşılmalıdır.
6. Kısıtlamalar
Number Input elementi yalnızca sayısal değer girişi için tasarlanmıştır; metinsel veya karmaşık formatlı girişleri desteklemez.
Para birimi sembolü veya parasal formatlama (₺, $, €, binlik ayırıcı vb.) Number Input tarafından sağlanmaz. Bu tür senaryolar için Currency elementi kullanılmalıdır.
Aksiyonlar yalnızca onChange, onPressEnter ve onBlur Event’leri üzerinden tetiklenebilir.
