¿Qué debo hacer si puedo hacer clic en la página de la tabla de contenido de un PDF pero pierdo el nivel después de la extracción?

La página de índice del PDF se puede redirigir normalmente en el lector, pero después de extraerla mediante un script, la jerarquía puede ser plana, los números de página pueden estar mal colocados o incluso el índice puede ser anormal. Este tipo de problema es común al combinar archivos escaneados o archivos con estructuras de marcadores irregulares. Si los resultados de la extracción se entregan directamente a los usuarios intermedios, pueden producirse errores en la segmentación y la vinculación de la traducción.

Este artículo está dirigido a desarrolladores y equipos de documentación que necesitan procesar catálogos en PDF por lotes. Después de leer, podrá comprender el significado del valor de retorno de get_toc(), dominar las reglas de verificación de niveles y números de página y saber qué situaciones deben convertirse a verificación manual. Este artículo utiliza una muestra sintética para demostrar el método de procesamiento, y la muestra ha verificado el código en un entorno aislado, pero esto no representa una garantía de todos los archivos o efectos del producto reales. Antes de procesar documentos importantes, conserve los originales y revíselos de acuerdo con los límites y elementos de aceptación del texto.

¿Qué debo hacer si se puede hacer clic en la página de la tabla de contenido del PDF, pero la jerarquía se pierde después de la extracción? Conclusión de una frase

Verifique primero, luego escriba: primero se debe verificar el nivel del marcador, el primer elemento se considera el primer nivel, los niveles posteriores no deben exceder el elemento anterior más uno y no se escribirán entradas con números de página fuera de los límites.

¿Por qué el resultado de la extracción pierde niveles?

get_toc() por defecto genera una lista de tripletas [level, title, page]. Entre ellos, page es el número de página física a partir de 1, y level solo representa la profundidad de anidamiento y no garantiza continuidad ni legalidad.

Si el PDF de origen fue generado por una herramienta de combinación de escaneo, los problemas comunes incluyen:

• Salto de nivel: por ejemplo, salta directamente del 1 al 3
• Excepción del número de página: el número de página es 0 o excede el número total de páginas
• Excepción de título: el título contiene caracteres de control.

Si se usa directamente para tareas posteriores, causará confusión en los segmentos de traducción o fallas en el enlace. Lo que es más insidioso es que algunos archivos PDF tienen una página de índice visual pero no tienen metadatos de marcadores incrustados. Es normal que get_toc() devuelva una lista vacía en este momento y, en su lugar, es necesario utilizar el análisis de diseño de texto.

Ejemplo de composición autónoma

Consulte la lista de importación, por ejemplo, dependencias. El código construye la entrada en la memoria y los registros de ejecución se proporcionan por separado y no representan una garantía de todos los archivos reales.

import pymupdf
def validate(rows, pages):
    previous = 0
    for level, title, page in rows:
        if type(level) is not int or level < 1 or level > previous + 1:
            raise ValueError("invalid hierarchy")
        if type(page) is not int or not 1 <= page <= pages:
            raise ValueError("invalid destination")
        if not isinstance(title, str) or not title.strip():
            raise ValueError("empty title")
        previous = level
    return rows
with pymupdf.open() as doc:
    for _ in range(3):
        doc.new_page()
    rows = [[1, "Chapter", 1], [2, "Section", 2], [1, "Appendix", 3]]
    doc.set_toc(validate(rows, doc.page_count))
    assert doc.get_toc() == rows
    assert len(doc.get_toc()) == 3
    for bad in [[[2, "Bad", 1]], [[1, "Bad", 99]], [[1, "", 1]]]:
        try:
            validate(bad, doc.page_count)
        except ValueError:
            pass
        else:
            raise AssertionError("invalid outline accepted")

Reglas de procesamiento para entradas legales e ilegales

La entrada correcta debe satisfacer: una lista de tripletas con niveles continuos y números de página en el rango [1, doc.page_count]. Por ejemplo, [[1, "引言", 1], [2, "背景", 2], [1, "方法", 5]] es legal, el segundo nivel aparece después del primer nivel y se ajusta a la sintaxis del esquema PDF.

Las entradas incorrectas comunes incluyen:

• El nivel es 0 o negativo
• El número de página es 0
• El número de páginas supera el número total de páginas.
• El título es una cadena vacía o contiene sólo espacios en blanco.

Para estas situaciones, los métodos indicados en el artículo son los siguientes:

1. Omita las entradas con números de página no válidos y registre una advertencia.
2. Mantenga marcadores de posición como [untitled] para títulos vacíos para mantener la integridad estructural.
3. No interrumpa el análisis de todo el directorio debido a un solo error.

Con respecto al caso en el que el nivel es menor que 1, hay dos estrategias a tener en cuenta: la parte resumida del ejemplo aboga por rechazar los niveles ilegales y no corregirlos automáticamente, mientras que la descripción de la regla en el artículo es forzarlo a 1. Decida entre los dos según su proceso. Tenga en cuenta también que estas reglas están diseñadas para garantizar la solidez de los procesos posteriores y no son requisitos obligatorios del estándar PDF. Las pruebas reales encontraron que cuando el número de página cruza el límite, PyMuPDF imprimirá una advertencia pero no generará una excepción. Por lo tanto, la función de verificación debe filtrar activamente y no puede depender del comportamiento de la biblioteca.

📊 Comparación central

En diferentes situaciones de documentos, los resultados y los métodos de procesamiento sugeridos de get_toc() son diferentes:

Criterios de aceptación y límites de revisión manual

La siguiente tabla solo se centra en la extracción de metadatos del catálogo PDF:

Cabe señalar que la demostración del código solo verifica la legalidad de la estructura y el efecto de extremo a extremo debe combinarse con la representación para verificar si el salto es preciso.

🎯 ¿Qué método es el adecuado para ti?

Si necesita extraer directorios en lotes

Primero realice una verificación estructural en el resultado de get_toc(), luego escríbalo en el proceso posterior y conserve el registro para su revisión.

Si tu PDF tiene visualmente una tabla de contenido pero la extracción está vacía

No vuelva a intentar get_toc() repetidamente; en su lugar, utilice el procesamiento de análisis de diseño de texto.

Si la entrada de su directorio aparece en diferentes páginas con el mismo nombre

Convierta estas entradas a verificación manual y no seleccione automáticamente uno de los números de página.

Si estás enviando tu documento a un proceso de traducción

Primero confirme que la estructura del directorio y los números de página sean correctos antes de traducir para evitar confusiones en la segmentación.

❓ Preguntas frecuentes (FAQ)

1. ¿Por qué el número de página comienza desde 1, mientras que el índice de página generalmente comienza desde 0?

Los números de página de los marcadores son números de páginas físicas que comienzan en 1, mientras que los índices de páginas en bibliotecas como PyMuPDF generalmente comienzan en 0. Debe prestar atención a esta diferencia al realizar la conversión; de lo contrario, los números de página estarán desalineados.

2. ¿Significa que hay algún problema con el archivo si get_toc() devuelve una lista vacía?

incierto. Algunos archivos PDF tienen visualmente una página de índice, pero no incorporan metadatos de marcadores. Es normal devolver una lista vacía. En este caso, se debe utilizar el análisis del diseño del texto.

3. Cuando el número de página cruce el límite, ¿la biblioteca informará directamente un error?

No. La medición real en este artículo encontró que PyMuPDF imprimirá una advertencia pero no generará una excepción cuando el número de página cruce el límite, por lo que la función de verificación debe filtrar activamente.

4. ¿Necesitas rellenar las capas intermedias para los saltos de nivel (como pasar directamente del 1 al 3)?

La sugerencia del artículo es mantener la jerarquía original y no agregar capas intermedias, porque esta estructura aún es legal.

📝 Resumen

Es necesario verificar la jerarquía y los números de página del directorio PDF antes de su uso. El resultado original de get_toc() no puede considerarse directamente como una estructura confiable. Cuando encuentre ambigüedad o no tenga marcadores, cambiar al trabajo manual o utilizar otros métodos de manera oportuna puede evitar errores en los procesos posteriores.

Pruébelo ahora: cargue el documento para comenzar la traducción, conservando el diseño original

Referencias y próximos pasos

• Documento oficial PyMuPDF.get_toc

Siguiente paso sugerido: preparar un PDF de prueba que contenga problemas de directorio conocidos, ejecutar el script de verificación anterior y contar la proporción de varias anomalías. Si se producen saltos de nivel o cambios de número de página con frecuencia, considere agregar un paso de reconstrucción del directorio antes de la traducción.

Utilice esta lista de verificación para la traducción de documentos

Primero verifique el orden de las páginas, la ubicación de origen y la integridad del texto, y luego envíe la misma muestra insensibilizada al proceso de traducción. Después de la traducción, aún deberás comprobar si el título, el texto y las ilustraciones corresponden correctamente. No puedes simplemente comprobar si el texto es fluido.

OmniDoc proporciona un portal de traducción de documentos multiformato y el sitio web oficial presenta funciones de OCR, glosario y comparación bilingüe. Para los equipos que buscan comenzar a trabajar directamente desde archivos, este es un camino que vale la pena evaluar con ejemplos de la vida real. Utilice archivos no sensibles que tenga permiso para cargar y utilice los elementos de verificación de este artículo para revisar los resultados. Aquí no se afirma que OmniDoc utilice las bibliotecas de código abierto o los algoritmos internos de este artículo, ni el ejemplo reemplaza las pruebas de rendimiento del producto.