在 Java 中編輯 Word 文檔

Mon, 28 Sep 2026 16:09:16 +0000

在構建協作式 Java 應用程式時，遠端編輯 Microsoft Word 檔案是一項常見挑戰。 GroupDocs.Editor Cloud SDK for Java 提供了一個強大的基於 REST 的函式庫，讓您能在 Java 中編輯 Word 文件，而無需自行處理檔案解析。在本指南中，您將學習如何進行驗證、替換文字、呼叫編輯端點，並下載更新後的 DOCX，全部配合清晰的程式碼範例與效能技巧。

如何在 Java 中編輯 Word 文檔 - 步驟說明

使用您的憑證配置 API 客戶端：建立 Configuration 物件，設定 clientId、clientSecret 以及基礎 URL，然後實例化 ApiClient 和所需的 API。

Configuration config = new Configuration();
config.setClientId("YOUR_CLIENT_ID");
config.setClientSecret("YOUR_CLIENT_SECRET");
config.setBaseUrl("https://api.groupdocs.cloud");

ApiClient apiClient = new ApiClient(config);
EditorApi editorApi = new EditorApi(apiClient);
FilesApi filesApi = new FilesApi(apiClient);

為來源 DOCX 準備 FileInfo：定義存放於 GroupDocs Cloud 儲存中的輸入檔案路徑。

FileInfo fileInfo = new FileInfo();
fileInfo.setFilePath("input.docx");

定義 ReplaceText 操作: 建立一個 ReplaceText 實例，使用您想要取代的文字，並將其加入清單。

ReplaceText replace = new ReplaceText();
replace.setOldValue("Hello");
replace.setNewValue("Hi");
List<ReplaceText> replaceList = new ArrayList<>();
replaceList.add(replace);

建立 EditDocumentOptions 並呼叫 editDocument：結合檔案資訊、編輯選項和輸出設定，然後呼叫 editDocument 方法。這是實際在 Java 中編輯 Word 文件的核心步驟。

EditOptions editOptions = new EditOptions();
editOptions.setReplaceText(replaceList);

EditDocumentOptions options = new EditDocumentOptions();
options.setFileInfo(fileInfo);
options.setOutputPath("output.docx");
options.setFormat("docx");
options.setEditOptions(editOptions);

EditDocumentRequest editRequest = new EditDocumentRequest(options);
EditDocumentResult editResult = editorApi.editDocument(editRequest);
System.out.println("Document edited. Document ID: " + editResult.getDocumentId());

下載已編輯的 DOCX 檔案: 使用 FilesApi 從雲端儲存取得已編輯的檔案。

DownloadFileRequest downloadRequest = new DownloadFileRequest("output.docx");
InputStream inputStream = filesApi.downloadFile(downloadRequest);
try (FileOutputStream outputStream = new FileOutputStream("downloaded_output.docx")) {
    byte[] buffer = new byte[8192];
    int bytesRead;
    while ((bytesRead = inputStream.read(buffer)) != -1) {
        outputStream.write(buffer, 0, bytesRead);
    }
    System.out.println("Edited document downloaded as downloaded_output.docx");
}

如需詳細的類別資訊，請參閱 EditorApi 參考頁面。

完整的可運行範例：在 Java 中編輯 Word 文檔

以下範例示範如何使用 GroupDocs.Editor Cloud SDK for Java 透過取代文字來編輯 DOCX 檔案。

import com.groupdocs.editor.cloud.api.EditorApi;
import com.groupdocs.editor.cloud.api.FilesApi;
import com.groupdocs.editor.cloud.client.ApiClient;
import com.groupdocs.editor.cloud.client.ApiException;
import com.groupdocs.editor.cloud.client.Configuration;
import com.groupdocs.editor.cloud.model.EditDocumentOptions;
import com.groupdocs.editor.cloud.model.EditDocumentResult;
import com.groupdocs.editor.cloud.model.EditOptions;
import com.groupdocs.editor.cloud.model.FileInfo;
import com.groupdocs.editor.cloud.model.ReplaceText;
import com.groupdocs.editor.cloud.model.requests.EditDocumentRequest;
import com.groupdocs.editor.cloud.model.requests.DownloadFileRequest;

import java.io.FileOutputStream;
import java.io.IOException;
import java.io.InputStream;
import java.util.ArrayList;
import java.util.List;

public class GroupDocsEditorExample {
    public static void main(String[] args) {
        // Configuration – replace with your actual credentials
        Configuration config = new Configuration();
        config.setClientId("YOUR_CLIENT_ID");
        config.setClientSecret("YOUR_CLIENT_SECRET");
        config.setBaseUrl("https://api.groupdocs.cloud");

ApiClient apiClient = new ApiClient(config);
        EditorApi editorApi = new EditorApi(apiClient);
        FilesApi filesApi = new FilesApi(apiClient);

// Input and output file paths in the cloud storage
        String inputPath = "input.docx";
        String outputPath = "output.docx";

try {
            // Prepare file information
            FileInfo fileInfo = new FileInfo();
            fileInfo.setFilePath(inputPath);

// Define replace text operation
            ReplaceText replace = new ReplaceText();
            replace.setOldValue("Hello");
            replace.setNewValue("Hi");
            List<ReplaceText> replaceList = new ArrayList<>();
            replaceList.add(replace);

// Set edit options
            EditOptions editOptions = new EditOptions();
            editOptions.setReplaceText(replaceList);

// Build edit document options
            EditDocumentOptions options = new EditDocumentOptions();
            options.setFileInfo(fileInfo);
            options.setOutputPath(outputPath);
            options.setFormat("docx");
            options.setEditOptions(editOptions);

// Execute edit operation
            EditDocumentRequest editRequest = new EditDocumentRequest(options);
            EditDocumentResult editResult = editorApi.editDocument(editRequest);
            System.out.println("Document edited. Document ID: " + editResult.getDocumentId());

// Download the edited document
            DownloadFileRequest downloadRequest = new DownloadFileRequest(outputPath);
            InputStream inputStream = filesApi.downloadFile(downloadRequest);
            try (FileOutputStream outputStream = new FileOutputStream("downloaded_output.docx")) {
                byte[] buffer = new byte[8192];
                int bytesRead;
                while ((bytesRead = inputStream.read(buffer)) != -1) {
                    outputStream.write(buffer, 0, bytesRead);
                }
                System.out.println("Edited document downloaded as downloaded_output.docx");
            } finally {
                if (inputStream != null) {
                    inputStream.close();
                }
            }
        } catch (ApiException apiEx) {
            System.err.println("API error: " + apiEx.getMessage());
        } catch (IOException ioEx) {
            System.err.println("IO error: " + ioEx.getMessage());
        }
    }
}

注意： 此代碼示例演示了核心功能。在將其用於您的項目之前，請確保更新所有文件路徑和配置值以匹配實際環境，驗證所有必需的依賴項已正確安裝，並在開發環境中徹底測試。如果遇到任何問題，請參閱官方文檔或聯繫支援團隊尋求協助。

使用 cURL 在 Java 中透過 REST 修改 Word 文檔

以下是一個 cURL 工作流程，可在不編寫 Java 代碼的情況下執行相同的文字替換操作。它對於快速測試或與其他服務的整合非常有用。

取得存取權杖（將佔位符替換為您的憑證）。

curl -X POST "https://api.groupdocs.cloud/v2.0/oauth2/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET"

上傳來源 DOCX 至您的雲端儲存。

curl -X PUT "https://api.groupdocs.cloud/v2.0/storage/file/input.docx" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "file=@/path/to/local/input.docx"

呼叫 editDocument 端點，使用定義取代操作的 JSON 載荷。

curl -X POST "https://api.groupdocs.cloud/v2.0/editor/edit/document" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "fileInfo": { "filePath": "input.docx" },
        "outputPath": "output.docx",
        "format": "docx",
        "editOptions": {
            "replaceText": [
                { "oldValue": "Hello", "newValue": "Hi" }
            ]
        }
      }'

下載已編輯的檔案 一旦操作成功。

curl -X GET "https://api.groupdocs.cloud/v2.0/storage/file/output.docx" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -o downloaded_output.docx

欲了解完整的 REST 規範，請參閱 API 參考。

安裝與設定 GroupDocs.Editor Cloud SDK for Java

使用提供的依賴程式碼片段將 SDK 添加到您的 Maven 專案中。


    com.groupdocs
    groupdocs-editor-cloud
    25.7

從下載頁面下載最新的 JAR 檔案。
確保您的 Java 執行環境版本為 8 或更高，且您擁有有效的 GroupDocs Cloud 帳戶，具備 client ID 和 secret。

GroupDocs.Editor Cloud SDK for Java 的主要功能

完整的 Word 編輯 - 在 DOCX、DOC、和 ODT 格式中替換文字、圖像和表格。
雲端儲存整合 - 直接與 GroupDocs Cloud 儲存配合，消除本機檔案處理。
REST API 驅動 - 所有操作皆透過安全的 HTTP 呼叫執行，適用於微服務架構。
串流下載 - 大型文件以串流方式傳輸，避免高記憶體消耗。
可擴充選項 - 透過 EditOptions 微調編輯行為（例如，替換文字、移除註解）。

如需更深入的細節，請參閱官方文件。

配置文件編輯選項

EditOptions 物件讓您指定要套用的變更。在範例中，我們使用了 replaceText，但您也可以設定其他操作，例如移除註解或更新欄位。

EditOptions editOptions = new EditOptions();
editOptions.setReplaceText(replaceList); // replaceList defined earlier

其他選項，例如 removeComments 或 updateFields，已在 API 參考中記錄。

透過 REST 編輯 Word 的效能考量

Use Streaming: SDK 以串流方式處理檔案內容，減少大型 DOCX 檔案的堆積記憶體使用。
Batch Replacements: 在單一請求中結合多個 ReplaceText 物件，以避免重複的網路呼叫。
Keep Files in Cloud: 直接在雲端儲存的檔案上執行編輯操作，可避免多次上傳和下載大型二進位檔案的開銷。
Reuse ApiClient: 只建立一次 ApiClient，並在多個編輯操作中重複使用，以受益於連線池。

結論

在 Java 中編輯 Word 文件變得簡單，只需使用 GroupDocs.Editor Cloud SDK for Java。按照此處提供的步驟、程式碼範例和 cURL 工作流程，您可以將強大的文件編輯功能整合到任何 Java 後端服務中。請務必保護您的客戶端憑證，並在臨時授權頁面測試臨時授權，當您遷移到正式環境時，升級為正式授權。祝開發愉快！

常見問題

如何在 Java 中使用 REST API 編輯 Word 文件？
使用 GroupDocs.Editor Cloud SDK for Java 的 editDocument 端點。發送定義替換操作的 JSON 載荷，服務將返回已編輯的 DOCX。
什麼是對 Editor API 呼叫進行身份驗證的最佳方式？
建立一個包含您的 client ID 和 client secret 的 Configuration 物件，然後讓 SDK 自動取得 OAuth 令牌。請參閱官方文件以獲得更多詳細資訊。
我可以在一次請求中替換多個佔位符嗎？
是的。將多個 ReplaceText 條目添加到 EditOptions 中的 replaceText 列表。SDK 會在一次編輯調用中處理所有替換。
編輯的 Word 檔案大小是否有限制？
雲端服務可處理高達數百兆位元組的檔案，但為了獲得最佳效能，請將檔案大小保持在 100 MB 以下，並使用串流下載以避免記憶體突增。

java document manipulation on Document Processing REST APIs | GroupDocs Cloud