Linearizar un PDF para visualización web rápida en JavaScript (React)

Haces clic en un enlace a un PDF grande y obtienes un marco en blanco. El indicador de carga gira, llegan unos cuantos megabytes y solo entonces aparece la primera página. El archivo estaba bien, la red estaba bien; el documento simplemente se escribió en un orden que obliga al visor a esperar a que llegue todo antes de poder dibujar algo. Ese es el problema que resuelve la linealización, y es una solución estructural, no una solución de tamaño: los mismos bytes, organizados de modo que las partes necesarias para renderizar la primera página queden al principio.

En este artículo se linealiza un PDF en el navegador con Spire.PDF for JavaScript. La biblioteca se ejecuta sobre WebAssembly y trabaja con el documento a través de un sistema de archivos virtual (VFS), por lo que un archivo puede reestructurarse en la máquina del usuario sin tener que pasar por un servicio de optimización remoto.

Las instrucciones de configuración se encuentran en Integración de Spire.PDF for JavaScript en un proyecto de React. El ejemplo siguiente supone que el paquete está instalado y que el módulo WebAssembly se ha inicializado.

Qué significa realmente la vista web rápida

Un PDF es un contenedor, y sus objetos se almacenan en el orden en que los escribió quien lo produjo. Un visor, en cambio, necesita un conjunto pequeño y específico —el catálogo del documento, el árbol de páginas y los objetos que respaldan la primera página— antes de poder dibujar nada. Si esos objetos están cerca del final del archivo, detrás de una imagen incrustada grande, el visor no tiene más remedio que seguir descargando hasta llegar a ellos.

Vista web rápida es el nombre que se da al usuario para un PDF linealizado: aquel cuya disposición interna coloca los objetos de la primera página cerca del principio, de modo que un cliente que admite solicitudes de rango de bytes HTTP puede pedir solo esos bytes, renderizar la primera página de inmediato y obtener el resto en segundo plano. El lector ve contenido mientras continúa la descarga, en lugar de mirar fijamente un marco vacío.

La consecuencia práctica es que dos archivos de idéntico tamaño pueden sentirse completamente distintos al abrirlos. La misma cantidad de páginas, las mismas imágenes, el mismo texto: distinto tiempo hasta el primer pintado.

Cómo la linealización reorganiza un archivo

La linealización reescribe cómo se dispone el archivo sin tocar lo que contiene:

• Los objetos de los que depende la primera página se trasladan al principio del archivo.
• Se escribe un diccionario de linealización cerca del inicio para que un cliente pueda descubrir la disposición antes de haber leído todo el documento.
• Una tabla de indicaciones registra dónde se encuentran los objetos de cada página, que es lo que permite a un lector saltar hacia delante a una página arbitraria con una solicitud de rango de bytes.
• La información de referencias cruzadas se coloca de modo que pueda leerse pronto en lugar de al final del archivo.

Todo lo que un lector ve realmente —texto, imágenes, fuentes, gráficos vectoriales, enlaces, anotaciones, marcadores, metadatos— se traslada sin cambios. Las palabras de la página son las mismas palabras en los mismos lugares. Lo que cambió es el orden de los bytes, no el contenido. Por eso es imposible detectar un documento linealizado a simple vista: abre el original y la salida uno al lado del otro y son indistinguibles, porque la diferencia solo se manifiesta en cuándo pueden leerse las piezas.

Linealizar un documento en el navegador

El uso es similar al de los demás convertidores de la biblioteca: entrega el archivo de entrada a PdfToLinearizedPdfConverter y luego llama a ToLinearizedPdf para escribir el documento reestructurado.

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 escribe un archivo nuevo, por lo que la entrada permanece en el VFS y el original queda disponible para comparación. Nada de la llamada depende del contenido del documento: un informe, un manual y un archivo escaneado pasan todos por los mismos dos miembros.

El documento linealizado no se ve diferente en la página; el cambio está dentro de la estructura del archivo

Linealizar o comprimir

Estas dos operaciones se confunden con frecuencia porque a ambas se las describe como "optimizar un PDF", pero responden a preguntas diferentes.

Un archivo puede necesitar ambas, y el orden importa. La compresión reescribe el documento, y cualquier operación que reescriba un PDF descarta la disposición linealizada; así que si quieres ambas, comprime primero y linealiza al final, de modo que la estructura linealizada sea el estado final del archivo.

Cuándo vale la pena la linealización

La linealización vale la pena en un contexto específico: un documento lo bastante grande como para que la descarga sea perceptible, entregado por HTTP a un visor que admite solicitudes de rango.

• Manuales, catálogos e informes largos servidos desde un sitio. Este es el caso clásico: decenas de megabytes, abiertos desde un enlace, con lectores que quieren saltar directamente a un capítulo.
• Lectores móviles con conexiones lentas. La primera página aparece con los primeros bytes solicitados, por lo que el tiempo de carga percibido disminuye aunque la descarga total no lo haga.
• Documentos en los que los lectores suelen entrar por el medio. Las solicitudes de rango de bytes permiten que un cliente obtenga primero una página posterior, lo cual solo es posible con la tabla de indicaciones que lleva un archivo linealizado.

No vale la pena en otros casos. Un archivo abierto desde el disco local no se obtiene por HTTP, así que no hay ninguna solicitud de rango de la que aprovecharse. Un documento corto ya se renderiza antes de que la diferencia pudiera percibirse. Y un flujo de trabajo interno de impresión ni transmite ni salta: quiere el documento completo, en orden, de una vez.

Confirmar que la salida está linealizada

Como las páginas visibles son idénticas, "se ve bien" no demuestra nada. El cambio está en el archivo, así que la comprobación tiene que leer el archivo.

Un PDF linealizado lleva un diccionario de linealización cerca del inicio de sus bytes, y el marcador es texto plano, por lo que los primeros cientos de bytes de la salida bastan para confirmarlo. Tanto la entrada como la salida están en el VFS, lo que convierte la comparación en un par de lecturas de archivo:

// 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');

Eso es una protección útil para una canalización: convierte un documento y luego verifica que el marcador esté presente antes de pasar el archivo. Si falta, el archivo fue reescrito por algo posterior a la linealización; recuerda que cualquier reguardado, incluida una operación de compresión, descarta la disposición linealizada.

Problemas comunes

La primera página sigue tardando en aparecer. Comprueba cómo se entrega el archivo. La linealización solo ayuda cuando el cliente puede solicitar partes del archivo: servido por HTTP con soporte de rangos. Si el archivo completo se obtiene de una vez, o si el documento es corto, la operación no puede cambiar lo que estás viendo.

La salida tiene una línea de texto adicional. Una compilación sin licencia añade Evaluation Warning : The document was created with Spire.PDF for JavaScript. al documento, una vez por cada llamada de conversión. Una licencia temporal de 30 días la elimina junto con los límites funcionales; contacta con ventas para obtener una.

El tamaño del archivo no disminuyó. Normalmente no lo hará. La linealización reordena los bytes existentes; no elimina ninguno. Si el tamaño es el problema, eso es trabajo de compresión, no de linealización.

No ocurre nada en el primer clic. El módulo WebAssembly se carga de forma asíncrona. if (!pdfModule) return; es la protección en el ejemplo; en una interfaz real, deshabilita el control hasta que el módulo esté listo en lugar de mostrar una alerta.

Preguntas frecuentes

¿Linealizar un PDF cambia su contenido o su calidad? No. El texto, las imágenes, las fuentes, el formato, los enlaces y los metadatos se trasladan exactamente igual; solo cambia el orden interno de los bytes. Las páginas se ven y se comportan de forma idéntica.

¿Es la linealización lo mismo que comprimir un PDF? No. Comprimir elimina redundancia para producir menos bytes; linealizar reorganiza los bytes que ya tiene para que la primera página pueda leerse antes. Una apunta al tamaño de descarga, la otra al tiempo hasta el primer renderizado.

¿Ayuda si el archivo se abre desde el disco local? Rara vez. El beneficio proviene de la transmisión por HTTP con solicitudes de rango de bytes, así que un documento abierto desde una ruta local no tiene nada que ganar.

¿Un archivo linealizado seguirá estando linealizado? Solo hasta que algo lo reescriba. Cualquier herramienta que vuelva a guardar el documento —una operación de compresión, una edición, una combinación— descarta la disposición linealizada, por lo que la linealización debería ser el último paso de la canalización.

¿Funciona con un archivo cifrado o protegido con contraseña? El cifrado es una cuestión aparte de la disposición. Descifra primero el documento y deja que el convertidor trabaje con un archivo ya legible.

¿Puedo convertir varios archivos a la vez? Sí. El convertidor es una operación de un solo archivo, así que un lote es un bucle: los mismos dos miembros, con un nombre de salida distinto para cada entrada.

Véase también

• Cómo convertir PDF a escala de grises en JavaScript (React)
• Reducir el tamaño de archivo PDF: imágenes, fuentes y flujos de contenido en JavaScript (React)
• Cómo obtener el número de páginas de un PDF en JavaScript (React)
• Integración de Spire.PDF for JavaScript en un proyecto de React
• Página del producto Spire.PDF for JavaScript