pptx

Criação, edição e análise de PPTX

Um .pptx é um arquivo ZIP de arquivos XML. Escolha sua abordagem conforme a tarefa:

Tarefa	Abordagem
Criar um novo deck	Escreva um script pptxgenjs — veja as armadilhas abaixo
Editar um deck existente ou criar a partir de um modelo	descompacte → edite ppt/slides/slideN.xml → compacte
Ler conteúdo	markitdown deck.pptx (um bloco por slide sob os marcadores <!-- Slide number: N -->); grade visual: python scripts/thumbnail.py deck.pptx

Scripts

Os caminhos são relativos ao diretório desta habilidade. Todo o resto é Python puro, node ou shell.

Script	O que faz
scripts/thumbnail.py deck.pptx [prefixo]	Grade rotulada de cada slide, para escolher layouts de modelo. Apenas .pptx. Passe prefixo — o padrão é thumbnails, que sobrescreve as grades de qualquer outro deck no mesmo diretório
scripts/add_slide.py descompactado/ slide2.xml [--after slideN.xml]	Duplica um slide (ou um slideLayoutN.xml) com toda a contabilidade do pacote. Também aceita um .pptx diretamente com -o saida.pptx
scripts/clean.py descompactado/	Exclui slides, mídia e relacionamentos não mais referenciados. Execute depois que <p:sldIdLst> estiver final
scripts/office/validate.py deck.pptx [--original src.pptx]	Verificações de esquema, relacionamento, tipo de conteúdo, gráfico e slide; cada falha nomeia sua correção. Passe --original para qualquer deck derivado de modelo — ele define uma linha de base das verificações de esquema contra o modelo, para que os erros XSD do próprio modelo não sejam interpretados como seus
scripts/office/soffice.py --headless --convert-to pdf deck.pptx	Invólucro do LibreOffice — soffice puro trava neste ambiente

Criando com pptxgenjs — armadilhas

pptxgenjs está pré-instalado — não execute npm install primeiro; escreva o script e use require('pptxgenjs') diretamente. Apenas se esse require falhar: npm install pptxgenjs. O modelo conhece a API; estas são as armadilhas:

• Defina pres.layout antes de adicionar slides. A tela padrão é LAYOUT_16x9 = 10" × 5,625", não 13,3" de largura. Coordenadas além da borda são escritas, não cortadas — a forma simplesmente não está no slide. (LAYOUT_WIDE é 13,3" × 7,5".)
• Cores hexadecimais: nunca #, nunca 8 dígitos. color: "FF0000". Tanto "#FF0000" quanto alfa embutido no hex ("00000020") corrompem o arquivo. Para translucidez: transparency: 0-100 em preenchimentos e imagens, opacity: 0.0-1.0 em sombras — cada um é ignorado silenciosamente no outro.
• pptxgenjs altera objetos de opções no local (converte valores para EMU no primeiro uso). Nunca compartilhe um único objeto shadow/options entre duas chamadas add* — crie um objeto novo a cada vez.
• O offset da sombra deve ser ≥ 0 — um deslocamento negativo corrompe o arquivo. Para projetar uma sombra para cima, use angle: 270 com um deslocamento positivo.
• letterSpacing é ignorado silenciosamente — a opção real é charSpacing.
• Listas: bullet: true em cada item, nunca um • literal (renderiza marcadores duplos). Defina breakLine: true em cada item do array, exceto o último. Espace parágrafos com marcadores usando paraSpaceAfter, não lineSpacing (cria lacunas enormes).
• Um new pptxgen() por arquivo de saída — nunca reuse uma instância.
• rectRadius funciona apenas em ROUNDED_RECTANGLE, não em RECTANGLE.
• Preenchimentos gradientes não são suportados — use uma imagem gradiente como fundo.
• Caixas de texto têm preenchimento interno embutido — defina margin: 0 sempre que o texto precisar se alinhar com uma forma, linha ou ícone no mesmo x.
• Notas do apresentador vão em slide.addNotes("...") (texto simples, uma vez por slide), nunca em uma caixa de texto no slide.
• Mantenha gráficos nativos. Use addChart() para tudo que o PowerPoint pode gráfico (passe um array de {type, data, options} para combos). Para recursos nativos do PowerPoint que a biblioteca não expõe (linhas de tendência, barras de erro), calcule a série extra você mesmo ou pós-processe o OOXML gerado — não recorra a uma imagem renderizada. Apenas tipos de gráfico para os quais o PowerPoint não tem forma nativa (Sankey, rede, corda) devem ser inseridos como imagens.
• Gráficos padrão renderizam nus — sem título, sem rótulos de dados, paleta datada. Defina showTitle + title, showValue: true + dataLabelPosition, chartColors: [...] da sua paleta, e silencie o quadro (catAxisLabelColor/valAxisLabelColor, valGridLine: { color, size }, catGridLine: { style: "none" }, showLegend: false para uma única série).
• Em um gráfico de barras ou colunas empilhadas, dataLabelPosition deve ser ctr, inEnd ou inBase. outEnd corrompe o arquivo.
• Uma série de combinação usando secondaryValAxis/secondaryCatAxis precisa de ambos valAxes e catAxes nas opções do gráfico, duas entradas cada. Sem eles, o pptxgenjs escreve ids de eixos que nunca declara, e o PowerPoint descarta esse gráfico e relata o arquivo como corrompido. Fornecer apenas valAxes não é suficiente.
• Após writeFile(), execute python scripts/office/validate.py deck.pptx. Ele relata as duas falhas de gráfico acima e os defeitos de slide-XML que o PowerPoint recusa, e nomeia a correção para cada um. Corrija-os no seu gerador, não editando manualmente o XML compactado.
• Nunca reorganize os filhos de <p:presentation>. O pptxgenjs escreve <p:notesMasterIdLst> logo após <p:sldIdLst> e aponta ambos os mestres para uma parte de tema. O PowerPoint lê isso feliz — mova o elemento e o mesmo deck se torna inabrível.
• Ícones: renderize react-icons para SVG (ReactDOMServer.renderToStaticMarkup), rasterize com sharp em ≥256px, e insira via addImage({ data: "image/png;base64," + buf.toString("base64") }) — o prefixo image/png;base64, é obrigatório (react-icons, react, react-dom e sharp estão pré-instalados — npm install react-icons react react-dom sharp apenas se um require falhar).

Editando decks e modelos existentes

Escolha os layouts primeiro: python scripts/thumbnail.py modelo.pptx modelo-thumbs escreve uma grade rotulada de cada slide e imprime o(s) arquivo(s) que criou — modelo-thumbs.jpg, dividido em modelo-thumbs-N.jpg após 12 slides. Sempre passe esse segundo argumento, nomeado conforme o deck. O padrão é thumbnails, então dois decks com miniaturas no mesmo diretório sobrescrevem silenciosamente as grades um do outro — as do primeiro deck simplesmente desaparecem (análise de modelo apenas — a garantia de qualidade visual precisa das renderizações em resolução total de Convertendo para Imagens; aceita apenas .pptx, então copie um .potx para um nome .pptx primeiro). Use-o com markitdown para mapear cada seção de conteúdo para um slide do modelo, e varie os layouts — não coloque cada seção no mesmo slide de título e marcadores.

python3 -c "import sys,zipfile; zipfile.ZipFile(sys.argv[1]).extractall('descompactado')" deck.pptx
python scripts/add_slide.py descompactado/ slide2.xml --after slide2.xml   # duplica um slide (ou slideLayoutN.xml); imprime o caminho do novo slide
# reordenar / excluir slides = edite <p:sldIdLst> em ppt/presentation.xml
python scripts/clean.py descompactado/                                     # após exclusões: remove slides órfãos, mídia, relacionamentos
# edite o conteúdo do slide em ppt/slides/slideN.xml
(cd descompactado && rm -f ../saida.pptx && zip -Xr ../saida.pptx .)           # compacte de DENTRO do diretório; rm primeiro ou partes excluídas sobrevivem
python scripts/office/validate.py saida.pptx --original deck.pptx

• Faça todo o trabalho estrutural — adicionar, excluir, reordenar — antes de editar o conteúdo de qualquer slide. add_slide.py copia um arquivo de slide literalmente, então duplicar após editar clona o conteúdo editado; e clean.py exclui qualquer slide ausente de <p:sldIdLst>, incluindo um que você acabou de escrever.
• Nunca copie um arquivo de slide manualmente — add_slide.py faz todo o registro que um novo slide precisa e relata o que criou (Created ppt/slides/slide17.xml from slide2.xml). Também funciona diretamente em um arquivo: add_slide.py deck.pptx slide2.xml -o saida.pptx — passe -o, ou ele reescreve o deck de entrada no local. Um slide duplicado ainda referencia as partes de gráfico/SmartArt/objeto incorporado de sua fonte em vez de cloná-las, então editar o gráfico de um slide altera o do outro.
• Se você usar python-pptx, três coisas que ele não fará: duplicar um slide (seu único ponto de entrada é add_slide(layout)), preservar a formatação através de text_frame.text = "..." (isso colapsa o parágrafo para uma única execução sem estilo — atribua run.text em vez disso), ou ler o SVG/EMF que a maioria das artes de modelo usa (add_picture levanta UnidentifiedImageError).
• O .ppt legado deve ser convertido primeiro: python scripts/office/soffice.py --headless --convert-to pptx arquivo.ppt. Modelos .potx descompactam e compactam identicamente — mantenha a extensão .potx na saída.
• Para reutilizar um ícone ou imagem de modelo, duplique um slide ou layout que já o contenha.

Ao preencher um modelo:

• Se você criar um script de transformação XML, analise com defusedxml.minidom — o arredondamento de OOXML através de xml.etree.ElementTree reescreve prefixos de namespace e corrompe o deck.
• Slots do modelo ≠ itens de origem. Se o modelo mostra 4 membros da equipe e você tem 3, exclua todo o grupo do 4º membro (imagem + caixas de texto), não apenas seu texto — então verifique se há elementos visuais órfãos na garantia de qualidade.
• Um <a:p> por item de lista — nunca concatene itens em um único parágrafo. Copie o <a:pPr> irmão para preservar o espaçamento e coloque b="1" no <a:rPr> de títulos, cabeçalhos de seção e rótulos inline (Status:, Owner:).
• Deixe os marcadores herdarem do layout; adicione apenas <a:buChar>, <a:buAutoNum> (numerado) ou <a:buNone> para substituir — nunca um • literal no texto.
• Texto com espaços iniciais ou finais precisa de xml:space="preserve" em seu <a:t>.

Ideias de Design

Não crie slides chatos. Marcadores simples em fundo branco não impressionarão ninguém. Considere ideias desta lista para cada slide.

Antes de Começar

• Escolha uma paleta de cores ousada e informada pelo conteúdo: A paleta deve parecer projetada para ESTE tópico. Se trocar suas cores em uma apresentação completamente diferente ainda "funcionasse", você não fez escolhas específicas o suficiente.
• Dominância sobre igualdade: Uma cor deve dominar (60-70% de peso visual), com 1-2 tons de apoio e um acento forte. Nunca dê a todas as cores peso igual.
• Contraste claro/escuro: Fundos escuros para slides de título + conclusão, claros para conteúdo (estrutura "sanduíche"). Ou opte por escuro em toda a apresentação para uma sensação premium.
• Comprometa-se com um motivo visual: Escolha UM elemento distintivo e repita-o — molduras de imagem arredondadas, ícones em círculos coloridos. Leve-o através de cada slide. Não use uma barra de cor ou faixa de acento como seu motivo (veja a lista de Evitar).

Paletas de Cores

Escolha cores que combinem com seu tópico — não use o padrão azul genérico. Use estas paletas como inspiração:

Tema	Primária	Secundária	Acento
Executivo Meia-Noite	1E2761 (marinho)	CADCFC (azul gelo)	FFFFFF (branco)
Floresta e Musgo	2C5F2D (floresta)	97BC62 (musgo)	F5F5F5 (creme)
Energia Coral	F96167 (coral)	F9E795 (dourado)	2F3C7E (marinho)
Terracota Quente	B85042 (terracota)	E7E8D1 (areia)	A7BEAE (sálvia)
Gradiente Oceânico	065A82 (azul profundo)	1C7293 (verde-azulado)	21295C (meia-noite)
Minimalista Carvão	36454F (carvão)	F2F2F2 (off-white)	212121 (preto)
Confiança Verde-azulada	028090 (verde-azulado)	00A896 (espuma do mar)	02C39A (hortelã)
Bagas e Creme	6D2E46 (baga)	A26769 (rosa empoeirado)	ECE2D0 (creme)
Calma Sálvia	84B59F (sálvia)	69A297 (eucalipto)	50808E (ardósia)
Cereja Ousada	990011 (cereja)	FCF6F5 (off-white)	2F3C7E (marinho)

Para Cada Slide

Cada slide precisa de um elemento visual — imagem, gráfico, ícone ou forma. Slides apenas com texto são esquecíveis.

Opções de layout:

• Duas colunas (texto à esquerda, ilustração à direita)
• Ícone + linhas de texto (ícone em círculo colorido, cabeçalho em negrito, descrição abaixo)
• Grade 2x2 ou 2x3 (imagem de um lado, grade de blocos de conteúdo do outro)
• Imagem com sangria parcial (lado esquerdo ou direito inteiro) com sobreposição de conteúdo

Exibição de dados:

• Destaques de estatísticas grandes (números grandes 60-72pt com pequenos rótulos abaixo)
• Colunas de comparação (antes/depois, prós/contras, opções lado a lado)
• Linha do tempo ou fluxo de processo (etapas numeradas, setas)

Polimento visual:

• Ícones em pequenos círculos coloridos ao lado de cabeçalhos de seção
• Texto de acento em itálico para estatísticas-chave ou slogans

Tipografia

Os nomes de fontes que você escreve no .pptx são renderizados pelo PowerPoint do usuário, não por este ambiente. Sua garantia de qualidade visual renderiza via LibreOffice, que substitui fontes que não possui — e para algumas fontes o substituto tem larguras diferentes, então sua prévia de QA pode mostrar transbordamento de texto (ou ajuste) que o deck real não terá. Para manter sua QA confiável:

• Fontes seguras (renderizam fielmente à largura na QA e vêm com o Office): Arial, Calibri, Cambria, Times New Roman, Courier New, Bookman Old Style, Century Schoolbook. Use estas para texto do corpo e qualquer coisa onde o ajuste importe.
• Cabeçalhos com personalidade com risco zero de QA: combine um cabeçalho serifado da lista segura (Cambria, Bookman Old Style, Century Schoolbook) com um corpo sans da lista segura (Calibri ou Arial). Você obtém contraste visual sem abrir mão de verificações confiáveis de transbordamento.
• Se o usuário pedir uma fonte fora da lista segura (por exemplo, Georgia ou Trebuchet MS): use-a onde o usuário pediu, mas dimensione esses contêineres com folga extra (~10%) e não confie nas verificações de ajuste de texto da QA nesses elementos — a prévia dessa fonte é aproximada. Se o usuário não especificou, prefira fontes da lista segura para texto do corpo.
• Fontes não confiáveis para QA (o substituto tem larguras diferentes — as verificações de transbordamento podem estar erradas): Georgia, Trebuchet MS, Impact, Arial Black, Garamond, Consolas, Palatino Linotype. A substituição do Calibri Light varia por ambiente; trate como não confiável para QA. Bom para títulos/accentos com folga; não confie no ajuste de texto da QA nestes.
• Nunca use Aptos como padrão — o padrão do Office pós-2023 não tem substituto metricamente compatível aqui e está ausente em instalações mais antigas do Office, então não é confiável em ambos os lados.

Elemento	Tamanho
Título do slide	36-44pt negrito
Cabeçalho de seção	20-24pt negrito
Texto do corpo	14-16pt
Legendas	10-12pt suave

…

[truncado para tradução]