Adım Adım HTML'den DOCX'e Dönüştürme Eğitimi Node.JS'de

Zengin HTML sayfalarını düzenlenebilir DOCX dosyalarına dönüştürmek, raporlama ve belge otomasyonu iş akışları için sıkça ihtiyaç duyulan bir durumdur. GroupDocs.Conversion Cloud SDK for Node.js geliştiricilerin bu dönüşümü tamamen REST‑tabanlı bir kütüphane aracılığıyla gerçekleştirmesini sağlar. Bu öğreticide, SDK’yı nasıl kuracağınızı, Node.JS içinde HTML’den DOCX’e dönüşüm yapan Node.JS kodunu nasıl yazacağınızı, API’yi çağırmak için cURL kullanmayı ve en iyi sonuçlar için yapılandırma seçeneklerini nasıl uygulayacağınızı göreceksiniz.

Önkoşullar ve Kurulum

Başlamadan önce, aşağıdakilere sahip olduğunuzdan emin olun:

• Geliştirme makinenizde yüklü Node.js 14 veya daha yeni bir sürüm.
• Aktif bir GroupDocs.Conversion Cloud hesabı (ürün sayfasından ücretsiz deneme için kaydolabilirsiniz).
• GroupDocs Cloud kontrol panelinizden Client ID ve Client Secret bilgileriniz.
• Bulut REST API’sini çağırmak için internet bağlantısı.

SDK’yı npm aracılığıyla kurun:

npm install groupdocs-conversion-cloud

En son paketi indirin ve kodu incelemeniz gerekiyorsa GitHub’da kaynağa göz atın:

İndir GroupDocs.Conversion Cloud SDK for Node.js

SDK yüklü ve kimlik bilgileri hazır olduğunda, uygulamaya geçebilirsiniz.

Node.JS’te HTML’den DOCX’e Dönüştürme: Adım Adım Kılavuz

Aşağıda, her mantıksal adımı gösteren kısa bir yürütme rehberi bulunmaktadır. Tam kaynak kodu daha sonra sağlanacaktır.

Adım 1: Dönüştürme API İstemcisini Başlat

ConversionApi örneği oluşturun ve kimlik doğrulamayı yapılandırın.

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

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

const conversionApi = new ConversionApi(config);

Adım 2: HTML Kaynak Dosyasını Yükle

Dönüştürmek istediğiniz HTML dosyasını yükleyin. API, dönüşüm için kullanacağınız bir dosya tanımlayıcısı döndürür.

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;

Adım 3: Dönüştürme Seçeneklerini Ayarla

Herhangi bir DOCX‑özel seçeneği yapılandırın, örneğin yazı tiplerini gömmek veya sayfa kenar boşluklarını ayarlamak gibi. Bu adım HTML’den DOCX Oluşturma özelleştirmesini gösterir.

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

Adım 4: Dönüşümü Gerçekleştir

Yukarıda tanımlanan ayarlarla ve kaynak dosya kimliğiyle convert metodunu çağırın.

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

Adım 5: Oluşturulan DOCX’i İndir

Oluşturulan DOCX dosyasını alın ve yerel olarak kaydedin.

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

Yukarıdaki adımlar, GroupDocs.Conversion Cloud SDK kullanarak Node.JS’te HTML’den DOCX’e dönüşüm iş akışını tam olarak göstermektedir.

Tam Kod Örneği: HTML İçeriğinden DOCX Oluşturma

Aşağıdaki program, tüm parçaları tek bir çalıştırılabilir betikte bir araya getirir.

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

Not: Bu kod örneği temel işlevselliği gösterir. Projenizde kullanmadan önce dosya yollarını (sample.html, output.docx) güncellediğinizden, tüm gerekli bağımlılıkların doğru şekilde yüklendiğinden emin olun ve geliştirme ortamınızda kapsamlı bir şekilde test edin. Herhangi bir sorunla karşılaşırsanız, lütfen resmi belgeler adresine bakın veya destek ekibi ile iletişime geçin.

cURL ve REST API ile Dönüştürme İşlemini Gerçekleştirme

HTTP ile doğrudan çalışmayı tercih ediyorsanız, aşağıdaki cURL komutları aynı dönüşümü gerçekleştirir.

1. Erişim belirteci alın

YOUR_CLIENT_ID ve YOUR_CLIENT_SECRET öğelerini kimlik bilgilerinizle değiştirin.

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"

Yanıt access_token içerir.

2. HTML dosyasını yükleyin

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

3. Dönüşümü başlat

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. Dönüştürülmüş DOCX’i İndir

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

Tam parametre listesi için, resmi API belgelerine bakın.

HTML İçeriğini DOCX’e Dönüştürme Seçeneklerini Yapılandırma

SDK, çıktıyı ince ayar yapmanıza olanak tanıyan çeşitli özellikler sunar:

• embedFonts - Tüm referans verilen yazı tiplerini DOCX’e gömer, görsel tutarlılığı sağlar.
• pageSize - Sayfa boyutunu ayarlar (A4, Letter, vb.).
• marginTop / marginBottom / marginLeft / marginRight - Sayfa kenar boşluklarını puan cinsinden ayarlar.

Bu seçeneklerin uygulanmasına bir örnek:

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

Tam liste için ConversionOptions sınıfı bakın.

HTML İçeriğinin DOCX’e Dönüştürülmesi İçin Performans Düşünceleri

Büyük veya karmaşık HTML belgelerini dönüştürürken, bu ipuçlarını aklınızda bulundurun:

1. API istemcisini yeniden kullanın - Her dosya için yeni bir ConversionApi örneği oluşturmak ek yük getirir.
2. Büyük HTML dosyalarını akış olarak işleyin - Tüm dosyayı belleğe yüklemek yerine, akışları (fs.createReadStream) ve SDK’nın uploadFileStream metodunu kullanın.
3. Gömülü kaynakları sınırlayın - İşleme süresini azaltmak için HTML’yi yüklemeden önce gereksiz resimleri veya betikleri kaldırın.
4. Toplu dönüşümler - Dosyaları bir döngüde sıralı olarak işleyin, ancak kısıtlamaları önlemek için API oran sınırlamalarına uyun.

Bu uygulamaları benimsemek, düşük gecikme süresi ve makul bellek tüketimini sürdürmeye yardımcı olur.

Sonuç

HTML to DOCX dönüşümü Node.JS’de GroupDocs.Conversion Cloud SDK for Node.js ile çok basit hale gelir. Yukarıdaki adımları izleyerek HTML’den güvenilir DOCX üretimini herhangi bir sunucu‑tarafı uygulamaya entegre edebilir, çıktıyı özelleştirebilir ve büyük iş yükleri için performansı optimize edebilirsiniz. Üretim kullanımı için uygun bir lisans almayı unutmayın; bir abonelik satın alabilir veya geçici lisans sayfasından geçici bir lisans elde edebilirsiniz. Kodlamanın tadını çıkarın!

FAQs

Node.JS’de HTML’den DOCX dönüşümüne nasıl başlarım?

SDK’yı kullanarak bir ConversionApi istemcisi oluşturun, HTML dosyanızı yükleyin, istediğiniz dönüşüm seçeneklerini ayarlayın ve convert yöntemini çağırın. İşlem tamamen asenkron olup indirme için DOCX dosya kimliğini döndürür.

HTML’den DOCX oluşturma için hangi seçenekleri ayarlayabilirim?

ConversionOptions nesnesi, yazı tiplerini gömmenizi, sayfa boyutunu seçmenizi, kenar boşluklarını ayarlamanızı ve görüntü işleme kontrol etmenizi sağlar. Tüm mevcut ayarlar için API referansına bakın.

Harici CSS veya resimler içeren HTML’yi dönüştürebilir miyim?

Evet. Dönüştürmeye başlamadan önce, başvurulan tüm kaynakları (CSS, görseller) aynı depolama klasörüne yükleyin ve SDK işleme sırasında bağlantıları çözecektir.

Üretim dağıtımları için bir lisansa ihtiyacım var mı?

Üretim için geçerli bir lisans gereklidir. Test amaçlı geçici bir lisans alabilirsiniz geçici lisans sayfası ve yayına hazır olduğunuzda tam bir abonelik satın alabilirsiniz.

Read More

• JSON’u Node.js’te HTML’ye Dönüştür | JSON’dan Web Sayfasına Dönüşüm
• Adım Adım CSV’den PDF’ye Dönüştürme Örneği Node.JS’te
• Adım Adım HTML’den XLSX’e Dönüştürme Öğreticisi PHP’de