Best Practices ru

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

Рекомендации по docxi: как избежать типичных сюрпризов

Эти привычки следуют прямо из того, как работает docxi, и большинство из них предотвращают какую-либо проблему из раздела Устранение неполадок. Они сгруппированы по темам. Советы по параметрам страницы пригодятся всем, а советы по безопасности и производительности важнее всего для приложений в продакшене.

Параметры страницы

• Передавайте все четыре поля вместе. Хеш, переданный в Docxi::Document.new, заменяет значения по умолчанию, и любое из значений top, right, bottom и left, которое вы пропустите, записывается пустым.
• Задавайте колонтитулы первой страницы. docxi всегда включает отдельную первую страницу. Если странице 1 нужен колонтитул, вызовите также add_first_header и add_first_footer.

Текст

• Используйте space: true для пробелов в начале или в конце. Иначе Word их удалит, и слова двух фрагментов сольются.
• Выносите общее оформление на уровень абзаца. Параметры, переданные в p, например size: или font:, применяются ко всем фрагментам внутри него, и повторять их не нужно.
• Используйте p.br для разрывов строк и document.br(page: true) для разрывов страниц. document.br без page: true даёт недопустимый XML.

Таблицы

• Задавайте границы для строк или ячеек, а не для таблицы. В 0.1.0 borders: на уровне таблицы применяются к каждой ячейке, а не к внешнему контуру таблицы.
• Указывайте columns_width для каждого столбца. Ячейки берут ширину оттуда, и таблицы сохраняют ожидаемый макет.

Изображения

• Используйте файлы PNG. Каждое изображение сохраняется как часть PNG.
• Задавайте размер встроенных изображений через style:, например style: { width: "120pt", height: "60pt" }. В 0.1.0 это единственный размер изображения, который работает так, как ожидается.
• Передавайте путь, а не открытый File, если документ может формироваться несколько раз. Изображения из IO читаются во время render, и при повторном формировании изображение окажется пустым.
• Изображения в колонтитулах, ячейках таблиц и позиционированные изображения до выхода 0.2.0. Их ширина и высота вычисляются как width * height * 14.92 EMU, поэтому они получаются квадратными. Чтобы получить квадратное изображение со стороной S дюймов, передайте width и height, равные Math.sqrt(S * 914400 / 14.92).round; для одного дюйма это примерно 248.

Безопасность

• Не передавайте недоверенные строки в add_media. Путь заставляет docxi прочитать этот файл с вашего сервера, а URL заставляет ваш сервер его скачать. Передавайте IO, который вы открыли сами, или сначала проверяйте значение. См. Безопасность.
• Текст экранируется автоматически. Строки, переданные в text, записываются как текст XML, поэтому пользовательский ввод не может изменить структуру документа.

Производительность и надёжность

• Формируйте большие документы в фоновой задаче. Весь документ собирается в памяти при вызове render. См. Интеграции.
• Формируйте документ один раз и используйте байты повторно. Сохраните word.render.string, если документ нужно отправить или сохранить несколько раз.
• Зафиксируйте совместимую версию с помощью gem "docxi", "~> 0.1".
• Тестируйте то, что создаёте. .docx — это zip из XML-файлов, поэтому тесты могут распаковать его и проверить XML. Собственные тесты docxi работают именно так. См. Архитектура.

Связанные страницы

• Возможности
• Настройка
• Устранение неполадок

---

← Главная вики · README