Gereksinimler ve Ön Hazırlık
Bu rehberi uygulamak için bilgisayarınızda Node.js'in güncel bir sürümünün (LTS) yüklü olması gerekir. React projenizde PDF oluşturma işlemleri için en kararlı iki kütüphane olan react-to-print (yazdırma odaklı) ve jspdf (dosya oluşturma odaklı) araçlarını kullanacağız.
Projenizi başlatmak veya mevcut projenize gerekli paketleri kurmak için terminalinizde şu komutu çalıştırın:
npm install react-to-print jspdf html2canvasKurulum tamamlandıktan sonra, projenizin package.json dosyasında bu bağımlılıkların göründüğünden emin olun. react-to-print, DOM yapısını doğrudan yazıcıya göndermek için optimize edilmiştir; jspdf ve html2canvas ise DOM elemanlarını görüntüye çevirip PDF dosyası olarak kaydetmek için kullanılır.
React İçerisinde Yazdırılabilir Bileşen Tasarımı
Yazdırılabilir bir rapor oluşturmanın ilk adımı, yazdırılacak içeriği izole bir bileşen (component) olarak tasarlamaktır. Bu bileşen, ana sayfa düzeninden bağımsız, temiz ve CSS ile optimize edilmiş bir yapıya sahip olmalıdır.
import React from 'react';
const RaporIcerigi = React.forwardRef((props, ref) => {
return (
Aylık Satış Raporu
Ürün Adı Adet Fiyat Laptop 5 150.000 TL
);
});
export default RaporIcerigi;Yukarıdaki kod bloğunda React.forwardRef kullanarak bileşenin referansını üst bileşene taşıyoruz. Bu referans, yazdırma kütüphanesinin hangi DOM elementini hedef alacağını belirlemesi için zorunludur.
react-to-print Kullanarak Yazdırma İşlemi
react-to-print kütüphanesi, tarayıcının yerel yazdırma penceresini tetiklemek için en güvenli yöntemdir. Bu yöntem, PDF oluşturma sürecinde CSS stillerinin korunmasını sağlar.
import React, { useRef } from 'react';
import { useReactToPrint } from 'react-to-print';
import RaporIcerigi from './RaporIcerigi';
const RaporSayfasi = () => {
const componentRef = useRef();
const handlePrint = useReactToPrint({
content: () => componentRef.current,
documentTitle: 'Satis-Raporu-2026',
});
return (
PDF Olarak Yazdır
);
};Bu örnekte, useRef kancası (hook) ile bileşene erişim sağlıyoruz. handlePrint fonksiyonu tetiklendiğinde, tarayıcı belirlenen alanı yazıcı dostu bir görünüme sokarak kullanıcıya PDF olarak kaydetme veya yazdırma seçeneği sunar.
PDF Dosyası Olarak İndirme (jsPDF ve html2canvas)
Eğer kullanıcıya doğrudan bir dosya indirtmek istiyorsanız, html2canvas ile DOM elemanını bir görsele çevirip, jspdf ile bu görseli PDF içine gömebilirsiniz. Bu yöntem, tarayıcı yazdırma penceresini atlayarak doğrudan indirme sağlar.
import jsPDF from 'jspdf';
import html2canvas from 'html2canvas';
const pdfIndir = async (element) => {
const canvas = await html2canvas(element);
const imgData = canvas.toDataURL('image/png');
const pdf = new jsPDF('p', 'mm', 'a4');
pdf.addImage(imgData, 'PNG', 0, 0, 210, 297);
pdf.save('rapor.pdf');
};Bu fonksiyon, bir HTML elementini alır, onu tuvale (canvas) çizer ve A4 boyutunda bir PDF dokümanına dönüştürür. 210x297 mm ölçüleri standart A4 kağıt boyutlarını temsil eder.
Yöntemlerin Karşılaştırılması
Hangi yöntemi seçeceğinize karar verirken aşağıdaki tabloyu referans alabilirsiniz:
| Özellik | react-to-print | jsPDF + html2canvas |
|---|---|---|
| Kullanım Kolaylığı | Yüksek | Orta |
| CSS Desteği | Mükemmel | Kısıtlı |
| Doğrudan İndirme | Hayır (Yazdırma penceresi) | Evet |
| Performans | Hızlı | İşlemci Yoğun |
Kritik Uyarılar ve Güvenlik
Güvenlik Uyarısı: PDF oluşturma süreçlerinde, kullanıcıdan alınan verileri doğrudan DOM'a yerleştirirken XSS (Cross-Site Scripting) saldırılarına karşı dikkatli olun. Kullanıcı girdilerini her zaman sanitize edin (temizleyin). Ayrıca, sunucu tarafında oluşturulmayan PDF'lerde hassas verilerin (şifreler, özel anahtarlar) istemci tarayıcısında açık metin olarak bulunmadığından emin olun.
Sıkça Sorulan Sorular
PDF raporumda Türkçe karakterler neden bozuk çıkıyor?
jsPDF kullanırken özel fontlar yüklemeniz gerekebilir. Eğer Türkçe karakter sorunu yaşıyorsanız, jspdf içerisine desteklenen bir fontu (örneğin Roboto veya Open Sans) Base64 formatında eklemelisiniz.
Çok sayfalı raporlarda içerik neden kesiliyor?
html2canvas tek bir görsel oluşturduğu için sayfa sonlarını otomatik yönetemez. Çok sayfalı raporlar için veriyi parçalara ayırarak her parçayı ayrı bir sayfaya yazdırmanız gerekir.
Yazdırma penceresinde arka plan renkleri görünmüyor, neden?
Tarayıcılar varsayılan olarak mürekkep tasarrufu için arka plan renklerini yazdırmaz. CSS içerisinde -webkit-print-color-adjust: exact; özelliğini kullanarak bu durumu zorlayabilirsiniz.
Mobil cihazlarda bu yöntemler çalışır mı?
Evet, ancak mobil tarayıcıların yazdırma yetenekleri masaüstüne göre daha kısıtlıdır. Kullanıcılara "PDF İndir" seçeneğini sunmak, mobil deneyimde daha tutarlı sonuçlar verir.
Büyük verilerde tarayıcı donuyor, ne yapmalıyım?
Çok büyük tablolarda html2canvas bellek tüketimini artırır. Bu durumda veriyi sunucu tarafında (Node.js/Puppeteer gibi) PDF'e dönüştürüp istemciye hazır dosya göndermek en profesyonel yaklaşımdır.
PDF Raporlarında Dinamik Grafik Entegrasyonu
Raporlarınızı görselleştirmek, verilerin okunabilirliğini artırır. Recharts kütüphanesini kullanarak PDF çıktısına dahil edilecek bir grafik bileşeni oluştururken dikkat etmeniz gereken en önemli nokta, grafiklerin SVG tabanlı olması ve yazdırma sırasında ölçeklenmesidir.
Aşağıdaki örnekte, bir satış grafiğini PDF'e uygun şekilde nasıl render edeceğinizi görebilirsiniz:
import { BarChart, Bar, XAxis, YAxis, CartesianGrid, Tooltip, ResponsiveContainer } from 'recharts';
const ReportChart = ({ data }) => (
);İpucu: Yazdırma sırasında grafiklerin bulanık çıkmasını önlemek için ResponsiveContainer bileşeninin sabit bir genişlik ve yükseklik değerine sahip olduğundan emin olun. Ayrıca, yazdırma CSS'inde @media print bloğu içerisinde grafik kapsayıcısına page-break-inside: avoid; kuralını ekleyerek grafiğin sayfalar arasında bölünmesini engelleyebilirsiniz.
PDF Üretim Sürecinde Performans Optimizasyonu
Büyük veri setleri ile çalışırken, istemci tarafında PDF oluşturmak tarayıcıyı kilitleyebilir. Performansı artırmak için aşağıdaki stratejileri uygulayabilirsiniz:
- Web Workers Kullanımı: Ağır hesaplamaları veya büyük tablo verilerinin PDF'e dönüştürülme işlemlerini ana iş parçacığından (main thread) ayırmak için Web Workers kullanın.
- Lazy Loading: Rapor bileşenlerini sadece yazdırma veya indirme butonuna tıklandığında yükleyin (
React.lazyveSuspense). - Görüntü Sıkıştırma: Raporunuza eklediğiniz logoları veya görselleri PDF'e gömmeden önce
canvasüzerinden optimize ederek boyutlarını küçültün.
Veri İşleme ve Bellek Yönetimi
Eğer 1000 satırdan fazla veri içeren bir rapor oluşturuyorsanız, DOM'a tüm satırları tek seferde render etmek yerine, veriyi sayfalara bölerek (pagination) render etmek bellek kullanımını ciddi oranda düşürür.
// Örnek: Büyük veriyi parçalara ayırma
const chunkArray = (array, size) => {
const result = [];
for (let i = 0; i < array.length; i += size) {
result.push(array.slice(i, i + size));
}
return result;
};
// PDF oluştururken her sayfayı ayrı bir bileşen olarak render edin
const pages = chunkArray(largeData, 50);
pages.map((pageData, index) => (
));Bu yöntem, tarayıcının tek bir büyük DOM ağacı oluşturmak yerine, daha küçük ve yönetilebilir parçalarla çalışmasını sağlar. Özellikle düşük donanımlı mobil cihazlarda bu yaklaşım, uygulamanın çökmesini (crash) engellemek için kritiktir.
Sonuç
React ile PDF raporu oluşturmak, doğru araçlar kullanıldığında oldukça verimli bir süreçtir. Basit yazdırma ihtiyaçları için react-to-print, dosya indirme odaklı özel çözümler için ise jsPDF kombinasyonu 2026 standartlarında en güvenilir yollardır. Bir sonraki adımda, raporlarınıza grafikler eklemek için recharts veya chart.js kütüphanelerini bu PDF yapısıyla entegre etmeyi deneyebilirsiniz.
Kod güvenliği sorumluluk reddi: Bu rehberde paylaşılan kodlar eğitim amaçlıdır. Üretim ortamında (production) kullanmadan önce kütüphanelerin güncel güvenlik yamalarını kontrol edin ve kullanıcı verilerinin gizliliğini koruyacak gerekli tüm önlemleri (input validation, sanitization) uygulayın.
Yorumlar (0)
Yorum Yaz