HotPDF Delphi Hyperlinks: Συμβουλές σχολιασμού PrintHyperlink

Οι υπερσύνδεσμοι PDF είναι σχολιασμοί URI: ένα ορθογώνιο που καλύπτει κάποια περιοχή της σελίδας και, όταν γίνει κλικ, λέει στο πρόγραμμα προβολής να ανοίξει μια διεύθυνση URL. Ο σχολιασμός και το κείμενο κάτω από αυτόν είναι εντελώς ανεξάρτητα αντικείμενα. Το PrintHyperlink του HotPDF τα συνδυάζει και τα δύο σε μία κλήση, σχεδιάζοντας το κείμενο και υπολογίζοντας το ορθογώνιο του σχολιασμού από τις μετρήσεις του αποδοθέντος κειμένου. Αυτή η ευκολία κρύβει μια λεπτομέρεια που αξίζει να κατανοήσετε πριν γράψετε κώδικα παραγωγής

Πώς λειτουργεί το PrintHyperlink

Το PrintHyperlink βρίσκεται στο THPDFPage και δέχεται τέσσερα ορίσματα: συντεταγμένες X και Y (σε σημεία, προέλευση κάτω αριστερά, το Y αυξάνεται προς τα πάνω), τη συμβολοσειρά ετικέτας για σχεδίαση και τον στόχο URL. Εσωτερικά καλεί το TextOut στο τρέχον χρώμα υπερσυνδέσμου και, στη συνέχεια, υπολογίζει αμέσως το ορθογώνιο σχολιασμού από τα TextWidth και TextHeight στις τρέχουσες μετρήσεις γραμματοσειράς. Αυτό σημαίνει ότι η γραμματοσειρά και το μέγεθος πρέπει να οριστούν πριν από την κλήση, και δεν πρέπει να αλλάξουν μεταξύ της σχεδίασης της ετικέτας και της τοποθέτησης του σχολιασμού, επειδή και τα δύο επιλύονται στην ίδια κλήση

Το προεπιλεγμένο χρώμα είναι το clBlue. Το SetRGBHyperlinkColor το αλλάζει μόνο για επόμενες κλήσεις. Δεν ενημερώνει αναδρομικά σχολιασμούς που έχουν ήδη γραφτεί. Εάν χρειάζεστε διαφορετικά χρώματα για διαφορετικές ομάδες συνδέσμων στην ίδια σελίδα, καλέστε το SetRGBHyperlinkColor πριν από κάθε ομάδα και επαναφέρετέ το στη συνέχεια

Ακολουθεί ένα ελάχιστο έγγραφο που γράφει τρεις συνδέσμους με δύο διαφορετικά χρώματα:

procedure CreateLinkedReport(const FileName: string);
var
  Pdf: THotPDF;
begin
  Pdf := THotPDF.Create(nil);
  try
    Pdf.FileName := FileName;
    Pdf.BeginDoc;

    Pdf.CurrentPage.SetFont('Arial', [], 11);

    // Default blue for informational links
    Pdf.CurrentPage.TextOut(50, 750, 0, 'Reference links:');
    Pdf.CurrentPage.PrintHyperlink(50, 720, 'Product page', 'https://www.loslab.com/en-us/pdf-library/delphi-pdf-component.html');
    Pdf.CurrentPage.PrintHyperlink(50, 695, 'Online manual', 'https://www.loslab.com/en-us/pdf-library/delphi-pdf-component.html');

    // Red for the action link
    Pdf.CurrentPage.SetRGBHyperlinkColor(clRed);
    Pdf.CurrentPage.PrintHyperlink(50, 660, 'Purchase license', 'https://www.loslab.com/en-us/buy-hotpdf-fastspring.html');
    Pdf.CurrentPage.SetRGBHyperlinkColor(clBlue);  // restore default

    Pdf.EndDoc;
  finally
    Pdf.Free;
  end;
end;

Η παγίδα των συντεταγμένων

Το HotPDF χρησιμοποιεί μια προέλευση κάτω-αριστερά με το Y να αυξάνεται προς τα πάνω, σε σημεία (1/72 ίντσας). Μια σελίδα A4 είναι 595 x 842 pt. μια σελίδα US Letter είναι 612 x 792 pt. Το Y=750 βρίσκεται κοντά στην κορυφή μιας σελίδας A4 και το Y=50 θα ήταν κοντά στο κάτω περιθώριο. Οποιοσδήποτε προέρχεται από γραφικά οθόνης ή HTML υποθέτει το αντίθετο και τοποθετεί την πρώτη γραμμή συνδέσμου κατευθείαν έξω από την ορατή περιοχή

Το ορθογώνιο σχολιασμού που υπολογίζει το PrintHyperlink χρησιμοποιεί το ίδιο σύστημα συντεταγμένων. Εάν αργότερα περιστρέψετε τη σελίδα, την κλιμακώσετε ή αλλάξετε το μέγεθος της σελίδας χωρίς να υπολογίσετε ξανά τις τιμές X/Y, το ορατό κείμενο και το ορθογώνιο με δυνατότητα κλικ θα απομακρυνθούν. Ο σύνδεσμος "λειτουργεί" με την έννοια ότι το κλικ κάπου κοντά στο κείμενο ενεργοποιεί τη διεύθυνση URL, αλλά η ενεργή ζώνη δεν ταιριάζει πλέον με αυτό που βλέπει ο αναγνώστης. Δοκιμάστε στο πραγματικό μέγεθος σελίδας και επίπεδο ζουμ που αποστέλλετε, όχι μόνο στο μηχάνημα ανάπτυξης στο 100%

Μία περίπτωση όπου η απόκλιση είναι εγγυημένη: εάν καλέσετε το PrintHyperlink με συντεταγμένες κατάλληλες για μια σελίδα A4 και, στη συνέχεια, μεταβείτε σε μια προσαρμοσμένη σελίδα στενής μορφής χωρίς να προσαρμόσετε τις τιμές X/Y, ο σχολιασμός μπορεί να καταλήξει εντελώς εκτός σελίδας. Το αντικείμενο σχολιασμού εξακολουθεί να είναι γραμμένο στο PDF. τα περισσότερα προγράμματα προβολής το αποκόπτουν σιωπηλά, επομένως ο σύνδεσμος απλώς εξαφανίζεται χωρίς κανένα σφάλμα

Κείμενο ετικέτας έναντι στόχου URL

Τα ορίσματα Text και Link είναι ανεξάρτητα. Μπορείτε να σχεδιάσετε το "Download invoice PDF" ενώ ο στόχος είναι ένα πλήρως προσδιορισμένο URL HTTPS με παραμέτρους ερωτήματος. Αυτός ο διαχωρισμός είναι σκόπιμος. η ορατή ετικέτα πρέπει να είναι αναγνώσιμη από τον άνθρωπο και η διεύθυνση URL μπορεί να είναι μεγάλη ή να δημιουργηθεί δυναμικά

Αυτό που δημιουργεί προβλήματα είναι όταν η ετικέτα είναι η ίδια η ανεπεξέργαστη διεύθυνση URL, ειδικά μια μεγάλη. Εάν η διεύθυνση URL τυλίγεται οπτικά σε δύο γραμμές, αλλά το ορθογώνιο σχολιασμού υπολογίστηκε για μια συμβολοσειρά μίας γραμμής, μόνο η πρώτη γραμμή έχει δυνατότητα κλικ. Το PrintHyperlink δεν χειρίζεται ροή πολλαπλών γραμμών. κρατήστε την ετικέτα αρκετά σύντομη ώστε να χωράει σε μία γραμμή στο τρέχον μέγεθος γραμματοσειράς και πλάτος σελίδας ή χρησιμοποιήστε μια σύντομη περιγραφική ετικέτα με την πλήρη διεύθυνση URL ως στόχο

Για έγγραφα που θα αρχειοθετηθούν ή θα διανεμηθούν χωρίς ενεργή σύνδεση στο Διαδίκτυο, εξετάστε επίσης εάν η ίδια η διεύθυνση URL θα πρέπει να εμφανίζεται σε έντυπη μορφή κάπου στο σώμα του εγγράφου, όχι μόνο ως μεταδεδομένα σχολιασμού. Ένας αναγνώστης που εκτυπώνει το PDF σε χαρτί δεν παίρνει τίποτα από έναν σχολιασμό URI

Περιορισμός πολλών γραμμών και εναλλακτική AddURILink

Το PrintHyperlink είναι βολικό για μία γραμμή, αλλά η αναδίπλωση κειμένου δεν αποτελεί ενιαίο σχολιασμό πολλών γραμμών. Για κείμενο που σπάει σε γραμμές χρησιμοποιήστε PrintWrappedHyperlink ή σχεδιάστε το κείμενο και τοποθετήστε ξεχωριστό ορθογώνιο AddURILink πάνω από την περιοχή που πρέπει να γίνει κλικ

Εσωτερική πλοήγηση με AddGoToLink

Για σύνδεση σε άλλη σελίδα του ίδιου PDF, το AddGoToLink χρησιμοποιεί δείκτη σελίδας και ορθογώνιο προορισμού αντί για εξωτερικό URL. Κατά τη δημιουργία πίνακα περιεχομένων υπολογίστε τον τελικό αριθμό σελίδας πριν γράψετε τον σχολιασμό

Ένα πλήρες παράδειγμα δημιουργίας εγγράφου

Το παρακάτω μοτίβο δείχνει ένα πιο ρεαλιστικό σενάριο: δημιουργία μιας σύντομης αναφοράς με μια ενότητα κεφαλίδας, κείμενο σώματος και μια σειρά υποσέλιδου από συνδέσμους, όλα από κώδικα και όχι από μια φόρμα με πεδία TEdit:

procedure GenerateProductSheet(
  const FileName, ProductName, ProductURL, SupportURL: string);
var
  Pdf: THotPDF;
begin
  Pdf := THotPDF.Create(nil);
  try
    Pdf.FileName := FileName;
    Pdf.Compression := cmFlateDecode;
    Pdf.BeginDoc;

    // Header
    Pdf.CurrentPage.SetFont('Arial', [fsBold], 16);
    Pdf.CurrentPage.TextOut(50, 750, 0, WideString(ProductName));

    // Body paragraph placeholder
    Pdf.CurrentPage.SetFont('Arial', [], 11);
    Pdf.CurrentPage.TextOut(50, 710, 0, 'See the links below for full documentation.');

    // Footer links
    Pdf.CurrentPage.SetFont('Arial', [], 10);
    Pdf.CurrentPage.TextOut(50, 80, 0, 'Links:');
    Pdf.CurrentPage.PrintHyperlink(50, 60, 'Product page', ProductURL);
    Pdf.CurrentPage.PrintHyperlink(200, 60, 'Support', SupportURL);

    Pdf.EndDoc;
  finally
    Pdf.Free;
  end;
end;

Σημειώστε ότι το SetFont καλείται πριν από κάθε ομάδα κλήσεων κειμένου. Η γραμματοσειρά δεν παραμένει σε όλο το AddPage και εάν ξεχάσετε να την ορίσετε πριν από το PrintHyperlink σε μια νέα σελίδα, το ορθογώνιο σχολιασμού θα υπολογιστεί με βάση τις προεπιλεγμένες μετρήσεις της σελίδας, οι οποίες ενδέχεται να διαφέρουν από αυτό που περιμένετε

Πού διαφέρει ο χειρισμός σχολιασμών στα προγράμματα προβολής

Οι σχολιασμοί URI PDF ορίζονται στο ISO 32000-1 §12.6.4.7 και κάθε συμβατό πρόγραμμα προβολής πρέπει να τους ακολουθεί. Στην πράξη, μερικές συμπεριφορές διαφέρουν ανάλογα με το πρόγραμμα προβολής. Το Adobe Acrobat εμφανίζει ένα μήνυμα ασφαλείας στο πρώτο κλικ για διευθύνσεις URL που δεν περιλαμβάνονται στη λίστα αξιόπιστων τομέων. Πολλά προγράμματα περιήγησης και ελαφριά προγράμματα ανάγνωσης δεν το κάνουν. Ορισμένα εταιρικά προγράμματα προβολής PDF σε κλειδωμένα περιβάλλοντα απενεργοποιούν εντελώς τους σχολιασμούς URI βάσει πολιτικής, επομένως ένα κλικ δεν κάνει τίποτα, χωρίς ορατό σφάλμα. Οι εφαρμογές PDF για κινητά διαφέρουν ως προς το εάν ανοίγουν συνδέσμους μέσα στην προβολή ιστού της εφαρμογής ή παραδίδουν στο πρόγραμμα περιήγησης συστήματος

Κανένα από αυτά δεν είναι σφάλματα που μπορείτε να διορθώσετε από την πλευρά της παραγωγής. Είναι αποφάσεις πολιτικής προγράμματος προβολής. Αυτό που μπορείτε να κάνετε είναι να γράψετε ετικέτες συνδέσμων που καθιστούν το URL ορατό και στο σώμα του εγγράφου, ώστε ένας αναγνώστης σε περιορισμένο περιβάλλον να μπορεί ακόμα να αντιγράψει τη διεύθυνση χειροκίνητα. Ο σχολιασμός είναι η ευκολία. Το κείμενο είναι η εναλλακτική λύση

Μια ακόμη λεπτομέρεια που αξίζει να γνωρίζετε: οι σχολιασμοί URI PDF δεν φέρουν καμία οπτική υπογράμμιση από προεπιλογή. Η υπογράμμιση που βλέπετε στα περισσότερα προγράμματα προβολής σχεδιάζεται από το ίδιο το πρόγραμμα προβολής με βάση τον τύπο σχολιασμού και όχι από ένα γλύφο στη ροή περιεχομένου. Εάν χρειάζεστε μια φυσική υπογράμμιση που να επιβιώνει στην εκτύπωση σε μη διαδραστικό πρόγραμμα απόδοσης ή σε μετατροπή PDF σε εικόνα, σχεδιάστε τη ρητά με τα LineTo και Stroke στην κατάλληλη μετατόπιση Y κάτω από τη γραμμή βάσης κειμένου. Αυτή είναι μια ξεχωριστή λειτουργία σχεδίασης, όχι κάτι που το PrintHyperlink χειρίζεται για εσάς

Το API υπερσυνδέσμων που εμφανίζεται εδώ αποτελεί μέρος του Στοιχείου HotPDF για Delphi και C++Builder