LivaDocsv1.1.2

LivaDataGrid

DevExtreme DataGrid üzerine kurulu, tam donanımlı veri tablosu bileşeni. Sayfalama, filtreleme, arama, seçim, satır içi düzenleme ve dışa aktarma gibi özellikler hazır prop'larla açılıp kapatılır. Veri kaynağı olarak yerel bir dizi veya ASP.NET uzak veri kaynağı tanımı kullanılabilir.

import { LivaDataGrid, type LivaDataGridColumn } from "@dataliva/livalib";

Temel kullanım

columns ve keyExpr zorunludur; dataSource düz bir dizi olabilir. Kolonlar LivaDataGridColumn tipindedir ve en sık dataField, caption, dataType, format ile alignment alanları kullanılır. showPager sayfalayıcıyı açar, pagingDefaultPageSize ve pagingAllowedPageSizes sayfa boyutunu yönetir.

type Personel = { id: number; adSoyad: string; sehir: string; gorev: string; maas: number };

const personeller: Personel[] = [
  { id: 1, adSoyad: "Ayşe Yılmaz", sehir: "İstanbul", gorev: "Yönetici", maas: 82000 },
  // ...
];

const kolonlar: LivaDataGridColumn[] = [
  { dataField: "adSoyad", caption: "Ad Soyad" },
  { dataField: "sehir", caption: "Şehir" },
  { dataField: "gorev", caption: "Görev" },
  { dataField: "maas", caption: "Maaş", dataType: "number", format: "#,##0 ₺", alignment: "right" },
];
Temel kullanım ve sayfalama
Önizleme yükleniyor…

Filtreleme ve arama

showFilterRow kolon altına filtre satırı, showHeaderFilter kolon başlığına değer listesi, showSearchPanel ise tablo genelinde arama kutusu ekler. rowAlternationEnabled satırları dönüşümlü renklendirerek okunabilirliği artırır.

Filtreleme ve arama
Önizleme yükleniyor…

Başlık filtresinde arama

showHeaderFilter açıkken açılan değer listesinin üstündeki arama kutusu üç noktada DevExtreme'in varsayılanından ayrılır; üçü de otomatiktir, prop gerektirmez:

  • Kutunun sağına bir mod seçici eklenir: Contains, Begins with, Ends with. Seçim listenin searchMode değerini anında değiştirir.
  • Arama, listede yazılı görünen metin üzerinde çalışır; ham sayısal değer üzerinde değil. format ile yuvarlanmış bir kolonda 1.234,57 yazıp arayabilirsiniz — varsayılan davranışta bu, arka plandaki 1234,5678 değerine denk gelmediği için sonuç vermez. Liste sayfalıysa eşleşmeler tüm sayfalarda aranır, yalnız ilk sayfada değil.
  • Liste yeniden açıldığında uygulanmış (işaretli) değerler en üstte durur; iki grubun kendi içindeki sıra (yapılandırılmış sıralama dahil) korunur. Yalnız pencere açıldığı anda uygulanmış olan seçim öne alınır — yeni işaretlenenler, filtre uygulanıp liste tekrar açılana kadar yerinde kalır.

Lookup'lu, özel dataSource verilmiş ve hiyerarşik tarih filtreli kolonlar kendi yükleme kurallarını koruduğu için biçimli metin aramasının dışında kalır; işaretli değerlerin öne alınması ise lookup'lu kolonlarda da çalışır (bunun için liste sayfalanmadan yüklenir). Bir kolonda headerFilter alanını kendiniz verdiğinizde Liva'nın varsayılanı tümüyle devre dışı kalır.

Toplam kayıt satırı — totalRow

totalRow açıldığında tablonun hemen altında (alt araç çubuğunun üstünde) Toplam kayıt: N yazan ince bir şerit çıkar. Dizi kaynakta başlangıç değeri dizinin uzunluğudur; grid içeriği her hazırlandığında sayı DevExtreme'in bildirdiği toplamla (totalCount()) tazelenir. Toplam alınamazsa son bilinen değer kalır, hiç bilinmiyorsa — görünür. lang değeri EN ile başlıyorsa etiket Total records olur ve sayı en-US biçimiyle yazılır; aksi halde Toplam kayıt ve tr-TR. Varsayılan false'tur.

Toplam kayıt satırı
Önizleme yükleniyor…

Ortak prop preset'i — getGridProps()

Çoğu sayfada aynı temel proplar tekrar eder. Bunları her tabloda tek tek yazmak yerine projenin kendi preset fonksiyonunu spread edin. Bir grid kurarken yazacağınız satır budur:

import { LivaDataGrid } from "@dataliva/livalib";
import { getGridProps } from "@/features/_shared/components";

<LivaDataGrid
  {...getGridProps()}
  keyExpr="id"
  dataSource={personeller}
  columns={kolonlar}
/>

Spread'i props listesinin en başına koyun; böylece sayfaya özel proplar preset'i ezebilir — tek bir ayarı değiştirmek için o prop'u yazmanız yeter:

<LivaDataGrid {...getGridProps()} editMode="cell" />  // editMode → "cell"

Yetki (allowAdding, allowEditing, allowDeleting), export, veri kaynağı (remoteOperations dahil) ve olaylar preset'e girmez; bunlar her sayfanın kendi kararıdır.

Preset fonksiyonunu tanımlama

Her proje bu fonksiyonu bir kez yazar ve tüm gridler onu çağırır. LivaBudget'ta _shared/components/getGridProps.ts altında durur:

import { LivaDataGrid } from "@dataliva/livalib";
import type { ComponentProps } from "react";

type LivaGridProps = ComponentProps<typeof LivaDataGrid>;

export function getGridProps(): Partial<LivaGridProps> {
  return {
    gridSize: "xxs",
    fullHeight: true,
    editMode: "batch",
    scrollingMode: "virtual",
    showToolbar: true,
    showSearchPanel: true,
    columnChooser: true,
    isLivaContextMenu: true,
    allowGrouping: false,

    lang: currentLanguage(),          // Accept-Language başlığı
    noDataText: t("Common.NoData"),   // çeviriden
  };
}

Değerler tahminle değil, mevcut kullanımların taranmasıyla seçilir: bir ayarı sayfaların tamamına yakını aynı yazıyorsa preset'e girer. LivaBudget'taki 63 <LivaDataGrid> kullanımında gridSize: "xxs" 62/62, fullHeight 54/54, scrollingMode: "virtual" 45/45, editMode: "batch" 51/51 çıktığı için bunlar preset'e alındı.

Bu bir hook DEĞİLDİR ve hook çağırmaz. Fonksiyon JSX içinde koşullu dallarda (yetkiVar ? <LivaDataGrid {...getGridProps()} /> : null) çağrılabildiği için useTranslation/useSelector gibi bir hook barındırırsa render'lar arasında hook sayısı değişir ve React "Rendered more hooks than during the previous render" hatası verir. Dil ve çeviri değerlerini store'dan / i18n örneğinden doğrudan okuyun; sayfa zaten çeviri değişiminde yeniden render olduğu için değerler tazelenir.

Ağaç sürümü için LivaTreeList'teki getTreeList() kullanılır.

Kütüphane tarafı — baseGridProps

@dataliva/livalib, baseGridProps adında asgari bir nesne de dışa aktarır:

PropDeğer
gridSize"xs"
fullHeighttrue
showToolbartrue
showSearchPaneltrue
editMode"batch"

as const satisfies Partial<LivaDataGridProps> ile tanımlıdır: değerler literal tipte kalır, yanlış bir prop adı derleme hatası verir. Bu, kütüphane genelinde güvenli olan en küçük ortak kümedir — bir projenin standardı bundan geniştir, o yüzden sayfalarda doğrudan baseGridProps spread etmeyin. Yeni bir projede preset fonksiyonuna başlangıç noktası olarak kullanabilirsiniz:

import { baseGridProps } from "@dataliva/livalib";

export function getGridProps(): Partial<LivaGridProps> {
  return { ...baseGridProps, gridSize: "xxs", scrollingMode: "virtual" /* … */ };
}

Toplu işlemler

selectionMode="multiple" (varsayılan) iken alt araç çubuğunda, Kaydet'in sağında bir İşlemler menüsü çıkar. Satır seçildiği anda buton primary renge döner. Menü üç katmandan oluşur ve bu sırayla dizilir:

  1. Seçim araçları — bulkSelectionTools ile yönetilir, varsayılan açık: Sadece Seçilileri Göster (mevcut filtrenin üstüne geçici bir filtre biner, kapatınca eski filtre geri gelir), Panoya Kopyala (başlıklarla) — Excel'e yapıştırılabilir TSV, Seçimi Tersine Çevir (yalnızca yüklü satırlarda) ve Seçimi Temizle.
  2. Seçilenleri Sil — allowBulkDelete ile açılır; verilmezse allowDeleting değerini devralır. Onay penceresinden sonra varsayılan silme çalışır; onBulkDelete verirseniz davranışı siz üstlenirsiniz.
  3. bulkActions — sayfaya özel işlemler, listenin en altına eklenir.
import type { LivaGridBulkAction } from "@dataliva/livalib";

const islemler: LivaGridBulkAction[] = [
  {
    id: "approve",
    text: (ctx) => `Onayla (${ctx.keys.length})`,
    icon: "check",
    disabled: (ctx) => ctx.keys.length === 0,
    confirm: (ctx) => `${ctx.keys.length} kayıt onaylanacak, devam edilsin mi?`,
    confirmTitle: "Toplu Onay",
    confirmButtonText: "Onayla",
    onClick: async (ctx) => {
      await api.approve(ctx.keys);
      ctx.component.refresh();
    },
  },
];

<LivaDataGrid {...getGridProps()} bulkActions={islemler} allowBulkDelete />

text, disabled ve confirm alanları düz değer ya da (ctx: LivaGridBulkActionContext) => … fonksiyonu alabilir; fonksiyon menü her açıldığında güncel seçimle çağrılır. danger: true öğeyi ve onay butonunu kırmızıya çevirir.

Sayfalı veya sanal kaynakta ctx.rows yalnızca yüklü satırları taşır; ctx.keys tam seçimdir. Sunucuya iş gönderirken keys üzerinden çalışın.

Excel refleksleri — excelMode

Grid, Excel'den gelen kullanıcının alışkanlıklarını karşılar: blok seçme, formül yazma, tutamaçla doldurma ve seçim özeti. Varsayılan olarak açıktır (excelMode = true); tek tek kapatmak için nesne verin.

<LivaDataGrid
  {...getGridProps()}
  excelMode={{ formulas: false, rangeTotals: false }}
  allowEditing
  editMode="batch"
  // ...
/>
AlanVarsayılanNe yapar
rangeSelectionaçıkSürükleyerek blok seçme, Shift+tık ile genişletme, Ctrl+tık ile ikinci blok ekleme, Shift+Ok ile klavyeden büyütme
fillHandleaçıkBloğun sağ alt köşesindeki tutamaçla doldurma; sabit farklı diziyi sürdürür
formulasaçıkSayı hücrelerine =2500*1,18 veya =SUM(Ocak:Mart)/3 yazılabilir
statsBaraçıkAlt şeritte seçili bloğun Toplam / Ort / Min / Max / Adet özeti
rangeTotalsaçıkSeçili bloğun sağında satır, altında sütun toplamı rozetleri; tablonun ya da ekranın kenarında yer kalmazsa rozet bloğun soluna / üstüne geçer
copyFormat'display'Panoya ekrandaki biçimli metin (1.234,56) ya da ham sayı ('raw') gider

Yazma gerektiren alanlar kendiliğinden kısıtlanır: fillHandle, formulas, Ctrl+V ve Delete yalnızca allowEditing açık ve editMode 'batch' veya 'cell' iken çalışır. rangeSelection, enableRowDragging ile birlikte kapanır — satır taşıma ile blok sürükleme aynı fareyi paylaşamaz, satır taşıma önceliklidir. rangeTotals ve statsBar blok seçimine bağlıdır.

Klavye ve pano

TuşEtki
Sürükle / Shift+tıkBlok seç / genişlet
Ctrl+tık, Ctrl+sürükleMevcut seçime ikinci blok ekle
Shift+OkBloğu klavyeden büyüt
Ctrl+CSeçili blokları TSV olarak panoya kopyala
Ctrl+VPanodaki matrisi bloğun sol üst köşesinden başlayarak yaz
Delete / BackspaceSeçili blokları temizle
EscapeSeçimi bırak

Tarayıcı pano okumaya izin vermediğinde (Firefox hiç vermez, Chrome sorar) sağ tık menüsündeki Excel'den Yapıştır penceresi kullanılır: metin kutusuna yapıştırılan matris önizlenir, sonra hücrelere yazılır.

Hücre içi formüller

Hesaplama = ister. = ile başlamayan giriş düz sayı olarak okunur — 1200+300 hesaplanmaz. Ayrıştırıcı elle yazılmıştır, eval kullanılmaz; Türkçe kolon adlarını ve 1.234,56 biçimini tanır.

=2500*1,18            düz aritmetik
=Ocak*1,1             aynı satırdaki başka kolon (başlık ya da dataField ile)
=SUM(Ocak:Mart)/3     görünür kolon sırasına göre aralık
=Ocak*%10             ön ekli yüzde (sonda da yazılabilir: 10%)
=BU*1,05              formülün yazıldığı kolon (SELF)

Fonksiyonlar: SUM, AVG, MIN, MAX, COUNT, ABS, SQRT, ROUND, FLOOR, CEIL — Türkçe eş adlarıyla birlikte (TOPLA, ORT, ENKUCUK, ENBUYUK, ADET, MUTLAK, KAREKOK, YUVARLA, TABAN, TAVAN).

Formül metni saklanmaz. Grid bir hesap tablosu değil; ayrıştırıcı sayı döndürür ve hücreye ham sayı yazılır. Sonraki açılışta hücrede yalnız sonuç durur.

Ondalık basamak — sağ tık menüsü

Sayısal (dataType: "number") bir kolonun ya da V001…V012 kalıbındaki ay kolonlarının hücresine sağ tıklandığında Görünüm → Ondalık Basamak alt menüsü çıkar: Küsuratsız, 1–4 basamak ve Varsayılan. Seçim kolonun kendi format tipini (para birimi, yüzde vb.) korur, yalnızca precision değerini ezer; string format verilmişse { type, precision } nesnesine, format hiç verilmemişse fixedPoint'e dönüştürülür.

Ay kolonlarında seçim tüm ay kolonlarına birden uygulanır — tek tek 12 kolonu ayarlamak gerekmez. Ayar bileşen state'inde tutulur; kalıcı değildir ve adlandırılmış düzenlere yazılmaz.

Aralık kuralı (Min / Max) — sağ tık menüsü

Aynı sağ tık menüsünün Denetim başlığı altında Aralık Gir (Min / Max) yer alır. Ondalık basamak hücrenin nasıl göründüğünü değiştirir; aralık kuralı değerin doğru olup olmadığını işaretler — bu yüzden ayrı başlıkta durur.

Açılan pencerede alt ve üst sınır girilir. Sınırlardan biri boş bırakılabilir; boş uç sınırsız demektir. Kural hiçbir hücreye yazmaz, yalnızca görsel bir denetimdir: aralık dışında kalan hücreler renklendirilir ve title ile sınır bilgisini taşır.

  • Kapsam — kuralın hangi kolonlara konacağı: yalnız bu kolon, Tüm ay sütunları (V001…V012 kalıbı), ya da Tüm sayı sütunları. Seçeneğin yanında kaç kolonu tuttuğu yazar. Ay kolonuna sağ tıklandığında ay kapsamı ön seçili gelir. Kural hangi kapsamla konulduysa Aralık Kuralını Kaldır aynı grubun tamamından birlikte kalkar.
  • Renk — kırmızı (varsayılan, "bu değer hatalı") ya da yeşil. Yeşil, olumsuz okunmaması gereken takip amaçlı denetimler için.
  • Önizleme — uygulamadan önce kaç hücrenin dışarıda kalacağını ve birkaç örnek hücreyi gösterir. Önizleme ekrandaki satırlar üzerinden hesaplanır; sanal kaydırmada tüm veri elde olmadığı için sayı yüklü satırları yansıtır.

Ondalık basamak ayarı gibi bu da bileşen state'inde tutulur: kalıcı değildir ve adlandırılmış düzenlere yazılmaz. Kural mantığı LivaTreeList ile ortaktır, iki bileşende de aynı menü ve aynı pencere çıkar.

Sağ tık menüsüne öğe ekleme — onContextMenuPreparing

Sayfaya özel menü öğeleri için onContextMenuPreparing verin. İşleyiciniz Liva'nın kendi öğeleri (kopyalama/yapıştırma, Görünüm, Denetim…) hazırlandıktan sonra çağrılır; e.items dizisine ekleme yapabilir, öğe çıkarabilir ya da sırayı değiştirebilirsiniz.

<LivaDataGrid
  {...getGridProps()}
  onContextMenuPreparing={(e) => {
    if (e.row?.rowType !== "data") return;
    const satir = e.row.data;
    e.items = e.items ?? [];
    e.items.unshift({
      text: "Kartı Aç",
      icon: "folder",
      onItemClick: () => kartiAc(satir.id),
    });
  }}
/>

LivaTreeList'teki aynı adlı prop da aynı sırayla çalışır.

İçe/dışa aktarma

exportOptions Excel/CSV/PDF dışa aktarma butonlarını açar. importExportSettings ise DataExchange sözleşmesine bağlanır: processKey verdiğinizde içe aktarma sihirbazı grid'in içine kendiliğinden monte edilir. Kurulum, uç noktalar ve adaptörler için Veri Alışverişi sayfasına bakın.

İçe aktarma başarıyla bittiğinde grid kendi refresh()'ini çağırır; bu yalnızca bağlı veri kaynağını yeniden okur. dataSource olarak yerel bir dizi veriyorsanız veriyi importExportSettings.onImportCompleted(report) içinde kendiniz yeniden yükleyin. Sihirbazın teknik bilgi kartı (showDiagnostics) importExportSettings.config.dataExchange üzerinden ya da uygulama genelinde LivaGridConfigProvider ile açılır.

Adlandırılmış düzenler

Grid bir LivaGridStateProvider altında kullanıldığında araç çubuğunda Düzen menüsü açılır. Kullanıcı kolon sırası, genişliği, görünürlüğü, sabitleme, sıralama, gruplama ve filtre ayarlarını adlandırarak sunucuda saklayabilir. id verilmezse kayıt anahtarı sayfa yolu, keyExpr ve kolon alanlarından otomatik üretilir; aynı sayfada aynı kolonlara sahip iki grid varsa ya da kolon eklenip çıkarıldığında düzenlerin korunması gerekiyorsa sabit bir id verin. Kolon şeması geriye uyumsuz değiştiğinde stateVersion değerini artırın. Provider kurulumu ve REST sözleşmesi ayrı rehberde yer alır.