O que devo fazer se puder clicar na página do índice de um PDF, mas perder o nível após a extração?

A página do índice do PDF pode ser redirecionada normalmente no leitor, mas após ser extraída por meio de um script, a hierarquia pode ficar plana, os números das páginas podem estar mal colocados ou até mesmo o índice pode estar anormal. Esse tipo de problema é comum ao mesclar arquivos digitalizados ou arquivos com estruturas de marcadores irregulares. Se os resultados da extração forem entregues diretamente aos utilizadores a jusante, poderão ocorrer erros na segmentação e ligação da tradução.

Este artigo é destinado a desenvolvedores e equipes de documentação que precisam processar catálogos PDF em lote. Após a leitura, você poderá entender o significado do valor de retorno get_toc(), dominar as regras de verificação de níveis e números de página e saber quais situações devem ser convertidas para verificação manual. Este artigo usa uma amostra sintética para demonstrar o método de processamento, e o código foi verificado pela amostra em um ambiente isolado, mas isso não representa uma garantia de todos os arquivos reais ou efeitos do produto. Antes de processar documentos importantes, guarde os originais e revise-os de acordo com os limites e itens de aceitação do texto.

O que devo fazer se a página do índice do PDF puder ser clicada, mas a hierarquia for perdida após a extração? Conclusão de uma frase

Verifique primeiro e depois escreva: O nível do marcador deve ser verificado primeiro, o primeiro item é considerado como o primeiro nível, os níveis subsequentes não devem exceder o item anterior mais um e as entradas com números de página fora dos limites não serão escritas.

Por que o resultado da extração perde níveis?

O padrão get_toc() é a saída de uma lista de triplos [level, title, page]. Entre eles, page é o número da página física começando em 1, e level representa apenas a profundidade do aninhamento e não garante continuidade ou legalidade.

Se o PDF de origem foi gerado por uma ferramenta de mesclagem de digitalização, os problemas comuns incluem:

• Salto de nível: por exemplo, pule diretamente de 1 para 3
• Exceção de número de página: o número da página é 0 ou excede o número total de páginas
• Exceção de título: o título contém caracteres de controle

Se usado diretamente para tarefas posteriores, causará confusão nos segmentos de tradução ou falha no link. Mais insidiosamente, alguns PDFs têm uma página de índice visual, mas nenhum metadado de marcador incorporado. É normal que get_toc() retorne uma lista vazia neste momento e, em vez disso, a análise de layout de texto precisa ser usada.

Exemplo de composição independente

Veja a lista de importação para exemplos de dependências. O código constrói a entrada na memória e os registros de execução são fornecidos separadamente e não representam uma garantia de todos os arquivos reais.

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")

Regras de processamento para informações legais e ilegais

A entrada correta deve satisfazer: uma lista de triplos com níveis contínuos e números de página no intervalo [1, doc.page_count]. Por exemplo, [[1, "引言", 1], [2, "背景", 2], [1, "方法", 5]] é legal, o segundo nível aparece após o primeiro nível e está em conformidade com a sintaxe de contorno do PDF.

Entradas incorretas comuns incluem:

• O nível é 0 ou negativo
• O número da página é 0
• O número de páginas excede o número total de páginas
• O título é uma string vazia ou contém apenas caracteres de espaço em branco

Para estas situações, os métodos indicados no artigo são os seguintes:

1. Ignore entradas com números de página inválidos e registre um aviso.
2. Mantenha espaços reservados como [untitled] para títulos vazios para manter a integridade estrutural.
3. Não interrompa a análise de todo o diretório devido a um único erro.

Em relação ao caso em que o nível é inferior a 1, há duas estratégias a ter em conta: a parte resumida do exemplo defende a rejeição de níveis ilegais e não a sua correção automática, enquanto a descrição da regra no artigo é forçá-lo a 1. Por favor, decida entre os dois de acordo com o seu processo. Observe também que essas regras foram projetadas para garantir a robustez dos processos posteriores e não são requisitos obrigatórios do padrão PDF. Os testes reais descobriram que quando o número da página ultrapassa o limite, o PyMuPDF imprimirá um aviso, mas não lançará uma exceção. Portanto, a função de verificação deve filtrar ativamente e não pode confiar no comportamento da biblioteca.

📊 Comparação principal

Em diferentes situações de documentos, os resultados e métodos de processamento sugeridos de get_toc() são diferentes:

Critérios de aceitação e limites de revisão manual

A tabela a seguir concentra-se apenas na extração de metadados do catálogo PDF:

Deve-se notar que a demonstração do código apenas verifica a legalidade da estrutura, e o efeito ponta a ponta precisa ser combinado com a renderização para verificar se o salto é preciso.

🎯 Qual método é adequado para você?

Se você precisar extrair diretórios em lotes

Primeiro execute a verificação estrutural no resultado get_toc(), depois grave-o no processo subsequente e guarde o registro para revisão.

Se o seu PDF tiver visualmente um índice, mas a extração estiver vazia

Não tente get_toc() repetidamente; em vez disso, use o processamento de análise de layout de texto.

Se a sua entrada de diretório aparecer em páginas diferentes com o mesmo nome

Converta essas entradas para verificação manual e não selecione automaticamente um dos números de página.

Se você estiver enviando seu documento para um processo de tradução

Primeiro confirme se a estrutura do diretório e os números das páginas estão corretos antes de traduzir para evitar confusão de segmentação.

❓ Perguntas frequentes (FAQ)

1. Por que o número da página começa em 1, enquanto o índice da página geralmente começa em 0?

Os números das páginas dos marcadores são números de páginas físicas começando em 1, enquanto os índices de páginas em bibliotecas como PyMuPDF geralmente começam em 0. Você precisa prestar atenção a essa diferença ao converter, caso contrário, os números das páginas ficarão desalinhados.

2. Se get_toc() retornar uma lista vazia, isso significa que há algo errado com o arquivo?

incerto. Alguns PDFs possuem visualmente uma página de índice, mas não incorporam metadados de marcadores. É normal retornar uma lista vazia. Neste caso, a análise de layout de texto deve ser usada.

3. Quando o número da página ultrapassar o limite, a biblioteca reportará um erro diretamente?

Não vai. A medição real neste artigo descobriu que o PyMuPDF imprimirá um aviso, mas não lançará uma exceção quando o número da página ultrapassar o limite, portanto, a função de verificação deve filtrar ativamente.

4. Você precisa preencher as camadas intermediárias para saltos de nível (como ir diretamente de 1 para 3)?

A sugestão do artigo é manter a hierarquia original e não adicionar camadas intermediárias, pois essa estrutura ainda é legal.

📝 Resumo

A hierarquia e os números de página do diretório PDF precisam ser verificados antes do uso. A saída original de get_toc() não pode ser considerada diretamente como uma estrutura confiável. Ao encontrar ambiguidade ou nenhum marcador, mudar para o trabalho manual ou usar outros métodos em tempo hábil pode evitar erros nos processos posteriores.

Experimente agora: carregue o documento para iniciar a tradução, mantendo o layout original

Referências e próximos passos

• Documento oficial PyMuPDF.get_toc

Próxima etapa sugerida: prepare um PDF de teste contendo problemas de diretório conhecidos, execute o script de verificação acima e conte a proporção de várias anomalias. Se saltos de nível ou mudanças no número de páginas ocorrerem com frequência, considere adicionar uma etapa de reconstrução de diretório antes da tradução.

Use esta lista de verificação para tradução de documentos

Primeiro verifique a ordem das páginas, a localização da fonte e a integridade do texto e, em seguida, envie a mesma amostra dessensibilizada para o processo de tradução. Após a tradução, ainda é necessário verificar se o título, o texto e as ilustrações correspondem corretamente. Você não pode simplesmente verificar se o texto está suave.

OmniDoc fornece um portal de tradução de documentos multiformato e o site oficial apresenta funções de OCR, glossário e comparação bilíngue. Para equipes que desejam começar a trabalhar diretamente a partir de arquivos, vale a pena avaliar esse caminho com exemplos da vida real. Use arquivos dessensibilizados que você tem permissão para carregar e use os itens de verificação neste artigo para revisar os resultados. Não há nenhuma afirmação aqui de que o OmniDoc use as bibliotecas de código aberto ou algoritmos internos neste artigo, nem o exemplo substitui o teste de desempenho do produto.