jsPDF SVG: Zachowaj ścieżki logo w PDF-ie utworzonym w przeglądarce

Aby umieścić ścieżki logo SVG w PDF-ie generowanym w przeglądarce za pomocą jsPDF, załaduj svg2pdf.js, przekaż element SVG do await doc.svg(...), a następnie zapisz dokument. Wybierz addSvgAsImage tylko wtedy, gdy obraz rastrowy jest akceptowalny. Dane wejściowe w formacie SVG nie oznaczają, że wynikowy PDF zawiera ścieżki SVG.

Przykład użycia svg2pdf.js dokumentuje asynchroniczne wywołanie przyjmujące element. Implementacja modułu SVG w jsPDF pokazuje drugą metodę: renderowanie na płótnie canvas, kodowanie do JPEG i dodawanie tego obrazu do PDF-a.

W przypadku logo na fakturze, bilecie lub w raporcie zachowaj oryginalny SVG jako edytowalny plik źródłowy. Ten przewodnik sprawdza prosty dwukolorowy znak, ustawia jego położenie w punktach PDF i analizuje zapisane obiekty. Nie zakłada, że każda funkcja SVG zostanie zachowana podczas konwersji.

Wybierz potrzebny rodzaj wyniku

Trzecia metoda przydaje się, gdy potrzebujesz przygotowanego PDF-a z logo zamiast dokumentu składanego w JavaScript. W przypadku pracy z dokumentami poza przeglądarką przewodnik po SVG w LaTeX wyjaśnia osobny proces eksportu i dołączania pliku. W przypadku procesu generowania dokumentów w Node przykład SVG w PDFKit rozróżnia wstawianie całego dokumentu od parsowania jednej ścieżki.

Jeśli wynikiem ma być prezentacja, skorzystaj z przewodnika po obrazach SVG w PptxGenJS. Sprawdza on proporcje logo, multimedia w wyeksportowanym pliku PPTX i wygląd logo w aplikacji do prezentacji, zamiast stosować ustawienia eksportu PDF do innego formatu dokumentu.

Najpierw uruchom mały przykład z ustalonymi wersjami

Przykład uruchomiono w przeglądarce z jsPDF 4.2.1 i svg2pdf.js 2.8.1. Są to przetestowane wersje, a nie gwarancja dotycząca przyszłych wydań. Pakiet nazywa się svg2pdf.js, łącznie z przyrostkiem; pakiety o podobnych nazwach mogą służyć do innych zastosowań.

W małym projekcie przeglądarkowym z narzędziem do bundlowania JavaScript zainstaluj:

npm install jspdf@4.2.1 svg2pdf.js@2.8.1

Użyj tego oryginalnego znaku jako danych wejściowych. Jego pierścień ma rzeczywisty otwór dzięki regule wypełnienia parzyste–nieparzyste. Druga ścieżka to zaokrąglony szczyt. Nie ma tu fontów, plików dołączanych przez odwołania, filtrów ani osadzonych obrazów rastrowych.

import { jsPDF } from 'jspdf';
import 'svg2pdf.js';
 
const svgText = `<svg xmlns="http://www.w3.org/2000/svg"
  width="240" height="160" viewBox="0 0 240 160">
  <path fill="#174d64" fill-rule="evenodd"
    d="M20 80 C20 15 120 15 120 80 C120 145 20 145 20 80 Z
       M48 80 C48 111 92 111 92 80 C92 49 48 49 48 80 Z"/>
  <path fill="#e66d45"
    d="M130 120 L170 35 Q178 20 188 35 L225 120 Z"/>
</svg>`;
 
async function makeVectorPdf() {
  const svg = new DOMParser()
    .parseFromString(svgText, 'image/svg+xml')
    .documentElement;
  const doc = new jsPDF({
    unit: 'pt',
    format: [300, 220],
    orientation: 'landscape'
  });
  await doc.svg(svg, { x: 30, y: 30, width: 240, height: 160 });
  return doc;
}
 
const doc = await makeVectorPdf();
doc.save('logo-vector.pdf');

Uruchom ten kod w przeglądarce, a nie bezpośrednio w skrypcie Node.js. Uwagi biblioteki dotyczące użycia i zakresu obsługi wymagają działającego DOM przeglądarki i opisują ograniczoną obsługę SVG. W aplikacji renderowanej po stronie serwera umieść tę operację w procedurze obsługi eksportu po stronie klienta.

Ten ciąg znaków zawiera zaufaną, stałą grafikę. Jeśli Twoja aplikacja przyjmuje dowolne przesyłane pliki SVG, samo parsowanie XML nie jest oczyszczaniem danych. Zanim zbudujesz proces przesyłania plików, zastosuj wskazówki biblioteki dotyczące oczyszczania SVG dostarczanych przez użytkowników i izolowania ich wykonywania.

Ustaw położenie niezależnie od viewBox

W tym przykładzie unit: 'pt' sprawia, że wymiary w PDF-ie są podawane w punktach. Strona ma 300 na 220 punktów; obszar wyświetlania grafiki zaczyna się 30 punktów od lewej i górnej krawędzi i zajmuje 240 na 160 punktów. Dokumentacja konstruktora jsPDF opisuje opcje jednostki dokumentu, formatu i orientacji.

Atrybut SVG viewBox="0 0 240 160" opisuje jego wewnętrzne współrzędne. Nie określa rozmiaru strony PDF. Zachowanie docelowej szerokości i wysokości w tych samych proporcjach 3:2 ułatwia sprawdzenie zamierzonego dopasowania. Aby zmniejszyć umieszczoną grafikę o połowę, użyj width: 120, height: 80; współrzędne ścieżek źródłowych mogą pozostać bez zmian.

Zanim zaczniesz diagnozować położenie SVG w PDF-ie, nadaj eksportowanemu SVG jawne wymiary i odpowiedni viewBox. Nieoczekiwanie duży pusty margines może należeć do obszaru roboczego SVG. Zmiana x i y przesuwa cały obszar wyświetlania SVG, łącznie z tą pustą przestrzenią.

Sprawdź oba zapisane PDF-y

Dla porównania podczas tego samego uruchomienia w przeglądarce utworzono również tę celowo zrasteryzowaną wersję:

const raster = new jsPDF({
  unit: 'pt',
  format: [300, 220],
  orientation: 'landscape'
});
await raster.addSvgAsImage(svgText, 30, 30, 240, 160);
raster.save('logo-raster.pdf');

W teście tej metody użyto zainstalowanej zależności canvg biblioteki jsPDF w wersji 3.0.11. Oba PDF-y zapisano, ponownie otwarto i wyrenderowano w tej samej skali. Inspekcja rysunków i obrazów w PyMuPDF wykazała:

Strumień zawartości pliku wektorowego zawierał polecenia krzywych i wypełnienie pierścienia według reguły parzyste–nieparzyste. W pliku rastrowym umieszczono obiekt obrazu. Te liczby opisują ten niewielki przykład testowy; bardziej złożony SVG może generować inne obiekty lub zawierać własną zawartość rastrową.

Czarny prostokąt to zaobserwowany wynik tego eksportu rastrowego, obejmujący również wcześniej przezroczysty otwór pierścienia. JPEG nie zachowuje przezroczystości alfa; nie zakładaj, że przezroczyste obszary SVG przetrwają tę metodę eksportu. Sprawdź tło, którego faktycznie potrzebujesz, szczególnie gdy logo ma znaleźć się na kolorowym panelu dokumentu.

Samo powiększenie nie jest wystarczającym dowodem. Każda przeglądarka PDF ostatecznie rysuje piksele na Twoim ekranie. Sprawdź obiekty PDF-a i porównaj zapisany wygląd z plikiem źródłowym SVG. Polecenie takie jak pdfimages -list logo-raster.pdf z pakietu Poppler może wyświetlić listę osadzonych obrazów. Sama pusta lista obrazów nie dowodzi, że zamierzone kształty zostały poprawnie wyeksportowane: strona może być pusta. Sprawdź również jej zawartość rysunkową i wygląd.

Napraw element eksportu, który zawodzi

SVG może już zawierać osadzony obraz rastrowy. Przekazanie takiego pliku do narzędzia eksportującego obsługującego grafikę wektorową nie przekształca jego pikseli w edytowalne kontury. Zanim zmienisz ustawienia PDF-a, skorzystaj z przewodnika po sprawdzaniu osadzonych obrazów rastrowych.

Ten test nie obejmuje układu tekstu, filtrów, obrazów zewnętrznych ani dowolnego CSS. svg2pdf.js wyraźnie ogranicza swój zakres do podzbioru SVG. W przypadku napisów przed konwersją zastosuj instrukcje konfiguracji fontów biblioteki lub przygotuj kontury w źródłowym projekcie, jeśli taki kompromis jest odpowiedni. Zachowaj plik źródłowy z edytowalnym tekstem, jeśli przyszłe zmiany treści mają znaczenie.

Przygotuj źródłowe logo za pomocą PerfectVector

Jeśli logo jest już poprawną grafiką wektorową, użyj tego źródła. Jeśli pozostał tylko PNG lub JPG, PerfectVector może pomóc odzyskać edytowalne kształty przed etapem tworzenia PDF-a. Zwektoryzuj logo, a następnie sprawdź jego zewnętrzny kontur, małe otwory i poszczególne kolory w edytorze SVG. Przewodnik po przygotowaniu logo opisuje tę kontrolę bardziej szczegółowo.

PerfectVector przygotowuje grafikę rastrową do tego procesu; nie dodaje obsługi SVG do jsPDF ani nie naprawia funkcji nieobsługiwanych przez narzędzie eksportujące. Porównaj odzyskane ścieżki z oryginalnym obrazem, uprość lub przerysuj szczegóły, które tego wymagają, a następnie ponownie sprawdź PDF. Zachowaj fotografię jako obraz, jeśli wektoryzacja usunęłaby potrzebne Ci szczegóły. Szerszy przewodnik po wektoryzacji obrazów wyjaśnia ten wybór źródła.

Najczęściej zadawane pytania

Czy addSvgAsImage zachowuje mój SVG jako ścieżki wektorowe? Nie. Przetestowana implementacja jsPDF 4.2.1 renderuje SVG za pośrednictwem płótna canvas i osadza JPEG. Użyj svg2pdf.js z doc.svg, gdy potrzebujesz przekonwertować obsługiwaną przez tę bibliotekę geometrię na zawartość rysunkową PDF-a.

Czy doc.svg przyjmuje nazwę pliku SVG? Pokazane API przyjmuje element SVG w DOM. Najpierw załaduj i sparsuj zaufany plik albo wybierz istniejący element SVG, a następnie przekaż ten element do doc.svg i zaczekaj na wynik.

Czy każdy SVG będzie wyglądał tak samo w PDF-ie? Nie. svg2pdf.js obsługuje ograniczoną część SVG. Przetestuj swoją rzeczywistą grafikę, w tym jej fonty, obrazy, efekty, wymiary i tła, a przed użyciem ponownie otwórz zapisany PDF.

Źródła

1. yWorks — svg2pdf.js usage and scope — API przyjmujące element SVG, konwersja asynchroniczna, konfiguracja fontów, wymagania dotyczące przeglądarki i ograniczenia zakresu obsługi.
2. jsPDF — SVG module at version 4.2.1 — Implementacja wykorzystująca canvas i JPEG, używana przez addSvgAsImage.
3. jsPDF — Constructor reference — Jednostki dokumentu PDF, format strony i opcje orientacji.
4. PyMuPDF — Page inspection — Metody inspekcji rysunków i obrazów użyte do zbadania zapisanych plików testowych.

Masz tylko logo rastrowe? Przygotuj edytowalny SVG ze swojego logo, sprawdź jego kontury i otwory, a następnie wyeksportuj go wybraną metodą do PDF-a i sprawdź zapisane obiekty oraz tło.