将 DOCX 文档转换为 HTML 是在构建基于 Web 的报告或内容管理解决方案时的常见需求。 GroupDocs.Conversion Cloud SDK for Python 使开发人员能够仅通过少量 API 调用在 Python 中自动执行 DOCX 到 HTML 的转换。在本教程中，您将设置 SDK，逐步实现，并查看完整的代码示例，学习如何为响应式网页微调输出。

Python 中 DOCX 转 HTML 转换的要求

构建文档驱动的 Web 应用程序的开发人员通常会从用户那里接收 DOCX 文件，并需要在浏览器中即时显示其内容。典型的需求包括：

  • 保持原始样式、表格和图像，同时渲染为 HTML。
  • 生成能够适应不同屏幕尺寸的标记，而无需额外的 CSS 工作。
  • 在服务器端环境中执行转换，无需安装大型办公套件。

使用桌面工具或开源库进行手动转换可能容易出错，尤其是对于复杂布局，并且无法满足大批量 API 驱动工作负载的扩展需求。

方法：自动将 DOCX 转换为 HTML

GroupDocs.Conversion Cloud SDK for Python 提供基于云的 API，处理格式转换的繁重工作。符合需求的关键功能包括：

  • 保留样式 - 引擎保持字体、颜色和段落格式完整。
  • 响应式 HTML 输出 - 内置选项生成适合移动设备的流式布局。
  • 可扩展的 REST 接口 - 您可以从任何 Python 应用程序调用该服务，而无需管理本地转换二进制文件。

有关详细的 API 用法，请参阅官方文档和API 参考。

构建解决方案：在 Python 中将 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），验证所有必需的依赖项已正确安装，并在开发环境中彻底测试。如果遇到任何问题，请参阅官方文档或联系支持团队获取帮助。

使用 cURL 和 REST API 自动化 DOCX 到 HTML 的转换

您可以通过对 REST 端点使用 cURL 命令，而无需编写 Python 代码，来执行相同的转换。

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

响应返回一个包含生成的 HTML 文件 path 的 JSON 对象。

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 的质量和大小。

  • Responsive flag - html_options.responsive = True 添加一个适配视口的 CSS 包装器。
  • Embed fonts - html_options.embed_fonts = True 确保自定义字体以 base64 数据形式包含。
  • Preserve images - html_options.extract_images = False 将图像保持内联，而不是创建单独的文件。
  • Custom CSS - 您可以通过 html_options.css 提供 CSS 字符串，以应用站点范围的样式。

设置自定义 CSS 字符串的示例：

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

根据您的 Web 前端需求调整这些设置。

结论

GroupDocs.Conversion Cloud SDK for Python 使在 Python 中将 DOCX 转换为 HTML 变得简单、可靠且可扩展。按照上述步骤，您可以将自动化转换集成到任何后端服务中，生成响应式标记，并对样式和资源保持完全控制。请记得为生产使用获取合适的许可证；产品页面上提供了定价详情，您还可以获取用于评估的临时许可证页面。有了该 SDK，从 DOCX 源生成丰富的 HTML 预览将成为您应用工作流的常规部分。

常见问题

  • 如何在 Python 中使用 GroupDocs 执行 DOCX 到 HTML 的转换？
    使用 GroupDocs.Conversion Cloud SDK for Python 中的 Convert API，配置 HtmlOptions 以获得响应式输出，并调用 convert_document。SDK 会返回生成的 HTML 文件的 URL。

  • 是否可以使 HTML 输出对移动设备友好？
    是的，设置 html_options.responsive = True。SDK 会注入 CSS，自动将布局适配不同的屏幕宽度。

  • SDK 需要什么身份验证机制？
    SDK 使用 OAuth 客户端凭证流程。在创建 API 实例之前，在 Configuration 对象中提供您的 client_id 和 client_secret。

  • DOCX 文件是否有大小限制？
    云服务接受的文件最大为 100 MB 用于转换。较大的文档应在上传前拆分或分块处理。

阅读更多