指南 · 基础

版本基线 4.x。本篇把「会画」用到「懂模型」：命令式绘图范式、坐标系与单位、状态型样式（颜色/线宽/字体）、长文本换行 splitTextToSize、页面尺寸读取与居中、text/rect/图形的 style。

一、命令式绘图：一块画布

jsPDF 不是声明式文档定义，而是命令式绘图：一份文档（每一页）就是一块从左上角 (0,0) 到 (pageWidth, pageHeight) 的画布，你逐条下达绘制指令：

const doc = new jsPDF();           // A4 / 纵向 / mm
doc.text('标题', 20, 20);          // 在 (20mm, 20mm) 写字
doc.line(20, 25, 190, 25);         // 画一条分隔线
doc.rect(20, 30, 60, 30);          // 画一个矩形

关键认知：坐标即绝对位置，原点在左上、x 向右、y 向下。jsPDF 没有自动页边距、内容流、自动换行或自动分页——这些都要你自己计算（留白、断行、addPage）。这正是它与 pdfmake / @react-pdf 的根本区别。

二、单位：坐标随 unit，字号恒为 pt

const doc = new jsPDF({ unit: 'mm' });
doc.text('x', 10, 10);   // 10 = 10 毫米
doc.setFontSize(12);     // 12 = 12 磅（pt），与 unit 无关

概念	受 unit 影响？
text/line/rect/addImage 的坐标与尺寸	✅ 是（mm/in/px…）
setFontSize 的字号	❌ 否，始终 pt
setLineWidth 的线宽	✅ 是

合法 unit：'pt'/'mm'/'cm'/'m'/'in'/'px'。没有 'inch'/'rem'/'%'。

三、状态型样式：先设后画

颜色、线宽、字体都是状态：调用设置方法后，影响其后的绘制，直到再次更改。所以必须在绘制之前设好。

doc.setFillColor(230, 230, 230); // 填充色
doc.setDrawColor(40, 40, 40);    // 描边色
doc.setLineWidth(0.5);
doc.rect(20, 30, 60, 30, 'FD');  // 此矩形：浅灰填充 + 深灰描边

三种颜色分工：

方法	控制
setDrawColor	描边/线条颜色（line、图形的 stroke 部分）
setFillColor	图形填充颜色（fill 部分）
setTextColor	文字颜色

顺序很重要：先 rect 再 setFillColor，颜色对这次绘制不生效。

四、图形与 style 参数

图形方法（rect/circle/ellipse/triangle/roundedRect）最后一个 style 控制绘制方式：

doc.rect(20, 30, 50, 20, 'S');   // 只描边（默认）
doc.rect(20, 60, 50, 20, 'F');   // 只填充
doc.rect(20, 90, 50, 20, 'FD');  // 填充 + 描边
doc.roundedRect(20, 120, 50, 20, 3, 3, 'FD'); // 圆角矩形（rx, ry）

style	含义	用色
'S'	stroke 只描边	drawColor
'F'	fill 只填充	fillColor
'FD' / 'DF'	填充并描边	两者

五、文字与对齐

doc.setFontSize(20);
doc.setTextColor(33, 33, 33);
doc.text('左对齐', 20, 20);

// 居中：x 取页宽一半，再 align: 'center'
const centerX = doc.internal.pageSize.getWidth() / 2;
doc.text('整页居中标题', centerX, 35, { align: 'center' });

// 右对齐：以 x 为右端
doc.text('右对齐', 190, 50, { align: 'right' });

align 以传入的 x 为基准：'center' 把 x 当水平中心、'right' 把 x 当右端。只写 align 不给正确的 x 不会整页居中。

六、长文本换行：splitTextToSize

text() 不自动换行，长字符串会冲出右边界。用 splitTextToSize 按宽度切成行数组再画：

const margin = 20;
const usableWidth = doc.internal.pageSize.getWidth() - margin * 2;

const long = '这是一段很长的文本……（略）';
const lines = doc.splitTextToSize(long, usableWidth); // 字符串数组，每项一行
doc.text(lines, margin, 30); // 传数组即按行排版

行高随字号与 setLineHeightFactor 变化。要知道文本占多高，可结合 lines.length 与字号估算，用于后续 y 定位或判断是否需要 addPage。

七、读取页面尺寸

居中、画满宽分隔线、定位页脚都需要页面尺寸：

const w = doc.internal.pageSize.getWidth();  // 当前单位下的页宽
const h = doc.internal.pageSize.getHeight(); // 页高
// 便捷别名
const w2 = doc.getPageWidth();
const h2 = doc.getPageHeight();

doc.line(20, h - 15, w - 20, h - 15); // 距底 15 单位画页脚线

不要写死 210×297——那只是 A4 + mm 的值，换 format/unit 就不对。

八、一个最小「卡片」示例

const doc = new jsPDF();
doc.setFillColor(245, 247, 250);
doc.setDrawColor(220);
doc.roundedRect(20, 20, 80, 40, 3, 3, 'FD'); // 卡片背景

doc.setTextColor(33);
doc.setFontSize(14);
doc.text('卡片标题', 28, 32);
doc.setFontSize(10);
doc.setTextColor(120);
doc.text('一段说明文字', 28, 42);

doc.save('card.pdf');

---

进入 指南 · 进阶：图片与 addImage、jspdf-autotable 表格、.html() 栅格化、多页页眉页脚、导出形态与上传。