リッチな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 がインストールされ、認証情報が準備できたら、実装に進むことができます。
Node.JSでのHTMLからDOCXへの変換: ステップバイステップのウォークスルー
以下は、各論理ステップを示す簡潔なウォークスルーです。完全なソースコードは後ほど提供されます。
ステップ 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 Generation from 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');
上記の手順は、GroupDocs.Conversion Cloud SDK を使用した完全な HTML から DOCX への変換（Node.JS） ワークフローを示しています。
完全なコード例：HTML コンテンツから DOCX を生成する
次のプログラムは、すべてのパーツを1つの実行可能なスクリプトにまとめます。
// 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 変換は Node.JS で、GroupDocs.Conversion Cloud SDK for Node.js を使用すると簡単になります。上記の手順に従うことで、HTML から信頼性の高い DOCX をサーバーサイド アプリケーションに統合し、出力をカスタマイズし、大規模なワークロードに対してパフォーマンスを最適化できます。製品版の使用には適切なライセンスを取得することを忘れないでください。サブスクリプションを購入するか、一時ライセンスページ から一時ライセンスを取得できます。ハッピーコーディング！
FAQs
Node.JSでHTMLからDOCXへの変換を開始するにはどうすればよいですか？
SDK を使用して ConversionApi クライアントを作成し、HTML ファイルをアップロードし、目的の変換オプションを設定し、convert メソッドを呼び出します。プロセスは完全に非同期で、ダウンロード用の DOCX ファイル識別子を返します。
HTML から DOCX を生成する際に調整できるオプションは何ですか？
ConversionOptions オブジェクトを使用すると、フォントの埋め込み、ページサイズの選択、余白の設定、画像処理の制御ができます。利用可能なすべての設定については、API reference を参照してください。
外部のCSSや画像を含むHTMLを変換できますか？
はい。変換を開始する前に、参照されているリソース（CSS、画像）を同じストレージフォルダーにアップロードしてください。SDK は処理中にリンクを解決します。
本番環境へのデプロイにライセンスは必要ですか？
本番環境では有効なライセンスが必要です。テスト用の一時ライセンスは一時ライセンスページから取得でき、ライブ運用の準備ができたらフルサブスクリプションを購入してください。