تبدیل فایلهای DOCX به Markdown یک نیاز مکرر برای توسعهدهندگانی است که به مستندات سبک وزن و سازگار با کنترل نسخه نیاز دارند. GroupDocs.Conversion Cloud SDK for Java کتابخانهای قدرتمند فراهم میکند که بار سنگین را در سمت سرور بر عهده میگیرد. در این راهنما خواهید آموخت که چگونه DOCX را به MD در جاوا تبدیل کنید، SDK را تنظیم کنید، کد را قدم به قدم بررسی کنید، از REST API با cURL استفاده کنید و گزینهها را بهدقت تنظیم کنید تا قالببندی حفظ شود.
پیشنیازها و راهاندازی
قبل از شروع، مطمئن شوید که موارد زیر را دارید:
- جاوا 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
هنگام تبدیل اسناد متعدد یا فایلهای بزرگ، این نکات را در نظر بگیرید:
- دوباره استفاده از نمونه
ConversionApi- ایجاد کلاینت یکبار و دوباره استفاده از آن از هزینهٔ تکراری احراز هویت جلوگیری میکند. - جریانسازی فایلها به جای بارگذاری کل اسناد در حافظه - SDK از جریانسازی برای فایلهای بزرگ DOCX پشتیبانی میکند و مصرف حافظه heap را کاهش میدهد.
- بارگذاریهای دستهای - در صورت امکان چندین فایل DOCX را در یک درخواست بارگذاری کنید، سپس تبدیلها را در یک حلقه فعال کنید.
- تنظیم همزمانی - از یک استخر رشتهها برای اجرای همزمان چندین تبدیل استفاده کنید، اما محدودیتهای نرخ 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 مراجعه کنید.