تحويل مستندات DOCX إلى HTML هو حاجة متكررة عند بناء حلول تقارير أو إدارة محتوى تعتمد على الويب. GroupDocs.Conversion Cloud SDK for Python يتيح للمطورين أتمتة تحويل DOCX إلى HTML في بايثون ببضع استدعاءات API فقط. في هذا البرنامج التعليمي ستقوم بإعداد SDK، وتستعرض تنفيذًا خطوة بخطوة، وتطلع على مثال شفرة كامل، وتتعلم كيفية ضبط المخرجات لتناسب صفحات الويب المتجاوبة.

متطلبات تحويل DOCX إلى HTML في بايثون

يقوم المطورون الذين يبنون تطبيقات ويب مدفوعة بالمستندات غالبًا باستلام ملفات DOCX من المستخدمين ويحتاجون إلى عرض محتواها فورًا في المتصفحات. المتطلبات النموذجية هي:

  • حافظ على التنسيق الأصلي والجداول والصور أثناء التحويل إلى HTML.
  • أنشئ تعليمات ترميز تتكيف مع أحجام الشاشات المختلفة دون الحاجة إلى عمل إضافي على CSS.
  • قم بإجراء التحويل في بيئة خادمة (server‑side) دون تثبيت حزم أوفيس الثقيلة.

يمكن أن تكون عملية التحويل اليدوي باستخدام أدوات سطح المكتب أو المكتبات المفتوحة المصدر عرضة للأخطاء، خاصةً بالنسبة للتصاميم المعقدة، ولا تتناسب مع أحمال العمل ذات الحجم الكبير المدفوعة عبر API.

النهج: تحويل DOCX إلى HTML تلقائيًا

GroupDocs.Conversion Cloud SDK for Python يقدم واجهة برمجة تطبيقات سحابية تتعامل مع التحويل الثقيل للملفات. القدرات الرئيسية التي تتطابق مع المتطلبات هي:

  • الحفاظ على التنسيق - يحتفظ المحرك بالخطوط والألوان وتنسيق الفقرات كما هو.
  • إخراج HTML متجاوب - الخيارات المدمجة تولد تخطيطات سائلة مناسبة للأجهزة المحمولة.
  • واجهة REST قابلة للتوسع - يمكنك استدعاء الخدمة من أي تطبيق Python دون إدارة ملفات التحويل المحلية.

للاطلاع على تفاصيل استخدام API راجع التوثيق الرسمي ومرجع API.

بناء الحل: تحويل DOCX إلى HTML باستخدام Python

تثبيت 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

يمكنك إجراء التحويل نفسه دون كتابة كود بايثون باستخدام أوامر 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 الذي ستستخدمه في المكالمات اللاحقة.

2. تحميل ملف 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 يضيف غلاف CSS متوافق مع عرض الشاشة.
  • تضمين الخطوط - 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 في بايثون بسيطًا، موثوقًا، وقابلًا للتوسع. باتباع الخطوات أعلاه يمكنك دمج التحويل الآلي في أي خدمة خلفية، إنشاء تعليمات HTML متجاوبة، والحفاظ على التحكم الكامل في التصميم والملفات. تذكر الحصول على ترخيص مناسب للاستخدام في الإنتاج؛ تفاصيل التسعير متاحة على صفحة المنتج ويمكنك الحصول على صفحة الترخيص المؤقت للتقييم. مع وجود SDK، يصبح تقديم معاينات HTML غنية من مصادر DOCX جزءًا روتينيًا من سير عمل تطبيقك.

FAQs

  • كيف يمكنني إجراء تحويل DOCX إلى HTML في بايثون باستخدام GroupDocs؟
    استخدم Convert API من GroupDocs.Conversion Cloud SDK for Python، قم بتكوين HtmlOptions للحصول على مخرجات مستجيبة، واستدعِ convert_document. تُعيد مجموعة الأدوات عنوان URL للملف HTML المُنشأ.

  • هل من الممكن جعل مخرجات HTML صديقة للهواتف المحمولة؟
    نعم، قم بتعيين html_options.responsive = True. يقوم SDK بحقن CSS يتكيف تلقائيًا مع تخطيط الشاشة لأحجام عرض مختلفة.

  • ما آلية المصادقة التي يتطلبها SDK؟
    يستخدم SDK تدفق OAuth client‑credentials. قدم client_id و client_secret في كائن Configuration قبل إنشاء مثيلات API.

  • هل هناك حدود لحجم ملفات DOCX؟
    تقبل خدمة السحابة ملفات تصل إلى 100 ميغابايت للتحويل. يجب تقسيم المستندات الكبيرة أو معالجتها على دفعات قبل التحميل.

اقرأ المزيد