DataGrid

Verileri satır ve sütunlardan oluşan bir tablo halinde gösteren nesnedir. Bir veri kaynağına bağlanır; kullanıcı tablo üzerinde filtreleme, sıralama, arama yapabilir, satır ekleyip silebilir ve hücreleri yerinde düzenleyebilir. Koddan da satır ekleyip okuyabilir, seçili satırları işleyebilirsiniz.

Ne zaman kullanılır?

Çok sayıda kaydı tek ekranda listelemek, kullanıcıya tablo üzerinde satır ekletmek/sildirmek ya da bir veri kaynağındaki kayıtları seçtirmek istediğinizde idealdir. Sipariş kalemleri, masraf satırları, malzeme listeleri gibi tekrar eden kayıtlar için kullanılır. Tek bir kayıt seçtirmek için Lookup, ağaç (üst-alt) yapısı için TreeList daha uygundur.

Değer tipi: Bu nesnenin tek bir Value değeri yoktur. DataGrid bir satır koleksiyonu (Rows) tutar; her satır (DataGridRow) hücrelerden (DataGridCell) oluşur. Bir hücreye satır indeksleyicisiyle erişirsiniz: satir["SütunAdı"] size bir DataGridCell döndürür, değeri okumak için .Value, ekrandaki metni için .Text kullanırsınız.

Tasarımcı özellikleri

Bir DataGrid seçildiğinde Özellik Görüntüleyici birkaç sekmeye ayrılır.

General

Özellik	Açıklama
Name	Nesnenin koddaki adı (ör. DataGrid1). Koddan bu adla erişirsiniz.
Caption	Tablonun yanındaki etiket (çok dilli).

Data Source

DataGrid'in gösterdiği veriyi bu sekme belirler.

Özellik	Açıklama
DataSource	Tablonun bağlandığı veri kaynağı. Satırlar buradan gelir.
DataSourceType	Veri kaynağının türü (sorgu, liste, statik veri vb.).

Columns (sütun modeli)

Columns, bir DataGridColumnCollection içinde DataGridColumn nesneleri tutar. Her sütunun zengin bir tanımı vardır.

DataGridColumn üyesi	Açıklama
Name	Sütunun alan adı. Hücreye bu adla erişirsiniz: satir["Name"].
Caption	Sütun başlığı (Dictionary<String,String>, çok dilli).
DbType	Sütunun veri türü (ColumnDbType).
EditType	Hücre editör türü (ColumnEditType: metin, sayı, tarih, seçim vb.).
Formula	Hesaplanmış sütun formülü.
Format / FormatType	Gösterim biçimi (ör. para, tarih).
IsPrimaryKey	Sütunun anahtar (kimlik) olup olmadığı.
AllowNull	Boş değere izin verir.
DefaultValue	Yeni satırda varsayılan değer.
Sorting / Filtering	Sütun bazlı sıralama / filtre ayarları.
SummaryTypes	Sütun altında toplam/ortalama gibi özet satırı.
Visible	Sütunu gizler/gösterir.
Width / PreferredWidth	Sütun genişliği.
ShowEditorAlways	Hücreyi sürekli düzenlenebilir gösterir.

DataGridActionButtonColumn, DataGridColumn'dan türeyen özel bir sütun türüdür; hücre yerine bir işlem butonu (ActionButtonProps) gösterir ve tıklanınca ActionButtonClick olayını tetikler.

Behavior

Özellik	Açıklama
Editing	Satır içi düzenleme ayarları: ekleme, güncelleme, silme açık mı.
Filtering	Sütun bazlı filtre satırını açar.
Searching	Tablonun üstüne genel arama kutusu ekler.
Sorting	Sütun başlığına tıklayarak sıralamayı açar.
Grouping	Satırları bir sütuna göre gruplamayı açar.
Paging	Verileri sayfalara böler.
Selection	Satır seçimini ve seçim türünü (tekli/çoklu) ayarlar.
DetailRow	Her satırın altında açılan detay paneli tanımlar.
TreeView	Satırları ağaç (üst-alt) yapısında gösterir.
RowDragging	Satırların sürükle-bırak ile yeniden sıralanmasına izin verir.
BatchOperations	Toplu işlem (birden çok satırı bir arada kaydetme) ayarları.
ToolbarActionButtons	Tablo araç çubuğuna eklenen özel işlem butonları (ExecuteActionButton).
ColumnAutoWidth	Sütun genişliklerinin içeriğe göre otomatik ayarlanmasını sağlar.
ColumnFixingEnabled	Bir sütunun sola/sağa sabitlenmesine izin verir.
ColumnHidingEnabled	Dar ekranlarda sütunların otomatik gizlenmesine izin verir.
ColumnVerticalBorder	Sütunlar arasına dikey çizgi koyar.
PreferredWidthType	Sütun genişliği davranışını belirler (piksel / yüzde vb.).
Rows	Tablodaki satır koleksiyonu (DataGridRowCollection). Koddan erişilir.
GetAllRows	Filtreden bağımsız bütün satırları döndürür (salt okunur).
SelectedRows	Kullanıcının seçtiği satırların koleksiyonu (salt okunur).
SelectedRowKeys	Seçili satırların anahtar değerleri (List<Object>).
SelectedRowsData	Seçili satırların verisi (List<Dictionary<String,Object>>).
HiddenRowColumnName	Hangi sütun değerine göre satırın gizleneceğini belirler.
HiddenRowValueMatchers	Gizlenecek satır değerlerini eşleştiren kurallar.
ExportToExcel	Tabloyu Excel'e aktarma butonunu açar.
ShowClearAllButton	"Tümünü temizle" butonunu gösterir.
VirtualScrolling	Çok sayıda satırda performans için satırları kademeli yükler.
CacheSettingsEnabled	Veri kaynağı sonuçlarının önbelleğe alınmasını açar.
HoverStateEnabled	Fare üzerine gelince satırı vurgular.
WordWrapEnabled	Uzun metinlerin hücre içinde alt satıra geçmesini sağlar.
FillForm	Seçilen satırın verisini form alanlarına doldurur.
SaveAction / SaveMode	Tablo değişikliklerinin kaydetme adımında nasıl işleneceğini belirler.
ReadOnly	Tabloyu salt okunur yapar; düzenleme kapanır.
Required	Tablonun en az bir satır içermesini zorunlu kılar.
Loading	Tablonun yükleniyor durumunu gösterir (Boolean).
Indexable	Satırların indekslenip indekslenmeyeceği.
Height	Tablonun yüksekliği (piksel).
ContextMenuKey / ContextMenuColumnKey / ContextMenuTarget	Tabloya/satıra/sütuna sağ tık menüsü bağlar.

Appearance

Özellik	Açıklama
Visible / Client Visible	Nesnenin görünürlüğü.
Enabled / Client Enabled	Nesnenin aktif olup olmadığı.
Title	Tablonun başlığı (MultiLanguageText, çok dilli).
GridLines	Tablo çizgilerinin türü (DataGridLineType: yatay / dikey / ikisi / yok).
GridBorder	Tablonun dış kenarlığını gösterir.
AlternateColor	Satırları bir açık bir koyu renklendirir (zebra deseni).
DisplayType	Tablonun görünüm biçimi (DataGridDisplayType).
Style / ContainerStyle	Tablonun ve kapsayıcısının stili.
CustomClassName	Özel CSS sınıfı.

Bu nesnede olmayan özellikler

DataGrid'in Text, Placeholder, TextAlign ve tek bir Value özelliği yoktur. Bunlar metin giriş nesnelerine (EditControl) aittir. DataGrid CompositeDataBoundControl'den türer ve veriyi yalnızca satır/sütun üzerinden tutar.

Olaylar

DataGrid'in olayları satır işlemleri etrafında döner. Genel yaşam döngüsü olayları (OnInit / OnLoad / OnRender vb.) bu nesnenin gerçek üyeleri değildir; aşağıdaki listeler nesnenin gerçekten tetiklediği olaylardır.

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

Sunucu olayları (Server)

Olay	Argüman tipi	Ne zaman çalışır
RowInserting	RowInsertingEventArgs (Row, Cancel)	Yeni satır eklenmeden önce. İptal edilebilir.
RowInserted	RowInsertedEventArgs (Row)	Satır eklendikten sonra.
RowUpdating	RowUpdatingEventArgs (NewRow, OldRow, Cancel)	Satır güncellenmeden önce. İptal edilebilir.
RowUpdated	RowUpdatedEventArgs (NewRow, OldRow)	Satır güncellendikten sonra.
RowRemoving	RowRemovingEventArgs (Row, Cancel)	Satır silinmeden önce. İptal edilebilir.
RowRemoved	RowRemovedEventArgs (Row)	Satır silindikten sonra.
RowEditingStart	RowEditingStartEventArgs (Row, Cancel)	Bir satır düzenlenmeye başlandığında.
RowSelectionChanged	RowSelectionChangedEventArgs (NewRow, OldRow)	Seçili satır değiştiğinde. En sık kullanılan olaydır.
ActionButtonClick	ActionButtonClickEventArgs	Satır içi işlem butonuna basılınca.
ToolbarButtonClick	ToolbarButtonClickEventArgs	Araç çubuğu butonuna basılınca.
BeforeToolbarButtonClick	BeforeToolbarButtonClickEventArgs	Araç çubuğu butonu işlenmeden hemen önce.
SetValueChange	SetCellValueChangeEventArgs	Bir hücre değeri kod ile atandığında.
ValidatingEvent	ValidatingEventArgs (salt okunur)	Tablo doğrulanırken (kaydetmeden önce).

Satır olaylarının argümanları farklıdır

Argüman tipini olaya göre seçin; aynı isimle her olayda e.Row yoktur:

• RowInserting / RowInserted / RowRemoving / RowRemoved / RowEditingStart → e.Row (tip Object) taşır. Satır olarak kullanmak için (DataGridRow)e.Row cast'i gerekir.
• RowUpdating / RowUpdated / RowSelectionChanged → e.NewRow ve e.OldRow taşır; bunlarda e.Row yoktur.
• Cancel yalnızca ...ing olaylarında (RowInserting, RowUpdating, RowRemoving, RowEditingStart) vardır; e.Cancel = true işlemi iptal eder. ...ed olaylarında işlem artık gerçekleşmiştir.

İstemci olayları (Client)

İstemci tarafında aynı satır olayları (RowInserting, RowUpdating, RowRemoving, RowSelectionChanged, RowEditingStart, ActionButtonClick, ToolbarButtonClick) TypeScript kodunda da işlenebilir.

Kod örnekleri

DataGrid'e iki yerden erişirsiniz: form kodunda doğrudan tipli nesne adıyla (DataGrid1), akış kodunda ise yalnızca Control tutarsınız ve GridData JSON yolu kullanılır. Sunucu örnekleri turuncu, istemci örnekleri kırmızı çerçevelidir.

Hücre okuma kuralı (en sık yapılan hata)

Satır indeksleyicisi satir["SütunAdı"] size bir DataGridCell döndürür, doğrudan değeri değil. Değeri okumak için .Value, ekrandaki metni için .Text kullanın:

object tutar = satir["Tutar"].Value;      // gerçek değer
string metin = satir["Tutar"].Text;       // ekrandaki metin

var deger = satir["Tutar"]; yazarsanız değeri değil, hücre nesnesini almış olursunuz.

Form kodu: satırları gezme ve hücre okuma (C#, sunucu)

Form kodunda nesneye doğrudan tipli adıyla erişirsiniz:

// Tüm satırları gez ve hücre değerini oku
decimal toplam = 0;
foreach (DataGridRow satir in DataGrid1.Rows)
{
    decimal tutar = Convert.ToDecimal(satir["Tutar"].Value ?? 0);
    string aciklama = satir["Aciklama"].Text;
    toplam += tutar;
}

// Satır sayısı (filtreden bağımsız tüm satırlar)
int satirSayisi = DataGrid1.GetAllRows.Count;

// Belirli bir hücreyi indeksle oku
object hucre = DataGrid1.GetCellValue(0, 1);   // 0. satır, 1. sütun

Form kodu: bir veri kaynağı döngüsünden satır ekleme (C#, sunucu)

Tipli grid'e satır eklemenin doğrulanmış yolu NewRow() → hücreleri doldur → Rows.Add() → Reload() döngüsüdür.

// Önce mevcut satırları temizle (yeniden kurmak için)
DataGrid1.Rows.Clear();

foreach (var kalem in malzemeler)   // malzemeler: sorgudan/listeden gelen kayıtlar
{
    DataGridRow satir = DataGrid1.NewRow();
    satir["MalzemeNo"].Value = kalem.MalzemeNo;
    satir["MalzemeNo"].Text  = kalem.MalzemeNo.ToString();
    satir["MalzemeAdi"].Value = kalem.Ad;
    satir["MalzemeAdi"].Text  = kalem.Ad;
    satir["Miktar"].Value = kalem.Miktar;
    satir["Miktar"].Text  = kalem.Miktar.ToString();
    DataGrid1.Rows.Add(satir);
}

// Değişiklikleri ekrana yansıt
DataGrid1.Reload();

Tek seferde değerlerle satır oluşturmak isterseniz NewRowWithValues kullanabilirsiniz:

var degerler = new Dictionary<string, object>
{
    ["MalzemeNo"]  = "M-1001",
    ["MalzemeAdi"] = "Vida M6",
    ["Miktar"]     = 250
};
DataGridRow satir = DataGrid1.NewRowWithValues(degerler, "tr-TR", null);
DataGrid1.Rows.Add(satir);
DataGrid1.Reload();

Form kodu: seçili satırı form alanlarına doldurma (RowSelectionChanged, C#, sunucu)

RowSelectionChanged seçili satır değiştiğinde çalışır. Argümanda e.Row yoktur; e.NewRow kullanılır ve DataGridRow'a cast edilir.

void DataGrid1_RowSelectionChanged(object sender, RowSelectionChangedEventArgs e)
{
    if (e.NewRow == null) return;
    DataGridRow satir = (DataGridRow)e.NewRow;

    // Seçili satırın hücrelerini form alanlarına doldur
    TextBox_MalzemeAdi.Value = satir["MalzemeAdi"].Value?.ToString();
    TextBox_MalzemeAdi.Text  = satir["MalzemeAdi"].Text;
    NumericBox_Miktar.Value  = Convert.ToDecimal(satir["Miktar"].Value ?? 0);
}

Form kodu: bir satırın silinmesini engelleme (RowRemoving, C#, sunucu)

RowRemoving satır silinmeden hemen önce çalışır; e.Row (tip Object) taşır, DataGridRow'a cast edip değeri .Value ile okuyun, e.Cancel = true ile silmeyi iptal edin.

void DataGrid1_RowRemoving(object sender, RowRemovingEventArgs e)
{
    var satir = (DataGridRow)e.Row;
    // Onaylanmış satırların silinmesini engelle
    if (((DataGridRow)e.Row)["Durum"].Value?.ToString() == "Onaylandı")
    {
        e.Cancel = true;
        ShowMessage("Uyarı", "Onaylanmış satır silinemez.",
            Bimser.CSP.FormControls.RuleManager.AlertType.Validation);
    }
}

Form kodu: yeni satırı doğrulayıp eklemeyi iptal etme (RowInserting, C#, sunucu)

RowInserting yeni satır eklenmeden önce çalışır; e.Row taşır ve e.Cancel = true eklemeyi iptal eder.

void DataGrid1_RowInserting(object sender, RowInsertingEventArgs e)
{
    var satir = (DataGridRow)e.Row;
    decimal miktar = Convert.ToDecimal(satir["Miktar"].Value ?? 0);
    if (miktar <= 0)
    {
        e.Cancel = true;   // geçersiz satırın eklenmesini engelle
        ShowMessage("Uyarı", "Miktar sıfırdan büyük olmalıdır.",
            Bimser.CSP.FormControls.RuleManager.AlertType.Validation);
    }
}

Form kodu: seçili satırları okuma ve bir sütunu toplama (C#, sunucu)

// Kullanıcının seçtiği satırları işle
decimal seciliToplam = 0;
foreach (DataGridRow satir in DataGrid1.SelectedRows)
{
    seciliToplam += Convert.ToDecimal(satir["Tutar"].Value ?? 0);
}

// Seçili satırların ham verisi (alan-değer sözlüğü olarak)
List<Dictionary<string, object>> seciliVeri = DataGrid1.SelectedRowsData;

Akış (Flow) kodu: GridData JSON yolu (C#, sunucu)

Akış kodunda yalnızca bir Control tutarsınız; tipli DataGrid yüzeyi yoktur. Bu durumda GridData.FromControl(ctrl) ile yazılabilir bir kopya alır, GridDataRow / GridDataRowCell(value, name) ile satır ekler ve sonucu form verisine yazarsınız.

// 1. Grid kontrolünü yazılabilir bir GridData'ya çevir
Control gridCtrl = Document1.Controls["DataGrid1"];
GridData grid = GridData.FromControl(gridCtrl);

// 2. Satırları kur ve ekle (hücreler (değer, sütunAdı) şeklinde)
foreach (var kalem in malzemeler)
{
    var yeniSatir = new GridDataRow
    {
        Cells = new List<GridDataRowCell>
        {
            new GridDataRowCell(kalem.MalzemeNo, "MalzemeNo"),
            new GridDataRowCell(kalem.Ad,        "MalzemeAdi"),
            new GridDataRowCell(kalem.Miktar,    "Miktar"),
        }
    };
    grid.Rows.Add(yeniSatir);
}

// 3. Tüm grid'i JSON olarak kontrol değerine yaz, birleştir ve kaydet
FormData fd = new FormData();
fd.ControlValues.Add("DataGrid1", JsonConvert.SerializeObject(grid));
Document1.MergeData(fd.ControlValues);
Document1.Save();

Akış tarafında satırları okumak için yine GridData.FromControl kullanılır; hücreler sütun Name'iyle eşleştirilir:

Control ctrl = Document1.Controls["DataGrid1"];
GridData grid = GridData.FromControl(ctrl);
foreach (GridDataRow satir in grid.Rows)
{
    var hucre = satir.Cells
        .FirstOrDefault(c => c.Name == "Miktar");
    object miktar = hucre?.Value;
}

İstemci kodu (TypeScript, tarayıcı)

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

// Seçili satır anahtarlarını oku
const secili = this.DataGrid1.selectedRowKeys;

// Tabloyu görünür/gizli yap
this.DataGrid1.visible = true;

DataGridRow ve DataGridCell üyeleri

Satırları kodla dolaşırken bu üyeleri kullanırsınız.

DataGridRow üyesi	Açıklama
satir["SütunAdı"]	İndeksleyici; bir DataGridCell döndürür.
Cells	Satırdaki tüm hücreler (DataGridCellCollection).
CellData	Hücre verisi sözlüğü (Dictionary<String,Object>).
Data	Satırın alan-değer verisi (Dictionary<String,Object>).
Selected	Satır seçili mi (Boolean).
RowId	Satırın kimliği (Nullable<Int64>).
Index	Satırın sırası (Int32).
Name	Satırın adı.
ToDictionary()	Satırı sözlüğe çevirir.

DataGridCell üyesi	Açıklama
Value	Hücrenin saklanan değeri (Object).
Text	Hücrenin ekrandaki metni (String).
Name	Hücrenin (sütunun) adı.
Index	Hücrenin sütun sırası.
EditType	Hücre editör türü (ColumnEditType).

Metotlar

Metot	Açıklama
NewRow(int? index)	Boş bir DataGridRow üretir (henüz eklemez).
NewRowWithValues(Dictionary<string,object> values, string userLanguage, int? index)	Değerleriyle dolu bir DataGridRow üretir.
Rows.Add(row)	Satırı tabloya ekler.
Rows.Clear()	Tüm satırları siler.
Reload()	Değişiklikleri ekrana yansıtır (satır ekleme/silme sonrası gerekir).
GetCellValue(int rowIndex, int cellIndex)	Tek bir hücrenin değerini indeksle döndürür.
GetRowValues(int rowIndex)	Tek bir satırın değerlerini döndürür.
GetSelectedRows()	Seçili satırları döndürür.
LoadFrom(DataTable table)	Grid'i bir DataTable'dan doldurur.
ClearDataSource()	Bağlı veri kaynağını temizler.

İpuçları

• Bir hücreyi okurken mutlaka .Value ya da .Text kullanın; satir["Sütun"] tek başına hücre nesnesidir, değer değildir.
• Satır ekleme/silme sonrası değişikliklerin ekrana yansıması için Reload() çağırın.
• Akış kodunda yalnızca Control tutuyorsanız GridData.FromControl yolunu, form kodunda tipli DataGrid nesnesi varsa NewRow() / Rows.Add / Reload() yolunu kullanın.
• Satır olaylarında argüman tipini doğru seçin: ...ing olaylarında e.Cancel vardır; RowUpdating / RowSelectionChanged'de e.Row yerine e.NewRow / e.OldRow kullanılır.
• Çok sayıda kayıt gösterecekseniz Paging ya da VirtualScrolling açın; aksi halde tablo yavaşlar.
• En az bir satır zorunlu olsun istiyorsanız kodla kontrol etmek yerine Required özelliğini kullanın.
• Kullanıcının seçtiği satırı form alanlarına doldurmak için tasarımdaki FillForm özelliğini açabilir ya da RowSelectionChanged ile kod yazabilirsiniz.

Tüm tasarımcı özellikleri ve olaylar (tam liste)

General: Name, Caption

Data Source: DataSource, DataSourceType

Columns: Columns (DataGridColumnCollection / DataGridColumn), ColumnSettings, DataGridActionButtonColumn

Behavior: AlternateColor, BatchOperations, CacheSettingsEnabled, ColumnAutoWidth, ColumnFixingEnabled, ColumnHidingEnabled, ColumnVerticalBorder, ContextMenuColumnKey, ContextMenuKey, ContextMenuTarget, DetailRow, DisplayType, Editing, EntityPath, ExportToExcel, FillForm, Filtering, GetAllRows, GridBorder, GridLines, Grouping, Height, HiddenRowColumnName, HiddenRowValueMatchers, HoverStateEnabled, Indexable, Loading, Paging, PreferredWidthType, ReadOnly, Required, RowDragging, Rows, SaveAction, SaveMode, Searching, SelectedRowKeys, SelectedRows, SelectedRowsData, Selection, ShowClearAllButton, Sorting, ToolbarActionButtons, TreeView, VirtualScrolling, WordWrapEnabled

Appearance: ClientEnabled, ClientVisible, ContainerStyle, CustomClassName, Enabled, GridBorder, GridLines, Style, Title, Visible

Olaylar (Server / Client): ActionButtonClick, BeforeToolbarButtonClick, RowEditingStart, RowInserted, RowInserting, RowRemoved, RowRemoving, RowSelectionChanged, RowUpdated, RowUpdating, SetValueChange, ToolbarButtonClick, ValidatingEvent

Metotlar: NewRow, NewRowWithValues, Rows.Add, Rows.Clear, Reload, GetCellValue, GetRowValues, GetSelectedRows, GetValueAsObject, GetData, LoadFrom, ClearDataSource