DateRangePicker

Kullanıcının takvimden bir başlangıç ve bir bitiş tarihi seçerek bir tarih aralığı belirlemesini sağlayan nesnedir. İzin tarihleri, proje başlangıç-bitişi, rezervasyon dönemi gibi iki uçlu tarih alanları için kullanılır.

Ne zaman kullanılır?

İki uçlu (başlangıç ve bitiş) tarih seçimi gereken her yerde idealdir: izin dönemi, sözleşme süresi, raporlama aralığı. Tek bir tarih veya saat içeren tek bir an için DateTimePicker daha uygundur.

Değer tipi: DateTimeOffset?

DateRangePicker iki uçlu bir nesnedir; ekranda tek bir tarih değil, bir başlangıç-bitiş aralığı tutar. İki ucu nasıl okuyup yazacağınızı bilmek bu nesnenin püf noktasıdır:

• Value özelliği Nullable<DateTimeOffset> (yani DateTimeOffset?) tipindedir ve aralığın etkin ucunun skaler değerini taşır. Boş (null) olabilir; kullanıcı henüz seçim yapmadıysa değer atanmamıştır.
• Aralığın iki ucu StartDate ve EndDate özellikleriyle yönetilir. Her biri bir DateRangePickerOptions nesnesidir; o ucun tarihi StartDate.Value / EndDate.Value (yine DateTimeOffset?) üzerinden okunup yazılır.
• Değişiklik olaylarında (OnValueChanging / OnValueChanged) taşınan değer tek bir tarih değil, List<Nullable<DateTimeOffset>> tipinde [başlangıç, bitiş] çiftidir.

DateRangePickerOptions

StartDate ve EndDate, opak bir "ayar" değil, ayrı birer DateRangePickerOptions nesnesidir. Her ucu kod ile bu nesne üzerinden yönetirsiniz.

Özellik	Tip	Açıklama
Value	DateTimeOffset?	Bu ucun tarihi. Varsayılan değer atamak veya okumak için kullanılır.
AllowEmpty	bool?	Bu ucun boş bırakılabilmesine izin verir.
SetTodayAsDefault	bool?	Bu uca varsayılan olarak bugünü atar.
Placeholder	Dictionary<string,string>	Uç boşken görünen, dile göre soluk ipucu yazısı.
DisabledHours / DisabledMinutes / DisabledSeconds	string	ShowTime açıkken seçilemeyecek saat / dakika / saniye değerleri.

Tasarımcı özellikleri

Bir DateRangePicker seçildiğinde Özellik Görüntüleyici sekmelere ayrılır.

General

Özellik	Açıklama
Name	Nesnenin koddaki adı (ör. DateRangePicker1). Koddan bu adla erişirsiniz.
Field Name	Veritabanındaki alanın adı.

Label

Nesnenin yanındaki etiketi yönetir.

Özellik	Açıklama
Caption / Text	Etiketin yazısı (çok dilli olabilir).
Position	Etiketin yeri: solda (Left) veya üstte (Top).
Width / Height	Etiketin boyutu.
Font	Yazı tipi, kalın / italik / altı çizili.
Show Colon	Etiketin sonuna iki nokta (:) ekler.
Horizontal Align / Vertical Align	Etiketin hizası.
Visible	Etiketi gösterir veya gizler.

Behavior

Özellik	Açıklama
StartDate	Başlangıç ucunun DateRangePickerOptions nesnesi (varsayılan değer, boş bırakılabilirlik).
EndDate	Bitiş ucunun DateRangePickerOptions nesnesi (varsayılan değer, boş bırakılabilirlik).
Mode	Takvimin seçim kipi (gün, ay, yıl gibi).
Format	Tarihin ekranda gösterileceği biçim (ör. dd.MM.yyyy).
ShowTime	Tarihle birlikte saat seçimini de açar.
ShowToday	Takvimde "Bugün" düğmesini gösterir.
ActiveDateType	Takvim açıldığında hangi ucun etkin geleceğini belirler.
DateLimitType	Seçilebilir tarih aralığına getirilen sınırın türü.
DisabledDateType	Hangi tür tarihlerin kapatılacağını belirler (ör. geçmiş / gelecek).
DisabledDateRange	Bugüne göre kaç günlük bir aralığın kapatılacağını belirler.
DisabledDates	Tek tek seçilemez yapılan tarihlerin listesi.
AllowClear	Seçimi temizleme (x) düğmesini gösterir.
ReadOnly	Alanı salt okunur yapar.
Required	Alanı zorunlu yapar; boşsa form kaydedilmez.
Indexable	Değerin aranabilir/indekslenebilir olup olmadığını belirler.
Tab Index	Tab tuşuyla geçiş sırasını belirler.

Appearance

Özellik	Açıklama
Visible / Client Visible	Nesnenin görünürlüğü.
Enabled / Client Enabled	Nesnenin aktif olup olmadığı.
Placeholder	Alan boşken görünen soluk ipucu yazısı (çok dilli).
Text Align	Yazının hizası.
Title	Fare ile üzerine gelince çıkan başlık (tooltip, çok dilli).
Custom Class Name	Nesneye eklenen özel CSS sınıfı.
Size Type	Genişlik davranışı (sabit / esnek).

Olaylar

Bir nesne açılırken olaylar belirli bir sırayla tetiklenir; kullanıcı tarih seçince de ayrı olaylar çalışır. Doğru kodu doğru olaya yazmak için bu sırayı bilmek işinizi kolaylaştırır.

Kullanıcı seçim yaparken: OnTextChanging → OnTextChanged, aralık kesinleşince OnValueChanging → OnValueChanged. Alan doğrulanırken OnValidating çalışır.

Olaylar iki tarafta çalışabilir: sunucu olayları C# kodunda, istemci olayları tarayıcıdaki TypeScript kodunda.

Sunucu olayları (Server)

Olay	Ne zaman çalışır
OnTextChanging	Görünen metin değişmeden hemen önce.
OnTextChanged	Görünen metin değiştikten hemen sonra.
OnValueChanging	Aralık değişmeden hemen önce (iptal edilebilir).
OnValueChanged	Kullanıcı aralığı seçip değer kesinleştiğinde. En sık kullanılan olaydır.
OnValidating	Alan doğrulanırken çalışır; geçersiz seçim burada engellenebilir.

İstemci olayları (Client)

Aynı olaylar tarayıcı tarafında da kullanılabilir: OnTextChanging / OnTextChanged, OnValueChanging / OnValueChanged.

Olay parametreleri

OnValueChanging / OnValueChanged olaylarının taşıdığı değer bir aralıktır, tek bir tarih değil:

• C# tarafında parametre PropertyChangingEventArgs<List<Nullable<DateTimeOffset>>> (Changing) / PropertyChangedEventArgs<List<Nullable<DateTimeOffset>>> (Changed) tipindedir.
• e.NewValue / e.OldValue iki elemanlı bir List<DateTimeOffset?>'tir: ilk eleman başlangıç, ikinci eleman bitiş.
• e.Cancel = true yapılırsa değişiklik iptal edilir (yalnızca Changing olaylarında).

OnTextChanging / OnTextChanged ise PropertyChangingEventArgs<String> / PropertyChangedEventArgs<String> taşır (görünen metin).

Kod örnekleri

Bir DateRangePicker'a üç yerden erişebilirsiniz. Sunucu örnekleri turuncu, istemci örnekleri kırmızı çerçevelidir.

Form kodu (C#, sunucu)

Form kodunda nesneye doğrudan adıyla erişirsiniz. Aralığın iki ucunu StartDate.Value ve EndDate.Value üzerinden okuyup yazarsınız; her ikisi de DateTimeOffset? olduğu için okumadan önce kontrol edin:

// Oku: başlangıç ve bitiş uçları
DateTimeOffset? baslangic = DateRangePicker1.StartDate.Value;
DateTimeOffset? bitis     = DateRangePicker1.EndDate.Value;

if (baslangic.HasValue && bitis.HasValue)
{
    int gunSayisi = (bitis.Value - baslangic.Value).Days;
}

// Yaz: her ucu kendi DateRangePickerOptions.Value'su üzerinden
DateRangePicker1.StartDate.Value = DateTimeOffset.Now;
DateRangePicker1.EndDate.Value   = DateTimeOffset.Now.AddDays(7);

// Bir ucu boş bırakılabilir veya varsayılan bugün yapılabilir
DateRangePicker1.EndDate.AllowEmpty        = true;
DateRangePicker1.StartDate.SetTodayAsDefault = true;

Akış (Flow) kodu (C#, sunucu)

Akış kodunda nesneye Document1.Controls üzerinden erişirsiniz. Aralığı yine iki uç üzerinden okuyup yazarsınız:

var picker = (Bimser.CSP.FormControls.Controls.DateRangePicker)
    Document1.Controls["DateRangePicker1"];

// Oku
DateTimeOffset? baslangic = picker.StartDate.Value;
DateTimeOffset? bitis     = picker.EndDate.Value;

// Yaz
picker.StartDate.Value = DateTimeOffset.Now;
picker.EndDate.Value   = DateTimeOffset.Now.AddDays(30);

İstemci kodu (TypeScript, tarayıcı)

İstemci tarafında nesnelere this. ile erişilir ve özellik adları küçük harfle yazılır:

this.DateRangePicker1.startDate.value = null;   // başlangıç ucunu temizle
this.DateRangePicker1.endDate.value   = null;   // bitiş ucunu temizle

Boş değere dikkat

DateRangePicker iki uçludur ve her ucun değeri DateTimeOffset? olduğu için kullanıcı seçim yapmadığında null olur. C# tarafında StartDate.Value / EndDate.Value'yu okumadan önce HasValue ile kontrol edin, yoksa hata alırsınız.

Örnek: aralığın iki ucunu olaydan okuma (OnValueChanged)

OnValueChanged aralık kesinleştikten sonra çalışır. Bu olayda taşınan değer iki elemanlı bir List<DateTimeOffset?>'tir: ilk eleman başlangıç, ikinci eleman bitiş. Aşağıdaki örnekte aralık çiftini olaydan okuyup gün sayısını hesaplarız.

Sunucu (C#):

void DateRangePicker1_OnValueChanged(object sender,
    PropertyChangedEventArgs<List<Nullable<DateTimeOffset>>> e)
{
    var aralik = e.NewValue;                       // [başlangıç, bitiş]
    if (aralik != null && aralik.Count == 2
        && aralik[0].HasValue && aralik[1].HasValue)
    {
        int gunSayisi = (aralik[1].Value - aralik[0].Value).Days;
        TextBox1.Value = gunSayisi.ToString();
    }
}

Örnek: geçmiş başlangıcı engelleme (OnValueChanging)

OnValueChanging aralık değişmeden hemen önce çalışır; istemediğiniz bir seçimi burada iptal edebilirsiniz. NewValue yine [başlangıç, bitiş] çiftidir; aşağıda başlangıcın bugünden önce olması engellenir.

İstemci (TypeScript):

async DateRangePicker1_OnValueChanging(
    args: Controls.EventArgs.IPropertyChangingEventArgs<Date[]>) {
    const baslangic = args.newValue && args.newValue[0];
    if (baslangic && baslangic < new Date()) {
        args.cancel = true;                                   // Aralık değişimini iptal eder
        this.showMessage("Uyarı", "Başlangıç geçmiş bir tarih olamaz.", "Validation");
    }
}

Sunucu (C#):

void DateRangePicker1_OnValueChanging(object sender,
    PropertyChangingEventArgs<List<Nullable<DateTimeOffset>>> e)
{
    var aralik = e.NewValue;                       // [başlangıç, bitiş]
    if (aralik != null && aralik.Count > 0
        && aralik[0].HasValue && aralik[0].Value < DateTimeOffset.Now)
    {
        e.Cancel = true;
        ShowMessage("Uyarı", "Başlangıç geçmiş bir tarih olamaz.",
            Bimser.CSP.FormControls.RuleManager.AlertType.Validation);
    }
}

İpuçları

• Aralığın iki ucunu tek bir .Value ile değil, StartDate.Value ve EndDate.Value üzerinden okuyup yazın. Tek .Value skaler özelliği yalnızca etkin ucu temsil eder.
• Bir uca varsayılan bugünü atamak veya o ucu boş bırakılabilir yapmak için StartDate / EndDate üzerindeki SetTodayAsDefault ve AllowEmpty ayarlarını kullanın.
• Seçilemeyecek tarihleri kod ile kontrol etmek yerine DisabledDates, DisabledDateType ve DisabledDateRange ayarlarını kullanın; tasarımda belirlemek daha temizdir.
• Nesnenin Required özelliğini kullanarak kod ile boş/dolu kontrolü yapmanıza gerek kalmaz.
• Saat de seçtirmeniz gerekiyorsa ShowTime özelliğini açın; saat sınırlamalarını her uçtaki DisabledHours / DisabledMinutes / DisabledSeconds ile yapabilirsiniz.
• Ekrandaki tarih biçimini Format ile (ör. dd.MM.yyyy) belirleyebilirsiniz.

Tüm üyeler (tam liste)

Özellikler (PROP): ActiveDateType, AllowClear, Caption, ClientEnabled, ClientVisible, ContainerStyle, ContextMenuColumnKey, ContextMenuKey, ContextMenuTarget, ControlId, CustomClassName, DateLimitType, DefaultClientEnabled, DefaultEnabled, DefaultReadOnly, DisabledDateRange, DisabledDates, DisabledDateType, Enabled, EndDate (DateRangePickerOptions), EntityPath, Format, Indexable, Loading, Mode, Name, Placeholder (MultiLanguageText), ReadOnly, Required, ShowTime, ShowToday, SizeType, StartDate (DateRangePickerOptions), Style, TabIndex, Text (salt okunur), TextAlign, Title (MultiLanguageText), Value (DateTimeOffset?), Visible

DateRangePickerOptions üyeleri: Value (DateTimeOffset?), AllowEmpty (bool?), SetTodayAsDefault (bool?), Placeholder (Dictionary<string,string>), DisabledHours, DisabledMinutes, DisabledSeconds

Olaylar (EVENT): TextChanging / TextChanged (PropertyChanging/ChangedEventArgs<String>), ValueChanging / ValueChanged (PropertyChanging/ChangedEventArgs<List<Nullable<DateTimeOffset>>>), ValidatingEvent (ValidatingEventArgs)

Yöntemler (METHOD): GetData(), GetValueAsObject(), LoadData(sender, e), GetDifferences(otherObj)