Como criar uma mala direta automatizada com imagens no LibreOffice Writer

Você pode criar uma mala direta perfeitamente funcional no LibreOffice Writer para nomes, endereços, datas e outros campos de texto, mas descobrir que, no momento em que cada destinatário precisa de uma foto, assinatura, imagem de produto, código QR ou crachá diferente, o fluxo de trabalho simples deixa de ser simples. O motivo é importante: os campos de mala direta documentados do Writer são campos de banco de dados usados ​​como marcadores de texto. O LibreOffice também oferece suporte a gráficos incorporados e vinculados, mas sua ajuda atual não documenta um "campo de imagem de mala direta" nativo que substitua automaticamente uma imagem de uma coluna de caminho de arquivo para cada registro.

Isso deixa duas opções práticas. Se todos os documentos mesclados usarem o mesmo logotipo ou imagem de fundo, use a mala direta normal do Writer e mantenha essa imagem fixa no modelo. Se a imagem precisar mudar para cada linha, a abordagem mais controlável é manter os dados de texto e imagem no Calc, reservar um objeto gráfico nomeado no modelo do Writer e automatizar a mesclagem com uma macro do LibreOffice Basic. Este guia usa essa segunda abordagem.

As instruções estão alinhadas com a documentação do LibreOffice 26.2, disponível em 2026. Os menus podem diferir ligeiramente em outras versões ou no macOS. O guia atual do LibreOffice Writer afirma que as imagens podem ser incorporadas ou vinculadas, enquanto a API UNO expõe objetos gráficos do Writer XTextGraphicObjectsSuppliere permite a automação de definir um gráfico a partir de uma URL externa. Esses elementos tornam possível um fluxo de trabalho com imagens por registro, mesmo que o Assistente de Mala Direta padrão não o exponha como um campo de imagem dedicado.

Escolha o fluxo de trabalho correto antes de começar.

Se você utiliza apenas um logotipo fixo da empresa, pare por aqui e siga o fluxo de trabalho padrão de cartas do LibreOffice . O restante deste artigo se aplica a imagens variáveis.

Etapa 1: Prepare uma fonte de dados Calc limpa.

Crie uma planilha do Calc com uma linha de cabeçalho e um registro por linha. Mantenha as referências de imagem em sua própria coluna. Um layout prático é CustomerID, FirstName, LastName, Email, ImagePath, e OutputName.

Use caminhos absolutos durante a compilação e os testes da mesclagem. Eles são menos portáteis, mas eliminam a ambiguidade. Por exemplo, um caminho absoluto C:\MailMerge\Imageslice.jpgno Windows ou /home/user/mailmerge/images/alice.jpgno Linux é mais fácil de diagnosticar do que um caminho relativo, cujo diretório base muda dependendo de como o documento foi aberto.

Não misture formatos de caminho do Windows e do Linux no mesmo arquivo de produção. Os exemplos mistos na ilustração mostram apenas o tipo de valor que a coluna contém. Sua fonte de dados real deve usar caminhos válidos na máquina que executa a mesclagem.

Uma boa OutputNamecoluna também evita conflitos de nomes de arquivo. Prefira um ID estável ou um nome formatado em vez de um endereço de e-mail ou texto livre aleatório. Se o mesmo valor aparecer duas vezes, decida antecipadamente se a macro deve sobrescrever, adicionar um sufixo ou falhar.

Etapa 2: Confirme se o Writer consegue ler os registros.

A mala direta padrão do Writer usa uma fonte de dados registrada. Você pode usar o Assistente de Mala Direta, uma fonte de dados de endereço ou o navegador de fontes de dados. A documentação de ajuda atual do LibreOffice, Ferramentas > Assistente de Mala Direta , também permite a inserção de campos de banco de dados por meio de Inserir > Campo > Mais Campos > Banco de Dados . Consulte a referência oficial de campos de banco de dados .

Essa verificação é útil mesmo que a macro final leia a planilha diretamente. Ela detecta problemas comuns logo no início: planilha incorreta, nomes de cabeçalho inesperados, registros vazios ou uma planilha que foi movida após o registro.

Para mala direta simples, somente com texto, você pode arrastar um cabeçalho de coluna para o documento ou inserir um campo de mala direta na guia Banco de Dados. A ajuda oficial do Writer confirma que esses campos são substituídos pelo conteúdo do banco de dados quando a mala direta é executada. No entanto, para a imagem variável, não presuma que arrastar ImagePathpara a página transformará o caminho em uma imagem. Ela permanecerá como dado, a menos que o código a interprete e atualize um objeto gráfico.

Etapa 3: Crie o modelo do Writer e nomeie o espaço reservado para a imagem.

Crie o layout da carta, certificado, crachá ou relatório no Writer. Para os valores de texto, use campos de mala direta normais ou marcadores inconfundíveis, como <br> {FirstName}, {LastName}<br> e <br>, {CustomerID}caso sua macro os substitua automaticamente.

Em seguida, insira uma imagem de exemplo onde a imagem variável deve aparecer. Defina o tamanho, o alinhamento e a âncora desejados antes de automatizar o processo. O LibreOffice documenta o dimensionamento, o posicionamento, a ancoragem, o alinhamento e o comportamento de imagens vinculadas no capítulo Imagens e Gráficos da versão 26.2 do Writer .

Dê ao objeto gráfico um nome estável, como MergeImage. A caixa de diálogo de propriedades exata pode variar de acordo com a versão, portanto, se você não tiver certeza de qual objeto o Writer expõe, use Ferramentas > Ferramentas de Desenvolvimento . As Ferramentas de Desenvolvimento do LibreOffice podem inspecionar objetos gráficos, propriedades, métodos e interfaces no documento atual. Isso as torna uma ferramenta de diagnóstico mais segura do que tentar adivinhar o nome interno de um objeto.

Para um layout previsível, use a mesma proporção para todas as imagens de origem ou decida como deseja que elas sejam recortadas. O Writer pode redimensionar um gráfico para as dimensões do espaço reservado, mas uma foto em formato retrato inserida em uma moldura larga em formato de banner ainda ficará estranha, a menos que você normalize os arquivos primeiro.

Etapa 4: Automatize a exportação de imagens e documentos variáveis.

A principal operação de automação é simples: abra o modelo, substitua os marcadores de texto, encontre o objeto gráfico nomeado, carregue o arquivo de imagem da linha nesse objeto e, em seguida, exporte o resultado. A API UNO do LibreOffice documenta getGraphicObjects()o acesso a gráficos incorporados e vinculados, bem como o TextGraphicObjectserviço para propriedades gráficas. A GraphicURLpropriedade `image` está obsoleta para armazenamento geral de objetos em favor de `image` Graphic, mas a API atual observa explicitamente que definir uma URL externa carrega essa imagem no objeto gráfico. Isso facilita o uso de uma macro simples em Basic com caminhos de arquivos locais.

O exemplo a seguir é intencionalmente pequeno. Altere os três caminhos, o nome da planilha, os índices das colunas e os nomes dos espaços reservados para corresponder aos seus próprios arquivos. Teste com dois registros antes de executar um lote grande.

Sub MailMergeWithImages()
    Dim calcDoc As Object, sheet As Object, doc As Object
    Dim graphics As Object, imageObj As Object
    Dim row As Long
    Dim firstName As String, lastName As String
    Dim imagePath As String, outputName As String
    Dim sourceURL As String, templateURL As String, outputDir As String

    sourceURL = ConvertToURL("C:\MailMerge\customers.ods")
    templateURL = ConvertToURL("C:\MailMerge\LetterTemplate.odt")
    outputDir = ConvertToURL("C:\MailMerge\Output")

    calcDoc = StarDesktop.loadComponentFromURL(sourceURL, "_blank", 0, Array())
    sheet = calcDoc.Sheets.getByName("Sheet1")

    row = 1  ' row 0 contains headers
    Do While sheet.getCellByPosition(0, row).String <> ""
        firstName = sheet.getCellByPosition(1, row).String
        lastName = sheet.getCellByPosition(2, row).String
        imagePath = sheet.getCellByPosition(4, row).String
        outputName = sheet.getCellByPosition(5, row).String

        doc = StarDesktop.loadComponentFromURL(templateURL, "_blank", 0, Array())

        ReplaceAll doc, "{FirstName}", firstName
        ReplaceAll doc, "{LastName}", lastName

        graphics = doc.getGraphicObjects()
        If graphics.hasByName("MergeImage") Then
            imageObj = graphics.getByName("MergeImage")
            imageObj.GraphicURL = ConvertToURL(imagePath)
        Else
            MsgBox "Graphic object MergeImage was not found."
            doc.close(True)
            Exit Sub
        End If

        Dim args(1) As New com.sun.star.beans.PropertyValue
        args(0).Name = "FilterName"
        args(0).Value = "writer_pdf_Export"
        args(1).Name = "Overwrite"
        args(1).Value = True

        doc.storeToURL(outputDir & outputName & ".pdf", args())
        doc.close(True)
        row = row + 1
    Loop

    calcDoc.close(True)
End Sub

Sub ReplaceAll(doc As Object, findText As String, replacement As String)
    Dim d As Object
    d = doc.createReplaceDescriptor()
    d.SearchString = findText
    d.ReplaceString = replacement
    doc.replaceAll(d)
End Sub

Esta macro é um padrão, não um programa universal pronto para uso. As instalações do LibreOffice podem ter diferentes políticas de segurança de macros, regras de caminho do sistema operacional e layouts de modelos. Os conceitos importantes e verificados da API são que o Writer expõe sua coleção de objetos gráficos e o LibreOffice pode definir um gráfico a partir de uma URL externa. Para implantações maiores, considere carregar o gráfico por meio da GraphicAPI moderna em vez de confiar no comportamento de compatibilidade GraphicURL. As referências oficiais são XTextGraphicObjectsSupplier e TextGraphicObject .

Etapa 5: Execute um pequeno lote e verifique o resultado.

Antes de processar toda a fonte de dados, execute duas ou três linhas deliberadamente diferentes: uma JPG, uma PNG e, idealmente, uma imagem com uma proporção diferente. Confirme todos os seguintes itens antes de ampliar a imagem:

• O nome do destinatário no documento corresponde à imagem da mesma linha da planilha.
• Nenhum caminho de imagem é exibido como texto literal no documento final.
• O nome do arquivo de saída corresponde ao registro pretendido e não sobrescreve o de outro destinatário.
• A imagem se ajusta à área reservada sem empurrar o texto para uma nova página ou cobrir outro objeto.
• O PDF ou ODT gerado abre independentemente após o LibreOffice e o Calc serem fechados.

Essa última verificação é importante porque gráficos vinculados e gráficos incorporados se comportam de maneira diferente. O guia atual do Writer explica que uma imagem vinculada permanece como uma referência de arquivo separada, enquanto uma imagem incorporada passa a fazer parte do documento. Se você estiver enviando arquivos ODT para outra máquina, verifique se o resultado não depende de um caminho local que existe apenas no computador que realizou a mesclagem.

Falhas comuns e a solução mais rápida

A saída mostra o caminho do arquivo em vez da imagem.

Você inseriu ImagePathcomo um campo de mala direta normal. Isso deve gerar texto. Mantenha o caminho na fonte de dados, mas deixe a macro carregá-lo no objeto gráfico nomeado.

Cada registro recebe a mesma imagem.

A imagem do modelo nunca foi alterada entre os registros, ou seu loop está lendo uma célula fixa. Registre o número da linha ImagePathdurante um teste com dois registros. Se o caminho mudar, mas a imagem não, inspecione o nome do objeto gráfico com as Ferramentas de Desenvolvedor.

A macro diz que MergeImage não existe.

O gráfico foi renomeado, substituído ou não está exposto com o nome esperado. Selecione a imagem e inspecione-a em Ferramentas > Ferramentas de Desenvolvimento . A API UNO expõe objetos gráficos por nome, portanto, a macro e o modelo devem ser exatamente iguais.

As imagens desaparecem em outro computador.

Você provavelmente salvou um documento que ainda faz referência a arquivos externos. Se a portabilidade for importante, certifique-se de que o arquivo final inclua a imagem ou exporte para PDF após o carregamento da imagem. O guia de imagens do LibreOffice explica a diferença entre gráficos vinculados e incorporados e como quebrar os links para incorporar arquivos.

A mala direta HTML perde imagens

Essa é uma limitação documentada que vale a pena verificar antes de escolher o envio por e-mail. A Ajuda do LibreOffice afirma que, quando uma carta-modelo está em formato HTML, imagens incorporadas ou com links não são enviadas com o e-mail. Se a imagem for essencial, use um anexo em PDF ou teste outro fluxo de trabalho de envio, em vez de presumir que a mala direta em HTML irá preservá-la. Consulte Criando uma Carta-Modelo .

Quando usar o serviço MailMerge UNO do LibreOffice em vez de

Se seus campos de texto já utilizam a função nativa de mala direta do Writer e você precisa de controle programático sobre a saída, o LibreOffice também oferece um MailMergeserviço. Suas propriedades documentadas incluem `MailMerge` DataSourceName, Command` DocumentURLImageFilePath`, OutputURL`ImageFilePath` , `ImageFilePath` FileNameFromColumne ` SaveAsSingleFileImageFilePath`. Essa API é útil quando você deseja automatizar a mala direta padrão a partir de código. Ela ainda não documenta, por si só, um campo de caminho de arquivo de imagem por registro, portanto, você pode precisar combinar a execução da mala direta com o tratamento de objetos gráficos. Consulte a referência oficial do serviço MailMerge .

Lista de verificação final

• Use a mala direta normal do Writer quando a imagem for fixa para todos os destinatários.
• Use uma única ImagePathcoluna limpa quando a imagem variar de registro para registro.
• Dê um nome ao espaço reservado para a imagem do escritor e mantenha suas dimensões estáveis.
• Resolva o caminho da imagem na automação; não espere que um campo de mesclagem de texto se transforme em uma imagem automaticamente.
• Faça um teste com dois ou três registros antes de executar um lote completo.
• Abra os arquivos exportados após fechar os documentos de origem para comprovar que a saída é autossuficiente.

Para a maioria dos trabalhos de pequeno e médio porte, uma planilha do Calc, um modelo do Writer e uma pequena macro em Basic oferecem o melhor equilíbrio entre transparência e controle. Requer mais configuração do que a mala direta de texto comum, mas permite visualizar exatamente qual linha contém cada imagem, escolher o nome do arquivo de saída e validar o resultado antes de enviar centenas de arquivos personalizados.