API JavaScript برای تولید اسناد Word پویا
کتابخانه منبع باز JavaScript برای ایجاد اسناد Word پویا با Node.js و برنامههای مبتنی بر مرورگر.
Docx-templates چیست؟
Docx-Templates یک کتابخانهٔ متنباز جاوااسکریپت است که به توسعهدهندگان نرمافزار امکان تولید اسناد دینامیک 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 تولید سند مبتنی بر قالب از طریق API جاوااسکریپت
کتابخانه منبع باز 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);
تزریق تصویر پویا از طریق جاوااسکریپت
فراتر از متن، کتابخانه منبع باز Docx-Templates میتواند تصاویر را بهصورت لحظهای وارد کند. این شامل فایلهای محلی، تصاویر از یک URL یا حتی کدهای QR تولید شده برنامهنویسی میشود. میتوانید اندازه تصویر و مکان آن را کنترل کنید. این ویژگی برای ایجاد کارتهای شناسایی، کاتالوگهای محصول یا گزارشهایی که به نمودارها و شواهد بصری پویا نیاز دارند، تحولآفرین است. در اینجا یک مثال ساده آورده شده است که نشان میدهد چگونه میتوان تصویر را بهوسیله JavaScript API در اسناد Word وارد کرد.
چگونه بهصورت لحظهای تصویر را در اسناد Word از طریق API جاوااسکریپت وارد کنیم؟
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}
*/
زمینه سفارشی جاوااسکریپت (EXEC)
یکی از پیشرفتهترین ویژگیهای کتابخانه Docx-Templates قابلیت اجرای قطعات دلخواه JavaScript با استفاده از دستور EXEC (یا !) است. با ارائهٔ additionalJsContext، میتوانید توابع کمکی سفارشی را به الگو در دسترس قرار دهید. این امکان به الگو اجازه میدهد تا محاسبات را انجام دهد، تاریخها را قالببندی کند یا رشتهها را بهصورت داخلی دستکاری کند، بدون اینکه نیاز به پیشپردازش هر قطعه داده در منطق اصلی برنامه شما باشد.
