Pré-requisitos e Configuração

Antes de começar, verifique se você tem o seguinte:

• Node.js 14 ou posterior instalado na sua máquina de desenvolvimento.
• Uma conta ativa do GroupDocs.Conversion Cloud (você pode se inscrever para um teste gratuito na página do produto).
• Seu Client ID e Client Secret do painel do GroupDocs Cloud.
• Conectividade com a Internet para chamar a API REST da nuvem.

Instale o SDK via npm:

npm install groupdocs-conversion-cloud

Baixe o pacote mais recente e visualize o código‑fonte no GitHub se precisar explorar o código:

Baixar GroupDocs.Conversion Cloud SDK for Node.js

Com o SDK instalado e as credenciais prontas, você pode prosseguir para a implementação.

Conversão de HTML para DOCX em Node.JS: Guia passo a passo

Abaixo está um tutorial conciso que mostra cada passo lógico. O código‑fonte completo é fornecido mais adiante.

Etapa 1: Inicializar o Cliente da API de Conversão

Crie uma instância de ConversionApi e configure a autenticação.

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

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

const conversionApi = new ConversionApi(config);

Etapa 2: Carregar o arquivo de origem HTML

Faça upload do arquivo HTML que você deseja converter. A API retorna um identificador de arquivo que você usará para a conversão.

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;

Passo 3: Definir opções de conversão

Configure quaisquer opções específicas de DOCX, como incorporação de fontes ou definição de margens de página. Esta etapa demonstra a personalização da Geração de DOCX a partir de HTML.

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

Etapa 4: Executar a Conversão

Chame o método convert com o ID do arquivo de origem e as configurações definidas acima.

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

Etapa 5: Baixe o DOCX resultante

Recupere o arquivo DOCX gerado e salve‑o localmente.

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

As etapas acima ilustram um fluxo de trabalho completo de conversão de HTML para DOCX em Node.JS usando o GroupDocs.Conversion Cloud SDK.

Exemplo de Código Completo: Gerando DOCX a partir de Conteúdo HTML

O programa a seguir reúne todas as partes em um único script executável.

// 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);
});

Nota: Este exemplo de código demonstra a funcionalidade principal. Antes de usá‑lo em seu projeto, certifique‑se de atualizar os caminhos dos arquivos (sample.html, output.docx), verifique se todas as dependências necessárias estão corretamente instaladas e teste minuciosamente em seu ambiente de desenvolvimento. Se encontrar algum problema, consulte a documentação oficial ou entre em contato com a equipe de suporte para obter assistência.

Executando Conversão via cURL e a API REST

Se você preferir trabalhar diretamente com HTTP, os seguintes comandos cURL realizam a mesma conversão.

1. Obter um token de acesso

Substitua YOUR_CLIENT_ID e YOUR_CLIENT_SECRET pelas suas credenciais.

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"

A resposta contém access_token.

2. Carregue o arquivo HTML

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

3. Iniciar a conversão

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

4. Baixe o DOCX convertido

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

Para uma lista completa de parâmetros, veja a documentação oficial da API.

Configurando Opções para Conversão de Conteúdo HTML para DOCX

O SDK expõe várias propriedades que permitem ajustar finamente a saída:

• embedFonts - Incorpora todas as fontes referenciadas no DOCX, garantindo fidelidade visual.
• pageSize - Define o tamanho da página (A4, Letter, etc.).
• marginTop / marginBottom / marginLeft / marginRight - Ajusta as margens da página em pontos.

Exemplo de aplicação dessas opções:

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

Consulte a classe ConversionOptions para a lista completa.

Considerações de desempenho para conversão de conteúdo HTML para DOCX

Ao converter documentos HTML grandes ou complexos, tenha em mente estas dicas:

1. Reutilizar o cliente da API - Criar uma nova instância ConversionApi para cada arquivo adiciona sobrecarga.
2. Transmitir arquivos HTML grandes - Em vez de carregar o arquivo inteiro na memória, use streams (fs.createReadStream) e o método uploadFileStream do SDK.
3. Limitar recursos incorporados - Remova imagens ou scripts desnecessários do HTML antes de fazer upload para reduzir o tempo de processamento.
4. Conversões em lote - Processar arquivos sequencialmente em um loop, mas respeitar os limites de taxa da API para evitar restrições.

Aplicar essas práticas ajuda a manter baixa latência e consumo moderado de memória.

Conclusão

A conversão de HTML para DOCX em Node.JS torna‑se simples com o GroupDocs.Conversion Cloud SDK for Node.js. Seguindo os passos acima, você pode integrar a geração confiável de DOCX a partir de HTML em qualquer aplicação server‑side, personalizar a saída e otimizar o desempenho para cargas de trabalho grandes. Lembre‑se de adquirir uma licença adequada para uso em produção; você pode comprar uma assinatura ou obter uma licença temporária na página de licença temporária. Feliz codificação!

Perguntas Frequentes

Como iniciar uma conversão de HTML para DOCX no Node.JS?

Use o SDK para criar um cliente ConversionApi, fazer upload do seu arquivo HTML, definir as opções de conversão desejadas e chamar o método convert. O processo é totalmente assíncrono e retorna o identificador do arquivo DOCX para download.

Quais opções posso ajustar para geração de DOCX a partir de HTML?

O objeto ConversionOptions permite incorporar fontes, escolher o tamanho da página, definir margens e controlar o tratamento de imagens. Consulte a referência da API para todas as configurações disponíveis.

Posso converter HTML que contém CSS externo ou imagens?

Sim. Carregue todos os recursos referenciados (CSS, imagens) na mesma pasta de armazenamento antes de iniciar a conversão, e o SDK resolverá os links durante o processamento.

Preciso de uma licença para implantações de produção?

Uma licença válida é necessária para produção. Você pode obter uma licença temporária para testes na página de licença temporária e adquirir uma assinatura completa quando estiver pronto para entrar em produção.

Read More

• Converter JSON para HTML em Node.js | Conversão de JSON para Página Web
• Exemplo passo a passo de conversão de CSV para PDF em Node.js
• Tutorial passo a passo de conversão de HTML para XLSX em PHP