پیش‌نیازها و راه‌اندازی

قبل از شروع، مطمئن شوید که موارد زیر را دارید:

• جاوا 8 یا بالاتر نصب شده است.
• یک IDE مانند IntelliJ IDEA یا Eclipse.
• یک حساب GroupDocs Cloud با Client Id و Client Secret شما.
• Maven برای مدیریت وابستگی‌ها.

SDK را با وابستگی Maven زیر به پروژه خود اضافه کنید. همچنین می‌توانید آخرین JAR را از صفحه دانلود دریافت کنید.

<dependency>
    <groupId>com.groupdocs</groupId>
    <artifactId>groupdocs-conversion-cloud</artifactId>
    <version>26.8</version>
</dependency>

اعتبارهای خود را پیکربندی کنید تا SDK بتواند با ابر GroupDocs احراز هویت کند:

Configuration config = new Configuration();
config.setClientId("YOUR_CLIENT_ID");
config.setClientSecret("YOUR_CLIENT_SECRET");

با آماده بودن SDK، می‌توانید به پیاده‌سازی بروید. بخش بعدی هر خط از کدی را که برای انجام تبدیل DOCX به MD نیاز دارید، تجزیه و تحلیل می‌کند.

تبدیل DOCX به MD در جاوا: راهنمای گام به گام

در زیر یک راهنمای دقیق از فرآیند تبدیل آورده شده است. هر گام با یک قطعه کد کوچک که از مثال کامل گرفته شده است، مطابقت دارد.

مرحله 1: پیکربندی اعتبارهای API

یک شیء Configuration ایجاد کنید و اعتبارهای مشتری خود را فراهم کنید.

Configuration config = new Configuration();
config.setClientId("YOUR_CLIENT_ID");
config.setClientSecret("YOUR_CLIENT_SECRET");

مرحله ۲: تعریف گزینه‌های تبدیل به Markdown

فایل منبع DOCX، فایل هدف MD را تنظیم کنید و حفظ قالب‌بندی را فعال کنید.

MarkdownConvertOptions options = new MarkdownConvertOptions();
options.setFilePath("input.docx");
options.setOutputPath("output.md");
options.setPreserveOriginalFormatting(true);

مرحله 3: مقداردهی اولیه API تبدیل

یک شیء ConversionApi را با پیکربندی‌ای که ایجاد کرده‌اید، نمونه‌سازی کنید.

ConversionApi conversionApi = new ConversionApi(config);

مرحله ۴: ایجاد و ارسال درخواست تبدیل

گزینه‌ها را در یک ConvertDocumentRequest بپیچید و متد تبدیل را فراخوانی کنید.

ConvertDocumentRequest request = new ConvertDocumentRequest(options);
ConvertResult result = conversionApi.convertDocument(request);

مرحله 5: پردازش نتیجه تبدیل

نتیجه را بررسی کنید و مسیر فایل Markdown تولید شده را خروجی دهید.

System.out.println("Conversion completed successfully. Output file: " + result.getPath());

برای جزئیات بیشتر در مورد کلاس‌های استفاده‌شده، به مرجع API مراجعه کنید.

مثال کامل کد: خروجی مارک‌داون با حفظ قالب‌بندی

قطعه کد زیر برنامه کامل و آماده‑به‑اجرا را نشان می‌دهد که یک فایل DOCX را به مارک‌داون تبدیل می‌کند در حالی که قالب‌بندی اصلی را حفظ می‌کند.

import com.groupdocs.cloud.conversion.api.ConversionApi;
import com.groupdocs.cloud.conversion.client.Configuration;
import com.groupdocs.cloud.conversion.model.MarkdownConvertOptions;
import com.groupdocs.cloud.conversion.model.ConvertResult;
import com.groupdocs.cloud.conversion.model.requests.ConvertDocumentRequest;

public class DocxToMarkdownExample {
    public static void main(String[] args) {
        // Configure API client (replace with your actual credentials)
        Configuration config = new Configuration();
        config.setClientId("YOUR_CLIENT_ID");
        config.setClientSecret("YOUR_CLIENT_SECRET");

// Initialize Conversion API
        ConversionApi conversionApi = new ConversionApi(config);

// Set conversion options for DOCX → Markdown
        MarkdownConvertOptions options = new MarkdownConvertOptions();
        options.setFilePath("input.docx");          // source DOCX file in storage
        options.setOutputPath("output.md");         // target Markdown file in storage
        options.setPreserveOriginalFormatting(true); // keep formatting where possible

// Create request object
        ConvertDocumentRequest request = new ConvertDocumentRequest(options);

try {
            // Execute conversion
            ConvertResult result = conversionApi.convertDocument(request);
            System.out.println("Conversion completed successfully. Output file: " + result.getPath());
        } catch (Exception e) {
            System.err.println("Conversion failed: " + e.getMessage());
            e.printStackTrace();
        }
    }
}

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

انجام تبدیل DOCX به MD با cURL و REST API

اگر ترجیح می‌دهید از روش صرفاً HTTP استفاده کنید، همان تبدیل می‌تواند با دستورات cURL انجام شود. در زیر یک جریان کاری حداقل آورده شده است.

ابتدا یک توکن دسترسی OAuth2 دریافت کنید:

curl -X POST "https://api.groupdocs.cloud/v2.0/oauth2/token" \
     -H "Content-Type: application/json" \
     -d '{"client_id":"YOUR_CLIENT_ID","client_secret":"YOUR_CLIENT_SECRET","grant_type":"client_credentials"}'

فرض کنید پاسخ شامل "access_token":"YOUR_ACCESS_TOKEN" باشد، فایل DOCX را بارگذاری کنید:

curl -X PUT "https://api.groupdocs.cloud/v2.0/storage/file/input.docx" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -H "Content-Type: application/octet-stream" \
     --data-binary @input.docx

درخواست تبدیل به Markdown:

curl -X POST "https://api.groupdocs.cloud/v2.0/conversion/convert" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
           "outputPath":"output.md",
           "format":"MD",
           "preserveOriginalFormatting":true,
           "filePath":"input.docx"
         }'

در نهایت، فایل Markdown تولید شده را دانلود کنید:

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

برای دریافت فهرست کامل پارامترها، به مستندات رسمی API مراجعه کنید.

تنظیم دقیق گزینه‌های تبدیل DOCX به MD

SDK چندین گزینه ارائه می‌دهد که می‌توانید برای کنترل خروجی تنظیم کنید.

• PreserveOriginalFormatting - عناوین، فهرست‌ها، جدول‌ها و سایر سبک‌ها را حفظ می‌کند.

options.setPreserveOriginalFormatting(true);

• OutputPath - مسیر ذخیره‌سازی فایل Markdown در فضای ابری شما را تعریف می‌کند.

options.setOutputPath("output.md");

• تنظیمات سفارشی مارک‌داون - می‌توانید با استفاده از ویژگی‌های اضافی در MarkdownConvertOptions، شکست خطوط، مدیریت بلوک‌های کد و موارد مشابه را تنظیم کنید (به مرجع API مراجعه کنید).

با این تنظیمات آزمایش کنید تا ظاهر دقیق مورد نیاز خود را در فایل MD نهایی به دست آورید.

ملاحظات عملکرد برای تبدیل DOCX به MD

هنگام تبدیل اسناد متعدد یا فایل‌های بزرگ، این نکات را در نظر بگیرید:

1. دوباره استفاده از نمونه ConversionApi - ایجاد کلاینت یک‌بار و دوباره استفاده از آن از هزینهٔ تکراری احراز هویت جلوگیری می‌کند.
2. جریان‌سازی فایل‌ها به جای بارگذاری کل اسناد در حافظه - SDK از جریان‌سازی برای فایل‌های بزرگ DOCX پشتیبانی می‌کند و مصرف حافظه heap را کاهش می‌دهد.
3. بارگذاری‌های دسته‌ای - در صورت امکان چندین فایل DOCX را در یک درخواست بارگذاری کنید، سپس تبدیل‌ها را در یک حلقه فعال کنید.
4. تنظیم همزمانی - از یک استخر رشته‌ها برای اجرای همزمان چندین تبدیل استفاده کنید، اما محدودیت‌های نرخ API را نظارت کنید.

به‌کارگیری این روش‌ها به شما کمک می‌کند تا فرآیند تبدیل DOCX به MD را به‌صورت کارآمد مقیاس‌پذیر کنید.

نتیجه‌گیری

تبدیل DOCX به MD در جاوا به‌صورت ساده‌ای با GroupDocs.Conversion Cloud SDK for Java امکان‌پذیر است. با دنبال کردن مراحل تنظیم، استفاده از مثال کد ارائه‌شده، یا فراخوانی REST API با cURL، می‌توانید خطوط لوله مستندسازی را خودکار کنید در حالی که قالب‌بندی حفظ می‌شود. به یاد داشته باشید گزینه‌های مجوزدهی را مرور کنید؛ SDK تحت یک مجوز تجاری در دسترس است و می‌توانید برای ارزیابی، یک مجوز موقت از صفحه مجوز موقت دریافت کنید. امروز تبدیل DOCX به MD را یکپارچه کنید و جریان کار محتوای خود را بهینه‌سازی کنید.

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

چگونه می‌توانم DOCX را به MD در جاوا تبدیل کنم بدون از دست دادن قالب‌بندی؟
در MarkdownConvertOptions مقدار preserveOriginalFormatting را به true تنظیم کنید. SDK سعی خواهد کرد تا عناوین، جدول‌ها و فهرست‌ها را در طول تبدیل دست‌نخورده نگه دارد.

آیا امکان تبدیل چندین فایل DOCX به MD در یک اجرا وجود دارد؟
بله. لیست فایل‌های خود را به‌صورت حلقه‌ای پردازش کنید، از همان نمونه ConversionApi استفاده مجدد کنید و برای هر فایل convertDocument را فراخوانی کنید. این رویکرد بار اضافی را کاهش داده و سرعت پردازش دسته‌ای را افزایش می‌دهد.

روش احراز هویت مورد نیاز API REST برای تبدیل DOCX به MD چیست؟
API از جریان client‑credentials OAuth2 استفاده می‌کند. یک توکن دسترسی با شناسه کلاینت و راز خود دریافت کنید، سپس آن را در هدر Authorization: Bearer برای تمام درخواست‌های بعدی گنجانید.

آیا می‌توانم سبک خروجی Markdown (مثلاً قفسه‌های کد، کاراکترهای بولت) را سفارشی کنم؟
کلاس MarkdownConvertOptions چندین ویژگی برای تنظیم دقیق سینتکس Markdown ارائه می‌دهد. برای لیست کامل گزینه‌های قابل پیکربندی به API reference مراجعه کنید.

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

• تبدیل Word به JPG در Java - DOCX به JPG با استفاده از Java REST API
• تبدیل JSON به HTML در Java - مبدل JSON به HTML
• تبدیل PDF به PowerPoint با Java - PDF به PPT در Java