Best Practices ja

English · 简体中文 · 繁體中文 · Español · العربية · Français · Português (Brasil) · Deutsch · हिन्दी · 日本語 · 한국어 · Русский · Bahasa Indonesia · Türkçe · Italiano · Tiếng Việt

docxi のベストプラクティス：よくある落とし穴を避ける

ここで紹介する習慣は docxi の仕組みから直接導かれるもので、ほとんどがトラブルシューティングに載っている問題を防ぎます。トピックごとにまとめています。ページ設定の助言はすべての人に、セキュリティとパフォーマンスの助言は特に本番環境のアプリケーションに役立ちます。

ページ設定

• 4 つの余白をまとめて渡す。Docxi::Document.new に渡したハッシュはデフォルト値を置き換え、top、right、bottom、left のうち省略したものは空で書き出されます。
• 1 ページ目のヘッダーとフッターを設定する。docxi は常に 1 ページ目を別扱いにします。1 ページ目にヘッダーやフッターが必要なら、add_first_header と add_first_footer も呼び出してください。

テキスト

• 先頭や末尾の空白には space: true を使う。そうしないと Word が空白を削除し、2 つのランの単語がくっついてしまいます。
• 共通の書式は段落に設定する。size: や font: など p に渡したオプションは段落内のすべてのランに適用されるので、繰り返し書く量が減ります。
• 改行には p.br、改ページには document.br(page: true) を使う。page: true なしの document.br は無効な XML を生成します。

表

• 罫線は表ではなく行かセルに設定する。0.1.0 では、表単位の borders: は表の外枠ではなく各セルに適用されます。
• すべての列に columns_width を指定する。セルの幅はここから決まるので、表のレイアウトが期待どおりに保たれます。

画像

• PNG ファイルを使う。すべての画像は PNG パーツとして保存されます。
• インライン画像のサイズは style: で指定する。たとえば style: { width: "120pt", height: "60pt" } のようにします。0.1.0 で期待どおりに動く画像サイズの指定方法はこれだけです。
• ドキュメントを複数回レンダリングする可能性があるなら、開いた File ではなくパスを渡す。IO の画像は render の中で読み込まれるため、2 回目のレンダリングでは空の画像になります。
• 0.2.0 までのヘッダー、表のセル、配置を指定した画像について。幅と高さがどちらも width * height * 14.92 EMU として計算されるため、正方形になります。一辺 S インチの正方形の画像にするには、width と height の両方を Math.sqrt(S * 914400 / 14.92).round にします。1 インチならおよそ 248 です。

セキュリティ

• 信頼できない文字列を add_media に渡さない。パスを渡すと docxi はサーバー上のそのファイルを読み、URL を渡すとサーバーがそれをダウンロードします。自分で開いた IO を渡すか、先に値を確認してください。セキュリティを参照してください。
• テキストは自動でエスケープされる。text に渡した文字列は XML のテキストとして書き出されるため、ユーザーの入力でドキュメントの構造が変わることはありません。

パフォーマンスと信頼性

• 大きなドキュメントはバックグラウンドジョブで作る。render を呼び出すと、ドキュメント全体がメモリ上で組み立てられます。連携を参照してください。
• レンダリングは 1 回にして、バイト列を再利用する。ドキュメントを何度も送信または保存する必要があるなら、word.render.string を保持しておいてください。
• gem "docxi", "~> 0.1" で互換性のあるバージョンに固定する。
• 生成したものをテストする。.docx は XML ファイルの zip なので、テストで展開して XML を確認できます。docxi 自身のテストもこの方法です。アーキテクチャを参照してください。

関連ページ

• 機能
• 設定
• トラブルシューティング

---

← Wiki ホーム · README