Best Practices ar

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