使用 GroupDocs.Metadata for Java 建立自訂 XMP 套件

在現代數位工作流程中，建立自訂 XMP 套件 是將豐富且可搜尋的中繼資料直接嵌入檔案內的關鍵。無論您處理的是影像、PDF 或多媒體資產，GroupDocs.Metadata for Java 都提供可靠的方式來管理檔案中繼資料以及為 PDF 新增自訂中繼資料，且不需外部資料庫。本教學將逐步說明完整流程——從設定函式庫到嵌入完整的 XMP 封包——讓您立即開始為文件增添價值。

快速答覆

第一步是什麼？ 將 GroupDocs.Metadata 加入 Maven 相依性或下載 JAR。
需要多少行程式碼？ 只需三行簡潔語句即可建立並附加自訂 XMP 套件。
支援哪些檔案格式？ 超過 50 種格式，包括 JPEG、PNG、PDF、DOCX 與 TIFF。
需要授權嗎？ 開發階段可使用免費試用版；正式上線需購買永久授權。
可以在 Java 11+ 使用嗎？ 可以，函式庫相容於 Java 8 至 Java 21。

什麼是「建立自訂 XMP 套件」？

建立自訂 XMP 套件 意指建構包含使用者自訂中繼資料欄位的 XMP 封包，並將其嵌入支援的檔案中。此封包儲存在檔案的 XMP 區段，使得中繼資料可攜帶且可被任何支援 XMP 的應用程式搜尋。

為何使用 GroupDocs.Metadata for Java 來管理檔案中繼資料？

GroupDocs.Metadata 支援 超過 50 種輸入與輸出格式，且可在不將整個文件載入記憶體的情況下處理高達 2 GB 的檔案，將大型資產的 RAM 使用量降低至 80 %。API 亦提供執行緒安全的操作，讓企業環境中的高吞吐量批次處理變得輕鬆。

前置條件

Java Development Kit 8 或更新版本（建議使用 Java 11+）。
如 IntelliJ IDEA 或 Eclipse 等 IDE。
已安裝 Maven 以管理相依性。
具備 Java 類別與中繼資料概念的基本認識。

設定 GroupDocs.Metadata for Java

Maven 設定

在 pom.xml 檔案中加入以下相依性，即可引入 GroupDocs.Metadata：

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

<dependencies>
   <dependency>
      <groupId>com.groupdocs</groupId>
      <artifactId>groupdocs-metadata</artifactId>
      <version>24.12</version>
   </dependency>
</dependencies>

請參考 API Documentation 取得完整方法簽名。
欲取得詳細 API 參考說明，請見 GroupDocs.Metadata Java Docs。

直接下載 – 若您偏好手動設定，可從 GroupDocs.Metadata for Java releases 取得最新 JAR。亦可前往 Latest Releases 頁面查看更新日誌。

取得授權

免費試用 – 無償評估全部功能。
暫時授權 – 取得開發測試用的時限金鑰。（Obtain a Temporary License）
購買授權 – 為正式環境取得永久授權。

原始程式碼與範例可在 GroupDocs Metadata on GitHub 取得。

實作指南

以下為逐步說明，展示如何建立自訂 XMP 套件並將其嵌入檔案。

如何建立自訂 XMP 套件並附加至檔案？

使用 Metadata 類別載入目標檔案，建立 XmpPacketWrapper，定義自訂 XMP 欄位，最後儲存變更。此端對端流程在初始化後僅需三個方法呼叫，即可確保 XMP 封包正確嵌入，且檔案在所有支援的應用程式中仍能完整運作。

初始化 Metadata 物件

Metadata 為代表檔案的主要類別，提供讀寫中繼資料的方法。

Metadata metadata = new Metadata("sample.pdf");

建立新的 XmpPacketWrapper

XmpPacketWrapper 作為一或多個 XMP 封包的容器，可在儲存前一次批次更新。

XmpPacketWrapper xmpWrapper = new XmpPacketWrapper();

定義與設定自訂 XMP 套件

IXmp 介面讓您定義自訂 XMP 綱要並在封包內設定屬性值。

IXmp customXmp = xmpWrapper.createPackage("http://mycompany.com/custom");
customXmp.setProperty("Creator", "John Doe");
customXmp.setProperty("Project", "Metadata Migration");
customXmp.setProperty("Version", "1.0");

儲存已更新的中繼資料

Metadata.save() 將修改後的中繼資料寫回原始檔案，保留所有新增的 XMP 封包。

metadata.getXmp().addPacket(xmpWrapper);
metadata.save();

主要元件說明

Metadata 物件 – 存取檔案中繼資料的中心樞紐。
IXmp 介面 – 提供讀寫 XMP 專屬欄位的方法。
XmpPacketWrapper – 容納一或多個 XMP 封包，支援批次更新。
自訂 XMP 套件 – 您自行定義的綱要，用於儲存額外資訊。

常見問題與解決方案

不支援的檔案格式 – 請確認目標檔案類型列於官方格式清單（支援超過 50 種格式）。
找不到授權 – 確認授權檔案放置於應用程式根目錄，或透過 License.setLicense("license_path") 設定。
大型檔案記憶體耗盡 – 使用 metadata.setLoadOptions(LoadOptions.lazyLoad()) 以延遲載入方式處理中繼資料，降低記憶體使用。

如需進一步協助，請造訪 GroupDocs Support 論壇。

實務應用

數位資產管理 – 直接在影像與 PDF 中嵌入授權與使用權資訊。
內容個人化 – 為文件附加使用者特定識別碼，以實現目標化傳遞。
法規遵循 – 將稽核追蹤與保存政策儲存於檔案本身，簡化治理稽核。

效能考量

資源最佳化 – 以串流模式處理中繼資料，確保 1 GB 以上檔案的 RAM 使用量維持在 100 MB 以下。
版本更新 – 保持函式庫為最新版本；每個主要發行版皆會加入新格式支援，並提升處理速度最高 30 %。

結論

透過本指南，您已掌握如何使用 GroupDocs.Metadata for Java 建立自訂 XMP 套件，從而高效管理檔案中繼資料並為 PDF 及其他多種格式新增自訂中繼資料。您可以嘗試更多 XMP 綱要，將此工作流程整合至 CI 管線，或與 GroupDocs.Viewer 結合，實現端對端的文件處理。

常見問答

Q: 哪些檔案格式支援自訂 XMP 套件？
A: 超過 50 種格式，包括 JPEG、PNG、PDF、DOCX 與 TIFF，皆支援 XMP 封包注入。完整清單請參閱 GroupDocs.Metadata documentation。

Q: 我可以編輯已存在的 XMP 中繼資料嗎？
A: 可以，函式庫允許使用 IXmp 介面讀取、修改與刪除任何 XMP 屬性。

Q: 若檔案本身不支援 XMP，該怎麼處理？
A: 對於不支援的格式，可考慮將檔案轉換為支援 XMP 的容器（例如轉為 PDF），或改用其他中繼資料儲存方式。

Q: 函式庫是否相容於 Java 17 LTS？
A: 完全相容——GroupDocs.Metadata 已在 Java 8 至 Java 21（含所有 LTS 版本）上進行測試。

Q: 加入 XMP 套件時常見的錯誤有哪些？
A: 常見問題包括使用錯誤的命名空間 URI、封包大小超過上限（≈ 2 MB），或嘗試寫入唯讀檔案。請確保權限正確，並在儲存前驗證 XML 綱要。

最後更新： 2026-06-12
測試環境： GroupDocs.Metadata 23.12 for Java
作者： GroupDocs

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

<dependencies>
   <dependency>
      <groupId>com.groupdocs</groupId>
      <artifactId>groupdocs-metadata</artifactId>
      <version>24.12</version>
   </dependency>
</dependencies>

import com.groupdocs.metadata.Metadata;

try (Metadata metadata = new Metadata("YOUR_DOCUMENT_DIRECTORY")) {
    // Proceed with operations on metadata
}

import com.groupdocs.metadata.Metadata;
import com.groupdocs.metadata.core.IXmp;

try (Metadata metadata = new Metadata("YOUR_DOCUMENT_DIRECTORY")) {
    // Get the root XMP package from the metadata
    IXmp root = (IXmp) metadata.getRootPackage();

import com.groupdocs.metadata.core.XmpPacketWrapper;

// Create a new XmpPacketWrapper to hold custom packages
XmpPacketWrapper packet = new XmpPacketWrapper();

import com.groupdocs.metadata.core.XmpPackage;
import com.groupdocs.metadata.core.XmpArray;
import com.groupdocs.metadata.core.XmpArrayType;

// Define and configure the custom XMP package
custom = new XmpPackage("gd", "GroupDocs Custom Package");
custom.set("CustomProperty", "CustomValue");

// Add it to the packet
packet.addPackage(custom);

<dependency>
    <groupId>com.groupdocs</groupId>
    <artifactId>groupdocs-metadata</artifactId>
    <version>23.12</version>
</dependency>