Keywords: jsPDF | PDF page dimensions | font size configuration
Abstract: This technical article provides an in-depth analysis of customizing PDF page width, height, and font sizes using the jsPDF library. Based on technical Q&A data, it explores the constructor parameters orientation, unit, and format, explaining how the third parameter functions as a dimension array with long-side and short-side logic. Through code examples, it demonstrates various unit and dimension combinations, discusses default page formats and unit conversion ratios, and supplements with font size setting methods using setFontSize(). The article offers developers a complete solution for generating customized PDF documents programmatically.
Understanding jsPDF Constructor Parameters
The core of creating PDF documents in the jsPDF library revolves around the constructor jsPDF(orientation, unit, format). The orientation parameter controls page orientation, accepting either "portrait" or "landscape", with shorthand forms "p" and "l" respectively. This parameter not only determines the visual orientation but more importantly influences how subsequent dimension parameters are interpreted.
The unit parameter specifies the measurement unit, supporting "pt" (points), "mm" (millimeters), "cm" (centimeters), and "in" (inches). Internally, all units are converted to points (pt) for calculation, with specific conversion ratios available in the jsPDF source code. For instance, 1 millimeter approximately equals 2.83464567 points, ensuring dimensional consistency across different units.
The most critical format parameter can accept either predefined page format strings like 'a3', 'a4', 'a5', 'letter', 'legal', or directly receive a two-number array for custom dimensions. When using an array, it's essential to understand that these numbers represent the long side and short side lengths, not directly width and height. The constructor determines which becomes width and height based on the orientation parameter value.
Implementing Custom Page Dimensions
To create PDF documents with custom dimensions, developers need to pass a two-number array as the third constructor parameter. For example, to create a portrait document 210mm wide and 297mm high:
// Create portrait document 210mm wide, 297mm high
new jsPDF('p', 'mm', [297, 210]);In this example, the array [297, 210] has 297 as the long side and 210 as the short side. With orientation set to 'p' (portrait), the system uses the short side 210 as width and the long side 297 as height. This design allows developers to use a consistent array format regardless of page orientation.
For landscape document creation, simply change the orientation parameter to 'l':
// Create landscape document 297mm wide, 210mm high
new jsPDF('l', 'mm', [297, 210]);Now, the same array [297, 210] is interpreted as 297mm width and 210mm height. This flexibility enables creating differently oriented documents with identical dimension values, simplifying code logic.
Beyond millimeters, jsPDF supports other common units. For instance, creating a landscape document 5 inches wide and 3 inches high:
// Create landscape document 5 inches wide, 3 inches high
new jsPDF('l', 'in', [3, 5]);Here, inches serve as the unit, with 5 as the long side becoming width and 3 as the short side becoming height. The diversity of unit systems allows jsPDF to accommodate measurement conventions across different regions and industries.
Default Page Formats and Unit Systems
jsPDF includes multiple standard page formats, with their dimensions stored in points (pt) within the library. For example, A4 format measures 595.28pt × 841.89pt, while letter format is 612pt × 792pt. When developers choose predefined formats, the system automatically applies these standard dimensions without manual calculation.
The unit conversion system is a crucial feature of jsPDF. The library maintains an internal unit proportion table that converts all units to the base point unit. This design ensures consistent physical dimensions across different units. Developers can examine the unit proportion definitions in the source code to understand specific conversion relationships.
Font Size Configuration Methods
Beyond page dimensions, font size control is vital in PDF generation. jsPDF provides the setFontSize(size) method to configure font size for subsequent text elements. This method accepts a numerical parameter representing font size in points.
For example, to set font size to 12 points:
doc.setFontSize(12);
doc.text('This text will display at 12-point size', 10, 10);Note that setFontSize only affects text added after the method call; previously added text remains unchanged. This design allows using multiple font sizes within a single document, enhancing layout flexibility.
Font size configuration and page dimension settings operate as independent systems. Page dimensions define the document's physical boundaries, while font size controls text display proportions within those boundaries. Appropriate font size selection should consider page dimensions, margins, and content density to ensure document readability and aesthetic quality.
Practical Implementation Recommendations
In actual development, it's advisable to first determine basic document requirements, including target output dimensions, content structure, and layout needs. For fixed-size documents, use predefined formats directly; for special dimension requirements, employ custom dimension arrays.
When using custom dimensions, clearly understand how the orientation parameter affects dimension interpretation. Adding explicit comments in code to explain array value meanings is recommended, particularly when long-side and short-side values are similar, to avoid confusion during future maintenance.
Font size selection should consider the document's final use case. Printed documents typically require larger fonts (10-12 points), while screen-read documents can use smaller fonts (8-10 points). By appropriately combining page dimensions and font sizes, developers can create both aesthetically pleasing and practical PDF documents.