Node.JS 中的逐步 HTML 转 DOCX 转换教程

Mon, 27 Jul 2026 10:59:23 +0000

将丰富的HTML页面转换为可编辑的DOCX文件是报告和文档自动化工作流中的常见需求。 GroupDocs.Conversion Cloud SDK for Node.js 使开发人员能够通过基于 REST 的库完整地执行此转换。在本教程中，您将了解如何设置 SDK、编写在 Node.JS 中执行 HTML 到 DOCX 转换的代码、使用 cURL 调用 API，以及应用配置选项以获得最佳结果。

先决条件和设置

在开始之前，请确保您具备以下内容：

在开发机器上安装 Node.js 14 或更高版本。
一个有效的 GroupDocs.Conversion Cloud 账户（您可以在产品页面上注册免费试用）。
从 GroupDocs Cloud 仪表板获取的 Client ID 和 Client Secret。
用于调用云 REST API 的互联网连接。

通过 npm 安装 SDK：

npm install groupdocs-conversion-cloud

如果您需要探索代码，请下载最新的包并在 GitHub 上查看源代码：

下载 GroupDocs.Conversion Cloud SDK for Node.js

安装好 SDK 并准备好凭据后，您可以继续进行实现。

HTML 转 DOCX 转换（Node.JS）：逐步演练

下面是一个简明的演练，展示了每个逻辑步骤。完整的源代码将在后面提供。

步骤 1：初始化 Conversion API 客户端

创建 ConversionApi 的实例并配置身份验证。

const { ConversionApi, Configuration } = require('groupdocs-conversion-cloud');

const config = new Configuration({
    clientId: 'YOUR_CLIENT_ID',
    clientSecret: 'YOUR_CLIENT_SECRET'
});

const conversionApi = new ConversionApi(config);

步骤 2：上传 HTML 源文件

上传您想要转换的 HTML 文件。API 返回一个文件标识符，您将在转换时使用它。

const fs = require('fs');
const path = require('path');

const htmlPath = path.resolve(__dirname, 'sample.html');
const fileBytes = fs.readFileSync(htmlPath);

const uploadResponse = await conversionApi.uploadFile({
    file: fileBytes,
    fileName: 'sample.html'
});
const sourceFileId = uploadResponse.id;

步骤 3：设置转换选项

配置任何 DOCX‑特定的选项，例如嵌入字体或设置页面边距。此步骤演示 DOCX 从 HTML 生成 的自定义。

const convertSettings = {
    outputFormat: 'DOCX',
    options: {
        embedFonts: true,
        pageSize: 'A4',
        marginTop: 20,
        marginBottom: 20,
        marginLeft: 15,
        marginRight: 15
    }
};

步骤 4：执行转换

使用源文件 ID 和上面定义的设置调用 convert 方法。

const convertResponse = await conversionApi.convert({
    fileId: sourceFileId,
    convertSettings: convertSettings
});
const docxFileId = convertResponse.id;

第5步：下载生成的 DOCX

检索生成的 DOCX 文件并将其保存在本地。

const docxData = await conversionApi.downloadFile({ fileId: docxFileId });
fs.writeFileSync(path.resolve(__dirname, 'output.docx'), docxData);
console.log('DOCX file saved as output.docx');

上述步骤展示了一个完整的 HTML 到 DOCX 转换（Node.JS） 工作流，使用 GroupDocs.Conversion Cloud SDK。

完整代码示例：从 HTML 内容生成 DOCX

以下程序将所有部分组合成一个可运行的脚本。

// Full working example for HTML to DOCX conversion using GroupDocs.Conversion Cloud SDK for Node.js

const { ConversionApi, Configuration } = require('groupdocs-conversion-cloud');
const fs = require('fs');
const path = require('path');

async function convertHtmlToDocx() {
    // 1. Configure the API client
    const config = new Configuration({
        clientId: 'YOUR_CLIENT_ID',
        clientSecret: 'YOUR_CLIENT_SECRET'
    });
    const conversionApi = new ConversionApi(config);

// 2. Read the HTML file
    const htmlPath = path.resolve(__dirname, 'sample.html');
    const htmlBytes = fs.readFileSync(htmlPath);

// 3. Upload the HTML file
    const uploadResult = await conversionApi.uploadFile({
        file: htmlBytes,
        fileName: 'sample.html'
    });
    const sourceFileId = uploadResult.id;

// 4. Define conversion settings
    const convertSettings = {
        outputFormat: 'DOCX',
        options: {
            embedFonts: true,
            pageSize: 'A4',
            marginTop: 20,
            marginBottom: 20,
            marginLeft: 15,
            marginRight: 15
        }
    };

// 5. Perform the conversion
    const convertResult = await conversionApi.convert({
        fileId: sourceFileId,
        convertSettings: convertSettings
    });
    const docxFileId = convertResult.id;

// 6. Download the DOCX file
    const docxBytes = await conversionApi.downloadFile({ fileId: docxFileId });
    const outputPath = path.resolve(__dirname, 'output.docx');
    fs.writeFileSync(outputPath, docxBytes);
    console.log(`Conversion successful. DOCX saved to ${outputPath}`);
}

// Execute the conversion
convertHtmlToDocx().catch(err => {
    console.error('Conversion failed:', err);
});

注意： 此代码示例演示了核心功能。在项目中使用之前，请确保更新文件路径（sample.html、output.docx），验证所有必需的依赖项已正确安装，并在开发环境中进行彻底测试。如果遇到任何问题，请参阅官方文档或联系支持团队获取帮助。

通过 cURL 和 REST API 执行转换

如果您更喜欢直接使用 HTTP，以下 cURL 命令执行相同的转换。

获取访问令牌

将 YOUR_CLIENT_ID 和 YOUR_CLIENT_SECRET 替换为您的凭据。

curl -X POST "https://api.groupdocs.cloud/v2.0/oauth2/token" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET"

响应中包含 access_token。

上传 HTML 文件

curl -X POST "https://api.groupdocs.cloud/v2.0/storage/files/sample.html" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -F "file=@sample.html"

开始转换

curl -X POST "https://api.groupdocs.cloud/v2.0/conversion/convert" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
           "sourceFilePath": "sample.html",
           "outputFilePath": "output.docx",
           "outputFormat": "DOCX",
           "options": {
               "embedFonts": true,
               "pageSize": "A4"
           }
         }'

下载已转换的 DOCX

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

有关参数的完整列表，请参阅官方 API 文档。

配置 HTML 内容转换为 DOCX 的选项

SDK 提供了多个属性，让您可以微调输出：

embedFonts - 将所有引用的字体嵌入 DOCX，确保视觉保真度。
pageSize - 设置页面大小（A4、Letter 等）。
marginTop / marginBottom / marginLeft / marginRight - 调整页面边距（单位为点）。

应用这些选项的示例：

const convertSettings = {
    outputFormat: 'DOCX',
    options: {
        embedFonts: true,
        pageSize: 'Letter',
        marginTop: 30,
        marginBottom: 30,
        marginLeft: 20,
        marginRight: 20
    }
};

请参阅 ConversionOptions class 以获取完整列表。

HTML 内容转换为 DOCX 的性能考虑

在转换大型或复杂的 HTML 文档时，请记住以下提示：

重复使用 API 客户端 - 为每个文件创建新的 ConversionApi 实例会增加开销。
流式处理大型 HTML 文件 - 不要将整个文件加载到内存中，使用流 (fs.createReadStream) 并使用 SDK 的 uploadFileStream 方法。
限制嵌入资源 - 在上传之前从 HTML 中移除不必要的图片或脚本，以减少处理时间。
批量转换 - 在循环中顺序处理文件，但要遵守 API 速率限制，以避免被限流。

应用这些实践有助于保持低延迟和适度的内存消耗。

结论

HTML to DOCX conversion in Node.JS becomes straightforward with the GroupDocs.Conversion Cloud SDK for Node.js. 按照上述步骤操作，您可以将可靠的 HTML 转 DOCX 生成功能集成到任何服务器端应用程序中，定制输出，并针对大批量工作负载优化性能。请记得为生产环境获取合适的许可证；您可以购买订阅或从临时许可证页面获取临时许可证。祝编码愉快！

FAQs

如何在 Node.JS 中启动 HTML 到 DOCX 的转换？

使用 SDK 创建 ConversionApi 客户端，上传您的 HTML 文件，设置所需的转换选项，然后调用 convert 方法。该过程是完全异步的，并返回用于下载的 DOCX 文件标识符。

我可以为从 HTML 生成 DOCX 调整哪些选项？

ConversionOptions 对象允许您嵌入字体、选择页面大小、设置边距并控制图像处理。请参阅 API 参考了解所有可用设置。

我可以转换包含外部 CSS 或图像的 HTML 吗？

是的。在开始转换之前，将所有引用的资源（CSS、图像）上传到同一存储文件夹，SDK 将在处理期间解析这些链接。

在生产部署中需要许可证吗？

在生产环境中需要有效的许可证。您可以从临时许可证页面获取用于测试的临时许可证，并在准备上线时购买完整订阅。

nodejs html docx on Document Processing REST APIs | GroupDocs Cloud