Logotypy SVG w React-pdf: renderuj ścieżki w swoim PDF

Aby umieścić mały logotyp SVG w @react-pdf/renderer, zbuduj grafikę za pomocą komponentów Svg, Path i innych obsługiwanych komponentów tego pakietu. Nadaj zewnętrznemu Svg jawny rozmiar i zachowaj źródłowy viewBox. Dokumentacja komponentu Image renderera wymienia wejściowe obrazy PNG i JPG; przekazanie adresu URL pliku SVG do Image nie jest opisaną tutaj metodą wektorową.

Ten poradnik wykorzystuje kompletny przykład dla Node z kwadratowym emblematem i otworem w jego środku. Wyrenderowaliśmy PDF z zależnościami przypiętymi do konkretnych wersji i sprawdziliśmy wynik. Przykład rozdziela trzy rzeczy, które łatwo ze sobą pomylić: grafikę źródłową, drzewo komponentów i rozmiar, w jakim grafika zostaje umieszczona w PDF.

Sprawdź, którego pakietu React PDF używasz

W tym artykule generujemy dokumenty za pomocą @react-pdf/renderer. Odrębny pakiet o nazwie react-pdf służy do wyświetlania istniejących plików PDF. Sprawdź import w swoim pliku, zanim skopiujesz rozwiązanie z wyników wyszukiwania.

Wewnątrz komponentu Document renderera używaj komponentów eksportowanych przez ten renderer. Przeglądarkowe elementy svg i path, zapisane małymi literami, należą do innego środowiska renderowania. Oficjalna dokumentacja SVG component reference definiuje Svg jako kontener obszaru wyświetlania i pokazuje zaimportowane kształty React-pdf umieszczone w jego wnętrzu.

Dokumentacja Image reference opisuje wejściowe obrazy rastrowe. Wariant zastępczy w PNG może się przydać, gdy złożony wygląd jest ważniejszy niż zachowanie geometrii wektorowej. Zmienia on postać przekazywanego materiału, więc zachowaj osobno oryginał wektorowy.

Istnieje też oficjalny pakiet @react-pdf/svg. Jego README opisuje funkcję parseSvg(), która zwraca drzewo węzłów elementów podstawowych i przekształca nazwy atrybutów do zapisu camelCase. Dokumentacja podaje, że nieobsługiwane elementy są pomijane z ostrzeżeniem. To opis zasad działania parsera, a nie obietnica, że każdy SVG będzie renderowany identycznie jak w przeglądarce. Poniższy przykład używa jawnie zdefiniowanych komponentów, aby geometria, wypełnienie i obrys pozostały łatwe do sprawdzenia.

Wyrenderuj minimalny logotyp, zanim zaimportujesz własny

Uruchomiliśmy ten przykład z @react-pdf/renderer 4.9.0, React 19.2.4 i Node 22.19.0. Te wersje określają przetestowaną konfigurację; nie gwarantują zachowania przy innym drzewie zależności.

W nowym katalogu zainstaluj dwa pakiety potrzebne do uruchomienia:

npm install --save-exact @react-pdf/renderer@4.9.0 react@19.2.4

Zapisz poniższy kod jako logo.mjs, a następnie uruchom node logo.mjs. Używa on React.createElement, dzięki czemu Node może go wykonać bez etapu kompilacji JSX.

import React from 'react';
import { fileURLToPath } from 'node:url';
import {
  Document, Page, Svg, Path, Rect, renderToFile,
} from '@react-pdf/renderer';
 
const h = React.createElement;
const ring = 'M10 10H90V90H10Z M30 30H70V70H30Z';
 
const logo = h(
  Svg,
  { width: 144, height: 144, viewBox: '0 0 100 100' },
  h(Rect, {
    x: 0, y: 0, width: 100, height: 100, fill: '#f3ede2',
  }),
  h(Path, { d: ring, fill: '#087f8c', fillRule: 'evenodd' }),
);
 
await renderToFile(
  h(Document, null,
    h(Page, { size: 'A4', style: { padding: 36 } }, logo),
  ),
  fileURLToPath(new URL('./logo.pdf', import.meta.url)),
);

Zewnętrzny i wewnętrzny kwadrat tworzą jedną ścieżkę złożoną. fillRule: 'evenodd' pozostawia wewnętrzny kwadrat niewypełniony, odsłaniając jasny prostokąt pod spodem. Środka nie przykrywa żaden biały element. Dzięki temu otwór jest przydatnym punktem kontrolnym, gdy zastępujesz grafikę testową logotypem zawierającym światła wewnątrz liter lub wycięcia.

Współrzędne SVG obejmują 100 jednostek w każdym kierunku, a obszar wyświetlania umieszczony w dokumencie ma wymiary 144 na 144. viewBox opisuje układ współrzędnych rysunku; width i height opisują jego obszar wyświetlania. Zachowaj to rozróżnienie przy zmianie rozmiaru logotypu. Oficjalna tabela Svg props table opisuje te ustawienia oraz preserveAspectRatio.

Sprawdź zapisany PDF oraz jego podgląd

Nasz test wygenerował jedną stronę A4 z turkusową kwadratową obręczą w pobliżu lewego górnego rogu. Wyrenderowaliśmy ten plik za pomocą Popplera i wzrokowo sprawdziliśmy, czy jasne tło jest widoczne przez otwór. Polecenie Popplera pdfimages -list logo.pdf nie wykazało żadnych osadzonych obrazów w tym odizolowanym dokumencie.

Zakres tego wyniku jest celowo wąski. Dotyczy tej grafiki testowej opartej wyłącznie na ścieżkach. Nie dowodzi, że dokument ze zdjęciami, osadzonymi obrazami SVG lub nieobsługiwanymi efektami jest w całości wektorowy.

Jeśli masz Popplera na swoim komputerze, te polecenia umożliwiają dwa różne sprawdzenia:

pdfimages -list logo.pdf
pdftoppm -png -singlefile -scale-to 1000 logo.pdf logo-preview

Drugie polecenie tworzy rastrowy podgląd do oceny wizualnej; nie zamienia oryginalnego PDF w obraz rastrowy. Sprawdź w tym podglądzie otwór, narożniki, kolory i położenie, a następnie otwórz zapisany PDF w przeglądarce używanej przez odbiorcę. Sama ostrość podglądu nie dowodzi, że oryginalny dokument zawiera ścieżki: duży obraz rastrowy też może wyglądać ostro.

Aby przeprowadzić dokładniejszą kontrolę, sprawdź instrukcje rysowania w PDF i obiekty, do których odwołują się instrukcje dotyczące logotypu. Złożone raporty mogą zawierać zagnieżdżone obiekty, więc zanim zaczniesz diagnozować cały raport, zacznij od osobnego dokumentu z samym logotypem. Poradnik SVG w PDFKit wyjaśnia odrębny proces importowania SVG oraz sprawdzanie zapisanego PDF.

Przenoś swoją grafikę po jednym elemencie

Zastąp wartość d grafiki testowej własnymi danymi ścieżki, a następnie zachowaj powiązane wypełnienie, regułę wypełnienia, obrys i transformację. Skopiowanie samego kształtu ścieżki z pominięciem jej wypełnienia i obrysu może zmienić wynik, nawet jeśli same dane ścieżki są prawidłowe.

W przypadku małego, statycznego znaku ustaw kolory bezpośrednio na obsługiwanych kształtach. Jeśli logotyp korzysta z arkusza stylów strony internetowej, musisz rozwiązać te zależności, zanim stanie się samodzielnym komponentem dokumentu. Przechowuj źródłowy SVG obok kodu renderującego, aby późniejsze zmiany można było porównać z zatwierdzoną grafiką.

Oficjalna dokumentacja SVG overview wymienia dostępne elementy podstawowe. Traktuj ją jako listę kontrolną obsługiwanych funkcji, a nie pełny zestaw funkcji SVG dostępnych w przeglądarce. Przetestuj liternictwo, przycinanie i gradienty w zainstalowanej wersji, zanim dodasz je do raportu produkcyjnego.

Jeśli SVG zawiera osadzony PNG, przekształcenie jego kontenera nie odtworzy brakującej geometrii. Poradnik dotyczący osadzonych obrazów rastrowych pokazuje, jak odróżnić ścieżki od obrazu rastrowego przechowywanego wewnątrz pliku SVG.

Gdy punktem wyjścia jest logotyp PNG lub JPG

Jeśli istnieje oryginalny plik SVG, AI lub inny edytowalny oryginał wektorowy, najpierw poproś o niego. Jeśli zostały tylko piksele, wektoryzator logotypów PerfectVector może przygotować wstępny plik SVG przed rozpoczęciem pracy z React-pdf. Porównaj jego kontury, małe otwory i oddzielne obszary kolorów ze źródłem, zanim dostosujesz obsługiwane kształty do komponentu PDF.

Wektoryzacja nie naprawia integracji z rendererem, nie tworzy komponentu React ani nie gwarantuje obsługi każdej funkcji SVG. Liternictwo wymagające dokładnego odwzorowania geometrii marki poddawaj ręcznej kontroli. Poradnik wektoryzacji logotypów pomaga wybrać między trasowaniem, ponownym wpisaniem tekstu a przerysowaniem.

W przypadku źródła dostępnego wyłącznie jako obraz rastrowy przydatnym wynikiem jest sprawdzony wstępny plik wektorowy, a następnie zweryfikowany PDF. Jeśli masz już źródło wektorowe, przejdź bezpośrednio do sprawdzania komponentów i umieszczenia grafiki. Więcej wskazówek dotyczących przygotowania źródła znajdziesz na blogu.

Często zadawane pytania

Czy mogę przekazać plik SVG do komponentu Image w React-pdf? Udokumentowane formaty wejściowe komponentu Image to PNG i JPG. W opisanym tutaj procesie opartym na ścieżkach używaj elementów podstawowych Svg renderera i sprawdź zainstalowaną wersję, zanim zaczniesz polegać na obsłudze innych formatów wejściowych.

Czy muszę ręcznie przekształcać każdy SVG? Nie. Oficjalny pakiet @react-pdf/svg parsuje ciągi znaków SVG do drzew węzłów elementów podstawowych. Sprawdź obsługiwane elementy i ostrzeżenia, a następnie podłącz i przetestuj wynik w swoim procesie renderowania. Przykład z jawnie zdefiniowanymi komponentami w tym artykule pozwala uniknąć dodatkowego etapu parsowania.

Dlaczego środek mojego logotypu zostaje wypełniony? Sprawdź ścieżkę złożoną i jej regułę wypełnienia. Testowy emblemat używa evenodd, dzięki czemu jego wewnętrzny kwadrat pozostaje niewypełniony. Zanim zmienisz grafikę, zachowaj oryginalną geometrię oraz reguły wypełnienia i obrysu.

Czy ostry podgląd PDF dowodzi, że logotyp jest wektorowy? Nie. Sprawdź zawartość i obiekty obrazów w zapisanym PDF, a także jego wygląd. Odizolowana grafika testowa w tym poradniku nie zawierała osadzonych obrazów; ten wynik nie odnosi się automatycznie do innego logotypu.

Źródła

1. React-pdf — Svg component — Definiuje obszar wyświetlania, wymiary, viewBox i ustawienia proporcji.
2. React-pdf — Image component — Dokumentuje formy danych wejściowych PNG i JPG służących do umieszczania obrazów rastrowych.
3. React-pdf — SVG primitives — Wymienia komponenty SVG obsługiwane przez renderer.
4. React-pdf — SVG parser — Dokumentuje drzewo węzłów elementów podstawowych, konwersję atrybutów i ostrzeżenia o nieobsługiwanych elementach.

Masz logotyp tylko w PNG lub JPG? Przygotuj wstępny plik SVG za pomocą PerfectVector, porównaj jego kontury i otwory ze źródłem, a następnie dostosuj obsługiwane kształty i sprawdź zapisany PDF.