prime-one-table

İçindekiler

• prime-one-table
  • İçindekiler
  • Kurulum
  • Kullanım
    • Şablon
    • Kod Örneği
  • Olaylar
    • onLazyLoad
    • selectionChange
  • Özelleştirme
    • Özel Hücre Şablonları
    • Özel Filtreler
  • Excel Export
    • Frontend pagination
    • Backend pagination
    • Parçalı (chunked) çekim
    • Kolon bazlı ayarlar
    • Butonu kendiniz konumlandırmak
    • Farklı bir yazıcı kullanmak
  • Özellikler
  • Types
    • PrimeOnePrimaryColumn<T>
    • PrimeOnePagination<T>
    • PrimeOneColumn<T>
    • PrimeOneTableOptions<T>
    • CustomCellTemplateContext<T>
    • CustomFilterTemplateContext<T>
    • FilterType<T>
    • PrimeOneExcelExport<T>
    • PrimeOneExportRequest
    • PrimeOneExportProgress

Kurulum

Paketi kurmak için npm kullanabilirsiniz:

npm install prime-one-table

Kullanım

PrimeOneTable bileşenini kullanmak için aşağıdaki adımları takip edebilirsiniz:

Şablon

<lib-prime-one-table
  [tableOptions]="tableOptions()"
  (onLazyLoad)="onLazyLoad($event)"
  (selectionChange)="selectionChange($event)"
></lib-prime-one-table>

Kod Örneği

Aşağıdaki örnek, PrimeOneTable bileşenini nasıl yapılandırabileceğinizi gösterir:

import { Component, inject } from '@angular/core';
import { HttpClient } from '@angular/common/http';
import { PrimeOneTableComponent } from 'prime-one-table';
import { PrimeOneTableOptions, PrimeOneColumn } from 'path-to-prime-one-table/types/types';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [PrimeOneTableComponent, HttpClient],
  templateUrl: './app.component.html'
})
export class AppComponent {
  httpClient = inject(HttpClient);
  tableOptions = signal<PrimeOneTableOptions<ExampleData>>({
    lazy: true,
    data: [],
    selectable: true,
    dataKey: 'id',
    sortMode: 'multiple',
    resizable: true,
    gridlines: true,
    reorderable: true,
    filter: false,
    pagination: {
        initialRows: 10,
        totalRecords: 0,
        pagination: true,
        paginationPerPageOptions: [10, 20, 50]
    },
    columns: [
        { header: 'ID', field: 'id' },
        { header: 'Başlık', field: 'title' },
        { header: 'Gövde', field: 'body' }
    ],
  });

  ngOnInit() {
    this.httpClient
      .get('https://jsonplaceholder.typicode.com/posts')
      .subscribe((res: any) => {
        this.tableOptions.update(v => ({
            ...v,
            data: res,
            pagination: {
                ...v.pagination!,
                totalRecords: res.length
            }
        }))
      });
  }

  onLazyLoad(event: TableLazyLoadEvent) {
    console.log('Lazy Load Event:', event);
    this.httpClient
      .get('https://jsonplaceholder.typicode.com/posts', {params: {_start: (event.first ?? 0) / (event.rows ?? 1), _limit: (event.rows ?? this.tableOptions().pagination?.initialRows ?? 10)}})
      .subscribe((res: any) => {
        this.tableOptions.update(v => ({
            ...v,
            data: res,
            pagination: {
                ...v.pagination!,
                totalRecords: res.length
            }
        }))
      });
  }

  selectionChange(event: any) {
    console.log('Selection Change Event:', event);
  }
}

Olaylar

onLazyLoad

Tablo verileri lazy yükleme ile yüklendiğinde çağrılır.

function handleLazyLoad(event: TableLazyLoadEvent) {
  // event: Yükleme olayı ile ilgili detaylar
}

selectionChange

Seçim değiştiğinde çağrılır.

function handleSelectionChange(event: any) {
  // event: Seçim değişikliği ile ilgili detaylar
}

Özelleştirme

Tabloyu özelleştirmek için columns dizisine özel hücre şablonları ve filtreler ekleyebilirsiniz. İşte bir örnek:

Özel Hücre Şablonları

columns: [
  { header: 'ID', field: 'id' },
  {
    header: 'Başlık',
    field: 'title',
    customTemplate: true,
  },
  {
    header: 'Gövde',
    field: 'body',
    customTemplate: true,
  },
];

<ng-template
  customCellTemplate
  [typeData]="tableOptions().data"
  let-col="col"
  let-rowData="rowData"
>
  @switch (col.field) { @case ('title') {
  <strong class="text-red-500 font-semibold"> {{ rowData[col.field] }} </strong>
  } @case ('body') {
  <p class="text-red-600 font-light">{{ rowData[col.field] }}</p>
  } }
</ng-template>

Özel Filtreler

Özel filtreler kullanarak daha karmaşık filtreleme mantıkları uygulayabilirsiniz.

columns: [
  { header: 'ID', field: 'id' },
  {
    header: 'Başlık',
    field: 'title',
    customTemplate: true,
    filter: {
      field: 'title',
      type: 'custom',
      placeholder: 'Placeholder',
    },
  },
  {
    header: 'Gövde',
    field: 'body',
    customTemplate: true,
  },
];

<ng-template
  customFilterTemplate
  [typeData]="tableOptions().data"
  let-col="col"
  let-value="value"
  let-filter="filter"
>
  @switch (col.field) { @case ('title') {
  <input
    pInputText
    placeholder="Title"
    (onChange)="filter($event.target.value)"
  />
  } }
</ng-template>

Excel Export

tableOptions.excelExport tanımlandığında tablo başlığında bir Excel butonu belirir. Dışa aktarım, sayfalama türüne göre iki farklı şekilde çalışır:

| Mod | lazy | Veri kaynağı | | ------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | Frontend pagination | false | Bellekteki tüm veri. Aktif filtre ve sıralama uygulanır, sayfalama uygulanmaz — yalnızca görünen sayfa değil, tüm satırlar aktarılır. | | Backend pagination | true | excelExport.fetchAll ile backend'den çekilen, sayfalanmamış tüm veri. |

Çıktı bağımlılıksız dahili bir XLSX yazıcısı ile üretilir; exceljs / xlsx gibi ek bir paket kurmanız gerekmez. Tarih, sayı ve boolean değerler Excel'de gerçek tipleriyle yazılır; başlık satırı dondurulur ve otomatik filtre eklenir.

Frontend pagination

lazy: false ise ek bir ayar gerekmez:

tableOptions = signal<PrimeOneTableOptions<ExampleData>>({
  lazy: false,
  data: [],
  dataKey: 'id',
  excelExport: {
    fileName: () => `kullanicilar-${new Date().toISOString().slice(0, 10)}`,
    sheetName: 'Kullanıcılar',
  },
  columns: [
    { header: 'ID', field: 'id' },
    { header: 'Ad', field: 'name' },
  ],
});

Backend pagination

lazy: true ise fetchAll zorunludur. Fonksiyon, tablodaki güncel filtre ve sıralama durumunu taşıyan bir lazyLoadEvent alır ve sayfalanmamış veriyi döndürür. Observable, Promise veya doğrudan dizi döndürebilirsiniz.

excelExport: {
  fileName: 'kullanicilar',
  fetchAll: (request) =>
    this.httpClient.get<ExampleData[]>('/api/users', {
      params: {
        // Sayfalama alanları: tek istekte first = 0, rows = totalRecords
        _start: request.lazyLoadEvent.first ?? 0,
        _limit: request.lazyLoadEvent.rows ?? request.totalRecords,
        _sort: request.lazyLoadEvent.sortField ?? '',
        _order: request.lazyLoadEvent.sortOrder === -1 ? 'desc' : 'asc',
      },
    }),
}

fetchAll tanımlanmadan lazy: true bir tablo dışa aktarılmaya çalışılırsa export, exportError olayı ile anlamlı bir hata mesajı vererek sonlanır.

Parçalı (chunked) çekim

Sayfa boyutunu sınırlayan API'ler için chunkSize verin. Veri, backend tükenene kadar (boş ya da eksik dolu sayfa gelene veya totalRecords'a ulaşılana kadar) sayfa sayfa çekilir ve butonda yüklenen / toplam ilerlemesi gösterilir.

excelExport: {
  chunkSize: 1000,
  fetchAll: (request) =>
    this.httpClient
      .get<{ items: ExampleData[]; total: number }>('/api/users', {
        params: {
          skip: request.lazyLoadEvent.first ?? 0,
          take: request.lazyLoadEvent.rows ?? 1000,
        },
      })
      // totalRecords döndürmek, tablonun bildirdiği toplamı düzeltir.
      .pipe(map((res) => ({ data: res.items, totalRecords: res.total }))),
  // Güvenlik sınırı: aşılırsa dosya üretilmez, exportError tetiklenir.
  maxRows: 100_000,
}

Kolon bazlı ayarlar

columns: [
  // Excel'e hiç yazılmaz
  { header: 'İşlemler', field: 'id', exportable: false },

  // Ekranda farklı, Excel'de farklı başlık ve genişlik
  { header: 'Ad', field: 'name', exportHeader: 'Tam Ad', exportWidth: 30 },

  // Sayı biçimi korunur, hücre metin değil sayı olarak yazılır
  { header: 'Tutar', field: 'amount', exportFormat: '#,##0.00' },

  // Ekranda rozet gösteren bir kolonun Excel karşılığı
  {
    header: 'Durum',
    field: 'isActive',
    customTemplate: true,
    customExportValueFn: (data) => (data.isActive ? 'Aktif' : 'Pasif'),
  },
];

Hücre değeri şu öncelikle çözülür: customExportValueFn → customValueFn → field. customExportValueFn içinden Date, number veya boolean döndürmek, Excel'de metin yerine gerçek tipli hücre üretir — böylece sıralama ve formüller çalışır.

footerRow satırlarını da dosyaya eklemek için includeFooter: true verin; yalnızca isInFooter: true olan kolonlar doldurulur.

Butonu kendiniz konumlandırmak

hideButton: true ile hazır buton gizlenir ve dışa aktarım bileşenin exportExcel() metodu ile tetiklenir:

<prime-one-table
  #tablo
  [tableOptions]="tableOptions()"
  (exportDone)="onExportDone($event)"
  (exportError)="onExportError($event)"
>
  <ng-template customCaptionTemplate>
    <p-button
      label="Dışa Aktar"
      [loading]="tablo.exporting()"
      (onClick)="tablo.exportExcel()"
    />
  </ng-template>
</prime-one-table>

exporting() dışa aktarım sürerken true olur, exportProgress() ise parçalı çekimde { phase, loaded, total } bilgisini verir.

Farklı bir yazıcı kullanmak

Daha zengin bir çıktı (birden fazla sayfa, formül, resim vb.) gerekiyorsa writer ile kendi implementasyonunuzu verebilirsiniz. Kütüphane veriyi toplar, dosyayı sizin yazıcınız üretir:

excelExport: {
  writer: async (sheet) => {
    const ExcelJS = await import('exceljs');
    const workbook = new ExcelJS.Workbook();
    const worksheet = workbook.addWorksheet(sheet.name);

    worksheet.columns = sheet.columns.map((col) => ({
      header: col.header,
      width: col.width,
    }));
    sheet.rows.forEach((row) => worksheet.addRow(row));

    return new Blob([await workbook.xlsx.writeBuffer()]);
  },
}

Özellikler

| Özellik | Tip | Varsayılan | Açıklama | | ----------------- | ---------------------------------------------------------- | ---------- | ---------------------------------------------- | | tableOptions | PrimeOneTableOptions<T> | - | Tablo ayarlarını içeren konfigürasyon nesnesi. | | onLazyLoad | (lazyLoadEvent: TableLazyLoadEvent) => void | - | Lazy yükleme olayı. | | selectionChange | (selectEvent: any) => void | - | Seçim değişikliği olayı. | | exportStart | () => void | - | Excel dışa aktarımı başladığında tetiklenir. | | exportDone | (result: { fileName: string; rowCount: number }) => void | - | Dosya indirildiğinde tetiklenir. | | exportError | (error: unknown) => void | - | Dışa aktarım başarısız olduğunda tetiklenir. |

Types

PrimeOnePrimaryColumn<T>

| Alan | Tip | Açıklama | | --------------------- | ---------------------------------------------------------- | -------------------------------------------------------------------- | | header | string | Sütun başlığı. | | headerClass | string | Sütun Başlığına ait class | | sortField | string | Sıralama yapılacak alan. | | filter | FilterType<T> | Filtreleme ayarları. | | class | string | Sütuna ait class. | | customColClassFn | (data: T) => { [key: string]: boolean } | Sütuna ait koşullandırılabilir class. | | customValueFn | (data: T) => any | Sütuna ait kişiselleştirilebilir value | | exportable | boolean | false ise kolon Excel çıktısına dahil edilmez. Varsayılan true. | | exportHeader | string | Excel başlığı; verilmezse header kullanılır. | | exportWidth | number | Karakter cinsinden kolon genişliği; verilmezse içerikten hesaplanır. | | exportFormat | string | Excel sayı biçimi, ör. dd.mm.yyyy veya #,##0.00. | | customExportValueFn | (data: T) => string \| number \| boolean \| Date \| null | Excel hücre değeri. customValueFn'den önceliklidir. |

PrimeOnePagination<T>

| Alan | Tip | Açıklama | | -------------------------- | ---------- | ---------------------------------------- | | initialRows | number | Başlangıçtaki sayfa başına satır sayısı. | | totalRecords | number | Toplam kayıt sayısı. | | pagination | boolean | Sayfalama özelliği açık mı. | | paginationPerPageOptions | number[] | Sayfa başına gösterim seçenekleri. |

PrimeOneColumn<T>

| Alan | Tip | Açıklama | | ---------------- | --------- | ----------------------------- | | customTemplate | boolean | Özel hücre şablonu kullanımı. | | field | string | Kolon verisinin alanı. |

& PrimeOnePrimaryColumn<T>

PrimeOneTableOptions<T>

| Alan | Tip | Açıklama | | ------------------ | ------------------------------------------------- | ------------------------------------------------------------------ | | title? | string | Tablo Başlığı | | titleClass? | string | Tablo Başlığına ait class | | lazy | boolean | Lazy Loading özelliği. | | data | T[] | Tablo verileri. | | columns | PrimeOneColumn<T>[] | Tablo sütunları. | | dataKey | string | Verilerin anahtar alanı. | | sortMode | 'multiple' 'single' | Sıralama modu. | | resizable | boolean | Sütunların yeniden boyutlandırılabilirliği. | | reorderable | boolean | Sütunların sıralanabilirliği. | | expand | boolean | Satırların genişletilebilirliği | | size | 'small' 'normal' 'large' | Tablonun boyutu. | | filter | boolean | tabloda filtreleme özelliği açık mı. | | filterRowClass | string  | Tablodaki Filter satırına ait class | | headerRowClass | string | Tablo Başlık satırına ait class | | gridlines | boolean | Izgara çizgileri. | | stripedRows | boolean | Çizgili Satırlar. | | selectable | boolean | Satırların seçilebilirliği. | | lazyLoadEvent | (lazyLoadEvent: TableLazyLoadEvent) => void | Lazy yükleme olayı işleyicisi. | | pagination | PrimeOnePagination | Sayfalama ayarları. | | emptyMessage | string | Veri olmadığı durumda gösterilecek yazı | | hideColumnSelect | boolean | Sütun Filtereleme componenti gizlensin mi? | | excelExport | PrimeOneExcelExport<T> | Excel dışa aktarım ayarları. Verilmezse export butonu gösterilmez. |

CustomCellTemplateContext<T>

| Alan | Tip | Açıklama | | --------- | --------------------------------------- | ---------------- | | rowData | T | Satır verileri. | | col | PrimeOneColumn<T> | Kolon bilgileri. |

CustomFilterTemplateContext<T>

| Alan | Tip | Açıklama | | -------- | --------------------------------------- | ---------------------- | | filter | any | Filtreleme fonksiyonu. | | col | PrimeOneColumn<T> | Kolon bilgileri. | | value | any | Filtreleme değeri. |

FilterType<T>

| Alan | Tip | Açıklama | | ------------- | -------------------------------------------------------------------------------- | ------------------------------- | -------------------------- | | field | string | Objenin ilgili key değeri | Filtreleme yapılacak alan. | | placeholder | string | Filtreleme placeholder'ı. | | class | string | Filtreleme elemanına ait class. | | type | 'text' 'numeric' 'date' 'boolean' 'select' 'multi-select' 'custom' | Filtreleme türü. | | options | Signal<any> | Seçim seçenekleri (varsa). | | optionValue | string | Seçim değeri (varsa). | | optionLabel | string | Seçim etiketi (varsa). |

PrimeOneExcelExport<T>

| Alan | Tip | Varsayılan | Açıklama | | --------------- | ---------------------------------------------------------------------- | ----------------------- | ---------------------------------------------------------------------------------------------------------------------- | | hideButton | boolean | false | Hazır export butonunu gizler; dışa aktarım yalnızca exportExcel() ile tetiklenir. | | fileName | string \| (() => string) | export_<tarih>_<saat> | Dosya adı (uzantısız). | | sheetName | string | Sayfa1 | Excel sayfa adı. | | buttonLabel | string | Excel | Buton metni. | | buttonIcon | string | pi pi-file-excel | Buton ikonu. | | buttonClass | string | - | Butona ait class. | | buttonTooltip | string | - | Buton tooltip'i. | | columns | 'visible' \| 'all' | 'visible' | visible: kullanıcının kolon seçiminden geçen kolonlar, all: tüm kolonlar. | | includeFooter | boolean | false | footerRow satırlarını da dosyaya ekler. | | freezeHeader | boolean | true | Başlık satırını dondurur. | | autoFilter | boolean | true | Başlık satırına Excel filtresi ekler. | | maxRows | number | - | Güvenlik sınırı; aşılırsa dosya üretilmeden hata verilir. | | fetchAll | (request: PrimeOneExportRequest) => Observable<R> \| Promise<R> \| R | - | lazy: true için zorunlu. Sayfalanmamış veriyi döndürür. R = T[] veya { data: T[]; totalRecords?: number }. | | chunkSize | number | - | Verilirse veri backend'den bu büyüklükte parçalar halinde çekilir. | | writer | (sheet: XlsxSheet) => Promise<Blob> \| Blob | dahili XLSX yazıcısı | Dosyayı üreten katmanı değiştirir. |

PrimeOneExportRequest

| Alan | Tip | Açıklama | | --------------- | -------------------- | ---------------------------------------------------------------------------------- | | lazyLoadEvent | TableLazyLoadEvent | Tablonun güncel sıralama/filtre durumu; first ve rows istenen dilimi belirtir. | | totalRecords | number | Tablonun export anında bildirdiği toplam kayıt sayısı. | | chunkIndex | number | Parçalı çekimde 0 tabanlı parça indeksi; tek istekte her zaman 0. |

PrimeOneExportProgress

| Alan | Tip | Açıklama | | -------- | -------------------------- | ----------------------------------------------- | | phase | 'fetching' \| 'building' | Veri çekiliyor / dosya hazırlanıyor. | | loaded | number | O ana kadar toplanan satır sayısı. | | total | number | Beklenen toplam satır sayısı; bilinmiyorsa 0. |