Linearizzare un PDF per la visualizzazione web veloce in JavaScript (React)

Fai clic su un link a un PDF di grandi dimensioni e ottieni un riquadro vuoto. Lo spinner gira, arrivano alcuni megabyte e solo allora compare la prima pagina. Il file era a posto, la rete era a posto: il documento era semplicemente scritto in un ordine che costringe il visualizzatore ad attendere l'intero file prima di poter disegnare qualsiasi cosa. Questo è il problema che la linearizzazione risolve, ed è una correzione strutturale, non una correzione di dimensione: gli stessi byte, disposti in modo che le parti necessarie per renderizzare la prima pagina si trovino all'inizio.

Questo articolo linearizza un PDF nel browser con Spire.PDF for JavaScript. La libreria funziona su WebAssembly e opera sul documento tramite un file system virtuale (VFS), così un file può essere ristrutturato sulla macchina dell'utente senza essere inviato attraverso un servizio di ottimizzazione remoto.

Le istruzioni di configurazione si trovano in Integrare Spire.PDF for JavaScript in un progetto React. L'esempio seguente presuppone che il pacchetto sia installato e che il modulo WebAssembly sia stato inizializzato.

Cosa significa realmente la visualizzazione web veloce

Un PDF è un contenitore, e i suoi oggetti sono memorizzati nell'ordine in cui sono stati scritti da qualunque cosa lo abbia prodotto. Un visualizzatore, d'altra parte, ha bisogno di un piccolo insieme specifico — il catalogo del documento, l'albero delle pagine e gli oggetti che costituiscono la prima pagina — prima di poter disegnare qualsiasi cosa. Se quegli oggetti si trovano vicino alla fine del file, dietro una grande immagine incorporata, il visualizzatore non ha altra scelta che continuare a scaricare finché non li raggiunge.

Visualizzazione web veloce è il nome rivolto al consumatore di un PDF linearizzato: uno la cui disposizione interna colloca gli oggetti della prima pagina vicino all'inizio, così un client che supporta le richieste HTTP byte-range può richiedere solo quei byte, renderizzare immediatamente la prima pagina e recuperare il resto in background. Il lettore vede il contenuto mentre il download continua, invece di fissare un riquadro vuoto.

La conseguenza pratica è che due file di dimensioni identiche possono risultare completamente diversi all'apertura. Stesso numero di pagine, stesse immagini, stesso testo — diverso tempo al primo rendering.

Come la linearizzazione riorganizza un file

La linearizzazione riscrive il modo in cui il file è disposto senza toccare ciò che contiene:

• Gli oggetti da cui dipende la prima pagina vengono spostati all'inizio del file.
• Un dizionario di linearizzazione viene scritto vicino all'inizio, così un client può scoprire la disposizione prima di aver letto l'intero documento.
• Una tabella di suggerimenti registra dove si trovano gli oggetti di ogni pagina, ed è ciò che consente a un lettore di saltare avanti a una pagina arbitraria con una richiesta byte-range.
• Le informazioni di riferimento incrociato vengono posizionate in modo da poter essere lette presto anziché alla fine del file.

Tutto ciò che un lettore vede effettivamente — testo, immagini, font, grafica vettoriale, link, annotazioni, segnalibri, metadati — viene mantenuto invariato. Le parole sulla pagina sono le stesse parole nelle stesse posizioni. Ciò che è cambiato è l'ordinamento dei byte, non il contenuto. Ecco perché un documento linearizzato è impossibile da individuare guardandolo: apri l'originale e il risultato affiancati e sono indistinguibili, perché la differenza si manifesta solo in quando le parti possono essere lette.

Linearizzare un documento nel browser

L'utilizzo rispecchia gli altri convertitori della libreria: passa il file di input a PdfToLinearizedPdfConverter, poi chiama ToLinearizedPdf per scrivere il documento ristrutturato.

function App() {
  const convertToLinearized = async () => {
    // Get the Spire.PDF WASM module
    const pdfModule = window.wasmModule?.spirepdf;

    // Check whether the module is ready
    if (!pdfModule) {
      alert('Spire.PDF is not ready yet');
      return;
    }

    // Load the PDF file to be converted into the VFS
    const inputFileName = 'Business_Data_Overview.pdf';
    await window.spire.FetchFileToVFS(inputFileName, "", `${process.env.PUBLIC_URL}/data/`);

    // Define the output file name
    const outputFileName = 'LinearizedDocument.pdf';

    // Construct the linearization converter from the input file and write out the linearized document
    const converter = new pdfModule.PdfToLinearizedPdfConverter({ filePath: inputFileName });
    converter.ToLinearizedPdf({ filePath: outputFileName });
    converter.Dispose();

    // Read the generated file from the VFS and trigger the download
    const fileArray = window.dotnetRuntime.Module.FS.readFile(outputFileName);
    const blob = new Blob([fileArray], { type: 'application/pdf' });
    const url = URL.createObjectURL(blob);
    const a = document.createElement('a');
    a.href = url;
    a.download = outputFileName;
    a.click();
    URL.revokeObjectURL(url);
  };

  return (
    <div style={{ textAlign: 'center', height: '300px' }}>
      <h1>Linearize a PDF</h1>
      <button onClick={convertToLinearized}>
        Start Converting
      </button>
    </div>
  );
}

export default App;

ToLinearizedPdf scrive un nuovo file, quindi l'input rimane nel VFS e l'originale è disponibile per il confronto. Nulla nella chiamata dipende dal contenuto del documento: un report, un manuale e un archivio scansionato passano tutti attraverso gli stessi due membri.

Il documento linearizzato non appare diverso sulla pagina, il cambiamento è all'interno della struttura del file

Linearizzare o comprimere

Questi due passaggi vengono abitualmente confusi perché entrambi sono descritti come "ottimizzare un PDF", ma rispondono a domande diverse.

Un file può aver bisogno di entrambi, e l'ordine è importante. La compressione riscrive il documento, e qualsiasi passaggio che riscrive un PDF elimina la disposizione linearizzata: quindi se vuoi entrambi, comprimi prima e linearizza per ultimo, così la struttura linearizzata è lo stato finale del file.

Quando vale la pena linearizzare

La linearizzazione conviene in una situazione specifica: un documento abbastanza grande da rendere il download percepibile, distribuito via HTTP a un visualizzatore che supporta le richieste range.

• Manuali, cataloghi e report lunghi pubblicati da un sito. Questo è il caso classico — decine di megabyte, aperti da un link, con lettori che vogliono saltare direttamente a un capitolo.
• Lettori mobili su connessioni lente. La prima pagina appare dai primi byte richiesti, quindi il tempo di caricamento percepito diminuisce anche quando il download totale non cambia.
• Documenti che i lettori di solito aprono dal centro. Le richieste byte-range consentono a un client di recuperare prima una pagina successiva, cosa possibile solo con la tabella di suggerimenti che un file linearizzato contiene.

In altri casi non ne vale la pena. Un file aperto da disco locale non viene recuperato via HTTP, quindi non c'è alcuna richiesta range da sfruttare. Un documento breve viene già renderizzato prima che la differenza possa essere percepita. E un flusso di lavoro di stampa interno non esegue streaming né salti: vuole l'intero documento, in ordine, tutto in una volta.

Verificare che l'output sia linearizzato

Poiché le pagine visibili sono identiche, "sembra corretto" non dimostra nulla. Il cambiamento è nel file, quindi la verifica deve leggere il file.

Un PDF linearizzato contiene un dizionario di linearizzazione vicino all'inizio dei suoi byte, e il marcatore è testo in chiaro, quindi le prime centinaia di byte dell'output sono sufficienti per confermarlo. Sia l'input che l'output sono nel VFS, il che rende il confronto questione di un paio di letture di file:

// Read the head of the file and look for the linearization marker
const bytes = window.dotnetRuntime.Module.FS.readFile(outputFileName);
const head = new TextDecoder('latin1').decode(bytes.slice(0, 1024));
const linearized = head.includes('/Linearized');

Si tratta di una protezione utile per una pipeline: converti un documento, poi verifica che il marcatore sia presente prima di passare il file. Se manca, il file è stato riscritto da qualcosa a valle dopo la linearizzazione — ricorda che qualsiasi nuovo salvataggio, inclusa una fase di compressione, elimina la disposizione linearizzata.

Problemi comuni

La prima pagina richiede comunque tempo per apparire. Controlla come viene distribuito il file. La linearizzazione aiuta solo quando il client può richiedere parti del file — servito via HTTP con supporto range. Se l'intero file viene recuperato in una volta, o se il documento è breve, il passaggio non può cambiare ciò che stai vedendo.

L'output presenta una riga di testo in più. Una build non licenziata aggiunge al documento Evaluation Warning : The document was created with Spire.PDF for JavaScript., una volta per ogni chiamata di conversione. Una licenza temporanea di 30 giorni la rimuove insieme ai limiti funzionali — contatta il reparto vendite per ottenerla.

La dimensione del file non è diminuita. Di solito non diminuirà. La linearizzazione riordina i byte esistenti; non ne rimuove nessuno. Se la dimensione è il problema, quello è un lavoro di compressione, non di linearizzazione.

Non succede nulla al primo clic. Il modulo WebAssembly viene caricato in modo asincrono. if (!pdfModule) return; è la protezione nell'esempio; in un'interfaccia reale, disabilita il controllo finché il modulo non è pronto invece di mostrare un avviso.

Domande frequenti

Linearizzare un PDF ne modifica il contenuto o la qualità? No. Testo, immagini, font, formattazione, link e metadati vengono mantenuti esattamente; cambia solo l'ordinamento interno dei byte. Le pagine appaiono e si comportano in modo identico.

La linearizzazione è la stessa cosa della compressione di un PDF? No. La compressione rimuove la ridondanza per produrre meno byte; la linearizzazione riorganizza i byte che già possiede in modo che la prima pagina possa essere letta prima. Una mira alla dimensione del download, l'altra al tempo al primo rendering.

È utile se il file viene aperto dal disco locale? Raramente. Il vantaggio deriva dallo streaming via HTTP con richieste byte-range, quindi un documento aperto da un percorso locale non ha nulla da guadagnare.

Un file linearizzato rimarrà linearizzato? Solo finché qualcosa non lo riscrive. Qualsiasi strumento che risalva il documento — una fase di compressione, una modifica, un'unione — elimina la disposizione linearizzata, quindi la linearizzazione dovrebbe essere l'ultimo passaggio della pipeline.

Funziona su un file cifrato o protetto da password? La cifratura è una questione separata dalla disposizione. Decifra prima il documento e lascia che il convertitore lavori su un file già leggibile.

Posso convertire più file contemporaneamente? Sì. Il convertitore è un'operazione su singolo file, quindi un batch è un ciclo — gli stessi due membri, con un nome di output distinto per ogni input.

Vedi anche

• Come convertire un PDF in scala di grigi in JavaScript (React)
• Ridurre la dimensione dei file PDF: immagini, font e flussi di contenuto in JavaScript (React)
• Come ottenere il numero di pagine di un PDF in JavaScript (React)
• Integrare Spire.PDF for JavaScript in un progetto React
• Pagina del prodotto Spire.PDF for JavaScript