Una richiesta arriva sulla tua scrivania: prendi un lotto di estratti conto già renderizzati, oscura i numeri di conto, e spedisci due pagine per foglio per risparmiare carta. Entrambe le metà di questo compito sono chirurgia sul content stream di un PDF che non hai creato tu, quindi non c'è un comodo canvas di pagina su cui disegnare né un gestore di font su cui appoggiarti. Stai modificando direttamente il grafo di oggetti di un documento caricato, aggiungendo operatori di disegno grezzi a una pagina che ha impaginato qualche altro strumento. HotPDF espone esattamente due punti di ingresso per questo, e il più pericoloso dei due è quello che sembra innocuo
HotPDF è un componente PDF VCL nativo per Delphi e C++Builder, e la sua API per documenti caricati include metodi che creano contenuto di sana materia su una pagina che hai aperto da disco anziché una che hai costruito da zero. Due di loro sono il soggetto qui: RedactLoadedRect, che dipinge un rettangolo opaco su una regione, e StitchLoadedPage, che scala una pagina e la disegna sopra un'altra. Entrambi lavorano scrivendo operatori di content stream di ISO 32000-1 §8.5 nello stream /Contents della pagina. Capire cosa fanno quegli operatori, e altrettanto importante cosa non fanno, è la differenza tra uno strumento che funziona e una fuga di dati
Aggiungere operatori a una pagina caricata
Quando costruisci una pagina con la normale API di HotPDF, il componente possiede lo stream dei contenuti e serializza per te le chiamate TextOut e vettoriali. Una pagina caricata è diversa: il suo /Contents è un oggetto stream esistente, forse condiviso, forse parte di un array di contenuti, e devi innestarci senza corrompere ciò che c'è già. Tre piccoli helper lo rendono sicuro. NewIndirectStream alloca un THPDFStreamObject indiretto fresco con buffer vuoto e una voce /Length 0; ResolveLoadedStream segue un riferimento indiretto fino allo stream sottostante; e AppendLoadedStream scrive byte grezzi in coda allo stream e riscrive /Length così che l'oggetto salvato resti ben formato
Il pattern seguito da entrambi i metodi pubblici è lo stesso. Trova il /Contents della pagina, risolvilo in uno stream, e se non c'è uno stream utilizzabile, creane uno e collegalo. Poi aggiungi gli operatori. Poiché i nuovi byte vanno alla fine dello stream, il modello del painter garantisce che vengano renderizzati sopra a tutto ciò che il layout originale ha disegnato. Questo ordinamento è l'intero meccanismo dietro il rettangolo di redazione, ed è anche il motivo per cui quel rettangolo non è ciò che la maggior parte delle persone presume che sia
RedactLoadedRect: una copertura opaca, non una cancellazione
RedactLoadedRect accetta un indice di pagina a base zero, quattro coordinate in user space e tre componenti di colore nell'intervallo 0–1:
var
Pdf: THotPDF;
begin
Pdf := THotPDF.Create(nil);
try
if Pdf.LoadFromFile('statement.pdf') > 0 then
begin
// Copri la banda del numero di conto sulla pagina 1 con nero pieno.
// Le coordinate sono nello user space del PDF: origine in basso a sinistra, punti.
Pdf.RedactLoadedRect(0, 56, 690, 320, 706, 0, 0, 0);
Pdf.SaveLoadedDocument('statement-covered.pdf');
end;
finally
Pdf.Free;
end;
end;
Sotto il cofano il metodo emette tre operatori nel content stream: un'impostazione del colore di riempimento in DeviceRGB (r g b rg), un percorso rettangolare (x y w h re), e un riempimento (f). Larghezza e altezza sono derivate come X2 - X1 e Y2 - Y1, quindi passi due angoli opposti e lasci che il metodo calcoli l'estensione. Passa 0, 0, 0 per il colore e ottieni una barra nera; passa 1, 1, 1 per una bianca che si abbina a una pagina bianca. Le coordinate sono lo user space proprio della pagina caricata, il che significa che l'origine è l'angolo in basso a sinistra e le unità sono punti, e significa anche che ti serve il /MediaBox della pagina per posizionare qualsiasi cosa con precisione; GetLoadedPageBox con pbMediaBox te lo fornisce
Leggi questo due volte: un rettangolo riempito copre il contenuto visivamente, non lo rimuove. Il testo, l'immagine o la grafica vettoriale sotto il rettangolo sono ancora presenti nel PDF, ancora nel grafo di oggetti, ancora estraibili da chiunque copi la pagina, esegua un estrattore di testo, o semplicemente elimini il tuo rettangolo dal content stream. Questo è mascheramento visivo, non redazione nel senso legale o di sicurezza. Se stai nascondendo dati genuinamente sensibili — numeri di conto, cartelle cliniche, identità, qualsiasi cosa regolamentata — coprirli con un riquadro nero e spedire il file è una fuga di dati in attesa di essere scoperta. Una vera redazione richiede l'eliminazione degli oggetti di contenuto sottostanti, non la loro copertura con vernice
Il nome del metodo dice "Redact", e quello è un avvertimento utile su come il risultato verrà frainteso, non una promessa su ciò che elimina. RedactLoadedRect è per progetto una primitiva di redazione visiva; la redazione che rimuove contenuto è un'operazione diversa, una che percorre e riscrive gli operatori esistenti del content stream. Così la regola sicura è ristretta: usa RedactLoadedRect per mascheramento estetico non sensibile — nascondere una filigrana di bozza, vuotare una regione prima di uno screenshot, coprire un logo obsoleto su una prova interna. Nel momento in cui ciò che sta sotto il riquadro conterebbe se finisse fuori, questo metodo è lo strumento sbagliato, e la risposta giusta è rigenerare il documento senza i dati o usare una vera pipeline di rimozione del contenuto
StitchLoadedPage: scala, trasla, disegna
L'imposizione N-up è il problema più amichevole perché niente viene nascosto, solo riorganizzato. StitchLoadedPage accetta un indice di pagina di destinazione, un indice di pagina sorgente, un offset X/Y e un fattore di scala, e disegna la pagina sorgente su quella di destinazione in quella posizione e dimensione:
// Sovrapponi la pagina 2 (indice 1) alla pagina 1 (indice 0),
// scalata al 70% e spostata in alto a destra.
Pdf.StitchLoadedPage(0, 1, 40, 380, 0.7);
// 2-up di comodità: pagina sorgente sulla metà destra della destinazione.
Pdf.StitchLoadedPageSideBySide(0, 1);
La stringa di operatori che aggiunge è una sequenza standard di trasformazione e disegno: q per salvare lo stato grafico, una matrice cm che porta la scala sulla diagonale e l'offset negli slot di traslazione, /StitchSrc Do per invocare un oggetto esterno, e Q per ripristinare lo stato. La coppia q/Q è importante: isola la trasformazione così che la pagina cucita non faccia sanguinare il proprio sistema di coordinate in qualsiasi cosa venga aggiunta dopo. Il metodo protegge anche dagli errori ovvi — indici fuori intervallo, una destinazione uguale alla sorgente, una scala non positiva (che viene forzata a 1.0) — ed esce silenziosamente invece di sollevare un'eccezione, quindi controlla i tuoi input perché un no-op silenzioso appare identico a un successo
StitchLoadedPageSideBySide è una sottile comodità sopra il metodo generale. Legge la larghezza del media-box della destinazione, la dimezza, e chiama StitchLoadedPage con quella mezza larghezza come offset X e una scala fissa di 0.5, mettendo la sorgente nella metà destra. Quello 0.5 hard-coded assume che sorgente e destinazione condividano la stessa larghezza; se non è così, la sorgente non riempirà la sua metà in modo pulito, e ti servirà il StitchLoadedPage generale con una scala che calcoli tu stesso a partire da entrambi i media box
Come lo stitch referenzia la pagina sorgente
Questo è il dettaglio da sapere prima di fidarti dell'output tra viewer diversi. Un'imposizione N-up classica avvolge il contenuto della pagina sorgente in un Form XObject — un oggetto disegnabile autosufficiente che ISO 32000-1 §8.10.1 dice dover portare /Type /XObject, /Subtype /Form e il proprio box di clipping /BBox. StitchLoadedPage prende una strada più leggera: registra il dizionario di pagina stesso della sorgente direttamente sotto /Resources /XObject della destinazione con il nome StitchSrc, poi lo disegna con Do. Un dizionario di pagina e un Form XObject condividono abbastanza del proprio modello di contenuto — entrambi referenziano uno stream di contenuto e un dizionario di risorse — che molti reader renderizzano il risultato
Poiché l'oggetto registrato non porta il marcatore /Subtype /Form né un /BBox proprio, un consumer rigoroso è nel suo diritto di ignorare il Do o di clippare diversamente da come ti aspetti. Quindi verifica l'output cucito nei viewer specifici che i tuoi clienti usano, non solo in quello sulla tua macchina, e per PDF d'archivio o puliti verso validatore rigoroso, imponi le pagine attraverso un wrapper Form XObject completo a monte. La stessa disciplina vale per qualunque cosa tu costruisca sul grafo di oggetti caricato, ed è per questo che un passaggio di preflight PDF in Delphi si guadagna il posto nella pipeline di rilascio ogni volta che muti documenti via codice
Dove questi strumenti si inseriscono, e dove no
Entrambi i metodi sono strumenti a livello di content stream, quindi il modello mentale è lo stesso che usi per il disegno diretto. Se hai costruito pagine da zero con il componente, gli operatori vettoriali e di colore dietro queste chiamate ti sembreranno familiari da il disegno su canvas di HotPDF in Delphi; la differenza è solo che qui stai aggiungendo a uno stream scritto da qualcun altro invece che a uno di tua proprietà. Tieni a mente tre confini:
- La redazione è cosmetica.
RedactLoadedRectdipinge sopra il contenuto e non lo elimina mai. Per qualsiasi cosa sensibile, rigenera la sorgente oppure usa una vera rimozione del contenuto — un riquadro nero non è sicurezza - Lo stitch non è conforme per progettazione. La pagina sorgente viene referenziata come uno pseudo-XObject privo del
/Subtype /Forme del/BBoxprevisti da §8.10.1, quindi conferma il rendering nei tuoi visualizzatori di destinazione ed evitalo dove è richiesta una validazione rigorosa - Le coordinate sono lo user space della pagina. Origine in basso a sinistra, punti, determinate dal media box proprio della pagina. Leggi il box con
GetLoadedPageBoxprima di posizionare qualsiasi cosa, perché la pagina che hai caricato potrebbe non avere le dimensioni che presumevi
Usati con quei confini a mente, la coppia copre un flusso di lavoro reale: riorganizzare pagine per la stampa, mascherare regioni non confidenziali, e riscrivere il risultato con SaveLoadedDocument — tutto senza un re-render completo. L'API per documenti caricati che include queste primitive di stitch e mascheratura viaggia con HotPDF Delphi Component per Delphi e C++Builder, accanto ai suoi metodi per campi modulo, annotazioni e FDF