Mengimpor dan Mengekspor Anotasi PDF sebagai XFDF di Delphi

HotPDF mengekspor dan mengimpor anotasi PDF sebagai XFDF melalui dua fungsi yang bertindak pada dokumen yang saat ini dimuat, ExportLoadedAnnotationsToXFDF dan ImportLoadedAnnotationsFromXFDF. XFDF adalah format pertukaran anotasi XML yang distandardisasi sebagai ISO 19444-1, dan pasangan ini memungkinkan program Delphi atau C++Builder menyerahkan komentarnya ke Acrobat atau alat peninjau pihak ketiga lalu mengambil kembali hasil yang telah ditandai, semuanya tanpa menulis ulang konten halaman tempat anotasi tersebut berada

Bayangkan dua arah yang diselesaikan oleh fitur ini. Seorang peninjau membuka laporan yang Anda buat di Acrobat, menaruh panah merah pada gambar yang tidak sejajar, melingkari total yang salah, dan mengetik catatan di margin, lalu mengekspor komentar tersebut ke file XFDF kecil. Atau sebaliknya: program Anda menghasilkan tanda (markup) itu sendiri, dan Anda perlu mengirimkannya kepada seseorang yang alatnya bukan HotPDF. Dengan cara apa pun, anotasi ditransfer sebagai XML yang dipahami oleh kedua belah pihak, dan halaman PDF tetap sama persis secara byte-demi-byte

Apa perbedaan antara FDF dan XFDF?

FDF dan XFDF membawa payload yang sama dalam dua sintaks berbeda, dan perbedaannya menjadi penting saat Anda memutuskan file mana yang akan diserahkan ke alat lain. FDF adalah Forms Data Format lama yang ditentukan di dalam spesifikasi PDF itu sendiri: ia menggunakan sintaks objek PDF, sehingga file FDF terlihat seperti PDF yang disederhanakan dan memerlukan parser yang sadar PDF untuk membacanya. XFDF adalah ekspresi XML dari data yang sama, distandardisasi secara independen sebagai ISO 19444-1, yang berarti pustaka XML apa pun di platform apa pun dapat membuka, membandingkan (diff), atau menghasilkannya. Kedua format dapat membawa nilai field formulir dalam pohon <fields> yang diatur oleh klausul 6.3 ISO 19444-1, dan anotasi dalam pohon <annots>; HotPDF memisahkan tanggung jawab tersebut, mengarahkan data formulir melalui ExportLoadedFormToXFDF and mencadangkan ExportLoadedAnnotationsToXFDF untuk sisi <annots>. Ketika Anda bertukar komentar dengan web service, server peninjau Java, atau skrip, XFDF is the format that does not force the other side to embed a PDF parser

Bagaimana cara mengekspor anotasi PDF sebagai XFDF di Delphi?

HotPDF mengekspor anotasi dengan menelusuri setiap halaman dokumen yang dimuat, memancarkan satu elemen XFDF untuk setiap anotasi yang didukung, dan mengembalikan jumlah anotasi yang ditulis. Muat PDF terlebih dahulu, lalu panggil ExportLoadedAnnotationsToXFDF dengan jalur target. Hasil integer adalah jumlah anotasi yang diserialisasi; hasil nol atau di bawahnya berarti tidak ada yang diekspor dan tidak ada file yang ditulis, yang merupakan sinyal bahwa dokumen tidak membawa anotasi dari subtipe yang didukung

var
  Pdf: THotPDF;
  Written: Integer;
begin
  Pdf := THotPDF.Create(nil);
  try
    if Pdf.LoadFromFile('report-reviewed.pdf', '') > 0 then
    begin
      // Write one XFDF element per supported annotation on every page
      Written := Pdf.ExportLoadedAnnotationsToXFDF('comments.xfdf');
      if Written <= 0 then
        ShowMessage('No supported annotations were found');
    end;
  finally
    Pdf.Free;
  end;
end;

XFDF yang dihasilkan berupa XML biasa yang mudah dibaca. HotPDF menulis root <xfdf> dalam namespace ISO 19444-1, kontainer <annots>, dan satu anak per anotasi dengan indeks halaman berbasis nol, warna, dan geometrinya sebagai atribut atau elemen anak. Sebuah garis dengan isian kuning dan mata panah terbuka, yang terletak di sebelah poligon terisi, diserialisasi seperti ini

<?xml version="1.0" encoding="UTF-8"?>
<xfdf xmlns="http://ns.adobe.com/xfdf/">
  <annots>
    <line page="0" start="72,700" end="220,700"
          color="#FF0000" interior-color="#FFFF00"
          head="OpenArrow" tail="None">
      <contents-richtext>Baseline looks off</contents-richtext>
    </line>
    <polygon page="0" color="#0000FF" interior-color="#CCE5FF">
      <vertices>72,120;180,120;180,200;72,200</vertices>
    </polygon>
  </annots>
</xfdf>

Bagaimana subtipe anotasi memetakan ke elemen XFDF

Setiap subtipe anotasi memetakan ke elemen ISO 19444-1 tertentu dengan konvensi geometrinya sendiri, dan HotPDF mengikuti struktur tersebut alih-alih membuat strukturnya sendiri. Anotasi garis (line) membawa atribut start dan end yang menampung dua pasang koordinat titik ujung, yang diambil langsung dari array L anotasi, sedangkan gaya ujung garis LE menjadi atribut head dan tail. Anotasi poligon dan poliline memindahkan daftar titiknya ke dalam elemen anak <vertices> sebagai pasangan x,y yang dipisahkan titik koma, bukan sebagai atribut, karena pembaca yang mengharapkan elemen anak akan mengabaikan titik-titik yang tersembunyi di tempat lain secara diam-diam. Anotasi tinta (ink), yang dapat menampung beberapa guratan terpisah, menyarangkan elemen <inklist> dengan satu elemen anak <gesture> per guratan, sehingga tanda tangan multi-guratan bertahan dalam transfer sebagai guratan terpisah alih-alih satu gumpalan yang digabungkan

Teks kaya, warna, dan gaya batas (border styling) bertahan bersama dengan geometrinya. Isi teks kaya dari sebuah catatan ditulis sebagai elemen anak <contents-richtext>; isian interior yang disimpan PDF dalam array IC, cat di dalam lingkaran, kotak, poligon, atau mata panah garis, serta isian kotak redaksi, ditransfer sebagai atribut interior-color dalam format #RRGGBB; dan lebar batas, pola putus-putus, serta efek batas berawan memetakan ke atribut width, dashes, style, dan intensity, sehingga callout dengan garis batas berawan tetap terbaca berawan di sisi penerima. HotPDF juga mempertahankan jendela popup yang dilampirkan ke anotasi markup, mengimpor geometri anak popup beserta status terbuka atau tertutupnya ke dalam kamus Popup anotasi, dan membawa status terbuka dan tinjauan anotasi teks, sehingga dokumen yang ditinjau tidak hanya mempertahankan bentuknya tetapi juga metadata alur kerja yang diandalkan oleh peninjau

Mengimpor Kembali XFDF ke Dokumen yang Dimuat

HotPDF mengimpor XFDF dengan mengurai XML, membuat anotasi baru untuk setiap elemen melalui NewLoadedAnnotation, melampirkannya ke halaman yang dinamai elemen tersebut, dan mengembalikan berapa banyak anotasi yang ditambahkannya. Alur kerjanya simetris dengan ekspor: muat PDF dasar, panggil ImportLoadedAnnotationsFromXFDF dengan file peninjau, lalu simpan dokumen yang dimuat untuk mempertahankan markup baru. Jika file tidak ada atau XML tidak dapat diurai, fungsi mengembalikan nol dan dokumen yang dimuat dibiarkan tidak tersentuh

var
  Pdf: THotPDF;
  Added: Integer;
begin
  Pdf := THotPDF.Create(nil);
  try
    if Pdf.LoadFromFile('report.pdf', '') > 0 then
    begin
      Added := Pdf.ImportLoadedAnnotationsFromXFDF('comments.xfdf');
      if Added > 0 then
        Pdf.SaveLoadedDocument('report-annotated.pdf');
    end;
  finally
    Pdf.Free;
  end;
end;

Karena setiap elemen XFDF menamai indeks halamannya sendiri, anotasi mendarat pada halaman tempat mereka ditulis bahkan ketika Anda mengimpor beberapa file secara berurutan, yang membuatnya aman untuk mengumpulkan komentar dari lebih dari satu peninjau ke dokumen termuat yang sama sebelum sekali penyimpanan. Contoh di bawah ini menggabungkan dua peninjau menjadi satu salinan terpadu. Untuk membangun dan mengedit objek anotasi itu sendiri dalam kode daripada mempertukarkannya sebagai file, lihat bagaimana HotPDF membuat dan mengedit objek anotasi PDF secara langsung dari Delphi

var
  Pdf: THotPDF;
  Total, I: Integer;
  Files: array[0..1] of string;
begin
  Files[0] := 'alice-comments.xfdf';
  Files[1] := 'bob-comments.xfdf';
  Pdf := THotPDF.Create(nil);
  try
    if Pdf.LoadFromFile('master.pdf', '') > 0 then
    begin
      Total := 0;
      for I := Low(Files) to High(Files) do
        Inc(Total, Pdf.ImportLoadedAnnotationsFromXFDF(Files[I]));
      if Total > 0 then
        Pdf.SaveLoadedDocument('master-merged.pdf');
    end;
  finally
    Pdf.Free;
  end;
end;

Apa yang ditransfer dengan bersih, dan apa yang tidak

HotPDF mentransfer subtipe anotasi yang diwadahi oleh ISO 19444-1, dan sengaja melewatkan sisanya daripada memancarkan sesuatu yang akan disalahartikan oleh pembaca. Kumpulan yang didukung mencakup jenis markup yang mendominasi pekerjaan tinjauan nyata: catatan teks (text notes), teks bebas (free text), garis, persegi, lingkaran, poligon, poliline, empat jenis markup teks (highlight, underline, strikeout, dan squiggly), stempel (stamp), tinta (ink), dan caret, ditambah lampiran file, suara, redaksi, dan tautan, semuanya delapan belas subtipe.

Anotasi yang subtipe-nya berada di luar daftar tersebut akan dilewati saat diekspor, dan karena dilewati alih-alih ditulis kosong, ia tidak menggelembungkan jumlah yang dikembalikan fungsi

Teks kaya adalah batasan yang jujur. HotPDF mempertahankan isi <contents-richtext> sehingga teks bergaya dan konten biasa ikut ditransfer, tetapi XFDF membawa teks komentar dan markup gaya, bukan stream tampilan yang dirender, sehingga aplikasi penerima menggambar ulang popup dengan font dan tata letaknya sendiri daripada mereproduksi piksel tepat milik HotPDF. Perlakuan transfer ini sebagai kesetiaan terhadap konten dan maksud, bukan terhadap perenderan di layar hingga piksel terakhir. Jika konten bergaya Anda berada di data formulir XFA alih-alih stream anotasi, aturannya berbeda, dan bagaimana HotPDF menangani XFA exData, teks kaya, dan hyperlink mencakup jalur terpisah itu

Penanganan tingkat karakter lebih ketat daripada yang terlihat, yang merupakan apa yang Anda inginkan. HotPDF menerapkan aturan escaping klausul 5.8.2 ISO 19444-1 saat menulis teks, mengkodekan karakter XML-penting dan byte kontrol sehingga komentar yang berisi ampersand, tanda kurung siku, atau hentian baris menghasilkan XML yang diformat dengan baik yang diterima oleh parser mana pun yang patuh, dan membalikkan aturan yang sama saat impor. Itulah mengapa catatan yang ditempelkan dari spreadsheet, lengkap dengan tanda bacanya, kembali utuh alih-alih merusak file

Pertukaran anotasi adalah salah satu bagian dari apa yang dilakukan oleh API dokumen termuat, dan berpadu dengan bagian lainnya: mengimpor XFDF peninjau, menyesuaikan halaman atau mengedit metadata dokumen, meratakan atau mengubah izin file, lalu mengekspor XFDF baru untuk putaran berikutnya. Semua itu didistribusikan dalam standar HotPDF Component untuk Delphi dan C++Builder, yang referensinya mendokumentasikan cakupan subtipe anotasi lengkap dan fungsi pendamping XFDF data formulir