Como adicionar marcadores e estrutura de tópicos em um PDF usando Java

O que preciso antes de começar?

Antes de implementar marcadores de PDF, confirme que o IronPDF está configurado no seu projeto Java. A biblioteca requer Java 8 ou superior e integra-se através de Maven ou Gradle. Adicione a dependência do IronPDF ao arquivo de build do seu projeto. Para instruções detalhadas de configuração, consulte a Visão Geral de Início Rápido.

Uma chave de licença válida é necessária para uso em desenvolvimento e produção. Defina a chave de licença no início da sua aplicação antes de chamar qualquer método do IronPDF. Para informações sobre opções de licenciamento, visite o guia de licenciamento.

Como Adicionar Outlines e Marcadores a um PDF?

Os exemplos abaixo usam este PDF de exemplo para demonstrar a criação de outlines e marcadores. O processo envolve carregar um documento PDF existente e usar o BookmarkManager do IronPDF para adicionar pontos de navegação ao longo do documento.

//:path=/static-assets/ironpdf-java/content-code-examples/how-to/bookmarks/single-layer.java
import java.io.IOException;
import java.nio.file.Path;
import com.ironsoftware.ironpdf.License;
import com.ironsoftware.ironpdf.PdfDocument;
import com.ironsoftware.ironpdf.bookmark.BookmarkManager;

public class Main {
    public static void main(String[] args) throws IOException {
        // Set the license key for IronPDF
        License.setLicenseKey("IRONPDF-MYLICENSE-KEY-1EF01");

        // Load the PDF file
        PdfDocument pdf = PdfDocument.fromFile(Path.of("NovelSample.pdf"));

        // Get BookmarkManager object to manage bookmarks
        BookmarkManager bookmarks = pdf.getBookmark();

        // Add bookmarks at the end of the bookmark collection
        bookmarks.addBookMarkAtEnd("Title Page", 0);
        bookmarks.addBookMarkAtEnd("Table of Contents", 1);
        bookmarks.addBookMarkAtEnd("Dedication Page", 2);
        bookmarks.addBookMarkAtEnd("First Page", 3);
        bookmarks.addBookMarkAtStart("Page 4", 6);

        // Save the modified PDF with bookmarks
        pdf.saveAs(Path.of("bookmarked.pdf"));
    }
}

//:path=/static-assets/ironpdf-java/content-code-examples/how-to/bookmarks/single-layer.java
import java.io.IOException;
import java.nio.file.Path;
import com.ironsoftware.ironpdf.License;
import com.ironsoftware.ironpdf.PdfDocument;
import com.ironsoftware.ironpdf.bookmark.BookmarkManager;

public class Main {
    public static void main(String[] args) throws IOException {
        // Set the license key for IronPDF
        License.setLicenseKey("IRONPDF-MYLICENSE-KEY-1EF01");

        // Load the PDF file
        PdfDocument pdf = PdfDocument.fromFile(Path.of("NovelSample.pdf"));

        // Get BookmarkManager object to manage bookmarks
        BookmarkManager bookmarks = pdf.getBookmark();

        // Add bookmarks at the end of the bookmark collection
        bookmarks.addBookMarkAtEnd("Title Page", 0);
        bookmarks.addBookMarkAtEnd("Table of Contents", 1);
        bookmarks.addBookMarkAtEnd("Dedication Page", 2);
        bookmarks.addBookMarkAtEnd("First Page", 3);
        bookmarks.addBookMarkAtStart("Page 4", 6);

        // Save the modified PDF with bookmarks
        pdf.saveAs(Path.of("bookmarked.pdf"));
    }
}

Como faço para criar várias camadas de favoritos?

Marcadores aninhados são a escolha certa para documentação técnica, relatórios de pesquisa ou qualquer documento com vários capítulos, onde os leitores precisam navegar não apenas para capítulos, mas para subseções dentro desses capítulos. Comece com os mesmos marcadores planos criados na seção anterior e depois use insertBookmark para adicionar entradas em novas camadas.

O método insertBookmark aceita quatro parâmetros: o nome do marcador, o índice da página alvo, o nome do marcador pai e o nome do marcador irmão precedente. Passar um nome de marcador pai cria uma entrada filha aninhada abaixo dele. Definir o parâmetro irmão para null coloca a nova entrada como o primeiro filho desse pai.

//:path=/static-assets/ironpdf-java/content-code-examples/how-to/bookmarks/multi-layer.java
import java.io.IOException;
import java.nio.file.Path;
import com.ironsoftware.ironpdf.License;
import com.ironsoftware.ironpdf.PdfDocument;
import com.ironsoftware.ironpdf.bookmark.BookmarkManager;

public class Main {
    public static void main(String[] args) throws IOException {
        // Set the license key
        License.setLicenseKey("IRONPDF-MYLICENSE-KEY-1EF01");

        // Load the PDF file
        PdfDocument pdf = PdfDocument.fromFile(Path.of("NovelSample.pdf"));

        // Get BookmarkManager object
        BookmarkManager bookmarks = pdf.getBookmark();

        // Add top-level bookmarks at the end
        bookmarks.addBookMarkAtEnd("Title Page", 0);
        bookmarks.addBookMarkAtEnd("Table of Contents", 1);
        bookmarks.addBookMarkAtEnd("Dedication", 2);

        // Insert second-layer bookmarks as children of existing entries
        bookmarks.insertBookmark("First Page", 3, "Table of Contents", null);
        bookmarks.insertBookmark("Second Page", 4, "Table of Contents", "First Page");
        bookmarks.insertBookmark("End of Sample", 7, "Title Page", null);
        bookmarks.insertBookmark("Fourth page", 6, "Table of Contents", "Second Page");

        // Save the modified PDF with nested bookmarks
        pdf.saveAs(Path.of("multiLayer.pdf"));
    }
}

//:path=/static-assets/ironpdf-java/content-code-examples/how-to/bookmarks/multi-layer.java
import java.io.IOException;
import java.nio.file.Path;
import com.ironsoftware.ironpdf.License;
import com.ironsoftware.ironpdf.PdfDocument;
import com.ironsoftware.ironpdf.bookmark.BookmarkManager;

public class Main {
    public static void main(String[] args) throws IOException {
        // Set the license key
        License.setLicenseKey("IRONPDF-MYLICENSE-KEY-1EF01");

        // Load the PDF file
        PdfDocument pdf = PdfDocument.fromFile(Path.of("NovelSample.pdf"));

        // Get BookmarkManager object
        BookmarkManager bookmarks = pdf.getBookmark();

        // Add top-level bookmarks at the end
        bookmarks.addBookMarkAtEnd("Title Page", 0);
        bookmarks.addBookMarkAtEnd("Table of Contents", 1);
        bookmarks.addBookMarkAtEnd("Dedication", 2);

        // Insert second-layer bookmarks as children of existing entries
        bookmarks.insertBookmark("First Page", 3, "Table of Contents", null);
        bookmarks.insertBookmark("Second Page", 4, "Table of Contents", "First Page");
        bookmarks.insertBookmark("End of Sample", 7, "Title Page", null);
        bookmarks.insertBookmark("Fourth page", 6, "Table of Contents", "Second Page");

        // Save the modified PDF with nested bookmarks
        pdf.saveAs(Path.of("multiLayer.pdf"));
    }
}

JAVA

O PDF acima mostra a estrutura em árvore dos marcadores criados por insertBookmark. Expanda o painel de outline para verificar como cada entrada filha se aninha sob seu pai. Essa abordagem em camadas é adequada para relatórios com capítulos, subcapítulos e apêndices.

---

Minha biblioteca favorita desse tipo é o IronPDF. Ele permite a manipulação rápida e eficiente de arquivos PDF. Além disso, possui muitos recursos valiosos, como a exportação para o formato PDF/A e a assinatura digital de documentos PDF.

Milan Jovanovic

Microsoft MVP

Veja o estudo de caso

Com o IronOCR, podemos economizar US$ 40.000 por ano em processamento manual, ao mesmo tempo que aumentamos a produtividade e liberamos recursos para tarefas de alto impacto. Eu o recomendo fortemente.

Brent Matzelle

Diretor de Tecnologia, OPYN

Veja o estudo de caso

O IronSuite desempenha um papel crucial nas nossas operações. Estas são ferramentas que aumentam a eficiência no negócio, incluindo a criação de plantas baixas e melhoria na gestão de inventário.

David Jones

Engenheiro(a) de Software Líder, Agorus Build

Veja o estudo de caso

Como faço para recuperar marcadores existentes em um PDF?

Ler dados de marcadores de um PDF é um pré-requisito ao atualizar documentos sem reconstruir toda a estrutura de navegação. O IronPDF torna isso acessível através da mesma interface BookmarkManager usada para adicionar marcadores. Carregue o PDF com PdfDocument.fromFile(), acesse o BookmarkManager, e então chame getBookmarks() para recuperar todos os marcadores de nível superior.

Use get(index) para acessar um marcador específico por sua posição na lista. O método getText() retorna o rótulo de exibição do marcador, enquanto getPageIndex() retorna o número da página baseado em zero que ele almeja. Marcadores de criança não estão incluídos na lista plana retornada por getBookmarks(); acesse-os por meio de cada método getChildren() do marcador pai.

//:path=/static-assets/ironpdf-java/content-code-examples/how-to/bookmarks/retrieve-bookmarks.java
import java.io.IOException;
import java.nio.file.Path;
import java.util.List;
import com.ironsoftware.ironpdf.License;
import com.ironsoftware.ironpdf.PdfDocument;
import com.ironsoftware.ironpdf.bookmark.Bookmark;
import com.ironsoftware.ironpdf.bookmark.BookmarkManager;

public class Main {
    public static void main(String[] args) throws IOException {
        // Set the license key
        License.setLicenseKey("IRONPDF-MYLICENSE-KEY-1EF01");

        // Load the PDF file with bookmarks
        PdfDocument pdf = PdfDocument.fromFile(Path.of("bookmarked.pdf"));

        // Retrieve the bookmark manager
        BookmarkManager bookmarks = pdf.getBookmark();

        // Retrieve list of all bookmarks (includes child bookmarks)
        List<Bookmark> bookmarkList = bookmarks.getBookmarks();

        // Access a specific bookmark by zero-based index
        Bookmark bookmark = bookmarkList.get(2);

        // Print bookmark details
        System.out.println("Bookmark Title: " + bookmark.getText());
        System.out.println("Page Number: " + bookmark.getPageIndex());

        // Check if bookmark has children
        if (bookmark.getChildren() != null && !bookmark.getChildren().isEmpty()) {
            System.out.println("Number of child bookmarks: " + bookmark.getChildren().size());
        }
    }
}

//:path=/static-assets/ironpdf-java/content-code-examples/how-to/bookmarks/retrieve-bookmarks.java
import java.io.IOException;
import java.nio.file.Path;
import java.util.List;
import com.ironsoftware.ironpdf.License;
import com.ironsoftware.ironpdf.PdfDocument;
import com.ironsoftware.ironpdf.bookmark.Bookmark;
import com.ironsoftware.ironpdf.bookmark.BookmarkManager;

public class Main {
    public static void main(String[] args) throws IOException {
        // Set the license key
        License.setLicenseKey("IRONPDF-MYLICENSE-KEY-1EF01");

        // Load the PDF file with bookmarks
        PdfDocument pdf = PdfDocument.fromFile(Path.of("bookmarked.pdf"));

        // Retrieve the bookmark manager
        BookmarkManager bookmarks = pdf.getBookmark();

        // Retrieve list of all bookmarks (includes child bookmarks)
        List<Bookmark> bookmarkList = bookmarks.getBookmarks();

        // Access a specific bookmark by zero-based index
        Bookmark bookmark = bookmarkList.get(2);

        // Print bookmark details
        System.out.println("Bookmark Title: " + bookmark.getText());
        System.out.println("Page Number: " + bookmark.getPageIndex());

        // Check if bookmark has children
        if (bookmark.getChildren() != null && !bookmark.getChildren().isEmpty()) {
            System.out.println("Number of child bookmarks: " + bookmark.getChildren().size());
        }
    }
}

Esse padrão de recuperação é útil ao auditar a estrutura de navegação de um PDF existente antes da distribuição, ou ao construir ferramentas que precisam validar se as seções necessárias estão corretamente marcadas antes da publicação.

Como posso inserir um marcador em um índice específico?

Inserir marcadores em uma posição específica permite atualizar PDFs existentes de forma incremental, adicionando novas seções sem reconstruir todo o outline do zero. Isso é particularmente útil quando PDFs são gerados ou modificados em um pipeline e novo conteúdo é anexado posteriormente.

Recupere a lista de marcadores planos usando getBookmarks(), selecione o marcador alvo pelo seu índice de lista, e então chame addNextBookmark para inserir um novo irmão imediatamente após ele. Use addChildBookmark para colocar uma nova entrada em um nível mais profundo, aninhada sob o marcador selecionado. Ambos os métodos aceitam uma string de título e um índice de página baseado em zero.

//:path=/static-assets/ironpdf-java/content-code-examples/how-to/bookmarks/insert-at-index.java
import java.io.IOException;
import java.nio.file.Path;
import java.util.List;
import com.ironsoftware.ironpdf.License;
import com.ironsoftware.ironpdf.PdfDocument;
import com.ironsoftware.ironpdf.bookmark.Bookmark;
import com.ironsoftware.ironpdf.bookmark.BookmarkManager;

public class Main {
    public static void main(String[] args) throws IOException {
        // Set the license key
        License.setLicenseKey("IRONPDF-MYLICENSE-KEY-1EF01");

        // Load the PDF modified in the multi-layer example
        PdfDocument pdf = PdfDocument.fromFile(Path.of("multiLayer.pdf"));

        // Get the BookmarkManager
        BookmarkManager bookmarks = pdf.getBookmark();

        // Retrieve the flat bookmark list
        List<Bookmark> bookmarkList = bookmarks.getBookmarks();

        // Select a bookmark at a specific index
        Bookmark bookmark = bookmarkList.get(5);

        // Insert a new bookmark after the selected entry
        bookmark.addNextBookmark("Fourth Page", 6);

        // Add a child bookmark under the selected entry
        bookmark.addChildBookmark("Section 1", 7);

        // Save the updated PDF
        pdf.saveAs(Path.of("specificIndex.pdf"));
    }
}

//:path=/static-assets/ironpdf-java/content-code-examples/how-to/bookmarks/insert-at-index.java
import java.io.IOException;
import java.nio.file.Path;
import java.util.List;
import com.ironsoftware.ironpdf.License;
import com.ironsoftware.ironpdf.PdfDocument;
import com.ironsoftware.ironpdf.bookmark.Bookmark;
import com.ironsoftware.ironpdf.bookmark.BookmarkManager;

public class Main {
    public static void main(String[] args) throws IOException {
        // Set the license key
        License.setLicenseKey("IRONPDF-MYLICENSE-KEY-1EF01");

        // Load the PDF modified in the multi-layer example
        PdfDocument pdf = PdfDocument.fromFile(Path.of("multiLayer.pdf"));

        // Get the BookmarkManager
        BookmarkManager bookmarks = pdf.getBookmark();

        // Retrieve the flat bookmark list
        List<Bookmark> bookmarkList = bookmarks.getBookmarks();

        // Select a bookmark at a specific index
        Bookmark bookmark = bookmarkList.get(5);

        // Insert a new bookmark after the selected entry
        bookmark.addNextBookmark("Fourth Page", 6);

        // Add a child bookmark under the selected entry
        bookmark.addChildBookmark("Section 1", 7);

        // Save the updated PDF
        pdf.saveAs(Path.of("specificIndex.pdf"));
    }
}

O método addNextBookmark insere a nova entrada como um irmão do marcador selecionado, imediatamente após ele na lista. O método addChildBookmark coloca a nova entrada em um nível mais profundo, aninhada sob o marcador selecionado. Ambos os métodos aceitam uma string de título e um índice de página baseado em zero.

Quais São os Próximos Passos para Marcadores de PDF em Java?

Os marcadores de PDF dão aos usuários um caminho de navegação direta através de documentos complexos sem rolagem. O BookmarkManager da IronPDF lida com toda a gama de operações de marcador: adicionando listas de entrada plana, construindo esboços multi-nível profundos, recuperando entradas existentes e inserindo em posições específicas.

Para continuar trabalhando com estrutura e recursos de navegação de documentos, explore estes recursos relacionados:

• Dividir PDFs em Java: criar documentos menores, autônomos, que carregam sua própria estrutura de marcadores
• Imprimir PDFs em Java: enviar documentos com marcadores para uma impressora com navegação preservada
• Tutoriais de Java PDF: exemplos adicionais de ponta a ponta para fluxos de trabalho comuns de PDF
• Adicionar anotações aos PDFs em Java: anexar comentários e marcações a localizações específicas das páginas
• Exemplos de IronPDF for Java: amostras de código para copiar e colar para toda a API Java do IronPDF

Comece seu teste gratuito para adicionar marcadores, outlines e outros recursos de navegação ao seu fluxo de trabalho de PDF em Java. Para adquirir uma licença para uso em produção, veja as opções de licenciamento.