Build has been canceled!

adnsistemas / pdf-lib / #18

Committed 24 Mar 2026 08:15PM UTC coverage: 74.286% (+0.3%) from 74.001%

Build # #18

Build Type

push

Committed by David N. Abdala

Commit Message

Documentation change

Coverage Stats

2569 of 3981 branches covered (64.53%)

Branch coverage included in aggregate %.

7372 of 9401 relevant lines covered (78.42%)

297170.51 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

77.64

/src/api/form/PDFButton.ts

import PDFDocument from '../PDFDocument';
import PDFPage from '../PDFPage';
import PDFFont from '../PDFFont';
import PDFImage from '../PDFImage';
import { ImageAlignment } from '../image/alignment';
import {
  AppearanceProviderFor,
  normalizeAppearance,
  defaultButtonAppearanceProvider,
} from './appearances';
import PDFField, {
  FieldAppearanceOptions,
  assertFieldAppearanceOptions,
} from './PDFField';
import { rgb } from '../colors';
import { degrees } from '../rotations';

import { PDFRef, PDFAcroPushButton, PDFWidgetAnnotation } from '../../core';
import { assertIs, assertOrUndefined, assertPositive } from '../../utils';
import { isPDFInstance, PDFClasses } from '../objects';

/**
 * Represents a button field of a [[PDFForm]].
 *
 * [[PDFButton]] fields are interactive controls that users can click with their
 * mouse. This type of [[PDFField]] is not stateful. The purpose of a button
 * is to perform an action when the user clicks on it, such as opening a print
 * modal or resetting the form. Buttons are typically rectangular in shape and
 * have a text label describing the action that they perform when clicked.
 */
export default class PDFButton extends PDFField {
  static className = () => PDFClasses.PDFButton;
  myClass(): PDFClasses {
    return PDFClasses.PDFButton;
  }
  /**
   * > **NOTE:** You probably don't want to call this method directly. Instead,
   * > consider using the [[PDFForm.getButton]] method, which will create an
   * > instance of [[PDFButton]] for you.
   *
   * Create an instance of [[PDFButton]] from an existing acroPushButton and ref
   *
   * @param acroPushButton The underlying `PDFAcroPushButton` for this button.
   * @param ref The unique reference for this button.
   * @param doc The document to which this button will belong.
   */
  static of = (
    acroPushButton: PDFAcroPushButton,
    ref: PDFRef,
    doc: PDFDocument,
  ) => new PDFButton(acroPushButton, ref, doc);

  /** The low-level PDFAcroPushButton wrapped by this button. */
  readonly acroField: PDFAcroPushButton;

  private constructor(
    acroPushButton: PDFAcroPushButton,
    ref: PDFRef,
    doc: PDFDocument,
  ) {
    super(acroPushButton, ref, doc);

    assertIs(acroPushButton, 'acroButton', [
      [PDFAcroPushButton, 'PDFAcroPushButton'],
    ]);

    this.acroField = acroPushButton;
  }

  /**
   * Display an image inside the bounds of this button's widgets. For example:
   * ```js
   * const pngImage = await pdfDoc.embedPng(...)
   * const button = form.getButton('some.button.field')
   * button.setImage(pngImage, ImageAlignment.Center)
   * ```
   * This will update the appearances streams for each of this button's widgets.
   * @param image The image that should be displayed.
   * @param alignment The alignment of the image.
   */
  setImage(image: PDFImage, alignment = ImageAlignment.Center) {
    const widgets = this.acroField.getWidgets();
    for (let idx = 0, len = widgets.length; idx < len; idx++) {
      const widget = widgets[idx];
      const streamRef = this.createImageAppearanceStream(
        widget,
        image,
        alignment,
      );
      this.updateWidgetAppearances(widget, { normal: streamRef });
    }

    this.markAsClean();
  }

  /**
   * Set the font size for this field. Larger font sizes will result in larger
   * text being displayed when PDF readers render this button. Font sizes may
   * be integer or floating point numbers. Supplying a negative font size will
   * cause this method to throw an error.
   *
   * For example:
   * ```js
   * const button = form.getButton('some.button.field')
   * button.setFontSize(4)
   * button.setFontSize(15.7)
   * ```
   *
   * > This method depends upon the existence of a default appearance
   * > (`/DA`) string. If this field does not have a default appearance string,
   * > or that string does not contain a font size (via the `Tf` operator),
   * > then this method will throw an error.
   *
   * @param fontSize The font size to be used when rendering text in this field.
   */
  setFontSize(fontSize: number) {
    assertPositive(fontSize, 'fontSize');
    this.acroField.setFontSize(fontSize);
    this.markAsDirty();
  }

  /**
   * Show this button on the specified page with the given text. For example:
   * ```js
   * const ubuntuFont = await pdfDoc.embedFont(ubuntuFontBytes)
   * const page = pdfDoc.addPage()
   *
   * const form = pdfDoc.getForm()
   * const button = form.createButton('some.button.field')
   *
   * button.addToPage('Do Stuff', page, {
   *   x: 50,
   *   y: 75,
   *   width: 200,
   *   height: 100,
   *   textColor: rgb(1, 0, 0),
   *   backgroundColor: rgb(0, 1, 0),
   *   borderColor: rgb(0, 0, 1),
   *   borderWidth: 2,
   *   rotate: degrees(90),
   *   font: ubuntuFont,
   * })
   * ```
   * This will create a new widget for this button field.
   * @param text The text to be displayed for this button widget.
   * @param page The page to which this button widget should be added.
   * @param options The options to be used when adding this button widget.
   */
  addToPage(
    // TODO: This needs to be optional, e.g. for image buttons
    text: string,
    page: PDFPage,
    options?: FieldAppearanceOptions,
  ) {
    assertOrUndefined(text, 'text', ['string']);
    assertOrUndefined(page, 'page', [[PDFPage, 'PDFPage']]);
    assertFieldAppearanceOptions(options);

    // Create a widget for this button
    const widget = this.createWidget({
      x: (options?.x ?? 0) - (options?.borderWidth ?? 0) / 2,
      y: (options?.y ?? 0) - (options?.borderWidth ?? 0) / 2,
      width: options?.width ?? 100,
      height: options?.height ?? 50,
      textColor: options?.textColor ?? rgb(0, 0, 0),
      backgroundColor: options?.backgroundColor ?? rgb(0.75, 0.75, 0.75),
      borderColor: options?.borderColor,
      borderWidth: options?.borderWidth ?? 0,
      rotate: options?.rotate ?? degrees(0),
      caption: text,
      hidden: options?.hidden,
      page: page.ref,
    });
    const widgetRef = this.doc.context.register(widget.dict);

    // Add widget to this field
    this.acroField.addWidget(widgetRef);

    // Set appearance streams for widget
    const font = options?.font ?? this.doc.getForm().getDefaultFont();
    this.updateWidgetAppearance(widget, font);

    // Add widget to the given page
    page.node.addAnnot(widgetRef);
  }

  /**
   * Returns `true` if this button has been marked as dirty, or if any of this
   * button's widgets do not have an appearance stream. For example:
   * ```js
   * const button = form.getButton('some.button.field')
   * if (button.needsAppearancesUpdate()) console.log('Needs update')
   * ```
   * @returns Whether or not this button needs an appearance update.
   */
  needsAppearancesUpdate(): boolean {
    if (this.isDirty()) return true;

    const widgets = this.acroField.getWidgets();
    for (let idx = 0, len = widgets.length; idx < len; idx++) {
      const widget = widgets[idx];
      const hasAppearances = isPDFInstance(
        widget.getAppearances()?.normal,
        PDFClasses.PDFStream,
      );
      if (!hasAppearances) return true;
    }

    return false;
  }

  /**
   * Update the appearance streams for each of this button's widgets using
   * the default appearance provider for buttons. For example:
   * ```js
   * const helvetica = await pdfDoc.embedFont(StandardFonts.Helvetica)
   * const button = form.getButton('some.button.field')
   * button.defaultUpdateAppearances(helvetica)
   * ```
   * @param font The font to be used for creating the appearance streams.
   */
  defaultUpdateAppearances(font: PDFFont) {
    assertIs(font, 'font', [[PDFFont, 'PDFFont']]);
    this.updateAppearances(font);
  }

  /**
   * Update the appearance streams for each of this button's widgets using
   * the given appearance provider. If no `provider` is passed, the default
   * appearance provider for buttons will be used. For example:
   * ```js
   * const helvetica = await pdfDoc.embedFont(StandardFonts.Helvetica)
   * const button = form.getButton('some.button.field')
   * button.updateAppearances(helvetica, (field, widget, font) => {
   *   ...
   *   return {
   *     normal: drawButton(...),
   *     down: drawButton(...),
   *   }
   * })
   * ```
   * @param font The font to be used for creating the appearance streams.
   * @param provider Optionally, the appearance provider to be used for
   *                 generating the contents of the appearance streams.
   */
  updateAppearances(
    font: PDFFont,
    provider?: AppearanceProviderFor<PDFButton>,
  ) {
    assertIs(font, 'font', [[PDFFont, 'PDFFont']]);
    assertOrUndefined(provider, 'provider', [Function]);

    const widgets = this.acroField.getWidgets();
    for (let idx = 0, len = widgets.length; idx < len; idx++) {
      const widget = widgets[idx];
      this.updateWidgetAppearance(widget, font, provider);
    }
  }

  private updateWidgetAppearance(
    widget: PDFWidgetAnnotation,
    font: PDFFont,
    provider?: AppearanceProviderFor<PDFButton>,
  ) {
    const apProvider = provider ?? defaultButtonAppearanceProvider;
    const appearances = normalizeAppearance(apProvider(this, widget, font));
    this.updateWidgetAppearanceWithFont(widget, font, appearances);
  }
}

1	import PDFDocument from '../PDFDocument';
2	import PDFPage from '../PDFPage';	54✔
3	import PDFFont from '../PDFFont';	54✔
4	import PDFImage from '../PDFImage';
5	import { ImageAlignment } from '../image/alignment';	54✔
6	import {	54✔
7	AppearanceProviderFor,
8	normalizeAppearance,
9	defaultButtonAppearanceProvider,
10	} from './appearances';
11	import PDFField, {	54✔
12	FieldAppearanceOptions,
13	assertFieldAppearanceOptions,
14	} from './PDFField';
15	import { rgb } from '../colors';	54✔
16	import { degrees } from '../rotations';	54✔
17
18	import { PDFRef, PDFAcroPushButton, PDFWidgetAnnotation } from '../../core';	54✔
19	import { assertIs, assertOrUndefined, assertPositive } from '../../utils';	54✔
20	import { isPDFInstance, PDFClasses } from '../objects';	54✔
21
22	/**
23	* Represents a button field of a [[PDFForm]].
24	*
25	* [[PDFButton]] fields are interactive controls that users can click with their
26	* mouse. This type of [[PDFField]] is not stateful. The purpose of a button
27	* is to perform an action when the user clicks on it, such as opening a print
28	* modal or resetting the form. Buttons are typically rectangular in shape and
29	* have a text label describing the action that they perform when clicked.
30	*/
31	export default class PDFButton extends PDFField {	54✔
32	static className = () => PDFClasses.PDFButton;	54✔
33	myClass(): PDFClasses {
34	return PDFClasses.PDFButton;	×
35	}
36	/**
37	* > NOTE: You probably don't want to call this method directly. Instead,
38	* > consider using the [[PDFForm.getButton]] method, which will create an
39	* > instance of [[PDFButton]] for you.
40	*
41	* Create an instance of [[PDFButton]] from an existing acroPushButton and ref
42	*
43	* @param acroPushButton The underlying `PDFAcroPushButton` for this button.
44	* @param ref The unique reference for this button.
45	* @param doc The document to which this button will belong.
46	*/
47	static of = (	54✔
48	acroPushButton: PDFAcroPushButton,
49	ref: PDFRef,
50	doc: PDFDocument,
51	) => new PDFButton(acroPushButton, ref, doc);	334✔
52
53	/** The low-level PDFAcroPushButton wrapped by this button. */
54	readonly acroField: PDFAcroPushButton;
55
56	private constructor(
57	acroPushButton: PDFAcroPushButton,
58	ref: PDFRef,
59	doc: PDFDocument,
60	) {
61	super(acroPushButton, ref, doc);	334✔
62
63	assertIs(acroPushButton, 'acroButton', [	334✔
64	[PDFAcroPushButton, 'PDFAcroPushButton'],
65	]);
66
67	this.acroField = acroPushButton;	334✔
68	}
69
70	/**
71	* Display an image inside the bounds of this button's widgets. For example:
72	* ```js
73	* const pngImage = await pdfDoc.embedPng(...)
74	* const button = form.getButton('some.button.field')
75	* button.setImage(pngImage, ImageAlignment.Center)
76	* ```
77	* This will update the appearances streams for each of this button's widgets.
78	* @param image The image that should be displayed.
79	* @param alignment The alignment of the image.
80	*/
81	setImage(image: PDFImage, alignment = ImageAlignment.Center) {	×
82	const widgets = this.acroField.getWidgets();	×
83	for (let idx = 0, len = widgets.length; idx < len; idx++) {	×
84	const widget = widgets[idx];	×
85	const streamRef = this.createImageAppearanceStream(	×
86	widget,
87	image,
88	alignment,
89	);
90	this.updateWidgetAppearances(widget, { normal: streamRef });	×
91	}
92
93	this.markAsClean();	×
94	}
95
96	/**
97	* Set the font size for this field. Larger font sizes will result in larger
98	* text being displayed when PDF readers render this button. Font sizes may
99	* be integer or floating point numbers. Supplying a negative font size will
100	* cause this method to throw an error.
101	*
102	* For example:
103	* ```js
104	* const button = form.getButton('some.button.field')
105	* button.setFontSize(4)
106	* button.setFontSize(15.7)
107	* ```
108	*
109	* > This method depends upon the existence of a default appearance
110	* > (`/DA`) string. If this field does not have a default appearance string,
111	* > or that string does not contain a font size (via the `Tf` operator),
112	* > then this method will throw an error.
113	*
114	* @param fontSize The font size to be used when rendering text in this field.
115	*/
116	setFontSize(fontSize: number) {
117	assertPositive(fontSize, 'fontSize');	×
118	this.acroField.setFontSize(fontSize);	×
119	this.markAsDirty();	×
120	}
121
122	/**
123	* Show this button on the specified page with the given text. For example:
124	* ```js
125	* const ubuntuFont = await pdfDoc.embedFont(ubuntuFontBytes)
126	* const page = pdfDoc.addPage()
127	*
128	* const form = pdfDoc.getForm()
129	* const button = form.createButton('some.button.field')
130	*
131	* button.addToPage('Do Stuff', page, {
132	* x: 50,
133	* y: 75,
134	* width: 200,
135	* height: 100,
136	* textColor: rgb(1, 0, 0),
137	* backgroundColor: rgb(0, 1, 0),
138	* borderColor: rgb(0, 0, 1),
139	* borderWidth: 2,
140	* rotate: degrees(90),
141	* font: ubuntuFont,
142	* })
143	* ```
144	* This will create a new widget for this button field.
145	* @param text The text to be displayed for this button widget.
146	* @param page The page to which this button widget should be added.
147	* @param options The options to be used when adding this button widget.
148	*/
149	addToPage(
150	// TODO: This needs to be optional, e.g. for image buttons
151	text: string,
152	page: PDFPage,
153	options?: FieldAppearanceOptions,
154	) {
155	assertOrUndefined(text, 'text', ['string']);	1✔
156	assertOrUndefined(page, 'page', [[PDFPage, 'PDFPage']]);	1✔
157	assertFieldAppearanceOptions(options);	1✔
158
159	// Create a widget for this button
160	const widget = this.createWidget({	1✔
161	x: (options?.x ?? 0) - (options?.borderWidth ?? 0) / 2,	12!
162	y: (options?.y ?? 0) - (options?.borderWidth ?? 0) / 2,	12!
163	width: options?.width ?? 100,	6!
164	height: options?.height ?? 50,	6!
165	textColor: options?.textColor ?? rgb(0, 0, 0),	6!
166	backgroundColor: options?.backgroundColor ?? rgb(0.75, 0.75, 0.75),	6!
167	borderColor: options?.borderColor,	3!
168	borderWidth: options?.borderWidth ?? 0,	6!
169	rotate: options?.rotate ?? degrees(0),	6!
170	caption: text,
171	hidden: options?.hidden,	3!
172	page: page.ref,
173	});
174	const widgetRef = this.doc.context.register(widget.dict);	1✔
175
176	// Add widget to this field
177	this.acroField.addWidget(widgetRef);	1✔
178
179	// Set appearance streams for widget
180	const font = options?.font ?? this.doc.getForm().getDefaultFont();	1!
181	this.updateWidgetAppearance(widget, font);	1✔
182
183	// Add widget to the given page
184	page.node.addAnnot(widgetRef);	1✔
185	}
186
187	/**
188	* Returns `true` if this button has been marked as dirty, or if any of this
189	* button's widgets do not have an appearance stream. For example:
190	* ```js
191	* const button = form.getButton('some.button.field')
192	* if (button.needsAppearancesUpdate()) console.log('Needs update')
193	* ```
194	* @returns Whether or not this button needs an appearance update.
195	*/
196	needsAppearancesUpdate(): boolean {
197	if (this.isDirty()) return true;	17✔
198
199	const widgets = this.acroField.getWidgets();	13✔
200	for (let idx = 0, len = widgets.length; idx < len; idx++) {	13✔
201	const widget = widgets[idx];	13✔
202	const hasAppearances = isPDFInstance(	13✔
203	widget.getAppearances()?.normal,	39✔
204	PDFClasses.PDFStream,
205	);
206	if (!hasAppearances) return true;	13✔
207	}
208
209	return false;	12✔
210	}
211
212	/**
213	* Update the appearance streams for each of this button's widgets using
214	* the default appearance provider for buttons. For example:
215	* ```js
216	* const helvetica = await pdfDoc.embedFont(StandardFonts.Helvetica)
217	* const button = form.getButton('some.button.field')
218	* button.defaultUpdateAppearances(helvetica)
219	* ```
220	* @param font The font to be used for creating the appearance streams.
221	*/
222	defaultUpdateAppearances(font: PDFFont) {
223	assertIs(font, 'font', [[PDFFont, 'PDFFont']]);	5✔
224	this.updateAppearances(font);	5✔
225	}
226
227	/**
228	* Update the appearance streams for each of this button's widgets using
229	* the given appearance provider. If no `provider` is passed, the default
230	* appearance provider for buttons will be used. For example:
231	* ```js
232	* const helvetica = await pdfDoc.embedFont(StandardFonts.Helvetica)
233	* const button = form.getButton('some.button.field')
234	* button.updateAppearances(helvetica, (field, widget, font) => {
235	* ...
236	* return {
237	* normal: drawButton(...),
238	* down: drawButton(...),
239	* }
240	* })
241	* ```
242	* @param font The font to be used for creating the appearance streams.
243	* @param provider Optionally, the appearance provider to be used for
244	* generating the contents of the appearance streams.
245	*/
246	updateAppearances(
247	font: PDFFont,
248	provider?: AppearanceProviderFor<PDFButton>,
249	) {
250	assertIs(font, 'font', [[PDFFont, 'PDFFont']]);	5✔
251	assertOrUndefined(provider, 'provider', [Function]);	5✔
252
253	const widgets = this.acroField.getWidgets();	5✔
254	for (let idx = 0, len = widgets.length; idx < len; idx++) {	5✔
255	const widget = widgets[idx];	5✔
256	this.updateWidgetAppearance(widget, font, provider);	5✔
257	}
258	}
259
260	private updateWidgetAppearance(
261	widget: PDFWidgetAnnotation,
262	font: PDFFont,
263	provider?: AppearanceProviderFor<PDFButton>,
264	) {
265	const apProvider = provider ?? defaultButtonAppearanceProvider;	6!
266	const appearances = normalizeAppearance(apProvider(this, widget, font));	6✔
267	this.updateWidgetAppearanceWithFont(widget, font, appearances);	6✔
268	}
269	}

adnsistemas / pdf-lib / #18

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous