gdr-hl-pdf

v2.0.7

Published

3 days ago

PDF Viewer Web Component with highlighting capabilities

0High
0Medium
0Low

gianluigi.ferraris

pdf viewer web-component stencil highlight annotation

gdr-hl-pdf

PDF Viewer Web Component with highlighting capabilities

Un Web Component costruito con Stencil.js che fornisce un visualizzatore PDF con funzionalità di evidenziazione e annotazione.

Caratteristiche

📄 Visualizzazione PDF completa con supporto per navigazione tra pagine
🖍️ Evidenziazione di aree del PDF tramite selezione con il mouse
🔄 Supporto per rotazione e zoom
📊 Conversione automatica tra coordinate viewport e coordinate PDF
🎨 Trasparenza personalizzabile per gli highlights
⚡ Costruito con Stencil.js per massime prestazioni
📦 Aggiornato con le ultime versioni di Stencil (4.x) e PDF.js (5.x)

Installazione

npm install gdr-hl-pdf

Utilizzo

Script Tag

<script type="module">
  import { defineCustomElements } from 'https://unpkg.com/gdr-hl-pdf/loader/index.es2017.js';
  defineCustomElements();
</script>

<gdrp-pdf src="path/to/your/document.pdf"></gdrp-pdf>

Node Modules

JavaScript/TypeScript

import { defineCustomElements } from 'gdr-hl-pdf/loader';

defineCustomElements();

<gdrp-pdf src="path/to/your/document.pdf"></gdrp-pdf>

React

import { GdrpPdf } from 'gdr-hl-pdf/dist/components/gdrp-pdf';

function MyComponent() {
  return <GdrpPdf src="path/to/your/document.pdf" scale={1.5} />;
}

Vue

<template>
  <gdrp-pdf :src="pdfUrl" :scale="1.5"></gdrp-pdf>
</template>

<script>
import { defineCustomElements } from 'gdr-hl-pdf/loader';

defineCustomElements();

export default {
  data() {
    return {
      pdfUrl: 'path/to/your/document.pdf'
    };
  }
};
</script>

Proprietà (Props)

| Proprietà | Tipo | Default | Descrizione | |-----------|------|---------|-------------| | src | string | - | URL o percorso del file PDF | | src64 | string | - | PDF in formato base64 | | scale | number | 1 | Scala di visualizzazione del PDF | | rotation | number | 0 | Rotazione in gradi (0, 90, 180, 270) | | pageNum | number | 1 | Numero di pagina corrente | | bodyWidth | number | 800 | Larghezza del contenitore per calcolo scala automatica | | bodyHeight | number | 600 | Altezza del contenitore per calcolo scala automatica | | alpha | number | 0.4 | Trasparenza degli highlights (0-1) | | hllist | string | - | Lista di highlights in coordinate viewport (JSON) | | hllistsingle | string | - | Singolo highlight in coordinate viewport (JSON) | | hllistpdf | string | - | Lista di highlights in coordinate PDF (JSON) |

Metodi

`pageNext(e: MouseEvent): Promise<void>`

Naviga alla pagina successiva.

const pdfViewer = document.querySelector('gdrp-pdf');
pdfViewer.pageNext(event);

`pagePrev(e: MouseEvent): Promise<void>`

Naviga alla pagina precedente.

const pdfViewer = document.querySelector('gdrp-pdf');
pdfViewer.pagePrev(event);

Eventi

`pageRendered`

Emesso quando una pagina viene renderizzata completamente.

pdfViewer.addEventListener('pageRendered', (event) => {
  console.log('Page rendered:', event.detail);
  // event.detail contiene: { vph, vpw, scale }
});

`pageChange`

Emesso quando cambia la pagina corrente.

pdfViewer.addEventListener('pageChange', (event) => {
  console.log('Current page:', event.detail);
});

`pdfSelectionChange`

Emesso quando l'utente seleziona un'area del PDF.

pdfViewer.addEventListener('pdfSelectionChange', (event) => {
  const selection = JSON.parse(event.detail);
  console.log('Selection:', selection);
  // selection contiene: { ux, uy, lx, ly, pdfUx, pdfUy, pdfLx, pdfLy }
});

Esempio Completo

<!DOCTYPE html>
<html>
<head>
  <script type="module">
    import { defineCustomElements } from 'https://unpkg.com/gdr-hl-pdf/loader/index.es2017.js';
    defineCustomElements();
  </script>
  <style>
    gdrp-pdf {
      width: 100%;
      height: 600px;
    }
  </style>
</head>
<body>
  <div>
    <button onclick="prevPage()">Previous</button>
    <button onclick="nextPage()">Next</button>
    <button onclick="zoomIn()">Zoom In</button>
    <button onclick="zoomOut()">Zoom Out</button>
  </div>
  
  <gdrp-pdf 
    id="pdf-viewer"
    src="document.pdf"
    scale="1"
  ></gdrp-pdf>

  <script>
    const viewer = document.getElementById('pdf-viewer');
    let currentScale = 1;

    viewer.addEventListener('pdfSelectionChange', (e) => {
      console.log('Selected area:', e.detail);
    });

    function prevPage() {
      viewer.pagePrev(new MouseEvent('click'));
    }

    function nextPage() {
      viewer.pageNext(new MouseEvent('click'));
    }

    function zoomIn() {
      currentScale += 0.25;
      viewer.scale = currentScale;
    }

    function zoomOut() {
      currentScale = Math.max(0.25, currentScale - 0.25);
      viewer.scale = currentScale;
    }
  </script>
</body>
</html>

Testing Rapido

⚡ Modo più veloce per testare

Apri examples/standalone.html direttamente nel browser! Questo esempio:

✅ Funziona senza server locale
✅ Non richiede build
✅ Include tutte le funzionalità base

🔧 Per usare `examples/index.html` (componente completo)

Devi usare un server locale per evitare errori CORS:

# Opzione 1: Python (già installato su Mac/Linux)
python3 -m http.server 8080

# Opzione 2: npx (Node.js)
npx serve -p 8080

# Opzione 3: Script incluso
./serve.sh  # Mac/Linux
serve.bat   # Windows

Poi apri: http://localhost:8080/examples/index.html

📖 Vedi CORS_HELP.md per altre soluzioni

Sviluppo

Prerequisiti

Node.js >= 16
npm >= 8

Setup

# Clone del repository
git clone https://github.com/yourusername/gdr-hl-pdf.git
cd gdr-hl-pdf

# Installazione delle dipendenze
npm install

# Sviluppo con hot reload
npm start

# Build per produzione
npm run build

# Esecuzione dei test
npm test

Struttura del Progetto

gdr-hl-pdf/
├── src/
│   ├── components/
│   │   └── gdrp-pdf/
│   │       ├── gdrp-pdf.tsx      # Componente principale
│   │       ├── gdrp-pdf.css      # Stili del componente
│   │       └── readme.md         # Documentazione auto-generata
│   └── index.ts                  # Entry point
├── dist/                         # File compilati
├── stencil.config.ts            # Configurazione Stencil
├── tsconfig.json                # Configurazione TypeScript
└── package.json

Changelog

v1.0.0 (2026)

✨ Aggiornamento a Stencil 4.x
✨ Aggiornamento a PDF.js 5.x
✨ Migrazione completa a TypeScript
✨ Miglioramento della gestione del worker PDF.js
✨ Supporto migliorato per base64
🐛 Fix vari nella gestione degli highlights
📚 Documentazione completa e aggiornata

v0.0.14 (Versione precedente)

Versione iniziale con Stencil 2.x e PDF.js 2.5.x

Browser Support

Chrome/Edge (ultime 2 versioni)
Firefox (ultime 2 versioni)
Safari (ultime 2 versioni)

Licenza

Contribuire

Le pull request sono benvenute! Per modifiche sostanziali, apri prima un issue per discutere cosa vorresti cambiare.

Supporto

Per bug report e richieste di funzionalità, utilizza la sezione Issues di GitHub.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

gdr-hl-pdf

Caratteristiche

Installazione

Utilizzo

Script Tag

Node Modules

JavaScript/TypeScript

React

Vue

Proprietà (Props)

Metodi

pageNext(e: MouseEvent): Promise<void>

pagePrev(e: MouseEvent): Promise<void>

Eventi

pageRendered

pageChange

pdfSelectionChange

Esempio Completo

Testing Rapido

⚡ Modo più veloce per testare

🔧 Per usare examples/index.html (componente completo)

Sviluppo

Prerequisiti

Setup

Struttura del Progetto

Changelog

v1.0.0 (2026)

v0.0.14 (Versione precedente)

Browser Support

Licenza

Contribuire

Supporto

`pageNext(e: MouseEvent): Promise<void>`

`pagePrev(e: MouseEvent): Promise<void>`

`pageRendered`

`pageChange`

`pdfSelectionChange`

🔧 Per usare `examples/index.html` (componente completo)