واجهة برمجة تطبيقات JavaScript لإنشاء مستندات Word ديناميكية
مكتبة JavaScript مفتوحة المصدر لإنشاء مستندات Word ديناميكية باستخدام Node.js وتطبيقات المتصفح.
ما هو Docx-templates؟
Docx-Templates هي مكتبة JavaScript مفتوحة المصدر تمكّن مطوري البرمجيات من إنشاء مستندات Microsoft Word (.docx) ديناميكية باستخدام قوالب مُعرّفة مسبقًا. بدلاً من بناء مستندات Word يدويًا برمجيًا، يمكن للمطورين تصميم القوالب في Microsoft Word وإدخال البيانات الديناميكية باستخدام أوامر مدمجة. تعمل هذه المكتبة في بيئات Node.js والمتصفح، مما يجعلها متعددة الاستخدامات للتطبيقات الحديثة على الويب والخوادم. تقوم بمعالجة ملفات DOCX عن طريق تحليل بنية XML الداخلية واستبدال أوامر القالب بالبيانات الفعلية أثناء وقت التشغيل.
مكتبة Docx-Templates هي أداة قوية ومفتوحة المصدر مصممة لكل من بيئات Node.js والمتصفح. الميزة الأساسية للمكتبة هي فصل التصميم عن المنطق. يمكن للمستخدمين غير التقنيين تصميم التخطيط والتنسيق في Word، بينما يركز المطورون على حقن البيانات. تدعم المنطق المعقد مثل الحلقات، التنسيق الشرطي، وحتى تنفيذ مقاطع JavaScript مباشرة داخل المستند. هذا يجعلها حلاً مثالياً للمطورين الذين يحتاجون إلى إنتاج تقارير عالية الدقة دون الحاجة إلى التعامل مع XML أو أدوات التصميم المملوكة.
البدء مع Docx-templates
الطريقة الموصى بها لتثبيت مكتبة Docx-templates هي عبر npm. يرجى استخدام الأمر التالي لتثبيت سلس.
تثبيت Docx-Templates عبر NPM
$ npm install docx-templates تثبيت Docx-Templates عبر Yarn/strong>
$ yarn add docx-templates إنشاء مستندات مبنية على القوالب عبر واجهة برمجة التطبيقات JS
تتيح مكتبة Docx-Templates مفتوحة المصدر للمطورين تصميم المستندات في Word وإدخال البيانات ديناميكيًا باستخدام أوامر بسيطة. يفصل هذا النهج بين العرض والمنطق، مما يجعل القوالب سهلة الإدارة والتحديث دون تغيير الشيفرة. يمكنك الوصول مباشرة إلى الخصائص من كائن البيانات الخاص بك أو حتى تشغيل تعبيرات بسيطة. على سبيل المثال، لإدراج الاسم الكامل، سيبدو القالب هكذا: {firstName} {surname}. تقوم المكتبة بتقييم الشيفرة واستبدالها بسلاسة.
كيف تنشئ مستندات Word ديناميكيًا داخل تطبيقات JavaScript؟
import createReport from 'docx-templates';
import fs from 'fs';
const template = fs.readFileSync('template.docx');
const report = await createReport({
template,
data: { name: 'John', surname: 'Doe' },
});
fs.writeFileSync('output.docx', report);
إدراج صور ديناميكية عبر JavaScript
بعيدًا عن النص، يمكن لمكتبة Docx-Templates مفتوحة المصدر إدراج الصور فورًا. يشمل ذلك الملفات المحلية، الصور من عنوان URL، أو حتى رموز QR التي تُنشأ برمجيًا. يمكنك التحكم في حجم الصورة وموقعها. تُعد هذه الميزة نقطة تحول لإنشاء بطاقات التعريف، كتالوجات المنتجات، أو التقارير التي تتطلب مخططات ديناميكية وأدلة بصرية. إليك مثالًا بسيطًا يوضح كيفية إدراج صورة في مستند Word عبر واجهة برمجة تطبيقات JavaScript.
كيف تُدرج صورة مباشرة داخل مستندات Word عبر واجهة برمجة تطبيقات JavaScript؟
const buffer = await createReport({
template,
data: {
userAvatar: async () => {
const resp = await fetch('https://example.com/photo.png');
return { width: 3, height: 3, data: await resp.arrayBuffer(), extension: '.png' };
}
},
});
// In Word: {IMAGE userAvatar()}
حلقات قوية (FOR/END-FOR)
معالجة قوائم البيانات سلسة باستخدام أمر FOR. تتيح لك هذه الميزة التكرار عبر المصفوفات لإنشاء صفوف جدول أو قوائم أو حتى أقسام كاملة من المستند. تضمّن مكتبة Docx-Templates دعم الحلقات المتداخلة، مما يسمح لك بتمثيل هياكل بيانات هرمية معقدة، مثل قائمة الأقسام مع موظفيها المعنيين، مع الحفاظ على تنسيق Word الأصلي. يوضح مثال الشيفرة التالي كيفية تحقيق ذلك.
كيف تُطبق حلقة متقدمة داخل تطبيقات JavaScript؟
const buffer = await createReport({
template,
data: {
projects: [
{ name: 'SEO Optimization', status: 'Completed' },
{ name: 'API Integration', status: 'In Progress' }
]
},
});
/* In Word:
{FOR project IN projects}
Project: {project.name} - Status: {project.status}
{END-FOR}
*/
سياق JavaScript مخصص (EXEC)
إحدى أكثر الميزات تقدماً في مكتبة Docx-Templates هي القدرة على تشغيل مقاطع JavaScript عشوائية باستخدام أمر EXEC (أو !) . من خلال توفير additionalJsContext، يمكنك إتاحة وظائف مساعدة مخصصة للقالب. يتيح ذلك للقالب إجراء حسابات، تنسيق تواريخ، أو تعديل سلاسل نصية داخلياً دون الحاجة إلى معالجة مسبقة لكل قطعة من البيانات في منطق التطبيق الرئيسي الخاص بك.
