如何使用 GroupDocs.Watermark Java 向 Excel 添加附件

介绍

在当今快速发展的商业环境中，add attachment to excel 是一种强大的方式，可将相关文档一起保存，而不会使文件系统变得杂乱。无论是需要将合同 PDF 与财务模型捆绑，还是将图像附加到项目跟踪器，将文件直接嵌入 Excel 工作表都能简化协作并提升数据完整性。本教程将一步步演示如何使用 GroupDocs.Watermark for Java 快速可靠地 add attachment to excel 工作表。

快速答案

  • 什么库可以向 Excel 添加附件？ GroupDocs.Watermark for Java.
  • 需要多少行代码？ Only two lines after loading the workbook.
  • 我可以附加任何文件类型吗？ Yes – PDFs, images, Word docs, and more (50+ formats).
  • 我需要许可证来进行测试吗？ A free temporary license is sufficient for evaluation.
  • 内存使用是个问题吗？ The API streams data, so even 500‑page workbooks stay under 200 MB RAM.

什么是向 Excel 添加附件？

Add attachment to excel 指将外部文件嵌入到 Excel 工作表中，使用户能够直接从电子表格打开该文件。此功能将支持文档与其描述的数据放在一起，消除单独文件传输的需求。

为什么使用 GroupDocs.Watermark for Java 来嵌入文件？

GroupDocs.Watermark 支持 30+ input and output formats，在不将整个文件加载到内存的情况下处理数百页的电子表格，并提供只需少量方法调用的简洁 API。使用该库可将手动 zip‑file 处理降低至 80 % 以上，并消除文件移动时链接断开的风险。

先决条件

  • Java Development Kit (JDK) 8+ – GroupDocs.Watermark 支持的最低版本。
  • GroupDocs.Watermark for Java 24.11 – 撰写时的最新稳定版本。
  • IDE – IntelliJ IDEA、Eclipse 或任何兼容 Maven 的环境。

所需库和依赖项

使用 Maven 将 GroupDocs.Watermark 集成到项目中，或直接下载 JAR 文件。以下是使用 Maven 的设置方法：

<repositories>
   <repository>
      <id>repository.groupdocs.com</id>
      <name>GroupDocs Repository</name>
      <url>https://releases.groupdocs.com/watermark/java/</url>
   </repository>
</repositories>

<dependencies>
   <dependency>
      <groupId>com.groupdocs</groupId>
      <artifactId>groupdocs-watermark</artifactId>
      <version>24.11</version>
   </dependency>
</dependencies>

直接下载
Alternatively, download the latest version from GroupDocs.Watermark for Java 发布版.

许可证获取

通过从此处下载临时许可证开始免费试用，以在无限制的情况下探索全部功能。生产环境请购买永久许可证。

设置 GroupDocs.Watermark for Java

Watermarker 类是 GroupDocs.Watermark 中所有文档操作的入口点。添加 Maven 依赖后，您可以使用 Excel 文件路径和可选的加载选项实例化 Watermarker。

import com.groupdocs.watermark.Watermarker;

public class SetupGroupDocs {
    public static void main(String[] args) throws Exception {
        // Initialize watermarker with an input file
        Watermarker watermarker = new Watermarker("path/to/your/spreadsheet.xlsx");
        
        // Your code to manipulate the document goes here
        
        // Close the watermarker when done
        watermarker.close();
    }
}

此初始化准备库读取、修改并保存电子表格内容。

实现指南

在本节中，我们将分解实现 add attachment to excel 工作表所需的每一步。

加载 Excel 电子表格

如何加载 Excel 工作簿？
Create a Watermarker instance, passing the Excel file path and a SpreadsheetLoadOptions object that tells the API to treat the file as a spreadsheet. This step opens the workbook in read/write mode while keeping memory usage low.

import com.groupdocs.watermark.options.SpreadsheetLoadOptions;

public class LoadSpreadsheet {
    public static void run() throws Exception {
        // Create new SpreadsheetLoadOptions instance
        SpreadsheetLoadOptions loadOptions = new SpreadsheetLoadOptions();
        
        // Initialize Watermarker with the Excel file path and load options
        Watermarker watermarker = new Watermarker("YOUR_DOCUMENT_DIRECTORY/spreadsheet.xlsx", loadOptions);
    }
}

将文件读取为字节数组

准备文件以进行附件的最佳方式是什么？
Read the external file (PDF, image, DOCX, etc.) into a byte array using Java’s Files.readAllBytes method. The resulting byte array can be passed directly to the attachment API, ensuring the original file format is preserved.

import java.io.File;
import java.io.FileInputStream;
import java.io.InputStream;

public class ReadFileToBytes {
    public static byte[] readFileToByteArray(String filePath) throws Exception {
        File file = new File(filePath);
        byte[] fileContentBytes = new byte[(int) file.length()];

        try (InputStream inputStream = new FileInputStream(file)) {
            inputStream.read(fileContentBytes);
        }
        
        return fileContentBytes;
    }
}

向电子表格工作表添加附件

如何在特定工作表中嵌入文件？
Call watermarker.getWorksheets().get(0).addAttachment("AttachmentName.ext", fileBytes). The first parameter is the display name that appears in the Excel “Attachments” pane, and the second is the byte array from the previous step. The attachment becomes part of the worksheet’s internal package.

addAttachment 将指定文件作为附件嵌入工作表。

import com.groupdocs.watermark.contents.SpreadsheetContent;
import com.groupdocs.watermark.contents.SpreadsheetWorksheet;

public class AddAttachmentToWorksheet {
    public static void run(Watermarker watermarker, byte[] attachmentBytes, String fileName, byte[] previewImageBytes) throws Exception {
        SpreadsheetContent content = watermarker.getContent(SpreadsheetContent.class);
        SpreadsheetWorksheet worksheet = content.getWorksheets().get_Item(0);

        worksheet.getAttachments().addAttachment(
            attachmentBytes,
            fileName,
            previewImageBytes,
            50, 100, 200, 400
        );
    }
}

保存对电子表格的更改

如何保存修改后的工作簿？
Invoke watermarker.save("output.xlsx", SaveFormat.Xlsx). The API writes the updated package, including the new attachment, to the specified path. All changes are persisted in a single operation, which keeps the process fast and atomic.

save 将修改后的工作簿（包括附件）写入指定文件。

public class SaveSpreadsheet {
    public static void run(Watermarker watermarker, String outputPath) throws Exception {
        watermarker.save("YOUR_OUTPUT_DIRECTORY/modified_spreadsheet.xlsx");
        watermarker.close();
    }
}

实际应用

在 Excel 工作簿中嵌入文件可解决许多实际问题：

  • 法律文件： 将已签署的合同与财务表格一起存储，确保审计员能够即时检索原始协议。
  • 报告与演示文稿： 将支持的 PDF 或幻灯片附加到数据驱动的报告中，为利益相关者提供一站式的全部材料视图。
  • 教育内容： 教师可以将工作表与参考 PDF 捆绑，简化向学生的分发。

性能考虑因素

在 add attachment to excel 时优化性能很简单：

  • 内存管理： 始终调用 watermarker.close()（或使用 try‑with‑resources 块）及时释放文件句柄。
  • 批量处理： 处理数十个工作簿时，将其分批（每批 10–20 个）处理，以避免堆内存消耗过大。
  • 大附件： 对于大于 50 MB 的文件，考虑分块流式传输字节数组，以保持 JVM 的内存占用低。

常见问题

问：我可以向同一工作表附加多个文件吗？
答：可以。重复调用 addAttachment，使用不同的文件名和字节数组；每次调用都会在工作表的附件集合中创建一个单独的条目。

问：附件会在 Excel 的 UI 中可见吗？
答：当然。Excel 在“插入 → 对象 → 从文件创建 → 显示为图标”面板下显示附件，用户可以双击图标打开嵌入的文档。

问：这在受密码保护的 Excel 文件上有效吗？
答：当您通过 SpreadsheetLoadOptions.setPassword("yourPassword") 提供密码时，GroupDocs.Watermark 可以打开受密码保护的工作簿。

问：附件有大小限制吗？
答：该库支持最高 2 GB 的附件，唯一限制是底层 ZIP 包格式和可用磁盘空间。

问：以后如何删除附件？
答：获取工作表的附件集合，在再次保存工作簿之前调用 removeAttachment("AttachmentName.ext")。

结论

您现在已经掌握了使用 GroupDocs.Watermark for Java add attachment to excel 的方法。通过加载工作簿、将外部文件转换为字节数组、使用单个 API 调用嵌入它们并保存结果，您可以将所有相关文档整洁、可搜索地保存在一个包中。尝试不同的文件类型、自动化批量处理，并探索其他水印功能，以进一步丰富您的电子表格。

最后更新： 2026-06-06
测试环境： GroupDocs.Watermark 24.11 for Java
作者： GroupDocs

相关教程