1. IronPDF
  2. Tutoriais
  3. Esboços e Marcadores

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

Curtis Chau
Curtis Chau
Atualizado:
This article was translated from English: Does it need improvement?
Translated
View the article in English

A biblioteca Java do IronPDF permite adicionar marcadores e tópicos a documentos PDF de forma programática através da classe BookmarkManager, suportando estruturas de marcadores de camada única e multicamadas com pontos de navegação personalizáveis.

Início Rápido: Adicionar Marcadores em PDF no Java

  1. Instale a biblioteca Java IronPDF e defina sua chave de licença
  2. Carregue seu PDF usando PdfDocument.fromFile()
  3. Obtenha o BookmarkManager com pdf.getBookmark()
  4. Adicione marcadores usando addBookMarkAtEnd("Title", pageNumber)
  5. Salve o PDF com pdf.saveAs()

```java :title=Início Rápido //:path=/static-assets/ironpdf-java/content-code-examples/how-to/bookmarks/quickstart.java PdfDocument pdf = PdfDocument.fromFile(Path.of("document.pdf")); BookmarkManager bookmarks = pdf.getBookmark(); bookmarks.addBookMarkAtEnd("Capítulo 1", 0); pdf.saveAs(Path.of("bookmarked.pdf"));


Os marcadores de PDF melhoram a usabilidade e a navegação de seus documentos. As outlines fornecem navegação estruturada dentro de PDFs, permitindo que os usuários acessem diretamente seções principais, muito parecido com um índice. Isso é essencial ao trabalhar com documentos longos, relatórios ou PDFs com vários capítulos que exigem navegação organizada.

IronPDF simplifica a manipulação de PDFs em aplicações Java. A API de marcação dá a você métodos diretos para criar marcadores personalizados em arquivos PDF. A biblioteca integra-se a aplicativos Java e suporta vários recursos de manipulação de PDF além da marcação, incluindo [mistura de PDFs](https://ironpdf.com/java/how-to/java-merge-pdf-tutorial/), [criação de formulários](https://ironpdf.com/java/how-to/create-forms/) e [adição de marcas d'água](https://ironpdf.com/java/how-to/custom-watermark/).

<div class="hsg-featured-snippet">
    <h2>Como adicionar marcadores e estrutura de tópicos em um PDF</h2>
    <ol>
        <li><a href="https://ironpdf.com/java/#download-modal">Instale a biblioteca Java para adicionar marcadores a PDFs</a></li>
        <li>Use a classe <strong>PdfDocument</strong> para carregar um arquivo PDF existente no Java</li>
        <li>Crie e personalize marcadores com a classe <strong>BookmarkManager</strong></li>
        <li>Use <code>addBookMarkAtEnd</code> para adicionar marcadores a páginas específicas do PDF.</li>
        <li>Salve o documento PDF contendo o novo esboço e os marcadores.</li>
    </ol>
</div>

## 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](https://central.sonatype.com/artifact/com.ironsoftware/ironpdf). 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](https://ironpdf.com/java/docs/).

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](https://ironpdf.com/java/get-started/license-keys/).


PontasTodos os índices de página no IronPDF usam numeração baseada em zero. A página 1 do seu documento é o índice 0, a página 2 é o índice 1, e assim por diante.


## Como Adicionar Outlines e Marcadores a um PDF?

Os exemplos abaixo usam este [PDF de exemplo](/static-assets/ironpdf-java/howto/bookmarks/NovelSample.pdf) para demonstrar a criação de outlines e marcadores. O processo envolve carregar um documento PDF existente e usar o recurso `BookmarkManager` do IronPDF para adicionar pontos de navegação em todo o documento.

### Como posso adicionar uma única camada de favoritos?

Uma lista de marcadores plana é adequada para documentos com uma estrutura clara e não hierárquica: relatórios, manuais de produtos ou apresentações em slides onde cada seção tem seu próprio destaque. Após carregar o PDF a partir de um caminho de arquivo usando `PdfDocument.fromFile()`, recupere o objeto `BookmarkManager` para começar a adicionar marcadores.

Os métodos `addBookMarkAtEnd` e `addBookMarkAtStart` adicionam entradas ao final ou ao início da coleção de favoritos, respectivamente. Esses métodos proporcionam flexibilidade na organização de marcadores para corresponder à estrutura do seu documento. Cada entrada leva um título de exibição e um índice de página baseado em zero.

```java
//: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"));
    }
}

Com o visualizador de PDF acima, verifique o índice no canto superior esquerdo da maioria dos navegadores para ver todos os marcadores adicionados. Essa estrutura de marcadores plana proporciona navegação direta para documentos com necessidades organizacionais simples.

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, em seguida, 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 de destino, o nome do marcador pai e o nome do marcador irmão anterior. Passar um nome de marcador pai cria uma entrada filha aninhada abaixo dele. Definir o parâmetro de 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 favoritos 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.

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, em seguida, chame getBookmarks() para recuperar todos os marcadores de nível superior.

Use get(index) para acessar um marcador específico pela 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 (base zero) para a qual ele aponta. Os favoritos filhos não estão incluídos na lista simples retornada por getBookmarks(); Acesse-os através do método getChildren() de cada 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());
        }
    }
}
JAVA

ObserveO método getBookmarks() retorna apenas uma lista simples de favoritos de nível superior. Para percorrer toda a árvore de favoritos, chame recursivamente getChildren() em cada favorito que tenha entradas aninhadas.

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 favoritos plana usando getBookmarks(), selecione o favorito de destino pelo seu índice na lista e, em seguida, chame addNextBookmark para inserir um novo irmão imediatamente após ele. Use addChildBookmark para inserir uma nova entrada um nível abaixo, 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"));
    }
}
JAVA

ObserveAo combinar dois PDFs cujos marcadores compartilham nomes idênticos, a lista de marcadores resultante pode se comportar de maneira inesperada. Renomeie marcadores conflitantes antes de combinar para manter um outline limpo.

O método addNextBookmark insere a nova entrada como um elemento irmão do marcador selecionado, imediatamente após ele na lista. O método addChildBookmark coloca a nova entrada um nível abaixo, 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. A função BookmarkManager do IronPDF lida com toda a gama de operações de marcadores: adicionar listas de entradas simples, construir estruturas de tópicos complexas com vários níveis, recuperar entradas existentes e inserir em posições específicas.

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

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.

Perguntas frequentes

Como adiciono marcadores a um documento PDF em Java?

Carregue seu PDF usando PdfDocument.fromFile(), então chame pdf.getBookmark() para obter o BookmarkManager. Use addBookMarkAtEnd("Title", pageIndex) para adicionar cada marcador por nome de exibição e número de página baseado em zero, depois salve com pdf.saveAs().

Quais são os pré-requisitos para adicionar marcadores em PDF no Java?

Você precisa de Java 8 ou superior, a biblioteca IronPDF adicionada como uma dependência Maven ou Gradle, e uma chave de licença válida definida com License.setLicenseKey() antes de qualquer chamada do IronPDF. Nenhuma ferramenta ou framework adicional é necessário.

Posso criar hierarquias de marcadores com vários níveis em PDFs?

Sim. Adicione os marcadores de nível superior primeiro com addBookMarkAtEnd, então chame insertBookmark(name, pageIndex, parentName, siblingName) para aninhar entradas infantis sob um marcador pai. Passe null como o nome do irmão para colocar a nova entrada como a primeira criança.

Qual é a diferença entre addBookMarkAtEnd e insertBookmark?

addBookMarkAtEnd anexa uma nova entrada de nível superior ao final da lista de marcadores. insertBookmark coloca um marcador em uma posição específica na hierarquia, especificando um nome de marcador pai e um irmão precedente opcional, permitindo delineamentos aninhados.

Como leio marcadores existentes de um PDF no Java?

Chame pdf.getBookmark().getBookmarks() para recuperar uma lista plana de marcadores de nível superior. Acesse entradas individuais por índice usando list.get(index). Use bookmark.getText() para o título e bookmark.getPageIndex() para o número da página baseado em zero. Marcadores filhos são acessíveis via bookmark.getChildren().

Como insiro um marcador após um marcador existente específico?

Recupere a lista de marcadores com getBookmarks(), selecione a entrada alvo por índice, então chame bookmark.addNextBookmark("Title", pageIndex) para inserir um irmão imediatamente após ele, ou bookmark.addChildBookmark("Title", pageIndex) para aninhar uma nova entrada abaixo dele.

Curtis Chau
Curtis Chau
  Converse agora mesmo com a equipe de engenharia.
Redator Técnico

Curtis Chau é bacharel em Ciência da Computação (Universidade Carleton) e se especializa em desenvolvimento front-end, com experiência em Node.js, TypeScript, JavaScript e React. Apaixonado por criar interfaces de usuário intuitivas e esteticamente agradáveis, Curtis gosta de trabalhar com frameworks modernos e criar manuais ...

Leia mais
Pronto para começar?
Versão: 2026.5 just released
Still Scrolling Icon

Ainda está rolando a tela?

Quer provas rápidas?
executar um exemplo Veja seu HTML se transformar em um PDF.