HotPDF xuất và nhập các chú thích PDF dưới dạng XFDF thông qua hai hàm tác động lên tài liệu hiện đang được tải: ExportLoadedAnnotationsToXFDF và ImportLoadedAnnotationsFromXFDF. XFDF là định dạng trao đổi chú thích XML được tiêu chuẩn hóa theo ISO 19444-1, và cặp hàm này cho phép một chương trình Delphi hoặc C++Builder chuyển giao các bình luận của nó cho Acrobat hoặc một công cụ đánh giá của bên thứ ba rồi nhận lại kết quả đã được đánh dấu, tất cả đều không cần viết lại nội dung trang nơi các chú thích đang ngụ trị
Hãy hình dung hai chiều xử lý mà giải pháp này giải quyết. Một người đánh giá mở báo cáo được tạo của bạn trong Acrobat, thả một mũi tên màu đỏ lên một hình vẽ bị lệch hàng, khoanh tròn một tổng số sai và gõ một ghi chú ở lề trang, sau đó xuất các bình luận thành một tệp XFDF nhỏ. Or Hoặc ngược lại: chương trình của bạn tự tạo ra các đánh dấu, và bạn cần gửi chúng cho một người sử dụng công cụ không phải là HotPDF. Dù theo cách nào, các chú thích đều di chuyển dưới dạng XML mà cả hai bên cùng hiểu, và các trang PDF vẫn giữ nguyên từng byte cấu trúc của chúng
Sự khác biệt giữa FDF và XFDF?
FDF và XFDF truyền tải cùng một lượng dữ liệu (payload) bằng hai cú pháp khác nhau, và sự khác biệt này trở nên quan trọng ngay khi bạn quyết định tệp nào sẽ được bàn giao cho một công cụ khác. FDF là Định dạng Dữ liệu Biểu mẫu (Forms Data Format) cũ hơn được định nghĩa bên trong chính đặc tả PDF: nó sử dụng cú pháp đối tượng PDF, do đó một tệp FDF trông giống như một bản PDF thu gọn và cần một trình phân tích cú pháp hiểu PDF để đọc. XFDF là biểu diễn XML của cùng dữ liệu đó, được tiêu chuẩn hóa độc lập dưới dạng ISO 19444-1, nghĩa là bất kỳ thư viện XML nào trên bất kỳ nền tảng nào đều có thể mở, so sánh (diff) hoặc tạo ra nó. Cả hai định dạng đều có thể mang các giá trị trường biểu mẫu trong một cây <fields>, được điều chỉnh bởi điều khoản 6.3 của ISO 19444-1, và các chú thích trong một cây <annots>; HotPDF chia tách các trách nhiệm đó, định tuyến dữ liệu biểu mẫu qua ExportLoadedFormToXFDF và dành riêng ExportLoadedAnnotationsToXFDF cho bên <annots>. Khi bạn trao đổi bình luận với một dịch vụ web, một máy chủ đánh giá Java hoặc một kịch bản, XFDF là định dạng không ép buộc phía bên kia phải tích hợp một trình phân tích cú pháp PDF
Làm thế nào để xuất các chú thích PDF dưới dạng XFDF trong Delphi?
HotPDF xuất các chú thích bằng cách duyệt qua từng trang của tài liệu đã tải, phát ra một phần tử XFDF cho mỗi chú thích được hỗ trợ, và trả về số lượng chú thích đã được ghi. Hãy tải tệp PDF trước, sau đó gọi ExportLoadedAnnotationsToXFDF với một đường dẫn đích. Kết quả số nguyên trả về là số lượng chú thích được tuần tự hóa; một kết quả bằng hoặc nhỏ hơn không nghĩa là không có gì được xuất ra và không có tệp nào được ghi, đây là tín hiệu cho bạn biết tài liệu không mang chú thích nào thuộc phân nhóm được hỗ trợ
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 đầu ra là mã XML thuần túy, dễ đọc. HotPDF ghi một gốc <xfdf> trong không gian tên ISO 19444-1, một bộ chứa <annots>, và một phần tử con cho mỗi chú thích với chỉ mục trang bắt đầu từ 0, màu sắc và hình học của nó dưới dạng các thuộc tính hoặc phần tử con. Một đường thẳng với màu tô màu vàng và đầu mũi tên mở, nằm cạnh một đa giác được tô màu, sẽ được tuần tự hóa như thế này
<?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>Cách các phân nhóm chú thích ánh xạ tới các phần tử XFDF
Mỗi phân nhóm chú thích ánh xạ tới một phần tử ISO 19444-1 cụ thể với quy ước hình học riêng của nó, và HotPDF tuân theo các cấu trúc đó thay vì tự phát minh ra cấu trúc riêng. Các chú thích đường thẳng mang thuộc tính start và end giữ hai cặp tọa độ điểm cuối, được lấy trực tiếp từ mảng L của chú thích, trong khi các kiểu kết thúc đường LE trở thành các thuộc tính head và tail. Các chú thích đa giác và đường gấp khúc (polyline) chuyển danh sách điểm của chúng vào một phần tử con <vertices> dưới dạng các cặp x,y phân tách bằng dấu chấm phẩy, chứ không phải thuộc tính, bởi vì một trình đọc mong đợi phần tử con sẽ âm thầm bỏ qua các điểm bị ẩn ở bất kỳ nơi nào khác. Các chú thích mực (ink), vốn có thể giữ nhiều nét vẽ riêng biệt, sẽ lồng một phần tử <inklist> với một phần tử con <gesture> cho mỗi nét vẽ, giúp một chữ ký đa nét tồn tại qua hành trình dưới dạng các cử chỉ riêng biệt thay vì một khối hợp nhất duy nhất
Văn bản định dạng, màu sắc và kiểu dáng đường viền vẫn tồn tại song song với dữ liệu hình học. Phần thân văn bản định dạng của một ghi chú được ghi dưới dạng phần tử con <contents-richtext>; phần tô màu bên trong mà PDF lưu trữ trong mảng IC, phần vẽ bên trong một hình tròn, hình vuông, đa giác hoặc đầu mũi tên đường thẳng và phần tô của một hộp redaction, truyền tới dưới dạng một thuộc tính interior-color ở định dạng #RRGGBB; và chiều rộng đường viền, mẫu nét đứt cũng như hiệu ứng đường viền đám mây được ánh xạ tới các thuộc tính width, dashes, style và intensity, giúp một chú thích có viền đám mây vẫn hiển thị đúng ở phía bên kia. HotPDF cũng bảo toàn cửa sổ bật lên (popup) đính kèm với một chú thích đánh dấu, nhập hình học con popup và trạng thái mở hoặc đóng của nó vào từ điển Popup của chú thích, và nó mang theo các trạng thái mở và đánh giá của chú thích văn bản, giúp một tài liệu được đánh giá giữ lại không chỉ các hình dạng của nó mà cả siêu dữ liệu quy trình công việc mà những người đánh giá dựa vào
Nhập ngược lại XFDF vào tài liệu đã tải
HotPDF nhập XFDF bằng cách phân tích cú pháp XML, tạo một chú thích mới cho mỗi phần tử thông qua NewLoadedAnnotation, đính kèm nó vào trang mà phần tử đặt tên, và trả về số lượng chú thích nó đã thêm vào. Quy trình công việc này đối xứng với quy trình xuất: tải tệp PDF gốc, gọi ImportLoadedAnnotationsFromXFDF với tệp của người đánh giá, sau đó lưu tài liệu đã tải để duy trì các đánh dấu mới. Nếu tệp bị thiếu hoặc XML không thể phân tích cú pháp, hàm sẽ trả về không và tài liệu đã tải được giữ nguyên không thay đổi
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;Bởi vì mỗi phần tử XFDF tự đặt tên chỉ mục trang của chính nó, các chú thích sẽ hạ cánh trên các trang mà chúng được tạo lập ngay cả khi bạn nhập nhiều tệp theo trình tự, điều này giúp an toàn khi thu thập các bình luận từ nhiều người đánh giá vào cùng một tài liệu đã tải trước khi lưu một lần duy nhất. Ví dụ bên dưới gộp hai người đánh giá vào một bản sao hợp nhất. Để xây dựng và chỉnh sửa chính các đối tượng chú thích trong mã nguồn thay vì trao đổi chúng dưới dạng tệp, hãy xem cách HotPDF tạo và chỉnh sửa các đối tượng chú thích PDF trực tiếp từ 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;Những gì truyền nhận hai chiều sạch sẽ, và những gì không
HotPDF truyền nhận hai chiều các phân nhóm chú thích được hỗ trợ bởi ISO 19444-1, và nó chủ ý bỏ qua phần còn lại thay vì phát ra thứ gì đó mà trình đọc có thể diễn giải sai. Bộ công cụ được hỗ trợ bao trùm các loại đánh dấu chiếm ưu thế trong công việc đánh giá thực tế: ghi chú văn bản, văn bản tự do, đường thẳng, hình vuông, hình tròn, đa giác, đường gấp khúc, bốn loại đánh dấu văn bản (nổi bật, gạch chân, gạch ngang và răng cưa), con dấu, mực và dấu mũ (caret), cộng với tệp đính kèm, âm thanh, redaction và liên kết, tổng cộng mười tám phân nhóm. Một chú thích có phân nhóm nằm ngoài danh sách đó sẽ được bỏ qua khi xuất, và bởi vì nó bị bỏ qua chứ không phải ghi trống, nó không làm tăng số lượng đếm mà hàm trả về
Văn bản định dạng là một lưu ý thực tế. HotPDF bảo toàn phần thân <contents-richtext> để văn bản có kiểu dáng và nội dung thuần túy hoàn thành hành trình, nhưng XFDF mang theo văn bản của bình luận và đánh dấu kiểu dáng của nó, chứ không phải một luồng diện mạo được kết xuất, do đó ứng dụng tiếp nhận sẽ vẽ lại popup bằng phông chữ và bố cục riêng của nó thay vì tái tạo chính xác từng điểm ảnh của HotPDF. Hãy xử lý việc truyền nhận hai chiều này ở mức trung thực về nội dung và ý định, chứ không phải kết xuất trên màn hình chi tiết đến từng điểm ảnh. Nếu nội dung định dạng của bạn nằm trong dữ liệu biểu mẫu XFA thay vì các luồng chú thích, các quy tắc sẽ khác biệt, và bài viết về việc cách HotPDF xử lý XFA exData, văn bản định dạng và siêu liên kết sẽ bao trùm con đường riêng biệt đó
Việc xử lý ở cấp độ ký tự nghiêm ngặt hơn so với vẻ ngoài của nó, đây chính xác là điều bạn mong muốn. HotPDF áp dụng các quy tắc thoát ký tự trong điều khoản 5.8.2 của ISO 19444-1 khi ghi văn bản, mã hóa các ký tự có ý nghĩa trong XML và các byte điều khiển để một bình luận chứa ký tự và (ampersand), dấu ngoặc nhọn hoặc dấu ngắt dòng tạo ra mã XML có cấu trúc chuẩn mà bất kỳ trình phân tích cú pháp tương thích nào cũng chấp nhận, và nó đảo ngược các quy tắc tương tự khi nhập. Đó là lý do tại sao một ghi chú được dán từ một bảng tính, bao gồm cả dấu câu và tất cả mọi thứ, trở lại nguyên vẹn thay vì làm hỏng tệp dữ liệu
Trao đổi chú thích là một phần nhỏ trong những gì API tài liệu đã tải thực hiện, và nó kết hợp với phần còn lại: nhập XFDF của người đánh giá, điều chỉnh các trang hoặc chỉnh sửa siêu dữ liệu tài liệu, làm phẳng hoặc cấp lại quyền cho tệp, sau đó xuất một XFDF mới cho lượt tiếp theo. Tất cả những tính năng này đi kèm trong HotPDF Component tiêu chuẩn dành cho Delphi và C++Builder, tài liệu tham khảo của nó giới thiệu đầy đủ phạm vi phân nhóm chú thích được hỗ trợ và các hàm XFDF dữ liệu biểu mẫu đi kèm