pdf maker

صانع قوات الدفاع الشعبي

PDF Maker عبارة عن مكتبة لإنشاء مستندات PDF بلغة JavaScript.

• سهل الاستخدام: يتم تعريف المحتويات في كائنات عادية.
• يعمل في أي مكان: في المتصفح، في Node.js، وDeno، وBun.
• دعم TypeScript: يتم تضمين الأنواع في حزمة npm.

هذا المشروع مستوحى من pdfmake ويعتمد على pdf-lib وfontkit. لن يكون موجودًا بدون العمل العظيم والمعرفة العميقة التي ساهم بها مؤلفو تلك المشاريع.

الاستخدام

تقوم الدالة makePdf() بإنشاء بيانات PDF من تعريف مستند معين. هذا التعريف هو كائن عادي.

محتوى

الخاصية الأكثر أهمية في التعريف هي content المسمى. تقبل هذه الخاصية قائمة الكتل . هناك أنواع مختلفة من الكتل، مثل كتل النص، وكتل الصور، وكتل تخطيط الأعمدة والصف.

مثال أساسي

 const fontData = await readFile ( 'Roboto-Regular.ttf' ) ;
const fontDataItalic = await readFile ( 'Roboto-Italic.ttf' ) ;

const pdfData = await makePdf ( {
  // Fonts must be registered (see below)
  fonts : {
    Roboto : [ { data : fontData } , { data : fontDataItalic , italic : true } ] ,
  } ,
  // Content as an array of blocks
  content : [
    // Blocks can contain text and text properties
    { text : 'Lorem ipsum' , fontStyle : 'italic' , textAlign : 'center' , fontSize : 24 } ,
    // Text can also be an array of text spans with different properties
    {
      text : [
        'dolor sit amet, consectetur adipiscing elit ' ,
        { text : 'sed do eiusmod' , fontStyle : 'italic' } ,
        ' tempor, incididunt ut labore et dolore magna aliqua.' ,
      ] ,
    } ,
  ] ,
} ) ;
await writeFile ( `hello.pdf` , pdfData ) ;

هناك المزيد من الأمثلة في الأمثلة/ المجلد.

الخطوط

جميع الخطوط مضمنة في ملف PDF ويجب تسجيلها في خاصية fonts . يتم قبول بيانات الخط بتنسيق .ttf أو .otf ، مثل ArrayBuffer أو Uint8Array. يمكن أن تحتوي كل عائلة خطوط على أشكال مختلفة يتم تحديدها بناءً على خصائص bold italic . تصبح عائلة الخطوط التي تم تسجيلها أولاً هي المجموعة الافتراضية.

 const documentDefinition = {
  fonts : {
    'DejaVu-Sans' : [
      // Different font versions for fontFamily "DejaVu-Sans"
      // TTF / OTF font data as ArrayBuffer or Uin8Array
      { data : fontDataDejaVuSansNormal } ,
      { data : fontDataDejaVuSansBold , bold : true } ,
      { data : fontDataDejaVuSansItalic , italic : true } ,
      { data : fontDataDejaVuSansBoldItalic , bold : true , italic : true } ,
    ] ,
    Roboto : [
      // Different font versions for fontFamily "Roboto"
      { data : fontDataRobotoNormal } ,
      { data : fontDataRobotoMedium , bold : true } ,
    ] ,
  } ,
  content : [
    { text : 'lorem ipsum' , fontFamily : 'Roboto' , fontWeight : 'bold' } , // will use Roboto Medium
    { text : 'dolor sit amet' } , // will use DejaVu-Sans (the font registered first), normal
  ] ,
} ;

الصور

يتم دعم صور JPG وPNG. عند استخدام نفس الصورة أكثر من مرة، يتم تضمين بيانات الصورة مرة واحدة فقط في ملف PDF. يمكن تحديد حجم الصورة باستخدام خصائص width height .

 // An image block
{ image : 'images/logo.png' , width : 200 , height : 100 } ,

أعمدة

لترتيب الكتل أفقيًا، يمكن تضمينها في كتلة ذات خاصية columns . عندما يكون للأعمدة خاصية width ، يتم احترامها. يتم توزيع معرف المساحة المتبقية بالتساوي عبر جميع الأعمدة.

 {
  columns : [
    { text : 'Column 1' , width : 100 } , // 100 pt wide
    { text : 'Column 2' } , // gets half of the remaining width
    { text : 'Column 3' } , // gets half of the remaining width
  ] ,
}

الصفوف

يمكن استخدام تخطيط الصف لتجميع صفوف متعددة في كتلة واحدة، على سبيل المثال لتطبيق خصائص مشتركة أو لإحاطة الصفوف في تخطيط الأعمدة المحيطة.

 {
  rows : [
    { text : 'Row 1' } ,
    { text : 'Row 2' } ,
    { text : 'Row 3' } ,
  ] ,
  textAlign : 'right' ,
}

الرسومات

يمكن أن تحتوي كل كتلة على خاصية graphics تقبل قائمة من الأشكال لرسمها في تلك الكتلة أو وظيفة ترجع قائمة من الأشكال. سيتم استدعاء الوظيفة مع عرض الكتلة وارتفاعها. يمكن استخدام هذا لرسم الأشكال التي تعتمد على حجم الكتلة.

يمكن أن تكون الأشكال عبارة عن خطوط أو مستطيلات أو دوائر أو مسارات SVG. في المثال التالي، يتم استخدام خاصية الرسومات لرسم خلفية صفراء خلف النص وحد أزرق عند الحافة اليسرى.

 {
  text : 'Lorem ipsum' ,
  graphics : ( { width , height } ) => [
    { type : 'rect' , x : 0 , y : 0 , width , height , fillColor : 'yellow' } ,
    { type : 'line' , x1 : 0 , y1 : 0 , x2 : 0 , y2 : height , lineColor : 'blue' , lineWidth : 2 } ,
  ] ,
  padding : { left : 5 } ,
}

راجع أيضًا المثال الرسومي.

الهامش والحشوة

يمكن استخدام خاصية margin لإضافة مسافة حول الكتل. فهو يقبل إما قيمة واحدة (تنطبق على جميع الحواف الأربعة) أو كائنًا له أي من الخصائص top و right و bottom و left و x و y . يمكن استخدام الخاصيتين x و y كاختصارات لتعيين كل من left right أو top bottom في نفس الوقت. يمكن إعطاء القيم كأرقام (بالنقطة) أو كسلاسل ذات وحدة. إذا تم إعطاء سلسلة، فيجب أن تحتوي على إحدى الوحدات pt أو in أو mm أو cm ؛

 {
  margin : { x : 5 , top : 10 } ,
  content : [
    { text : 'Lorem ipsum' } ,
    { text : 'dolor sit amet' } ,
  ] ,
}

يتم طي الهوامش top bottom للكتل المجاورة في هامش واحد يبلغ حجمه الحد الأقصى للهامشين. لا تنهار هوامش العمود.

يمكن استخدام خاصية padding لإضافة مسافة بين المحتوى وحواف الكتل.

تخطيط الصفحة

يمكن استخدام خاصية pageSize ذات المستوى الأعلى لتعيين حجم الصفحة. يتم دعم الأحجام القياسية المختلفة، مثل A4 و Letter و Legal . الافتراضي هو A4. يمكن تحديد حجم صفحة مخصص ككائن له خصائص width height . يمكن إعطاء القيم كأرقام (بالنقطة) أو كسلاسل ذات وحدة.

 {
  pageSize : { width : '20cm' , height : '20cm' }
}

يمكن استخدام خاصية pageOrientation لتعيين اتجاه الصفحة. يمكن أن تكون القيمة portrait أو landscape . الافتراضي هو عمودي.

 {
  pageSize : 'A5' ,
  pageOrientation : 'landscape' ,
  content : [
    { text : 'Lorem ipsum' } ,
    { text : 'dolor sit amet' } ,
  ] ,
}

الرؤوس والتذييلات

يمكن تعريف الرؤوس والتذييلات التي تتكرر في كل صفحة باستخدام خصائص header footer الاختيارية. كلاهما يقبل إما كتلة واحدة أو دالة تُرجع كتلة. سيتم استدعاء الوظيفة برقم الصفحة والعدد الإجمالي للصفحات. رقم الصفحة يبدأ بالرقم 1.

 {
  footer : ( { pageNumber , pageCount } ) => ( {
    text : `Page ${ pageNumber } of ${ pageCount } ` ,
    textAlign : 'right' ,
    margin : { x : '20mm' , bottom : '1cm' } ,
  } ) ,
  content : [
    { text : 'Lorem ipsum' } ,
    { text : 'dolor sit amet' } ,
  ] ,
}

فواصل الصفحات

يتم تضمين فواصل الصفحات تلقائيًا. عندما لا يتم احتواء الكتلة في الصفحة الحالية، تتم إضافة صفحة جديدة إلى المستند. لإدراج فاصل صفحات قبل الكتلة أو بعدها، قم بتعيين الخاصية breakBefore أو breakAfter للكتلة إلى always . لمنع فاصل الصفحات، قم بتعيين هذه الخاصية avoid .

يتم أيضًا إدراج فواصل الصفحات تلقائيًا بين أسطر كتلة النص. لمنع حدوث فاصل صفحات داخل كتلة نصية، قم بتعيين خاصية breakInside avoid .

 {
  content : [
    { text : 'Lorem ipsum' } ,
    { text : 'This text will go on a new page' , breakBefore : 'always' } ,
  ] ,
} 

التوثيق

على الرغم من عدم وجود وثائق تم إنشاؤها حتى الآن، يمكنك الرجوع إلى مجلد API للحصول على مواصفات جميع الخصائص المدعومة في تعريف المستند.

تحقق أيضًا من الأمثلة الموجودة في المجلد/الأمثلة.

رخصة

معهد ماساتشوستس للتكنولوجيا