Un singolo numero intero — il numero totale di pagine di un PDF — è alla base di un numero sorprendente di decisioni concrete: limiti di caricamento, stima della carta per la stampa, operazioni di suddivisione, barre di avanzamento. La maggior parte delle librerie di rendering PDF si limita a disegnare le pagine e non espone un semplice conteggio, e inviare il file a un backend solo per leggere il numero di pagine comporta latenza e problemi di privacy.
Spire.PDF for JavaScript carica e analizza i documenti PDF direttamente nel browser tramite WebAssembly, così il file non lascia mai il client. Il numero di pagine è disponibile come singola proprietà — nessun ciclo, nessun round-trip verso il server, nessuna soluzione alternativa basata sul rendering. Questo articolo illustra come recuperare tale conteggio e tre aspetti pratici: distinguere il numero di pagine fisiche dalle etichette visualizzate, gestire i file protetti da password ed evitare errori di off-by-one durante l'iterazione sulle pagine.
Per l'installazione e la configurazione del progetto, consulta Integrare Spire.PDF for JavaScript in un progetto React. Gli esempi seguenti presuppongono che Spire.PDF sia installato e che il modulo WebAssembly sia stato inizializzato.
Ottenere il numero di pagine di un documento PDF
Dopo che un oggetto PdfDocument ha caricato un file, la sua proprietà Pages espone la raccolta delle pagine e la proprietà Count di tale raccolta restituisce il numero totale di pagine. Non è necessario scorrere le pagine una per una — il conteggio è disponibile subito dopo il caricamento.
Il seguente componente React mostra l'intero flusso di lavoro: recupera il PDF nel file system virtuale, crea un PdfDocument, carica il file, legge Pages.Count e scrive il risultato in un file di testo scaricabile.
function App() {
const getPageCount = 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 counted into the VFS
const inputFileName = 'Multipage_Document.pdf';
await window.spire.FetchFileToVFS(inputFileName, '', `${process.env.PUBLIC_URL}/data/`);
// Create a PdfDocument object and load the PDF document
const doc = new pdfModule.PdfDocument();
doc.LoadFromFile(inputFileName);
// Pages is the document's page collection; Count is the total page count
const pageCount = doc.Pages.Count;
// Write the result to the VFS
const outputFileName = 'PageCountResult.txt';
const report = `Document: ${inputFileName}\r\nTotal pages: ${pageCount}`;
window.dotnetRuntime.Module.FS.writeFile(outputFileName, report);
doc.Close();
// 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: 'text/plain' });
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>Get PDF Page Count</h1>
<button onClick={getPageCount}>
Count Pages
</button>
</div>
);
}
export default App;
Il risultato viene scritto in un file di testo che registra il numero totale di pagine del documento:
In un'applicazione di produzione, in genere useresti direttamente il valore pageCount invece di scriverlo in un file — ad esempio per convalidare un caricamento, impostare il limite di un ciclo o mostrare metadati nell'interfaccia utente. L'approccio con output su file mostrato qui è utile per i test e per scopi dimostrativi.
Numero di pagine fisiche vs etichette di pagina
Ecco una situazione che coglie di sorpresa gli sviluppatori: leggi Pages.Count e ottieni 12, ma il lettore PDF sullo schermo dell'utente mostra l'ultima pagina come "pagina 8". Quale numero è corretto?
Lo sono entrambi — misurano cose diverse. Pages.Count restituisce il numero di pagine fisiche del documento, in modo semplice e diretto. Il numero visualizzato da un lettore, invece, deriva dalle etichette di pagina (la voce /PageLabels nella specifica PDF). Le etichette di pagina sono un livello di presentazione che gli editori usano per controllare come i numeri di pagina appaiono al lettore. Un editore di libri potrebbe escludere la copertina dalla numerazione, usare numeri romani (i, ii, iii) per le pagine introduttive e ricominciare il corpo da 1. Dopo tutto questo, la quinta pagina fisica potrebbe apparire come iii o 1 a seconda di come sono configurate le etichette.
Questa distinzione è importante quando l'applicazione deve mostrare agli utenti un numero di pagina che corrisponda a quello che vedono nel loro lettore. Se visualizzi Pages.Count come "pagina corrente", non coinciderà con la numerazione del lettore ogni volta che sono in gioco le etichette di pagina.
Quando ti serve l'etichetta visualizzata anziché l'indice fisico, leggi la proprietà PageLabel sul singolo oggetto pagina:
// What label the 5th physical page displays in a reader
const page = doc.Pages.get_Item(4);
console.log(page.PageLabel);
Nota l'indice a base zero: get_Item(4) recupera la quinta pagina fisica. Quando il documento non ha etichette di pagina configurate, PageLabel restituisce una stringa vuota. In questo caso comune, il numero visualizzato corrisponde all'ordine fisico delle pagine, quindi Count è il valore che ti serve.
Un modo pratico per gestire entrambi gli scenari è controllare prima PageLabel e ricorrere all'indice fisico quando è vuoto. In questo modo la tua applicazione ottiene un numero di pagina che corrisponde sempre a ciò che vede l'utente, indipendentemente dal fatto che il documento utilizzi etichette personalizzate.
Contare le pagine in un PDF crittografato
Molti PDF negli ambienti aziendali sono protetti da una password di apertura — una misura di sicurezza che impedisce la lettura del documento senza le credenziali corrette. Se provi a caricare un file di questo tipo con una semplice chiamata LoadFromFile, il runtime WASM genera un errore prima ancora di arrivare a Pages.Count:
Impossibile aprire un documento crittografato. La password non è valida.
Ciò accade al momento del caricamento, non nel punto in cui leggi il numero di pagine. Il contenuto del documento — inclusa la sua struttura di pagine — è crittografato, quindi la libreria non può analizzarlo senza la password. Non c'è modo di contare le pagine senza prima sbloccare il documento.
La soluzione è semplice: passa la password di apertura come secondo argomento a LoadFromFile. Una volta sbloccato il documento, il numero di pagine è disponibile esattamente come per un file non crittografato:
// The second argument is the open password
doc.LoadFromFile(inputFileName, 'spire123');
const pageCount = doc.Pages.Count;
In un'applicazione reale, in genere raccoglieresti la password dall'utente tramite un campo di un modulo e la passeresti dinamicamente invece di inserirla nel codice. Se l'utente inserisce la password sbagliata, viene generato lo stesso errore — quindi racchiudere la chiamata LoadFromFile in un blocco try/catch e mostrare un messaggio amichevole di "password errata" è una buona pratica.
C'è un'altra cosa da notare: questa password è la password di apertura (chiamata anche password utente), che controlla chi può visualizzare il documento. Un PDF può avere anche una password di autorizzazione (password proprietario) che limita la modifica, la stampa o la copia senza bloccare la visualizzazione. Ai fini del conteggio delle pagine, è rilevante solo la password di apertura — una volta aperto il documento, Pages.Count funziona indipendentemente dalle restrizioni di autorizzazione.
Usare il numero di pagine come limite di un ciclo
Una volta ottenuto il numero di pagine, un passo successivo naturale è scorrere ogni pagina — per estrarre testo, generare anteprime, dividere il documento o applicare qualche trasformazione. È qui che compare un bug sottile ma comune: usare Count come limite superiore inclusivo.
La raccolta Pages è a base zero, il che significa che gli indici validi vanno da 0 a Count - 1. Se la condizione del ciclo è scritta con <= invece di <, l'iterazione finale tenta di accedere alla pagina con indice Count, che non esiste. Il runtime WASM incapsula l'eccezione .NET sottostante ArgumentOutOfRangeException come Error JavaScript con un messaggio simile a:
ArgumentOutOfRange_IndexMustBeLess Arg_ParamName_Name, index
Poiché la proprietà name dell'errore è solo il generico Error, non puoi distinguerlo dal solo nome — devi confrontare la stringa del messaggio se vuoi gestirlo in modo specifico.
Il ciclo corretto usa < in modo che l'ultimo indice a cui si accede sia Count - 1:
// The upper bound is Count - 1, so use < rather than <=
for (let i = 0; i < doc.Pages.Count; i++) {
const page = doc.Pages.get_Item(i);
}
Questo schema di off-by-one è una delle fonti più frequenti di errori di runtime quando si lavora con raccolte di pagine. È facile non accorgersene durante i test se i documenti di esempio hanno solo una o due pagine — l'errore emerge solo all'iterazione finale, quindi un documento di una sola pagina non lo attiverà affatto. Testa sempre la logica del ciclo con un documento che abbia almeno tre pagine per assicurarti che la condizione al contorno sia corretta.
Vedi anche
- Integrare Spire.PDF for JavaScript in un progetto React — Guida alla configurazione per installare Spire.PDF e inizializzare il modulo WebAssembly in un'app React.
- Pagina del prodotto Spire.PDF for JavaScript — Panoramica delle funzionalità, delle operazioni supportate e delle capacità di elaborazione PDF basata su browser.
- spire.pdf su npm — Pagina del pacchetto per installare la libreria tramite npm.