0
# Editor API
1

2
Interactive annotation creation and editing tools including freetext, highlighting, stamps, and ink annotations. Provides a complete framework for creating and modifying PDF annotations.
3

4
## Capabilities
5

6
### Annotation Editor Layer
7

8
Main layer for interactive annotation editing, supporting multiple editor types and user interactions.
9

10
```javascript { .api }
11
class AnnotationEditorLayer {
12
  /**
13
   * Constructor for annotation editor layer
14
   * @param options - Editor layer options
15
   */
16
  constructor(options: AnnotationEditorLayerOptions);
17
  
18
  /**
19
   * Render the editor layer
20
   * @param parameters - Render parameters
21
   */
22
  render(parameters: AnnotationEditorLayerParameters): void;
23
  
24
  /**
25
   * Update the editor layer
26
   * @param parameters - Update parameters
27
   */
28
  update(parameters: AnnotationEditorLayerParameters): void;
29
  
30
  /**
31
   * Update editor mode
32
   * @param mode - Editor mode (AnnotationEditorType)
33
   */
34
  updateMode(mode: number): void;
35
  
36
  /**
37
   * Add ink editor if needed
38
   * @param isCommitting - Whether committing current editor
39
   */
40
  addInkEditorIfNeeded(isCommitting: boolean): void;
41
  
42
  /**
43
   * Add stamp editor if needed
44
   */
45
  addStampEditorIfNeeded(): void;
46
  
47
  /**
48
   * Destroy the editor layer
49
   */
50
  destroy(): void;
51
  
52
  /**
53
   * Set editing state
54
   * @param isEditing - Whether currently editing
55
   */
56
  setEditingState(isEditing: boolean): void;
57
  
58
  /**
59
   * Enable click events
60
   * @param enable - Whether to enable
61
   */
62
  enableClick(enable: boolean): void;
63
  
64
  /**
65
   * Add editor at coordinates
66
   * @param x - X coordinate
67
   * @param y - Y coordinate
68
   */
69
  addEditor(x: number, y: number): void;
70
}
71
```
72

73
### Annotation Editor Layer Parameters
74

75
Configuration for editor layer rendering and updates.
76

77
```javascript { .api }
78
interface AnnotationEditorLayerParameters {
79
  /** Annotation storage for persistence */
80
  annotationStorage?: AnnotationStorage;
81
  /** Page div element */
82
  div: HTMLElement;
83
  /** Page proxy */
84
  page: PDFPageProxy;
85
  /** Page viewport */
86
  viewport: PageViewport;
87
  /** UI manager for editor controls */
88
  uiManager: AnnotationEditorUIManager;
89
  /** Accessibility manager */
90
  accessibilityManager?: any;
91
  /** Additional HTML attributes */
92
  additionalAttributes?: Map<string, Map<string, any>>;
93
}
94

95
interface AnnotationEditorLayerOptions {
96
  /** UI manager instance */
97
  uiManager: AnnotationEditorUIManager;
98
  /** Page index */
99
  pageIndex: number;
100
  /** Page div element */
101
  div: HTMLElement;
102
  /** Accessibility manager */
103
  accessibilityManager?: any;
104
}
105
```
106

107
**Usage Examples:**
108

109
```javascript
110
import { AnnotationEditorLayer, AnnotationEditorUIManager } from "pdfjs-dist";
111

112
// Create UI manager
113
const uiManager = new AnnotationEditorUIManager();
114

115
// Create editor layer
116
const editorLayer = new AnnotationEditorLayer({
117
  uiManager: uiManager,
118
  pageIndex: 0,
119
  div: pageDiv
120
});
121

122
// Render editor layer
123
editorLayer.render({
124
  annotationStorage: annotationStorage,
125
  div: pageDiv,
126
  page: page,
127
  viewport: viewport,
128
  uiManager: uiManager
129
});
130

131
// Enable freetext editing mode
132
editorLayer.updateMode(AnnotationEditorType.FREETEXT);
133
```
134

135
### Annotation Editor UI Manager
136

137
Manages annotation editing UI, tool selection, and editor lifecycle.
138

139
```javascript { .api }
140
class AnnotationEditorUIManager {
141
  constructor();
142
  
143
  /**
144
   * Update UI for editor
145
   * @param editor - Editor instance
146
   */
147
  updateUI(editor: any): void;
148
  
149
  /**
150
   * Update editor mode
151
   * @param mode - Editor mode
152
   */
153
  updateMode(mode: number): void;
154
  
155
  /**
156
   * Get current editor mode
157
   * @returns Current mode
158
   */
159
  getMode(): number;
160
  
161
  /**
162
   * Set editor mode
163
   * @param mode - Editor mode
164
   * @param editId - Optional edit ID
165
   */
166
  setEditingState(mode: number, editId?: string): void;
167
  
168
  /**
169
   * Add editor to manager
170
   * @param pageIndex - Page index
171
   * @param editor - Editor instance
172
   */
173
  addEditor(pageIndex: number, editor: any): void;
174
  
175
  /**
176
   * Remove editor from manager
177
   * @param editor - Editor instance
178
   */
179
  removeEditor(editor: any): void;
180
  
181
  /**
182
   * Get editor by ID
183
   * @param id - Editor ID
184
   * @returns Editor instance
185
   */
186
  getEditor(id: string): any;
187
  
188
  /**
189
   * Get all editors on page
190
   * @param pageIndex - Page index
191
   * @returns Array of editors
192
   */
193
  getEditors(pageIndex: number): any[];
194
  
195
  /**
196
   * Focus editor
197
   * @param editor - Editor to focus
198
   */
199
  focusEditor(editor: any): void;
200
  
201
  /**
202
   * Add commands to undo stack
203
   * @param commands - Commands to add
204
   */
205
  addCommands(commands: any[]): void;
206
  
207
  /**
208
   * Destroy the UI manager
209
   */
210
  destroy(): void;
211
}
212
```
213

214
### Editor Types and Parameters
215

216
Configuration for different annotation editor types.
217

218
```javascript { .api }
219
enum AnnotationEditorType {
220
  DISABLE = -1,
221
  NONE = 0,
222
  FREETEXT = 3,
223
  HIGHLIGHT = 9,
224
  STAMP = 13,
225
  INK = 15
226
}
227

228
enum AnnotationEditorParamsType {
229
  RESIZE = 1,
230
  CREATE = 2,
231
  FREETEXT_SIZE = 11,
232
  FREETEXT_COLOR = 12,
233
  FREETEXT_OPACITY = 13,
234
  INK_COLOR = 21,
235
  INK_THICKNESS = 22,
236
  INK_OPACITY = 23,
237
  HIGHLIGHT_COLOR = 31,
238
  HIGHLIGHT_DEFAULT_COLOR = 32
239
}
240
```
241

242
### Color Picker
243

244
Color selection component for annotation editors.
245

246
```javascript { .api }
247
class ColorPicker {
248
  /**
249
   * Constructor for color picker
250
   * @param options - Color picker options
251
   */
252
  constructor(options: ColorPickerOptions);
253
  
254
  /**
255
   * Render main dropdown
256
   * @param buttons - Button configurations
257
   * @param className - CSS class name
258
   */
259
  renderMainDropdown(buttons: any[], className: string): HTMLElement;
260
  
261
  /**
262
   * Hide dropdown
263
   */
264
  hideDropdown(): void;
265
  
266
  /**
267
   * Show dropdown
268
   */
269
  showDropdown(): void;
270
  
271
  /**
272
   * Set color
273
   * @param color - Color value
274
   */
275
  setColor(color: string): void;
276
  
277
  /**
278
   * Get current color
279
   * @returns Current color
280
   */
281
  getColor(): string;
282
  
283
  /**
284
   * Destroy color picker
285
   */
286
  destroy(): void;
287
}
288

289
interface ColorPickerOptions {
290
  /** UI manager instance */
291
  uiManager: AnnotationEditorUIManager;
292
  /** Default colors */
293
  defaultColors?: string[];
294
  /** Current color */
295
  color?: string;
296
}
297
```
298

299
**Usage Examples:**
300

301
```javascript
302
// Create color picker for annotation editing
303
const colorPicker = new ColorPicker({
304
  uiManager: uiManager,
305
  defaultColors: ["#FF0000", "#00FF00", "#0000FF", "#FFFF00"],
306
  color: "#FF0000"
307
});
308

309
// Handle color changes
310
colorPicker.addEventListener("colorchange", (event) => {
311
  const newColor = event.detail.color;
312
  // Apply color to current editor
313
  uiManager.updateUI({ color: newColor });
314
});
315
```
316

317
### Freetext Editor
318

319
Text annotation editor for adding text annotations to PDFs.
320

321
```javascript { .api }
322
interface FreetextEditor {
323
  /** Editor type */
324
  editorType: number;
325
  /** Text content */
326
  content: string;
327
  /** Font size */
328
  fontSize: number;
329
  /** Text color */
330
  color: string;
331
  /** Font family */
332
  fontFamily: string;
333
  
334
  /**
335
   * Set font size
336
   * @param size - Font size in points
337
   */
338
  setFontSize(size: number): void;
339
  
340
  /**
341
   * Set text color
342
   * @param color - Color value
343
   */
344
  setColor(color: string): void;
345
  
346
  /**
347
   * Set font family
348
   * @param family - Font family name
349
   */
350
  setFontFamily(family: string): void;
351
  
352
  /**
353
   * Commit text changes
354
   */
355
  commit(): void;
356
  
357
  /**
358
   * Cancel editing
359
   */
360
  cancel(): void;
361
}
362
```
363

364
### Ink Editor
365

366
Drawing annotation editor for creating freehand drawings and signatures.
367

368
```javascript { .api }
369
interface InkEditor {
370
  /** Editor type */
371
  editorType: number;
372
  /** Stroke paths */
373
  paths: number[][];
374
  /** Stroke color */
375
  color: string;
376
  /** Stroke thickness */
377
  thickness: number;
378
  /** Stroke opacity */
379
  opacity: number;
380
  
381
  /**
382
   * Set stroke color
383
   * @param color - Color value
384
   */
385
  setColor(color: string): void;
386
  
387
  /**
388
   * Set stroke thickness
389
   * @param thickness - Thickness in pixels
390
   */
391
  setThickness(thickness: number): void;
392
  
393
  /**
394
   * Set stroke opacity
395
   * @param opacity - Opacity (0-1)
396
   */
397
  setOpacity(opacity: number): void;
398
  
399
  /**
400
   * Add stroke path
401
   * @param path - Array of coordinates
402
   */
403
  addPath(path: number[]): void;
404
  
405
  /**
406
   * Clear all paths
407
   */
408
  clear(): void;
409
  
410
  /**
411
   * Commit drawing
412
   */
413
  commit(): void;
414
}
415
```
416

417
### Stamp Editor
418

419
Stamp annotation editor for adding predefined stamps and images.
420

421
```javascript { .api }
422
interface StampEditor {
423
  /** Editor type */
424
  editorType: number;
425
  /** Stamp image */
426
  bitmap: ImageBitmap;
427
  /** Stamp dimensions */
428
  dimensions: { width: number; height: number };
429
  
430
  /**
431
   * Set stamp image
432
   * @param bitmap - Image bitmap
433
   */
434
  setBitmap(bitmap: ImageBitmap): void;
435
  
436
  /**
437
   * Set stamp from file
438
   * @param file - Image file
439
   */
440
  setFromFile(file: File): Promise<void>;
441
  
442
  /**
443
   * Resize stamp
444
   * @param width - New width
445
   * @param height - New height
446
   */
447
  resize(width: number, height: number): void;
448
  
449
  /**
450
   * Commit stamp placement
451
   */
452
  commit(): void;
453
}
454
```
455

456
### Highlight Editor
457

458
Text highlighting editor for marking and annotating text selections.
459

460
```javascript { .api }
461
interface HighlightEditor {
462
  /** Editor type */
463
  editorType: number;
464
  /** Highlight color */
465
  color: string;
466
  /** Selected text */
467
  text: string;
468
  /** Text rectangles */
469
  quadPoints: number[];
470
  
471
  /**
472
   * Set highlight color
473
   * @param color - Color value
474
   */
475
  setColor(color: string): void;
476
  
477
  /**
478
   * Set text selection
479
   * @param quadPoints - Selection rectangles
480
   */
481
  setSelection(quadPoints: number[]): void;
482
  
483
  /**
484
   * Commit highlight
485
   */
486
  commit(): void;
487
  
488
  /**
489
   * Remove highlight
490
   */
491
  remove(): void;
492
}
493
```
494

495
### Drawing Utilities
496

497
Helper classes and functions for drawing operations.
498

499
```javascript { .api }
500
class HighlightOutliner {
501
  /**
502
   * Create outline for text highlighting
503
   * @param boxes - Text boxes to outline
504
   * @param borderWidth - Border width
505
   * @param innerMargin - Inner margin
506
   * @param isLTR - Left-to-right text direction
507
   * @returns SVG path string
508
   */
509
  static createOutline(
510
    boxes: number[][],
511
    borderWidth: number,
512
    innerMargin: number,
513
    isLTR: boolean
514
  ): string;
515
}
516

517
class SignatureExtractor {
518
  /**
519
   * Extract signature paths from drawing input
520
   * @param paths - Input drawing paths
521
   * @param box - Bounding box
522
   * @returns Extracted signature data
523
   */
524
  static extract(paths: number[][], box: number[]): any;
525
}
526
```
527

528
**Usage Examples:**
529

530
```javascript
531
// Complete annotation editor setup
532
class PDFAnnotationEditor {
533
  constructor(container, annotationStorage) {
534
    this.container = container;
535
    this.annotationStorage = annotationStorage;
536
    this.uiManager = new AnnotationEditorUIManager();
537
    this.editorLayers = new Map();
538
    this.currentMode = AnnotationEditorType.NONE;
539
  }
540
  
541
  setupPage(pageIndex, page, viewport) {
542
    const pageDiv = document.createElement("div");
543
    pageDiv.className = "page";
544
    this.container.appendChild(pageDiv);
545
    
546
    const editorLayer = new AnnotationEditorLayer({
547
      uiManager: this.uiManager,
548
      pageIndex: pageIndex,
549
      div: pageDiv
550
    });
551
    
552
    editorLayer.render({
553
      annotationStorage: this.annotationStorage,
554
      div: pageDiv,
555
      page: page,
556
      viewport: viewport,
557
      uiManager: this.uiManager
558
    });
559
    
560
    this.editorLayers.set(pageIndex, editorLayer);
561
  }
562
  
563
  setMode(mode) {
564
    this.currentMode = mode;
565
    this.uiManager.updateMode(mode);
566
    
567
    // Update all editor layers
568
    for (const editorLayer of this.editorLayers.values()) {
569
      editorLayer.updateMode(mode);
570
    }
571
  }
572
  
573
  enableTextEditing() {
574
    this.setMode(AnnotationEditorType.FREETEXT);
575
  }
576
  
577
  enableInkDrawing() {
578
    this.setMode(AnnotationEditorType.INK);
579
  }
580
  
581
  enableHighlighting() {
582
    this.setMode(AnnotationEditorType.HIGHLIGHT);
583
  }
584
  
585
  enableStamps() {
586
    this.setMode(AnnotationEditorType.STAMP);
587
  }
588
  
589
  disableEditing() {
590
    this.setMode(AnnotationEditorType.DISABLE);
591
  }
592
  
593
  saveAnnotations() {
594
    return this.annotationStorage.serializable;
595
  }
596
  
597
  loadAnnotations(data) {
598
    // Load annotation data into storage
599
    Object.entries(data).forEach(([key, value]) => {
600
      this.annotationStorage.setValue(key, value);
601
    });
602
  }
603
}
604

605
// Usage example
606
const editor = new PDFAnnotationEditor(container, annotationStorage);
607

608
// Set up pages
609
pages.forEach((page, index) => {
610
  const viewport = page.getViewport({ scale: 1.0 });
611
  editor.setupPage(index, page, viewport);
612
});
613

614
// Enable different editing modes
615
document.getElementById("text-btn").onclick = () => editor.enableTextEditing();
616
document.getElementById("ink-btn").onclick = () => editor.enableInkDrawing();
617
document.getElementById("highlight-btn").onclick = () => editor.enableHighlighting();
618
document.getElementById("stamp-btn").onclick = () => editor.enableStamps();
619
document.getElementById("disable-btn").onclick = () => editor.disableEditing();
620
```