Konwertowanie bogatych stron HTML na edytowalne pliki DOCX jest częstą potrzebą w procesach raportowania i automatyzacji dokumentów. GroupDocs.Conversion Cloud SDK for Node.js umożliwia programistom wykonanie tej konwersji w pełni za pomocą biblioteki opartej na REST. W tym samouczku zobaczysz, jak skonfigurować SDK, napisać kod Node.JS, który wykonuje konwersję HTML do DOCX w Node.JS, używać cURL do wywoływania API oraz zastosować opcje konfiguracji dla optymalnych wyników.

Wymagania wstępne i konfiguracja

Zanim rozpoczniesz, upewnij się, że masz następujące:

  • Zainstalowany Node.js 14 lub nowszy na maszynie deweloperskiej.
  • Aktywne konto GroupDocs.Conversion Cloud (możesz zarejestrować się na bezpłatny okres próbny na stronie produktu).
  • Twoje Client ID i Client Secret z pulpitu nawigacyjnego GroupDocs Cloud.
  • Łączność internetowa niezbędna do wywoływania interfejsu REST API w chmurze.

Zainstaluj SDK za pomocą npm:

npm install groupdocs-conversion-cloud

Pobierz najnowszy pakiet i przeglądaj źródło na GitHubie, jeśli potrzebujesz zbadać kod:

Pobierz GroupDocs.Conversion Cloud SDK for Node.js

Po zainstalowaniu SDK i przygotowaniu danych uwierzytelniających możesz przejść do implementacji.

Konwersja HTML do DOCX w Node.JS: Przewodnik krok po kroku

Poniżej znajduje się zwięzły przewodnik, który pokazuje każdy logiczny krok. Pełny kod źródłowy zostanie podany później.

Krok 1: Zainicjuj klienta API konwersji

Utwórz instancję ConversionApi i skonfiguruj uwierzytelnianie.

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

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

const conversionApi = new ConversionApi(config);

Krok 2: Prześlij plik źródłowy HTML

Prześlij plik HTML, który chcesz przekonwertować. API zwraca identyfikator pliku, którego użyjesz do konwersji.

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;

Krok 3: Ustaw opcje konwersji

Skonfiguruj dowolne opcje specyficzne dla DOCX, takie jak osadzanie czcionek lub ustawianie marginesów strony. Ten krok demonstruje Generowanie DOCX z HTML dostosowanie.

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

Krok 4: Wykonaj konwersję

Wywołaj metodę convert z identyfikatorem pliku źródłowego i ustawieniami zdefiniowanymi powyżej.

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

Krok 5: Pobierz wynikowy DOCX

Pobierz wygenerowany plik DOCX i zapisz go lokalnie.

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

Powyższe kroki ilustrują kompletny konwersję HTML do DOCX w Node.JS workflow przy użyciu GroupDocs.Conversion Cloud SDK.

Pełny przykład kodu: Generowanie DOCX z treści HTML

Poniższy program łączy wszystkie elementy w jeden, uruchamialny skrypt.

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

Uwaga: Ten przykład kodu demonstruje podstawową funkcjonalność. Przed użyciem go w swoim projekcie upewnij się, że zaktualizowałeś ścieżki do plików (sample.html, output.docx), sprawdziłeś, czy wszystkie wymagane zależności są poprawnie zainstalowane, oraz dokładnie przetestowałeś w środowisku deweloperskim. Jeśli napotkasz jakiekolwiek problemy, odwołaj się do oficjalnej dokumentacji lub skontaktuj się z zespołem wsparcia w celu uzyskania pomocy.

Wykonywanie konwersji przy użyciu cURL i interfejsu REST API

Jeśli wolisz pracować bezpośrednio z HTTP, następujące polecenia cURL wykonują tę samą konwersję.

  1. Uzyskaj token dostępu

Zastąp YOUR_CLIENT_ID i YOUR_CLIENT_SECRET swoimi poświadczeniami.

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"

Odpowiedź zawiera access_token.

  1. Prześlij plik HTML
curl -X POST "https://api.groupdocs.cloud/v2.0/storage/files/sample.html" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -F "file=@sample.html"
  1. Rozpocznij konwersję
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"
           }
         }'
  1. Pobierz przekonwertowany DOCX
curl -X GET "https://api.groupdocs.cloud/v2.0/storage/files/output.docx" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -o output.docx

Aby uzyskać pełną listę parametrów, zobacz oficjalną dokumentację API.

Konfigurowanie opcji konwersji treści HTML do DOCX

SDK udostępnia kilka właściwości, które pozwalają precyzyjnie dostosować wynik:

  • embedFonts - Osadza wszystkie odwołane czcionki w pliku DOCX, zapewniając wizualną wierność.
  • pageSize - Ustawia rozmiar strony (A4, Letter itd.).
  • marginTop / marginBottom / marginLeft / marginRight - Dostosowuje marginesy strony w punktach.

Przykład zastosowania tych opcji:

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

Zapoznaj się z klasą ConversionOptions, aby uzyskać pełną listę.

Rozważania dotyczące wydajności przy konwersji treści HTML do DOCX

Podczas konwertowania dużych lub złożonych dokumentów HTML, pamiętaj o następujących wskazówkach:

  1. Ponowne użycie klienta API - Tworzenie nowej ConversionApi instancji dla każdego pliku zwiększa obciążenie.
  2. Strumieniowanie dużych plików HTML - Zamiast ładować cały plik do pamięci, użyj strumieni (fs.createReadStream) i metody uploadFileStream SDK.
  3. Ogranicz wbudowane zasoby - Usuń niepotrzebne obrazy lub skrypty z HTML przed przesłaniem, aby skrócić czas przetwarzania.
  4. Konwersje wsadowe - Przetwarzaj pliki kolejno w pętli, ale przestrzegaj limitów szybkości API, aby uniknąć ograniczeń.

Stosowanie tych praktyk pomaga utrzymać niskie opóźnienia i umiarkowane zużycie pamięci.

Wnioski

HTML do konwersji DOCX w Node.JS staje się proste dzięki GroupDocs.Conversion Cloud SDK for Node.js. Śledząc powyższe kroki, możesz zintegrować niezawodne generowanie DOCX z HTML w dowolnej aplikacji po stronie serwera, dostosować wynik i zoptymalizować wydajność przy dużych obciążeniach. Pamiętaj, aby uzyskać odpowiednią licencję do użytku produkcyjnego; możesz zakupić subskrypcję lub uzyskać tymczasową licencję ze strony tymczasowej licencji. Szczęśliwego kodowania!

FAQs

Jak rozpocząć konwersję HTML do DOCX w Node.JS?

Użyj SDK, aby utworzyć klienta ConversionApi, przesłać swój plik HTML, ustawić żądane opcje konwersji i wywołać metodę convert. Proces jest w pełni asynchroniczny i zwraca identyfikator pliku DOCX do pobrania.

Jakie opcje mogę dostosować przy generowaniu DOCX z HTML?

Obiekt ConversionOptions pozwala osadzać czcionki, wybierać rozmiar strony, ustawiać marginesy i kontrolować obsługę obrazów. Zobacz referencję API aby uzyskać wszystkie dostępne ustawienia.

Czy mogę konwertować HTML zawierający zewnętrzny CSS lub obrazy?

Tak. Prześlij wszystkie odwoływane zasoby (CSS, obrazy) do tego samego folderu przechowywania przed rozpoczęciem konwersji, a SDK rozwiąże linki podczas przetwarzania.

Czy potrzebuję licencji do wdrożeń produkcyjnych?

Do produkcji wymagana jest ważna licencja. Tymczasową licencję do testów możesz uzyskać ze strony tymczasowej licencji i zakupić pełną subskrypcję, gdy będziesz gotowy do uruchomienia.

Read More