ویرایش فایل‌های Microsoft Word به‌صورت از راه دور یک چالش رایج هنگام ساخت برنامه‌های Java مشترک است. GroupDocs.Editor Cloud SDK for Java کتابخانه‌ای قدرتمند مبتنی بر REST ارائه می‌دهد که به شما امکان می‌دهد اسناد Word را در Java و بدون نیاز به پردازش فایل به‌صورت دستی ویرایش کنید. در این راهنما خواهید آموخت که چگونه احراز هویت کنید، متن را جایگزین کنید، نقطه انتهایی ویرایش را فراخوانی کنید و نسخه به‌روز شدهٔ DOCX را دانلود کنید، همه اینها با مثال‌های کد واضح و نکات عملکردی.

نحوه ویرایش اسناد Word در Java - گام به گام

  1. پیکربندی کلاینت 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);
  1. آماده‌سازی FileInfo برای DOCX منبع: مسیر فایل ورودی ذخیره‌شده در GroupDocs Cloud storage را تعریف کنید.
FileInfo fileInfo = new FileInfo();
fileInfo.setFilePath("input.docx");
  1. تعریف عملیات ReplaceText: یک نمونه ReplaceText ایجاد کنید با متنی که می‌خواهید جایگزین کنید و آن را به یک لیست اضافه کنید.
ReplaceText replace = new ReplaceText();
replace.setOldValue("Hello");
replace.setNewValue("Hi");
List<ReplaceText> replaceList = new ArrayList<>();
replaceList.add(replace);
  1. ساخت EditDocumentOptions و فراخوانی editDocument: ترکیب اطلاعات فایل، گزینه‌های ویرایش و تنظیمات خروجی، سپس فراخوانی متد editDocument. این گام اصلی است که در آن واقعاً اسناد Word را در Java ویرایش می‌کنید.
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());
  1. دانلود فایل 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 مراجعه کنید.

مثال کامل عملی برای ویرایش اسناد Word در Java

مثال زیر نشان می‌دهد که چگونه می‌توان یک فایل DOCX را با جایگزینی متن با استفاده از GroupDocs.Editor Cloud SDK for Java ویرایش کرد.

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());
        }
    }
}

توجه: این مثال کد عملکرد اصلی را نشان می‌دهد. قبل از استفاده از آن در پروژه خود، مطمئن شوید که مسیرهای فایل و مقادیر پیکربندی را به‌گونه‌ای به‌روز کنید که با محیط واقعی شما مطابقت داشته باشد، اطمینان حاصل کنید که تمام وابستگی‌های مورد نیاز به‌درستی نصب شده‌اند و به‌طور کامل در محیط توسعه خود تست کنید. اگر با مشکلی مواجه شدید، لطفاً به مستندات رسمی مراجعه کنید یا برای دریافت کمک به تیم پشتیبانی مراجعه کنید.

ویرایش اسناد Word از طریق REST در Java با استفاده از cURL

در زیر یک جریان کاری cURL آورده شده است که همان عملیات جایگزینی متن را بدون نوشتن کد Java انجام می‌دهد. این برای تست سریع یا ادغام با سرویس‌های دیگر مفید است.

  1. دریافت یک توکن دسترسی (مقادیر جایگزین را با اعتبارهای خود جایگزین کنید).
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"
  1. بارگذاری 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"
  1. صدا زدن به نقطه انتهایی 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" }
            ]
        }
      }'
  1. فایل ویرایش‌شده را دانلود کنید پس از موفقیت عملیات.
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 خود اضافه کنید.

<dependency>
    <groupId>com.groupdocs</groupId>
    <artifactId>groupdocs-editor-cloud</artifactId>
    <version>25.7</version>
</dependency>

آخرین JARها را از صفحه دانلود دریافت کنید.
اطمینان حاصل کنید که زمان اجرا (runtime) جاوا شما نسخه 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 مستند شده‌اند.

ملاحظات عملکرد برای ویرایش Word از طریق REST

  • استفاده از استریمینگ: SDK محتوا را به صورت استریم می‌کند که مصرف heap را برای فایل‌های بزرگ DOCX کاهش می‌دهد.
  • جایگزینی‌های دسته‌ای: ترکیب چندین شیء ReplaceText در یک درخواست برای جلوگیری از تماس‌های مکرر شبکه.
  • نگه‌داشتن فایل‌ها در ابر: انجام عملیات ویرایش به‌صورت مستقیم روی فایل‌های ذخیره‌شده در ابر، هزینه بارگذاری و دانلود چندباره باینری‌های بزرگ را کاهش می‌دهد.
  • استفاده مجدد از ApiClient: یک بار ApiClient را ایجاد کنید و برای چندین عملیات ویرایش مجدداً استفاده کنید تا از مزایای استخر اتصال بهره‌مند شوید.

نتیجه‌گیری

ویرایش اسناد Word در Java به‌سادگی با GroupDocs.Editor Cloud SDK for Java امکان‌پذیر می‌شود. با دنبال کردن مراحل، مثال کد و جریان کاری cURL ارائه‌شده در اینجا، می‌توانید قابلیت‌های قدرتمند ویرایش سند را در هر سرویس بک‌اند Java یکپارچه کنید. به‌خاطر داشته باشید که اعتبارنامه‌های مشتری خود را ایمن کنید، با یک لایسنس موقت از صفحه لایسنس موقت آزمایش کنید و هنگام انتقال به محیط‌های زنده، به لایسنس تولیدی ارتقا دهید. برنامه‌نویسی خوش!

سوالات متداول

  • چگونه می‌توانم اسناد Word را در Java با استفاده از یک REST API ویرایش کنم؟
    از نقطه انتهایی editDocument در GroupDocs.Editor Cloud SDK for Java استفاده کنید. یک payload JSON که عملیات جایگزینی را تعریف می‌کند ارسال کنید، و سرویس DOCX ویرایش‌شده را برمی‌گرداند.

  • بهترین روش برای احراز هویت تماس‌ها به API ویرایشگر چیست؟
    یک شیء Configuration با شناسه مشتری و رمز مشتری خود ایجاد کنید، سپس اجازه دهید SDK به‌طور خودکار یک توکن OAuth دریافت کند. برای جزئیات بیشتر به مستندات رسمی مراجعه کنید.

  • آیا می‌توانم چندین جای‌دار را در یک درخواست جایگزین کنم؟
    بله. چندین ورودی ReplaceText را به فهرست replaceText داخل EditOptions اضافه کنید. SDK تمام جایگزینی‌ها را در یک فراخوانی ویرایشی واحد پردازش می‌کند.

  • آیا محدودیتی برای اندازهٔ فایل Word که می‌توانم ویرایش کنم وجود دارد؟
    سرویس ابری می‌تواند فایل‌ها را تا چند صد مگابایت مدیریت کند، اما برای عملکرد بهینه، فایل‌ها را زیر ۱۰۰ مگابایت نگه دارید و برای جلوگیری از افزایش ناگهانی حافظه، از دانلود استریمینگ استفاده کنید.

بیشتر بخوانید