如何在 LibreOffice Writer 中建立包含影像的自動郵件合併

你可以用 LibreOffice Writer 建立一個功能完善的郵件合併功能，用於處理姓名、地址、日期和其他文字欄位。然而，一旦每個收件者需要不同的照片、簽名、產品圖片、二維碼或徽章，原本簡單的流程就變得複雜起來。原因很重要：Writer 文件中記錄的郵件合併欄位實際上是用作文字佔位符的資料庫欄位。 LibreOffice 也支援嵌入式和連結式圖形，但其目前的說明文件中並沒有提供原生的“郵件合併影像欄位”，該欄位可以自動將文件路徑列中的影像替換為每筆記錄對應的影像。

這樣就剩下兩種實際可行的選擇。如果每個合併的文件都使用相同的標誌或背景影像，則可以使用 Writer 的常規郵件合併功能，並將該影像固定在範本中。如果每行圖像都必須更改，則更易於控制的方法是將文字和圖像資料保存在 Calc 中，在 Writer 模板中預留一個命名的圖形對象，並使用 LibreOffice Basic 巨集自動執行合併操作。本指南採用第二種方法。

這些說明與 2026 年發布的 LibreOffice 26.2 文件一致。其他版本或 macOS 上的選單可能略有不同。 LibreOffice 目前的 Writer 指南指出，圖像可以嵌入或鏈接，而 UNO API 透過XTextGraphicObjectsSupplier外部 URL 公開 Writer 圖形對象，並允許自動化設定圖形。即使標準的郵件合併精靈沒有將其作為專用影像欄位公開，這些功能也使得按記錄新增影像的工作流程成為可能。

開始之前，請選擇合適的工作流程。

如果您的使用場景僅限於固定的公司徽標，那麼到此為止，請使用LibreOffice 的標準信函工作流程即可。本文的其餘部分將介紹如何處理可變影像。

步驟 1：準備一個乾淨的 Calc 資料來源

建立一個Calc 工作表，包含一個標題行，每行一筆記錄。將圖像引用放在單獨的列中。一個實用的佈局是CustomerID：FirstName，，，，，和。LastNameEmailImagePathOutputName

在建置和測試合併操作時，請使用絕對路徑。雖然絕對路徑的可移植性較差，但它可以消除歧義。例如，C:\MailMerge\Imageslice.jpg在 Windows 或/home/user/mailmerge/images/alice.jpgLinux 系統上使用絕對路徑比使用相對路徑更容易診斷問題，因為相對路徑的根目錄會根據文件的開啟方式而變化。

請勿在同一個生產文件中混用 Windows 和 Linux 路徑格式。範例中的混合路徑格式僅用於展示列中儲存的值類型。您的實際資料來源應使用在執行合併作業的機器上有效的路徑。

一個好的OutputName欄位還可以防止檔案名稱衝突。最好使用穩定的 ID 或經過清理的名稱，而不是電子郵件地址或任意自由文字。如果同一個值出現兩次，請預先決定巨集應該覆寫、加上字尾還是失敗。

步驟 2：確認寫入器可以讀取記錄

LibreOffice Writer 的標準郵件合併功能使用已註冊的資料來源。您可以使用郵件合併精靈、位址資料來源或資料來源瀏覽器。目前 LibreOffice 說明文件位於「工具」>「郵件合併精靈」中，並且允許透過「插入」>「欄位」>「更多欄位」>「資料庫」插入資料庫欄位。請參閱官方的資料庫欄位參考文件。

即使最終巨集直接讀取電子表格，此檢查也很有用。它能及早發現常見問題：工作表錯誤、標題名稱意外、記錄為空，或註冊後電子表格被移動。

對於普通的純文字郵件合併，您可以將列標題拖曳到文檔，或從「資料庫」標籤插入郵件合併欄位。 Writer 官方說明文件確認，合併執行時，這些欄位會被資料庫內容取代。但是，對於可變圖像，不要以為拖入ImagePath頁面就會將路徑轉換為圖像。除非程式碼解析它並更新圖形對象，否則它將保持資料狀態。

步驟 3：建立 Writer 範本並命名映像佔位符

在 Writer 中建立信函、證書、徽章或報告版面。對於文字值，可以使用普通的郵件合併字段，或使用明確的標記，例如 <code><br></code>、<code><br></code>{FirstName}和{LastName}<code><br></code>，{CustomerID}前提是您的巨集會自動取代它們。

接下來，在應該顯示可變影像的位置插入範例影像。在實現自動化之前，設定所需的大小、換行和錨點。 LibreOffice 在目前的Writer 26.2 影像和圖形章節中記錄了影像大小、定位、錨點、換行和連結影像的行為。

給圖形物件一個穩定的名稱，例如 `<object_name> MergeImage`。具體的屬性對話方塊可能會因版本而異，因此如果您不確定 Writer 公開了哪個對象，請使用「工具」>「開發工具」。 LibreOffice 的開發工具可以檢查目前文件中的圖形物件、屬性、方法和介面。這比猜測內部物件名稱更安全可靠。

為了獲得可預測的佈局，請使用相同的寬高比處理所有來源影像，或決定如何裁剪它們。 Writer 可以將影像調整為佔位符的尺寸，但除非您先對檔案進行標準化處理，否則插入到寬橫幅形狀框架中的豎幅照片仍然會顯得不協調。

步驟 4：自動匯出可變影像和文檔

關鍵的自動化操作很簡單：打開模板，替換文字佔位符，找到指定的圖形對象，將該行的圖像檔案載入到該對像中，然後匯出結果。 LibreOffice 的 UNO API 文件getGraphicObjects()提供了存取嵌入式和連結圖形以及TextGraphicObject圖形屬性服務的說明。雖然該GraphicURL屬性已被棄用，不再用於通用物件存儲，而是建議使用其他方法Graphic，但目前的 API 明確指出，設定外部 URL 會將該圖像載入到圖形物件中。這使得使用本機檔案路徑的簡單 Basic 巨集非常方便。

以下範例故意設計得比較小。請將三個路徑、工作表名稱、列索引和占位符名稱變更為與您自己的檔案相符。在執行大量處理之前，請先用兩筆記錄進行測試。

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

此巨集是一種模式，並非通用的即插即用程式。 LibreOffice 安裝可能具有不同的巨集安全性策略、作業系統路徑規則和範本佈局。重要的驗證 API 概念是：Writer 公開其圖形物件集合，LibreOffice 可以從外部 URL 設定圖形。對於大型部署，建議透過現代GraphicAPI 載入圖形，而不是依賴其相容性行為GraphicURL。官方參考文件為XTextGraphicObjectsSupplier和TextGraphicObject。

步驟 5：執行小批量測試並驗證結果

在處理整個資料來源之前，先執行兩到三行刻意不同的資料：一行 JPG 格式，一行 PNG 格式，最好還有一行不同寬高比的圖片。在擴大規模之前，請確認以下所有事項：

• 文件中的收件人姓名與同一電子表格行中的影像相符。
• 最終文件中不會以文字顯示影像路徑。
• 輸出檔案名稱與預期記錄匹配，不會覆蓋其他收件者。
• 圖片完美地適應了預留區域，既不會將文字推到新頁，也不會遮住其他物件。
• 產生的 PDF 或 ODT 檔案在 LibreOffice 和 Calc 關閉後可以獨立開啟。

最後一步檢查至關重要，因為連結圖形和嵌入式圖形的行為方式不同。目前的 Writer 指南解釋說，連結圖像仍然是一個單獨的文件引用，而嵌入式圖像則會成為文件的一部分。如果您要將 ODT 檔案傳輸到另一台計算機，請確認傳輸結果不依賴僅存在於執行合併操作的計算機上的本機路徑。

常見故障及最快的解決方法

輸出結果顯示的是檔案路徑而不是影像。

您將其作為普通郵件合併欄位插入ImagePath，這符合預期，會產生文字。請保留資料來源中的路徑，但讓巨集將其載入到指定的圖形物件中。

每筆記錄都獲得相同的影像

模板圖像在記錄之間從未更改，或者您的循環讀取的是固定單元格。請記錄行號，並ImagePath在進行兩次記錄測試時記錄。如果路徑更改但圖像未更改，請使用開發工具檢查圖形物件名稱。

巨集提示 MergeImage 不存在

圖形已被重新命名、替換，或未以您預期的名稱顯示。請選擇該影像，然後使用“工具”>“開發工具”進行檢查。 UNO API 按名稱顯示圖形對象，因此巨集和模板必須完全一致。

圖片在另一台電腦上消失了。

您可能儲存了一個仍然引用外部文件的文件。如果需要考慮可移植性，請確保生成的交付物嵌入圖像，或在加載圖像後匯出為 PDF 文件。 LibreOffice 的圖像指南解釋了連結圖像和嵌入式圖像之間的區別，以及如何斷開連結以嵌入檔案。

HTML郵件合併會遺失圖片

這是一個已知的限制，在選擇電子郵件輸出之前，請務必檢查。 LibreOffice 幫助文件指出，當格式信函採用 HTML 格式時，嵌入或連結的圖像不會隨電子郵件一起傳送。如果圖像至關重要，請使用 PDF 附件或嘗試其他發送流程，而不是想當然地認為 HTML 郵件合併會保留圖像。請參閱「建立格式信函」。

何時應該改用 LibreOffice 的郵件合併 UNO 服務

如果您的文字欄位已使用 Writer 的原生資料庫郵件合併功能，並且您需要以程式設計方式控制輸出，LibreOffice 也提供了一項MailMerge服務。其文件中所列的屬性包括DataSourceName` <image_file_path>`、 Command` DocumentURL<image_file_path> `、` OutputURL<image_file_path> `、`<image_file_path> FileNameFromColumn` 和SaveAsSingleFile`<image_file_path>`。當您希望透過程式碼自動執行標準郵件合併時，此 API 非常有用。但它本身並未提供針對每個記錄的影像檔案路徑字段，因此您可能需要將郵件合併執行與圖形物件處理結合。請參閱官方的郵件合併服務參考文件。

最終檢查清單

• 如果圖片對所有收件者都是固定的，請使用普通的 Writer 郵件合併功能。
• ImagePath如果每筆記錄中的影像都不同，則使用一個乾淨的列。
• 為 Writer 圖形佔位符命名，並保持其尺寸穩定。
• 在自動化過程中解決圖像路徑問題；不要指望文字合併欄位會自動變成圖片。
• 在運行完整批次之前，先測試兩到三筆記錄。
• 關閉來源文件後開啟匯出的文件，以驗證輸出是否完整。

對於大多數中小型項目，使用 Calc 表格、Writer 範本和簡短的 Basic 宏，可以實現透明度和控制力的最佳平衡。雖然它比普通的文字郵件合併需要更多設置，但您可以清楚地看到每張圖片所在的行，選擇輸出檔名，並在發送數百個個人化文件之前驗證結果。