تبدیل اسناد DOCX به HTML یک نیاز مکرر هنگام ساخت راه‌حل‌های گزارش‌گیری مبتنی بر وب یا مدیریت محتوا است. GroupDocs.Conversion Cloud SDK for Python به توسعه‌دهندگان امکان می‌دهد تا تبدیل DOCX به HTML را در پایتون با تنها چند فراخوانی API خودکار کنند. در این آموزش، شما SDK را تنظیم می‌کنید، پیاده‌سازی گام‌به‌گام را مرور می‌کنید، یک مثال کامل کد را می‌بینید و یاد می‌گیرید چگونه خروجی را برای صفحات وب واکنش‌گرا به‌دقت تنظیم کنید.

نیازمندی‌های تبدیل DOCX به HTML در پایتون

توسعه‌دهندگانی که برنامه‌های وب مبتنی بر اسناد می‌سازند، اغلب فایل‌های DOCX را از کاربران دریافت می‌کنند و نیاز دارند محتوای آن‌ها را به‌سرعت در مرورگرها نمایش دهند. نیازهای معمول عبارتند از:

  • حفظ استایل اصلی، جدول‌ها و تصاویر هنگام رندر به HTML.
  • تولید مارکاپی که به اندازه‌های مختلف صفحه نمایش سازگار باشد بدون نیاز به کار اضافی با CSS.
  • انجام تبدیل در محیط سرور‑ساید بدون نصب مجموعه‌های اداری سنگین.

تبدیل دستی با استفاده از ابزارهای دسکتاپ یا کتابخانه‌های منبع باز می‌تواند مستعد خطا باشد، به‌ویژه برای طرح‌های پیچیده، و برای بارهای کاری با حجم بالا که توسط API هدایت می‌شوند، مقیاس‌پذیر نیست.

رویکرد: تبدیل خودکار DOCX به HTML

GroupDocs.Conversion Cloud SDK for Python یک API مبتنی بر ابر ارائه می‌دهد که بار سنگین تبدیل فرمت‌ها را بر عهده می‌گیرد. قابلیت‌های کلیدی که با الزامات مطابقت دارند عبارتند از:

  • حفظ استایل - موتور فونت‌ها، رنگ‌ها و قالب‌بندی پاراگراف‌ها را به همان صورت نگه می‌دارد.
  • خروجی HTML واکنش‌گرا - گزینه‌های داخلی طرح‌های سیال مناسب برای دستگاه‌های موبایل تولید می‌کنند.
  • رابط REST مقیاس‌پذیر - می‌توانید سرویس را از هر برنامه Python بدون مدیریت باینری‌های تبدیل محلی صدا بزنید.

برای استفاده دقیق از API به مستندات رسمی و مرجع API مراجعه کنید.

ساخت راه‌حل: تبدیل DOCX به HTML در پایتون

نصب SDK و وارد کردن کلاس‌های مورد نیاز

pip install groupdocs-conversion-cloud

from groupdocs_conversion_cloud import (
    ConvertApi, ConvertSettings, HtmlOptions,
    StorageApi, FileInfo, Configuration, ApiClient
)

پیکربندی کلاینت API با اعتبارها

config = Configuration()
config.client_id = "YOUR_CLIENT_ID"
config.client_secret = "YOUR_CLIENT_SECRET"

api_client = ApiClient(configuration=config)
convert_api = ConvertApi(api_client)
storage_api = StorageApi(api_client)

بارگذاری فایل منبع DOCX

# Assume 'sample.docx' is in the local folder
with open("sample.docx", "rb") as file:
    storage_api.upload_file(path="input/sample.docx", file=file)

تبدیل DOCX به HTML واکنش‌گرا

file_info = FileInfo()
file_info.file_path = "input/sample.docx"

html_options = HtmlOptions()
html_options.responsive = True          # Enable responsive layout
html_options.embed_fonts = True         # Embed custom fonts if any

convert_settings = ConvertSettings()
convert_settings.file_info = file_info
convert_settings.format = "html"
convert_settings.options = html_options

result = convert_api.convert_document(convert_settings)
# The result contains the URL of the generated HTML file
print("HTML file URL:", result.path)

دانلود فایل HTML تولید شده

output_path = "output/sample.html"
with open(output_path, "wb") as out_file:
    storage_api.download_file(path=result.path, out_file=out_file)
print("HTML saved to:", output_path)

مثال کامل کد: تبدیل DOCX به HTML با خروجی واکنش‌گرا

اسکریپت زیر تمام مراحل را در یک برنامه قابل اجرا ترکیب می‌کند.

from groupdocs_conversion_cloud import (
    ConvertApi, ConvertSettings, HtmlOptions,
    StorageApi, FileInfo, Configuration, ApiClient
)

def main():
    # 1. Configure the client
    config = Configuration()
    config.client_id = "YOUR_CLIENT_ID"
    config.client_secret = "YOUR_CLIENT_SECRET"

api_client = ApiClient(configuration=config)
    convert_api = ConvertApi(api_client)
    storage_api = StorageApi(api_client)

# 2. Upload DOCX file
    local_file = "sample.docx"
    remote_path = "input/sample.docx"
    with open(local_file, "rb") as f:
        storage_api.upload_file(path=remote_path, file=f)

# 3. Prepare conversion settings
    file_info = FileInfo()
    file_info.file_path = remote_path

html_options = HtmlOptions()
    html_options.responsive = True
    html_options.embed_fonts = True

settings = ConvertSettings()
    settings.file_info = file_info
    settings.format = "html"
    settings.options = html_options

# 4. Execute conversion
    result = convert_api.convert_document(settings)
    print("Conversion completed. HTML URL:", result.path)

# 5. Download the HTML result
    output_file = "sample_converted.html"
    with open(output_file, "wb") as out:
        storage_api.download_file(path=result.path, out_file=out)
    print("HTML saved to:", output_file)

if __name__ == "__main__":
    main()

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

اتوماتیک‌سازی تبدیل DOCX به HTML با cURL و REST API

می‌توانید همان تبدیل را بدون نوشتن کد Python با استفاده از دستورات cURL در برابر نقطه انتهایی REST انجام دهید.

1. دریافت توکن دسترسی

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"}'

پاسخ شامل access_token است که در تماس‌های بعدی از آن استفاده خواهید کرد.

۲. بارگذاری فایل DOCX

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

3. درخواست تبدیل DOCX به HTML واکنش‌گرا

curl -X POST "https://api.groupdocs.cloud/v2.0/conversion/convert" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
    "fileInfo": { "filePath": "input/sample.docx" },
    "format": "html",
    "options": { "responsive": true, "embedFonts": true }
}'

پاسخ یک شیء JSON را برمی‌گرداند که شامل path فایل HTML تولید شده است.

4. دانلود نتیجه HTML

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

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

تنظیمات دقیق تبدیل DOCX به HTML واکنش‌گرا

SDK چندین گزینه را ارائه می‌دهد که به شما امکان کنترل کیفیت و اندازه HTML تولید شده را می‌دهد.

  • پرچم واکنش‌گرا - html_options.responsive = True یک wrapper CSS سازگار با viewport اضافه می‌کند.
  • جاسازی قلم‌ها - html_options.embed_fonts = True اطمینان می‌دهد قلم‌های سفارشی به‌صورت داده base64 گنجانده شوند.
  • حفظ تصاویر - html_options.extract_images = False تصاویر را به‌صورت درون‌خطی نگه می‌دارد به‌جای ایجاد فایل‌های جداگانه.
  • CSS سفارشی - می‌توانید یک رشته CSS را از طریق html_options.css ارائه دهید تا استایل‌گذاری سراسری سایت اعمال شود.

مثال برای تنظیم یک رشته CSS سفارشی:

custom_css = "body {font-family: Arial, sans-serif; line-height: 1.6;}"
html_options.css = custom_css

این تنظیمات را بر اساس نیازهای رابط کاربری وب خود تنظیم کنید.

نتیجه‌گیری

GroupDocs.Conversion Cloud SDK for Python تبدیل DOCX به HTML در پایتون را ساده، قابل اعتماد و مقیاس‌پذیر می‌کند. با دنبال کردن مراحل بالا می‌توانید تبدیل خودکار را در هر سرویس بک‌اندی یکپارچه کنید، نشانه‌گذاری واکنش‌گرا تولید کنید و کنترل کامل بر استایل‌ها و دارایی‌ها داشته باشید. به‌خاطر داشته باشید که برای استفاده در محیط تولید یک لایسنس مناسب تهیه کنید؛ جزئیات قیمت‌گذاری در صفحه محصول موجود است و می‌توانید برای ارزیابی یک صفحه لایسنس موقت دریافت کنید. با داشتن SDK، ارائه پیش‌نمایش‌های غنی HTML از منابع DOCX به بخشی روتین از جریان کاری برنامه شما تبدیل می‌شود.

FAQs

  • چگونه می‌توانم تبدیل DOCX به HTML را در پایتون با استفاده از GroupDocs انجام دهم؟
    از Convert API موجود در GroupDocs.Conversion Cloud SDK for Python استفاده کنید، HtmlOptions را برای خروجی واکنش‌گرا پیکربندی کنید و convert_document را فراخوانی کنید. SDK یک URL به فایل HTML تولید شده برمی‌گرداند.

  • آیا می‌توان خروجی HTML را برای موبایل‌دوست کرد؟
    بله، html_options.responsive = True را تنظیم کنید. SDK CSS را تزریق می‌کند که به‌طور خودکار طرح‌بندی را با عرض‌های مختلف صفحه سازگار می‌کند.

  • SDK چه مکانیزم احراز هویتی را می‌طلبد؟
    SDK از جریان OAuth client‑credentials استفاده می‌کند. client_id و client_secret خود را در شیء Configuration قبل از ایجاد نمونه‌های API فراهم کنید.

  • آیا برای فایل‌های DOCX محدودیت اندازه وجود دارد؟
    سرویس ابری فایل‌ها را تا ۱۰۰ MB برای تبدیل می‌پذیرد. اسناد بزرگ‌تر باید قبل از بارگذاری به بخش‌های کوچک تقسیم یا به صورت تکه‌تکه پردازش شوند.

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