1. IronPDF
  2. Tutoriais
  3. Esboços e Marcadores
Como adicionar marcadores e tópicos em PDFs usando C# com o IronPDF

Como adicionar marcadores e tópicos em PDFs usando C# com o IronPDF

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

O IronPDF permite adicionar marcadores (estruturas) a documentos PDF em C#, criando recursos de navegação semelhantes a um sumário. Adicione marcadores de camada única ou múltipla para melhorar a usabilidade do documento e ajudar os usuários a acessar rapidamente as seções principais. Essa funcionalidade opera perfeitamente em ambientes Windows , Linux e macOS .

Início Rápido: Adicionando Marcadores ao Seu PDF em C#

Comece a usar o IronPDF rapidamente adicionando marcadores aos seus documentos PDF. Este guia demonstra como carregar um PDF existente, adicionar marcadores para navegação e salvar o documento atualizado. Ideal para desenvolvedores que desejam aprimorar a funcionalidade de PDF em seus projetos C#.

  1. Instale IronPDF com o Gerenciador de Pacotes NuGet

    PM > Install-Package IronPdf

  2. Copie e execute este trecho de código.

    var pdf = new IronPdf.PdfDocument("example.pdf");
pdf.Bookmarks.AddBookMarkAtEnd("Chapter 1", 1);
pdf.SaveAs("bookmarked.pdf");

  3. Implante para testar em seu ambiente de produção.

    Comece a usar IronPDF em seu projeto hoje com uma avaliação gratuita

    arrow pointer

Fluxo de trabalho mínimo (5 etapas)

  1. Baixe o IronPDF do NuGet.
  2. Carregar um documento PDF existente ou renderizar um novo documento PDF.
  3. Adicione marcadores de camada única para acessar seções importantes.
  4. Adicione marcadores em várias camadas para organização hierárquica.
  5. Recuperar e visualizar propriedades dos favoritos

Como faço para trabalhar com marcadores em PDF usando C#?

No Adobe Acrobat Reader, os tópicos (também conhecidos como marcadores) são exibidos na barra lateral esquerda, proporcionando uma maneira prática de acessar seções importantes do documento. Os marcadores funcionam como um índice interativo, permitindo que os leitores naveguem por documentos complexos de forma eficiente.

Com o IronPDF, você pode importar documentos PDF e realizar diversas operações em estruturas de tópicos existentes, como adicionar, reordenar, editar propriedades e excluir marcadores. Isso lhe dá controle total sobre a organização e a estrutura de seus arquivos PDF, de forma semelhante à maneira como você pode mesclar ou dividir PDFs para gerenciamento de documentos.

PontasTodos os índices de página seguem a indexação baseada em zero.

Como adiciono marcadores de camada única?

Adicionar um marcador no IronPDF é muito simples. Use o método AddBookmarkAtEnd, especificando o nome do marcador e o índice da página correspondente. Essa funcionalidade se integra bem a outras operações de PDF, como adicionar cabeçalhos e rodapés ou definir margens personalizadas para criar documentos profissionais. Segue abaixo um exemplo:

:path=/static-assets/pdf/content-code-examples/how-to/bookmarks-single-layer-bookmark.cs
using IronPdf;

// Create a new PDF or edit an existing document.
PdfDocument pdf = PdfDocument.FromFile("existing.pdf");

// Add a bookmark
pdf.Bookmarks.AddBookMarkAtEnd("NameOfBookmark", 0);

// Add a sub-bookmark
pdf.Bookmarks.AddBookMarkAtEnd("NameOfSubBookmark", 1);

pdf.SaveAs("singleLayerBookmarks.pdf");
Imports IronPdf

' Create a new PDF or edit an existing document.
Private pdf As PdfDocument = PdfDocument.FromFile("existing.pdf")

' Add a bookmark
pdf.Bookmarks.AddBookMarkAtEnd("NameOfBookmark", 0)

' Add a sub-bookmark
pdf.Bookmarks.AddBookMarkAtEnd("NameOfSubBookmark", 1)

pdf.SaveAs("singleLayerBookmarks.pdf")
$vbLabelText   $csharpLabel

O método AddBookMarkAtEnd anexa marcadores ao final da lista de marcadores existentes. Para mais controle sobre o posicionamento dos marcadores, use AddBookMarkAtStart para inserir marcadores no início da lista. Cada marcador faz referência a um índice de página específico, permitindo navegação precisa dentro do documento.

Documento de marcadores de camada única

Como criar hierarquias de favoritos com várias camadas?

O IronPDF permite adicionar marcadores em uma estrutura de árvore, o que é particularmente útil para manter a navegabilidade em documentos PDF grandes. Essa funcionalidade é valiosa ao lidar com grandes coleções de provas, relatórios de vendas ou recibos de diversas datas e locais em um único documento PDF. Assim como você pode criar formulários em PDF para coleta de dados, os marcadores estruturados ajudam a organizar informações complexas hierarquicamente.

O método AddBookMarkAtEnd retorna um objeto IPdfBookMark, permitindo adicionar marcadores filho. Por exemplo, use Children.AddBookMarkAtStart("Date1", 0) ou Children.AddBookMarkAtEnd("Date1", 0) para adicionar marcadores filho ao marcador "Examination". Essa estrutura aninhada cria uma organização hierárquica que reflete o fluxo lógico do seu documento. O código a seguir demonstra esse conceito:

:path=/static-assets/pdf/content-code-examples/how-to/bookmarks-multi-layer-bookmark.cs
using IronPdf;

// Load existing PDF document
PdfDocument pdf = PdfDocument.FromFile("examinationPaper.pdf");

// Assign IPdfBookMark object to a variable
var mainBookmark = pdf.Bookmarks.AddBookMarkAtEnd("Examination", 0);

// Add bookmark for days
var date1Bookmark = mainBookmark.Children.AddBookMarkAtStart("Date1", 1);

// Add bookmark for type of test
var paperBookmark = date1Bookmark.Children.AddBookMarkAtStart("Paper", 1);
paperBookmark.Children.AddBookMarkAtEnd("PersonA", 3);
paperBookmark.Children.AddBookMarkAtEnd("PersonB", 4);

// Add bookmark for days
var date2Bookmark = mainBookmark.Children.AddBookMarkAtEnd("Date2", 5);

// Add bookmark for type of test
var computerBookmark = date2Bookmark.Children.AddBookMarkAtStart("Computer", 5);
computerBookmark.Children.AddBookMarkAtEnd("PersonC", 6);
computerBookmark.Children.AddBookMarkAtEnd("PersonD", 7);

pdf.SaveAs("multiLayerBookmarks.pdf");
Imports IronPdf

' Load existing PDF document
Private pdf As PdfDocument = PdfDocument.FromFile("examinationPaper.pdf")

' Assign IPdfBookMark object to a variable
Private mainBookmark = pdf.Bookmarks.AddBookMarkAtEnd("Examination", 0)

' Add bookmark for days
Private date1Bookmark = mainBookmark.Children.AddBookMarkAtStart("Date1", 1)

' Add bookmark for type of test
Private paperBookmark = date1Bookmark.Children.AddBookMarkAtStart("Paper", 1)
paperBookmark.Children.AddBookMarkAtEnd("PersonA", 3)
paperBookmark.Children.AddBookMarkAtEnd("PersonB", 4)

' Add bookmark for days
Dim date2Bookmark = mainBookmark.Children.AddBookMarkAtEnd("Date2", 5)

' Add bookmark for type of test
Dim computerBookmark = date2Bookmark.Children.AddBookMarkAtStart("Computer", 5)
computerBookmark.Children.AddBookMarkAtEnd("PersonC", 6)
computerBookmark.Children.AddBookMarkAtEnd("PersonD", 7)

pdf.SaveAs("multiLayerBookmarks.pdf")
$vbLabelText   $csharpLabel

Essa abordagem hierárquica é particularmente valiosa ao trabalhar com documentos complexos que exigem organização detalhada. A estrutura aninhada permite que os usuários expandam e recolham seções de favoritos, tornando a navegação intuitiva mesmo em documentos com centenas de páginas.

Documento de marcadores em várias camadas

Como gerar automaticamente marcadores a partir de títulos HTML?

Ao renderizar HTML para PDF, o IronPDF pode automaticamente construir um esboço hierárquico de marcadores a partir da estrutura de títulos do documento (h1-h6) ou de quaisquer seletores CSS personalizados. Isso elimina a necessidade de chamar manualmente AddBookMarkAtEnd para cada seção.

Ative o recurso com a propriedade AutoBookmarksFromHeadings em RenderingOptions antes de chamar RenderHtmlAsPdf ou RenderUrlAsPdf:

:path=/static-assets/pdf/content-code-examples/how-to/bookmarks-auto-from-headings.cs
using IronPdf;

var renderer = new ChromePdfRenderer();

// Master switch: auto-generate bookmarks from HTML headings (h1-h6) during rendering
renderer.RenderingOptions.AutoBookmarksFromHeadings = true;

var html = @"
<h1>Annual Report</h1>
<h2>Executive Summary</h2>
<p>Overview of the year.</p>
<h2>Financial Results</h2>
<h3>Revenue</h3>
<h3>Expenses</h3>
<h2>Outlook</h2>
<p>Looking forward.</p>";

var pdf = renderer.RenderHtmlAsPdf(html);

// pdf.Bookmarks is already populated with a hierarchical outline matching the heading structure
pdf.SaveAs("auto-bookmarked.pdf");

Imports IronPdf

Dim renderer As New ChromePdfRenderer()

' Master switch: auto-generate bookmarks from HTML headings (h1-h6) during rendering
renderer.RenderingOptions.AutoBookmarksFromHeadings = True

Dim html As String = "
<h1>Annual Report</h1>
<h2>Executive Summary</h2>
<p>Overview of the year.</p>
<h2>Financial Results</h2>
<h3>Revenue</h3>
<h3>Expenses</h3>
<h2>Outlook</h2>
<p>Looking forward.</p>"

Dim pdf = renderer.RenderHtmlAsPdf(html)

' pdf.Bookmarks is already populated with a hierarchical outline matching the heading structure
pdf.SaveAs("auto-bookmarked.pdf")
$vbLabelText   $csharpLabel

As seguintes propriedades controlam quais elementos são marcados:

  • AutoBookmarksFromHeadings (bool, padrão false): Ative o recurso. Quando definido para true, o IronPDF constrói automaticamente um esboço de marcadores a partir de seus cabeçalhos HTML.
  • AutoBookmarkMinHeadingLevel (int, padrão 1): O nível de cabeçalho mais alto para começar. Defina para 1 para incluir h1 (o topo do documento).
  • AutoBookmarkMaxHeadingLevel (int, padrão 6): O nível de cabeçalho mais profundo para incluir. Defina para 3 para marcar apenas h1, h2 e h3 — ignorando h4 até h6.
  • AutoBookmarkCssSelectors (string[], padrão null): Use seletores CSS personalizados em vez de tags de cabeçalho. Por exemplo: ".chapter-title" ou "[data-bookmark]".

Personalizando Níveis de Títulos e Seletores CSS

Para restringir marcadores apenas a títulos de nível superior:

renderer.RenderingOptions.AutoBookmarksFromHeadings = true;
renderer.RenderingOptions.AutoBookmarkMaxHeadingLevel = 3;
renderer.RenderingOptions.AutoBookmarksFromHeadings = true;
renderer.RenderingOptions.AutoBookmarkMaxHeadingLevel = 3;
renderer.RenderingOptions.AutoBookmarksFromHeadings = True
renderer.RenderingOptions.AutoBookmarkMaxHeadingLevel = 3
$vbLabelText   $csharpLabel

Para marcar elementos personalizados em vez de títulos, forneça seletores CSS:

renderer.RenderingOptions.AutoBookmarksFromHeadings = true;
renderer.RenderingOptions.AutoBookmarkCssSelectors = new[]
{
    "h1",
    ".chapter-title",
    "[data-bookmark]"
};
renderer.RenderingOptions.AutoBookmarksFromHeadings = true;
renderer.RenderingOptions.AutoBookmarkCssSelectors = new[]
{
    "h1",
    ".chapter-title",
    "[data-bookmark]"
};
renderer.RenderingOptions.AutoBookmarksFromHeadings = True
renderer.RenderingOptions.AutoBookmarkCssSelectors = New String() {
    "h1",
    ".chapter-title",
    "[data-bookmark]"
}
$vbLabelText   $csharpLabel

Como consultar a localização renderizada de elementos HTML?

Após renderizar, o IronPDF pode relatar exatamente em qual página e coordenadas um determinado elemento HTML terminou. Isso substitui a solução alternativa antiga de renderizar primeiro, extrair texto e buscar páginas manualmente.

Defina ElementQuerySelectors em RenderingOptions antes de renderizar, depois chame GetElementLocations no PdfDocument resultante:

:path=/static-assets/pdf/content-code-examples/how-to/bookmarks-element-locations.cs
using IronPdf;
using System;

var renderer = new ChromePdfRenderer();

// Configure which elements should be queryable after rendering
renderer.RenderingOptions.ElementQuerySelectors = new[] { "h1", ".kpi-card" };

var html = @"
<h1>Q4 Dashboard</h1>
<div class='kpi-card'>Revenue: $1.2M</div>
<div class='kpi-card'>Growth: 18%</div>
<h1>Q3 Comparison</h1>
<div class='kpi-card'>Previous: $1.0M</div>";

var pdf = renderer.RenderHtmlAsPdf(html);

// Retrieve the rendered page location of each matched element
foreach (var location in pdf.GetElementLocations())
{
    Console.WriteLine($"'{location.Text}' on page {location.PageIndex + 1} " +
                      $"at ({location.Rectangle.X}, {location.Rectangle.Y})");
}

pdf.SaveAs("dashboard.pdf");

Imports IronPdf
Imports System

Dim renderer = New ChromePdfRenderer()

' Configure which elements should be queryable after rendering
renderer.RenderingOptions.ElementQuerySelectors = New String() {"h1", ".kpi-card"}

Dim html = "
<h1>Q4 Dashboard</h1>
<div class='kpi-card'>Revenue: $1.2M</div>
<div class='kpi-card'>Growth: 18%</div>
<h1>Q3 Comparison</h1>
<div class='kpi-card'>Previous: $1.0M</div>"

Dim pdf = renderer.RenderHtmlAsPdf(html)

' Retrieve the rendered page location of each matched element
For Each location In pdf.GetElementLocations()
    Console.WriteLine($"'{location.Text}' on page {location.PageIndex + 1} " &
                      $"at ({location.Rectangle.X}, {location.Rectangle.Y})")
Next

pdf.SaveAs("dashboard.pdf")
$vbLabelText   $csharpLabel

GetElementLocations retorna um List<RenderedElementLocation> contendo uma entrada por elemento correspondido:

Propriedade Tipo O que ele te informa
Text string O texto dentro do elemento.
PageIndex int Em qual página o elemento terminou (começa em 0).
Rectangle IronSoftware.Drawing.Rectangle A posição do elemento na página, em pontos PDF (1/72 polegada). A origem é no canto inferior esquerdo.
ElementIndex int A ordem do elemento no HTML original (começa em 0).

PontasOs resultados são armazenados em cache na primeira chamada. Se você modificar as anotações do documento após a renderização e precisar de coordenadas atualizadas, chame ResetElementLocationCache para forçar uma nova verificação na próxima chamada de GetElementLocations.

Combinando Auto-Marcadores com Rastreamento de Localização de Elementos

Os auto-marcadores e consultas de localização de elementos podem ser combinados em uma única renderização. Por exemplo, gerando um esboço a partir de cabeçalhos h1/h2 enquanto rastreia a localização da página de elementos .invoice-total:

:path=/static-assets/pdf/content-code-examples/how-to/bookmarks-auto-and-locations.cs
using IronPdf;
using System;

var renderer = new ChromePdfRenderer();

// Auto-generate bookmarks from top-level headings only
renderer.RenderingOptions.AutoBookmarksFromHeadings = true;
renderer.RenderingOptions.AutoBookmarkMaxHeadingLevel = 2;

// Also track the page location of invoice totals after rendering
renderer.RenderingOptions.ElementQuerySelectors = new[] { ".invoice-total" };

var html = @"
<h1>Invoice #2026-001</h1>
<h2>Line Items</h2>
<p>Services rendered for Q1.</p>
<p class='invoice-total'>Subtotal: $4,500.00</p>
<h1>Invoice #2026-002</h1>
<h2>Line Items</h2>
<p>Consulting hours for Q2.</p>
<p class='invoice-total'>Subtotal: $7,200.00</p>";

var pdf = renderer.RenderHtmlAsPdf(html);

// Bookmarks are populated automatically; locations can be queried after rendering
foreach (var location in pdf.GetElementLocations())
{
    Console.WriteLine($"{location.Text} appears on page {location.PageIndex + 1}");
}

pdf.SaveAs("invoices.pdf");

Imports IronPdf
Imports System

Dim renderer As New ChromePdfRenderer()

' Auto-generate bookmarks from top-level headings only
renderer.RenderingOptions.AutoBookmarksFromHeadings = True
renderer.RenderingOptions.AutoBookmarkMaxHeadingLevel = 2

' Also track the page location of invoice totals after rendering
renderer.RenderingOptions.ElementQuerySelectors = New String() {".invoice-total"}

Dim html As String = "
<h1>Invoice #2026-001</h1>
<h2>Line Items</h2>
<p>Services rendered for Q1.</p>
<p class='invoice-total'>Subtotal: $4,500.00</p>
<h1>Invoice #2026-002</h1>
<h2>Line Items</h2>
<p>Consulting hours for Q2.</p>
<p class='invoice-total'>Subtotal: $7,200.00</p>"

Dim pdf = renderer.RenderHtmlAsPdf(html)

' Bookmarks are populated automatically; locations can be queried after rendering
For Each location In pdf.GetElementLocations()
    Console.WriteLine($"{location.Text} appears on page {location.PageIndex + 1}")
Next

pdf.SaveAs("invoices.pdf")
$vbLabelText   $csharpLabel

Como posso recuperar e navegar pelos meus favoritos existentes?

O IronPDF facilita a recuperação e visualização de marcadores em um documento PDF. Navegar pela árvore de favoritos é simples e proporciona acesso fácil a diferentes seções. Essa funcionalidade é essencial ao trabalhar com PDFs existentes que precisam ser editados ou ao implementar recursos como busca e substituição de texto em seções com marcadores. Considere o exemplo de documento com marcadores em várias camadas acima.

O marcador "Examination" possui uma propriedade Children que aponta para os marcadores "Date1" e "Date2". O marcador "Date1" possui uma propriedade NextBookmark que aponta para o marcador "Date2". Além disso, o marcador "Date1" possui uma propriedade Children contendo o marcador "Paper". Essa estrutura interconectada permite padrões de navegação sofisticados e organização de documentos.

Para recuperar todos os marcadores no documento PDF aberto, use o método GetAllBookmarks. Isso fornece uma lista completa de todos os favoritos, permitindo que você analise e utilize a estrutura de favoritos:

:path=/static-assets/pdf/content-code-examples/how-to/bookmarks-retrieve-bookmark.cs
using IronPdf;

// Load existing PDF document
PdfDocument pdf = PdfDocument.FromFile("multiLayerBookmarks.pdf");

// Retrieve bookmarks list
var mainBookmark = pdf.Bookmarks.GetAllBookmarks();
Imports IronPdf

' Load existing PDF document
Private pdf As PdfDocument = PdfDocument.FromFile("multiLayerBookmarks.pdf")

' Retrieve bookmarks list
Private mainBookmark = pdf.Bookmarks.GetAllBookmarks()
$vbLabelText   $csharpLabel

ObserveA fusão de dois documentos PDF com nomes de marcadores idênticos pode desorganizar a lista de marcadores.

AvisoApenas os favoritos criados a partir de índices de página são suportados. Marcadores de outros elementos PDF terão seu valor de índice de página definido para -1.

Aprenda como criar um sumário ao gerar um PDF a partir de HTML no seguinte artigo: " Criando um sumário com o IronPDF ".

Pronto para ver o que mais você pode fazer? Confira nossa página de tutoriais aqui: Organizar PDFs

Perguntas frequentes

Como adiciono marcadores a um documento PDF em C#?

O IronPDF facilita a adição de marcadores a documentos PDF em C#. Você pode usar o método `AddBookmarkAtEnd` para adicionar marcadores de camada única, especificando o nome do marcador e o índice da página. Por exemplo: `pdf.Bookmarks.AddBookMarkAtEnd("Capítulo 1", 1)`. Isso cria recursos de navegação semelhantes a um sumário, que ajudam os usuários a acessar rapidamente as seções principais.

Qual a diferença entre os métodos AddBookmarkAtEnd e AddBookmarkAtStart?

O IronPDF oferece dois métodos para inserir marcadores. O método AddBookMarkAtEnd adiciona marcadores ao final da lista de marcadores existente, enquanto o método AddBookMarkAtStart insere marcadores no início da lista. Ambos os métodos fazem referência a índices de páginas específicos para uma navegação precisa dentro do documento.

Posso criar estruturas hierárquicas de favoritos com vários níveis?

Sim, o IronPDF permite criar hierarquias de marcadores em várias camadas em uma estrutura de árvore. Isso é particularmente útil para organizar documentos complexos com seções aninhadas, de forma semelhante à estrutura de um sumário detalhado com capítulos e subcapítulos.

A funcionalidade de favoritos é compatível em diferentes sistemas operacionais?

O recurso de marcadores do IronPDF funciona perfeitamente em ambientes Windows, Linux e macOS. Você pode adicionar, editar e gerenciar marcadores de PDF independentemente do sistema operacional, garantindo funcionalidade consistente em diferentes plataformas.

Que operações posso realizar em marcadores PDF existentes?

Com o IronPDF, você pode realizar diversas operações em estruturas de PDF existentes, incluindo adicionar novos marcadores, reordená-los, editar as propriedades dos marcadores e excluir marcadores indesejados. Isso lhe dá controle total sobre a organização e a estrutura de seus arquivos PDF.

Como os marcadores são exibidos quando os usuários abrem o PDF?

No Adobe Acrobat Reader e em visualizadores de PDF similares, os marcadores criados com o IronPDF aparecem como contornos na barra lateral esquerda. Eles funcionam como um sumário interativo, permitindo que os leitores naveguem por documentos complexos de forma eficiente, clicando para acessar seções específicas.

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?
Nuget Downloads 19,936,792 | Versão: 2026.7 recém-lançado
Still Scrolling Icon

Ainda está rolando a tela?

Quer provas rápidas? PM > Install-Package IronPdf
executar um exemplo Veja seu HTML se transformar em um PDF.