Renderização e exportação avançadas

Os caminhos de PDF, SVG, bitmap, metarquivo, visualização e impressão compartilham um único modelo de paginação e geometria neutra em relação ao backend, mantendo codificadores específicos de cada formato

Backends gráficos personalizados

TXLSGraphicsTextAlign define alinhamento de texto à esquerda, central e à direita para TXLSGraphicsBackend; as chamadas de desenho estilizadas recebem os enums compartilhados restantes — estilos de fonte (TXLSGraphicsFontStyles), terminações de linha (TXLSGraphicsLineCap), padrões de tracejado (TXLSGraphicsLineDash) e alinhamento vertical de texto (TXLSGraphicsTextVAlign)

As implementações recebem coordenadas em pontos, efeitos de texto e imagem resolvidos, recorte e posicionamento de desenho local à página, sem precisar repetir a lógica de layout da pasta de trabalho. Cada desenho em uma página lógica chega como um record TXLSPageDrawingPlacement cujo Kind (TXLSPageDrawingKind: xpdkImage, xpdkChart, xpdkTextBox, xpdkShape, xpdkControl) diz ao backend o que ele está pintando; tiles de plano de fundo de planilha chegam como TXLSSheetBackgroundRenderData

Geometria de renderização pertencente à operação

TXLSPaginationModel.RenderBackend seleciona a identidade do backend capturada pela próxima chamada de Build , e RenderGeometry expõe a calibração imutável resultante, a geração da pasta de trabalho, o backend e o estado limitado do cache de métricas; a sessão de renderização ativa viaja como um handle TXLSRenderSession e a política de cores é um TXLSRenderColorMode (xlsrcColor ou xlsrcMonochrome)

Modelos de PDF usam xlsrgbPdf, SVG usa xlsrgbSvg, imagens de página usam xlsrgbBitmap, modelos de impressão e de visualização de impressão usam xlsrgbPrintPreview, e o TXLSWorkbookViewer usa xlsrgbViewer; PaginationModel nos componentes de SVG, imagem, impressão e visualizador expõe o modelo ativo para diagnósticos sem transferir a propriedade

Os pontos de entrada HTML clássico e XLSX capturam xlsrgbHtml; TXLSHTMLExport.RenderGeometry expõe o snapshot clássico mais recente, enquanto TXLSXHtmlExportSession.RenderGeometry expõe o snapshot retido em todas as planilhas de uma exportação incremental

A saída de colunas HTML converte o modelo de largura de caracteres da pasta de trabalho por meio da largura máxima de dígito da fonte Normal e do dimensionamento de tela configurado antes de emitir um comprimento fixo em pixels CSS; a conversão entre pontos e pixels usa o mesmo DPI de medição capturado

Cada operação retém a calibração capturada mesmo que a pasta de trabalho mude depois, e a renderização nunca grava alturas de linha nem larguras de coluna da planilha. A paginação constrói páginas a partir de objetos TXLSLogicalPage cujos desenhos, orientação (TXLSPageOrientation: xpoPortrait ou xpoLandscape) e posicionamento de comentários (TXLSPrintComments: xpcNone ou xpcAtEnd) vêm da configuração de página resolvida

Uma página lógica expõe tudo de que um backend ou callback precisa: identidade (DocumentPageNumber, SheetPageNumber, SheetName, a ClassicWorksheet ou XlsxWorksheetproprietária), geometria (PageWidth, PageHeight, Scalee os valores LeftMargin, RightMargin, TopMargin, BottomMargin, HeaderMargine FooterMargin ), o retângulo de dados (DataFirstRow, DataLastRow, DataFirstCol, DataLastCol) com títulos de impressão (RepeatFirstRow, RepeatLastRow, RepeatFirstCol, RepeatLastCol), posicionamento do plano de fundo (BackgroundOffsetX, BackgroundOffsetY), saída de linhas de grade (PrintGridlines, GridlineColor), os seis textos das faixas de cabeçalho e rodapé (LeftHeader, CenterHeader, RightHeader, LeftFooter, CenterFooter, RightFooter) e os esqueletos de linhas e colunas da página (RowCount com Rows e RowEdges, ColumnCount com Columns e ColumnEdges), além da lista de desenhos (DrawingCount e Drawings). ExpandHeaderFooter resolve os códigos de formato de cabeçalho e rodapé contra a página, e ExpandHeaderFooterStyled informa ainda o tamanho de fonte inicial e a cor para que pintadores personalizados repliquem a renderização de cabeçalho do próprio Excel

Células mescladas na paginação nativa

TXLSPaginationModel.RenderPageToBackend resolve um intervalo mesclado até sua âncora original e pinta um retângulo visível por fragmento de página; células cobertas não emitem texto duplicado nem linhas de grade internas

Fragmentos XLSX compartilham o preenchimento, o alinhamento, a quebra de linha, a fonte e a avaliação de formato condicional da âncora, enquanto segmentos de borda externos explícitos permanecem visíveis e bordas internas da mesclagem são suprimidas; fragmentos Classic compartilham o texto e o preenchimento sólido da âncora por meio do pintador de texto Classic existente

Uma área de impressão ou uma quebra de página pode recortar um intervalo mesclado, e cada fragmento visível usa a âncora original mesmo quando ela está fora da área impressa; linhas e colunas ocultas contribuem com extensão zero, e fragmentos repetidos de títulos de impressão usam a mesma política de âncora

A mesclagem não força um intervalo para uma única página, não expande a área de impressão nem altera alturas de linha e larguras de coluna armazenadas; a paginação mantém a configuração de página existente e recorta cada fragmento para sua página lógica

Renderização do plano de fundo da planilha

O visualizador de pasta de trabalho exibe planos de fundo válidos de planilhas Classic e XLSX como tiles repetidos atrás de células sem preenchimento, enquanto os preenchimentos explícitos e condicionais de célula permanecem acima do plano de fundo

TXLSPaginationModel, TXLSSvgExport, TXLSPageImageExporter, TXLSPrintDocument, TXLSPDFExport, TXLSHTMLExport, TXLSXHtmlExportOptionse TXLSWorkbookViewer expõem ExportSheetBackgroundImages; o padrão é False para saída de impressão, visualização, metarquivo, PDF, SVG, bitmap e HTML. As planilhas armazenam seu payload com um formato de imagem TXLSSheetBackgroundFormat , e os bytes decodificados viajam como um TXLSSheetBackgroundResource chaveado por geração, DPI e modo de cor

A saída paginada habilitada ancora a disposição em tiles nas coordenadas da planilha entre os limites de página e retém uma imagem decodificada por combinação de planilha, geração de recurso, backend, DPI e modo de cor na sessão de renderização; BackgroundDecodeCount expõe o total de decodificações para diagnóstico, enquanto payloads corrompidos são pulados com um diagnóstico da pasta de trabalho. A TXLSRenderSession ativa gerencia esse cache compartilhado por conta própria: AcquireBackground busca (ou decodifica uma única vez) o TXLSSheetBackgroundRenderData em tiles de uma planilha, DrawTiledBackground o pinta por uma região recortada da página, e DecodeCount informa quantos payloads foram decodificados até então

Política de exibição de objetos da pasta de trabalho

ObjectDisplayMode seleciona xlsodmShowAll, xlsodmShowPlaceholdersou xlsodmHideAll tanto para pastas de trabalho XLS clássicas quanto XLSX; o visualizador consuma os três estados e usa caixas de baixo custo com tipo, nome, texto e texto alternativo para o modo placeholder

Os exportadores de PDF, SVG, bitmap, impressão física e HTML XLSX tratam o modo placeholder como saída de objeto completo por padrão; defina ExportObjectPlaceholders no exportador ou nas opções HTML correspondentes para pedir caixas sem decodificação de imagem nem construção de cena de gráfico

xlsodmHideAll é um gate global anterior que impede a coleta de desenhos, a expansão de intervalo orientada a objetos, o hit testing e a renderização de mídia; planos de fundo de planilha, ícones de formatação condicional, imagens de cabeçalho ou rodapé, células e filtros de objetos de impressão específicos do exportador permanecem independentes

Atualização dos dados de origem do gráfico

A serialização de gráficos XLSX e a renderização de gráficos compartilhada resolvem os caches locais de séries contra a geração atual da pasta de trabalho, de modo que edições em células de origem, recálculo e mudanças de visibilidade atualizem valores, categorias, tamanhos de bolha e nomes de séries vinculados a intervalos antes da saída

Intervalos de origem comuns devem ser uma única linha ou coluna de referências A1 locais; nomes de planilhas entre aspas são suportados, e um intervalo não qualificado resolve contra a planilha à qual o gráfico pertence; níveis hierárquicos de categorias retêm seu resolvedor separado de intervalos retangulares

O texto de categoria usa o texto formatado da célula, caches numéricos retêm slots de ponto vazios para células em branco e texto não numérico, células de erro retêm seus literais de erro exibidos, e datas usam o sistema serial 1900 ou 1904 da pasta de trabalho; PlotVisibleOnly determina se linhas e colunas de origem ocultas são omitidas

Caches importados ou preenchidos manualmente são retidos quando uma origem local nunca foi materializada, enquanto caches já gerenciados a partir de células locais limpam pontos obsoletos após a exclusão; TXLSXChartSeries.RefreshDataCaches atualiza explicitamente as origens locais resolvíveis, incluindo um intervalo de origem vazio

Referências a pastas de trabalho externas e expressões de referência sem suporte retêm seus caches armazenados; a atualização de cache não abre arquivos externos nem realiza requisições de rede

Eixos de data de gráficos com suporte a calendário

TXLSXChartSeries.ResolveDataCaches resolve as origens locais de séries suportadas para a geração atual, e RefreshDataCaches solicita uma atualização explícita mesmo quando uma origem vazia não tem histórico de células

Gráficos XLSX cujo eixo de categoria usa xlsxAxisDate mapeiam cada categoria válida pelo sistema de datas seriais 1900 ou 1904 da pasta de trabalho e mantêm a distância real entre datas esparsas em vez de atribuir slots de ponto iguais

BaseTimeUnit controla a normalização por dia, mês ou ano, enquanto MajorUnit, MinorUnit, MajorTimeUnite MinorTimeUnit avançam os ticks por unidades de calendário; intervalos de mês e ano, portanto, permanecem alinhados entre meses de comprimentos desiguais e anos bissextos

A mesma coleção limitada de ticks fornece coordenadas, rótulos, ticks e as linhas de grade solicitadas para a saída de PDF, SVG, bitmap, visualização, impressão e visualizador baseada em paginação, enquanto o HTML XLSX usa a mesma aritmética de calendário para o SVG inline dos seus gráficos

Escritor de PDF autônomo

TXLSPDFWriter cria documentos PDF que não se originam de uma pasta de trabalho, como faturas, tickets, etiquetas e formulários de sobreposição; BeginDoc define uma caixa de página precisa em pontos, NewPage fecha a página atual, e SaveToStream ou SaveToFile finaliza o documento

Os métodos de desenho usam pontos de PDF a partir do canto inferior esquerdo e cores da biblioteca na forma $00BBGGRR ou $AABBGGRR ; as primitivas disponíveis cobrem FillRectangle, StrokeRectangle, ClipRectangle, MeasureText, SaveGraphicsStatee RestoreGraphicsState para retângulos preenchidos e com traço, linhas, elipses, texto estilizado com medição exata de largura, transformações afins, recorte retangular e save/restore explícito do estado gráfico, enquanto PageWidth e PageHeight informam a caixa de página atual em pontos

Exportação SVG

TXLSSvgExport fornece sete sobrecargas de SaveAsSVG para intervalos clássicos e XLSX, planilhas, pastas de trabalho e páginas lógicas preparadas, além de saída de objetos nomeados onde houver suporte

UseWorksheetPageSetup, Orientatione Margin usam as mesmas decisões de configuração de página que a saída de PDF e de visualização

TXLSSvgExport.PrintComments (tipo TXLSPrintComments) seleciona como os comentários de célula são emitidos na saída SVG paginada; quando definido como xpcAtEnd, a última página da planilha anexa uma lista de comentários (endereço da célula, autor e texto) abaixo da área de dados, enquanto xpcNone omite os comentários

ExportPages envia um documento SVG completo por vez por meio de OnPage, informa a contagem de páginas confirmadas por meio de ExportedPageCounte para antes de gerar as páginas seguintes quando o callback cancela; IdPrefix cria namespaces de documento e de página determinísticos para clip paths, filtros, patterns e recursos compartilhados

HyperlinkMode (tipo TXLSSvgHyperlinkMode) com xshmSafe adiciona regiões de clique transparentes recortadas após o conteúdo visual; os esquemas externos permitidos são HTTP, HTTPS, mail, FTP e links relativos, enquanto destinos ativos, locais, UNC e com caracteres de controle são omitidos; LinksInNewWindow adiciona a proteção noopener noreferrer e as ScreenTips viram títulos SVG

Saída incremental em PNG, JPEG e TIFF multipágina

TXLSPageImageFormat seleciona a saída PNG ou JPEG e TXLSPageImageExporter mantém uma sessão de paginação ativa enquanto libera prontamente cada bitmap concluído

PDF com tags e PDF/A

TXLSPDFExport.TagMode habilita a estrutura automática de documento, tabela, linha, célula de cabeçalho, célula de dados e imagem informativa, com identificadores densos de marked-content locais à página, mapeamentos exatos na parent tree, spans de células mescladas e isolamento de artefatos; as linhas de títulos de impressão e as linhas de cabeçalho de tabela viram células de cabeçalho semânticas, as imagens XLSX com AltText não vazio viram elementos Figure independentes com texto alternativo Unicode, e as imagens sem texto alternativo permanecem artefatos decorativos

Cada instância visível de imagem informativa recebe seu próprio elemento Figure e identificador de marked-content, mesmo quando payloads de imagem iguais compartilham um XObject do PDF; AltTextTitle não substitui texto alternativo ausente, os gráficos permanecem artefatos, e este suporte focado em estrutura não afirma conformidade completa com o PDF/UA

TXLSPDFExport.PDFAProfile seleciona PDF/A-1, PDF/A-2 ou PDF/A-3 no nível de conformidade a ou b; criptografia, fontes, anexos, transparência, assinaturas e metadados incompatíveis são validados antes de o fluxo de saída ser confirmado

TXLSPDFExport.ExportCommentsAsAnnotations posiciona o texto Unicode do autor e do comentário nos retângulos das células de origem, enquanto a saída tradicional de comentários ao final permanece configurável de forma independente

UsePDFA é o comutador de compatibilidade para PDF/A-1b, enquanto UseXRefStream seleciona fluxos de referência cruzada onde o perfil escolhido os permite

Geometria e seleção de páginas

As seis sobrecargas de CalculatePageCount aceitam intervalos clássicos e XLSX, planilhas ou pastas de trabalho sem criar objetos de PDF

PaperWidth e PaperHeight substituem as dimensões do papel em pontos, LastPage fecha o intervalo de saída com base 1, Orientation (tipo TXLSPDFOrientation) seleciona saída retrato ou paisagem, HidePrintObjects (um conjunto de TXLSPDFHidePrintObject: xlsPdfHideHeaders, xlsPdfHideFooters) suprime faixas selecionadas de cabeçalho ou rodapé, e PageLayout (tipo TXLSPDFPageLayout) define a disposição inicial das páginas no visualizador

Modo de página e ação de abertura do PDF

TXLSPDFExport.PageMode (tipo TXLSPDFPageMode) define como um visualizador de PDF organiza os painéis quando o documento é aberto, por meio de xlsPdfModeDefault, xlsPdfModeUseOutlines, xlsPdfModeUseThumbs, xlsPdfModeFullScreen, xlsPdfModeUseOCe xlsPdfModeUseAttachments

OpenAction (tipo TXLSPDFOpenAction) seleciona o comportamento inicial do visualizador com xlsPdfOpenNone, xlsPdfOpenPageou xlsPdfOpenOutlines. Para xlsPdfOpenPage, OpenActionPage é a página alvo com base 1 (limitada à contagem de páginas) e OpenActionZoom é o fator de ampliação inicial, em que 0 mantém o zoom padrão do visualizador ou o ajuste à página

Geometria vetorial adaptativa compartilhada

XLSBuildEllipticArcCubics converte um arco elíptico em segmentos cúbicos de Bézier impondo recursivamente uma tolerância de achatamento escolhida pelo chamador; a renderização de PDF, SVG e bitmap usa essa geometria compartilhada, de modo que arcos grandes ou muito excêntricos recebem mais segmentos sem penalizar arcos simples

XLSDecodeVectorScene valida cabeçalhos EMF e WMF, alinhamento e tamanhos de registros, totais declarados, posicionamento exato do EOF e limites de recursos sem chamar o playback de metarquivo da plataforma; a whitelist nativa reproduz pilhas de estado de device context com save e restore, mapeamento de janela e viewport combinado com transformações de mundo, tabelas de objetos de pen, brush e pen estendida incluindo stock objects, retângulos, elipses, cadeias de linhas, polígonos, polilinhas e curvas Bézier com estilos de traço, path brackets com preenchimento, traço e passes combinados de traço e preenchimento, retângulos arredondados, arcos, cordas, pizzas e arcos de ângulo por meio de conversão exata de arco para Bézier, preenchimentos e molduras de região a partir de retângulos RGNDATA limitados, trechos de texto limitados com fontes, cores e alinhamento, e imagens stretch-DIB restritas recodificadas como PNG por meio de Canvas e SVG, rejeita registros de escape e deixa clipping e registros privados para o fallback limitado existente

Outlines de PDF e callbacks de página

Os outlines de PDF vivem na coleção Bookmarks (tipo TXLSPDFBookmarks): Add e AddForSheet anexam entradas, Delete remove uma, e Count com Items enumeram a árvore. Cada entrada TXLSPDFBookmark suporta entradas pai e filhas (Children), cadeias de irmãos, títulos Unicode, cores (Color), um alvo PageNumber , o SheetName de origem para bookmarks de planilha e flags de negrito ou itálico (conjunto de TXLSPDFBookmarkStyle: xlsPdfBookmarkBold, xlsPdfBookmarkItalic), além de descendentes expandidos ou recolhidos; os bookmarks automáticos de planilha usam o mesmo modelo de hierarquia e AutoSheetBookmarks alterna a geração deles

BeforeNewPage pode ajustar a caixa de cada página, enquanto BeforeGeneratePage e AfterGeneratePage desenham conteúdo de plano de fundo ou de sobreposição por meio dos helpers públicos de página AppendPageContent, FillPageRectangle, StrokePageRectanglee DrawPageText

Assinaturas e anexos

TXLSPDFSignature configura campos de assinatura visíveis ou invisíveis, enquanto CertificationPolicy opcionalmente cria uma assinatura de certificação DocMDP que não permite alterações, permite preenchimento e assinatura de formulários, ou permite preenchimento de formulários, assinatura e anotações; o PDF/A-1 não permite esse recurso do PDF 1.5 e é rejeitado antes de a saída ser confirmada

TXLSPDFCertificationPolicy oferece xlsPdfApprovalSignature, xlsPdfCertifyNoChanges, xlsPdfCertifyFormFillingAndSigninge xlsPdfCertifyFormFillingSigningAndAnnotations para selecionar a política de assinatura explicitamente

Um TXLSPDFSignDigestEvent recebe o resumo (digest) e retorna dados CMS criados pelo host, de modo que o HotXLS nunca precisa de uma chave privada

TXLSPDFExport.Signature anexa a configuração de assinatura e os perfis PDF/A-3 podem incluir arquivos associados validados por meio de AddAttachment, que enfileira um TXLSPDFAttachment; a sobrecarga detalhada aceita um nome de exibição Unicode, tipo MIME, descrição, hora de modificação, payload e um valor de TXLSPDFAttachmentRelationship entre Source, Data, Alternative, Supplement ou Unspecified, enquanto AttachmentCount informa o total na fila e AttachmentDuplicatePolicy (tipo TXLSPDFAttachmentDuplicatePolicy) seleciona como nomes iguais são tratados

TXLSPDFSignature.ImageData, ImageFormate ImageFit (tipo TXLSPDFSignatureImageFit: contain, cover ou stretch) posicionam um PNG na aparência normal do Form antes de o byte range ser congelado; os modos contain, cover e stretch compartilham o cache de imagens do documento, enquanto imagens inválidas falham antes da assinatura

A sobrecarga IXLSPDFAttachmentSource permanece lazy até o salvamento, invoca cada source uma vez por salvamento e faz spool de no máximo 256 MiB antes de o objeto EmbeddedFile ser criado, de modo que falhas do provedor deixem o destino da transação inalterado

A montagem final grava objetos sequencialmente no destino em vez de construir uma única string com o documento inteiro: exportações não assinadas fluem direto para streams forward-only, cada EmbeddedFile referencia seu tamanho em bytes por meio de um objeto indireto /Length emitido após o payload, e os bytes do provedor são copiados do spool em blocos fixos; exportações assinadas são montadas em um spool de documento limitado que recebe os patches de ByteRange e do conteúdo da assinatura, um SHA-256 incremental sobre os dois intervalos cobertos e uma única cópia forward

A saída PDF/A-3 grava cada arquivo associado tanto na name tree de EmbeddedFiles quanto no array AF do catálogo, com nome UF Unicode, PDF Name de MIME escapado, AFRelationship, tamanho em bytes, data de modificação opcional e descrição opcional; PDF/A-1 e PDF/A-2 rejeitam anexos na fila antes de confirmar a saída

Metadados do documento

DocumentTitle, DocumentAuthor, DocumentSubject, DocumentKeywordse DocumentFileName preenchem os dicionários de informações e de metadados do PDF

Fallback de fontes

TXLSPDFExport.SetFontFallbackChain, AddFontFallbacke ClearFontFallbackChains configuram camadas de fallback por família de origem e por estilo; LoadedFallbackFontCount expõe a contagem de faces em cache e FontFallbackSelectionCacheCount o número de decisões de fallback por seleção em cache, ambos para diagnósticos

TXLSPDFExport.FontSize define o tamanho de texto padrão em pontos, com 9 como padrão

A seleção de fallback usa a cobertura de glifos e preserva mapeamentos Unicode, escalares suplementares, agrupamentos de grafemas, agrupamentos de modelagem (shaping) e faces TTC autônomas

OnGetFontDirectories pode retornar um ou mais diretórios de fontes separados por ponto e vírgula para uma família e um estilo solicitados; os diretórios aceitos são percorridos recursivamente uma única vez, indexados pelos metadados internos de família/estilo e cacheados para medições e desenhos subsequentes

Política de incorporação de fontes

TXLSPDFExport.FontEmbedding (tipo TXLSPDFFontEmbedding) seleciona incorporação automática, subsetting obrigatório, o programa de fonte completo ou saída somente de mapa por meio de xlsPdfFontEmbedAuto, xlsPdfFontEmbedSubset, xlsPdfFontEmbedFulle xlsPdfFontEmbedNone; o subsetting obrigatório falha atomicamente quando um subset válido não pode ser produzido, faces TTC são convertidas em fontes autônomas, e o PDF/A rejeita saída somente de mapa

OnFontEmbed dispara uma vez por face Unicode antes de as métricas, o mapa de caracteres, o shaping e os identificadores de glifo serem resolvidos; definir Handled aceita o modo por fonte retornado e bytes de substituição opcionais, enquanto deixá-lo em false mantém a política do documento e a face original

Fontes OpenType autônomas com outlines CFF são incorporadas por meio de FontFile3 com um stream OpenType e um descendente CIDFontType0 ; os modos automático e completo retêm o programa completo, enquanto o subsetting CFF obrigatório falha atomicamente porque não consegue preservar um subset válido

Fontes incorporadas com dados GPOS do OpenType ou kern legado usam avanços de glifo posicionados para texto simples e complexo, de modo que medição, quebra de linha, alinhamento e as posições de glifo emitidas compartilham o mesmo resultado de kerning

Progresso e cancelamento

TXLSPDFExport.OnProgress e OnProgressEx informam as fases de início, página e fim; Cancel solicita o cancelamento e Aborted informa o estado final sem confirmar um fluxo parcial

Veja também

• TXLSPaginationModel
• SaveAsPDF
• Fluxos de trabalho avançados de pasta de trabalho