- Home
- » よくある質問(FAQ)
- » タグ・関数・構文など
- » cfhtmltopdf使用時の注意事項について
ColdFusion 11から追加された<cfhtmltopdf>は、PDFG(PDF Generator)と呼ばれるJettyサーバー（Add-onサービス）内で実行される HTML→PDFの変換エンジンを使用します。
cfhtmltopdf タグ
cfhtmltopdfタグ サンプル
従来の<cfdocument>に比べてHTMLの再現度が高く、CSSによるデザインもある程度（一部のCSS2やCSS3レベルには対応できていませんが）PDFに変換することができるなどの利点がありますが、<cfdocument>はColdFusion内で処理がすべて行われていたのに対して、<cfhtmltopdf>はColdFusion内部でHTMLを生成して、それをJettyサーバー（Add-onサービス）内で動く PDFg サービスに処理を渡して変換を行うため処理が複雑になるとともに、大量のHTML→PDF変換などを行うと、処理に時間が掛かりPDFG側でタイムアウトなどの障害が発生する場合があります。
ここでは<cfhtmltopdf>でいくつか確認されているトラブルや制限事項などについて紹介します。
- <cfdocument>と同様、Standard版ではcfhtmltopdfのPDF変換はシングル動作となります。多重で処理は行われないため、前の変換処理が終わらないと次の処理が始まらないため処理のボトルネックが生じないように、リクエストを調整してください。
- UCS-2に含まれない文字は使用することができません
- ColdFusionはUCS-2エンコードの対応となるため、それに含まれない文字（サロゲートペア文字）などは対応していません。また、<cfdocument>で使用するライブラリ、および、<cfhtmltopdf>で使用するPDFGも対応していません。ですので、UCS-2に含まれない文字を使用すると、その部分は文字化けを起こすかまたは空白になります。
- （参考）About character encodings
- ベクターグラフィックイメージは使用することができません
- <cfdocument>、<cfhtmltopdf>では、ベクターグラフィックを使用することができません
- <cfhtmltopdfitem type="pagebreak" />はLinux OSでは動作しません。また、Windows 環境の場合も下記の不具合に該当する場合はpagebreakが想定外の動作となります。これは変換エンジンの制限からくるため、制限となっています。
- cfhtmltopdfitem (adobe.com)で「<cfhtmltopdf> がサービスとして使用される場合は、pagebreak は機能しません。」とありますが、これはLinux版で確認された不具合の情報から内容が抜粋されたもので、Linux版でpagebreakが機能しないことを示しています
- Windows版についても、こちらで登録された不具合に該当する場合は正しくpagebreakが行えません
- Linux版のcfhtmltopdfは、Windows版と比較すると変換エンジンの制限が多いため、以下の点に注意してください。
- 変換エンジンが使用するライブラリ・フォントをインストールする必要があります。
- デフォルトのフォントでは日本語が表示できません。そのため、CSS等で日本語フォントを明示的に指定してください。
- 上記にも記載しましたが、pagebreakは機能しないため、複数ファイルに分割してpdfを作成し、処理の後にcfpdfでマージするなどでの対応を行ってください
- 多重に処理が途切れることがなくcfhtmltopdfが実行された場合、変換エンジンの処理が止まってしまう場合がある模様です。断続的に大量のcfhtmltopdfを実行しないよう、実行間隔を調整して変換処理を行ってください
- 変換エンジンは、Windows版は ColdFusion 2021|2018 Add-on Services、Linux版は cfjetty（[cf_root]/{インスタンス(cfusion等)}/jetty 内の cfjetty スクリプト）を起動することで動作します。ColdFusionのサービスが先に起動しているとAdd-on Services(cfjetty)への接続が行えず変換エンジンが動作しないため、先に Add-on Services(cfjetty)を起動するようにしてください。
- 発生するエラー： Error occurred while generating PDF.Reason: Error occurred while handling request.
- サービス運用中にAdd-on Services(cfjetty)を停止・再起動すると、以後の変換エンジンの処理でエラーが発生します。
- 発生するエラー： Error occurred while generating PDF.Reason: SERVER ERROR
- 複雑なHTMLの構文・一つのTABLE内に大量の入れ子のTABLEタグやレコードが含まれる・HTMLの構文が不十分などの場合、変換エンジンの処理に時間が掛かったり、変換が正しく行えずにタイムアウト（既定：120秒）を起こす場合があります。変換するHTMLについては、以下の点を考慮してください
- 変換するHTMLサイズをなるべく少なくする
- 複数ページにまたがったTABLEタグなどを使用せず、シンプルなHTML構文（<html>～</html>を含めた）で記述する
- PDFに変換するHTMLに、外部ファイル（画像ファイルやCSSファイル）などを相対パスで指定している場合、ColdFusionサーバー内から外部ファイルを取得しにいく必要があります。その際のURLは、リクエストを行った時のドメインやIPアドレスでアクセスしますので、ColdFusionサーバーからドメインやIPアドレスで到達できる必要があります
- 例：https://cftest.samuraiz.co.jp/xxx/yyy/pdf.cfm をリクエスト
<img src="abc.jpg" />
↓
※ColdFusionサーバー内から下記のリクエストが行われます
<img src="https://cftest.samuraiz.co.jp/xxx/yyy/abc.jpg" />
- ColdFusionサーバーからドメインの名前解決ができない場合は、外部ファイルに到達できずに変換処理のタイムアウト（既定120秒）を起こしますので、呼び出し方法を変更してください
- リクエストを行った時ドメイン（上記の例だとcftest.samuraiz.co.jp）に対して 127.0.0.1を参照するようにhostsファイルに記載する
- CSSファイルなどのテキストファイルは、外部ファイルの参照を止め、<cfinculde>でCSSファイルの内容を任意の場所（ヘッダ内等）にインクルードするようにコードを変更する
<head>
<style type="text/css">
< !--
<cfinclude template="sample.css">
-- >
</style>
</head>
- 相対パスではなくてローカルファイルを参照するようにコードを変更する
<img src="file:///C:/inetpub/wwwroot/xxx/yyy/abc.jpg" />
- 画像ファイルは、data URI を使用を使用してローカルファイルを参照するようにコードを変更する
<cfoutput>
<img src="data:image/jpg;base64,#toBase64(fileReadBinary(ExpandPath("abc.jpg")))#">
</cfoutput>
- Windows版のColdFusion 2021では、日本語が正しく表示されない不具合が確認されています。
- Linux版のColdFusion 2021で、Update 5～6を適用すると cfhtmltopdfを実行するとHTTP500エラーなどが発生して正しく動作しなくなります。これは、Update 5にて一部ライブラリの更新があり、それが影響してエラーが発生するようになりました。
（2023.9追記）このエラーはUpdate 7以降で修正されました。Update 5または6でこのエラーに遭遇した場合は、Update 7以降（最新のUpdateを推奨）を適用してください。
以下の手順でUpdateのバックアップから、該当ファイルを差し戻してください。
[手順]
念のため、下記のファイルのコピーを残します（元ファイルを移動するとファイルの所有者・権限等が変更される恐れがあるため、コピーにします）
対象フォルダ：[cf2021_root]/cfusion/jetty/webapps/PDFgServlet/Resources/bin 内
（例）
cd /opt/ColdFusion2021/cfusion/jetty/webapps/PDFgServlet/Resources/bin
sudo cp ./libcrypto.so libcrypto.back
sudo cp ./libcrypto.so.1.0.0 libcrypto.back.1.0.0
sudo cp ./libssl.so libssl.back
sudo cp ./libssl.so.1.0.0 libssl.back
「最初に」Update 5以降を適用した際のバックアップフォルダから、上記の場所にファイルをコピーします（例えば Upd5→6→10と適用した場合は、Update5のバックアップフォルダが対象です）。
バックアップフォルダ（Update 5の場合の例）：[cf2021_root]/cfusion/hf-updates/hf-2021-00005-330109/backup/jetty/webapps/PDFgServlet/Resources/bin 内
（例）
sudo cp /opt/ColdFusion2021/cfusion/hf-updates/hf-2021-00005-330109/
backup/jetty/webapps/PDFgServlet/Resources/bin/lib* .
※1.でバックアップした4つのファイルの上書き確認がありますので
すべてyを押して上書きしてくださいjettyを再起動します
/opt/ColdFusion2021/cfusion/jetty/cfjetty restartcoldfusionを再起動します
/opt/ColdFusion2021/cfusion/bin/coldfusion restart
記事公開日：2022年06月16日
最終更新日：2023年09月20日