螢光筆註解才剛由 FPDFPage_CreateAnnot 建好,FPDFAnnot_CountAttachmentPoints 就回報 0,而 FPDFAnnot_SetAttachmentPoints(Annot, 0, Quad) 對它傳回 0,座標怎麼給都一樣。問題不在座標。索引 0 的意思是「取代既有的第 0 號四邊形」,新建註解一個四邊形都沒有,負責開出插槽的呼叫是 FPDFAnnot_AppendAttachmentPoints
這件事一段話就能講完,卻很容易讓人耗掉好幾個小時,因為遇到 false 的第一反應是懷疑幾何。有人調換角點順序、翻轉 Y 軸、在裝置空間轉來轉去。這些全都改變不了結果。接下來依序談:按 ISO 32000-1 四邊形該裝什麼、經元件 API 和原生 C 函式怎麼寫、跨行選取,以及 Delphi、Free Pascal、C++Builder 之間索引起始不同的陷阱。本文是讀取與檢視既有註解一文的建立端姊妹篇,那篇沿著同樣的結構反向走一遍
QuadPoints 在 ISO 32000-1 §12.5.6.10 裡的意義
QuadPoints 是四種文字標記子類型——Highlight、Underline、Squiggly、StrikeOut——的必要條目:一個 8×n 個數字的陣列,在預設使用者空間給出 n 個四邊形,每個四邊形包住註解下方文字裡的一個詞或一組連續詞。註解仍帶有每種註解都需要的 Rect,但對標記子類型而言,四邊形說明哪些字形被標記,Rect 只負責框住它們。用四邊形而不用矩形,是因為文字可以在頁面上旋轉或斜切,所以每個角都當獨立點存放:x1 y1 x2 y2 x3 y3 x4 y4
角點順序正是規範文字與市面上檔案分道揚鑣之處。§12.5.6.10 說四個頂點按逆時針順序給出,並補充文字的方向沿著 (x1, y1) 到 (x2, y2) 這條邊。Acrobat,以及為了讀 Acrobat 輸出而打造的一長串工具,用的卻是 Z 字形:點 1 左上、點 2 右上、點 3 左下、點 4 右下。這種布局仍然守住了方向那一句,因為 1–2 這條邊沿著文字頂部走,但它並不是繞著形狀逆時針走一圈。請按 Z 順序寫。字面上的逆時針清單(左上、左下、右下、右上)在紙面上說得通,但按 Z 走訪這些點的閱讀器會讀成左上、左下、右上、右下,這些邊交叉成蝴蝶結
所有座標都是以點為單位的頁面座標,原點在頁面左下角,Y 向上增長。A4 頁面頂端附近的一行文字,Y 值因此大約在 700 到 800 之間,而且頂邊的 Y 較大。規範還規定外觀串流(AP)與 QuadPoints 同時存在時以外觀串流優先,所以四邊形對自行產生標記外觀的檢視器最重要
為什麼 FPDFAnnot_SetAttachmentPoints 會傳回 false?
FPDFAnnot_SetAttachmentPoints 在新註解上傳回 false,因為它只取代已存在的四邊形。PDFium 標頭把契約寫得直白:quad_index 「必須落在 FPDFAnnot_CountAttachmentPoints() 的結果範圍內」。FPDFPage_CreateAnnot 造出的每個註解計數都是零,根本沒有索引 0 可取代。FPDFAnnot_AppendAttachmentPoints 負責加一個插槽並把計數加一;之後索引 0 才存在,Set 也才肯收。這兩個函式在 PDFium 標頭裡都標為實驗性,而且當新的四邊形伸得比舊的遠時,兩者都會順帶擴大既有外觀串流的邊界框
PDFium Component 把所有 FPDFAnnot_* 進入點都引入 PDFium.pas,FS_QUADPOINTSF 記錄和 size_t 別名則住在 FPdfView.pas。如果你自己持有註解控制代碼,每次寫入前先按計數分流:
uses
SysUtils, PDFium, FPdfView;
// 在活動頁面的 AnnotIndex 註解上寫入 QuadIndex 號四邊形:
// 插槽存在就取代,不存在就附加一個新的
procedure WriteQuad(Pdf: TPdf; AnnotIndex: Integer; QuadIndex: size_t;
var Quad: FS_QUADPOINTSF);
var
Annot: FPDF_ANNOTATION;
Count: size_t;
Ok: Boolean;
begin
Annot := FPDFPage_GetAnnot(Pdf.Page, AnnotIndex);
if Annot = nil then
raise Exception.CreateFmt('No annotation at index %d', [AnnotIndex]);
try
Count := FPDFAnnot_CountAttachmentPoints(Annot);
if QuadIndex < Count then
Ok := FPDFAnnot_SetAttachmentPoints(Annot, QuadIndex, Quad) <> 0
else
Ok := FPDFAnnot_AppendAttachmentPoints(Annot, Quad) <> 0;
if not Ok then
raise Exception.Create('PDFium rejected the quad');
finally
FPDFPage_CloseAnnot(Annot);
end;
end;
同一族函式裡還埋著第二個陷阱。FPDFAnnot_CountAttachmentPoints 回傳無號的 size_t,所以對沒有四邊形的註解寫熟悉的 for I := 0 to Count - 1,會在無號算術裡算出 0 − 1 並迴繞成最大可能值。進任何四邊形迴圈之前先測 Count > 0,或先轉成有號型別。其他工具產生的標記幾乎總帶著至少一個四邊形;新建的註解則是零
使用 TPdf.CreateAnnotation 建立螢光筆
走元件 API 就不必在 Append 和 Set 之間挑。TPdf.CreateAnnotation 和 TPdf.SetAnnotation 都會先看註解已持有幾個四邊形,存在的插槽取代、缺的附加,所以建立路徑走附加、更新路徑走取代。你要提供的是帶 Subtype、顏色、四邊形和 Rectangle 的 TPdfAnnotation 記錄
這個記錄有兩個細節要留意。用 Default(TPdfAnnotation) 初始化。記錄裡有字串和動態陣列,對已帶字串的記錄上 FillChar 只會把記憶體漏掉,所以對每個要重用的記錄,Default 都是更保險的習慣。還有,Rectangle 一定要填:元件在每次建立和更新時都把它寫成註解的 Rect,清零的記錄即使四邊形正確也會生出 [0 0 0 0] 的 Rect。CreateAnnotation 作用在活動頁面上,AddPage 為新頁設定活動頁、PageNumber 為既有文件設定,PDFium 建不出要求的子類型時它拋出 'Unsupported annotation subtype'
var
Pdf: TPdf;
A: TPdfAnnotation;
begin
Pdf := TPdf.Create(nil);
try
Pdf.CreateDocument;
Pdf.AddPage(0, 595, 842); // A4,成為活動頁
A := Default(TPdfAnnotation);
A.Subtype := anHighlight;
A.HasColor := True;
A.Color := clYellow;
A.ColorAlpha := $80; // alpha 隨顏色一起傳入
A.HasAttachmentPoints := True;
A.AttachmentPoints[1].X := 50; A.AttachmentPoints[1].Y := 700; // 左上
A.AttachmentPoints[2].X := 250; A.AttachmentPoints[2].Y := 700; // 右上
A.AttachmentPoints[3].X := 50; A.AttachmentPoints[3].Y := 680; // 左下
A.AttachmentPoints[4].X := 250; A.AttachmentPoints[4].Y := 680; // 右下
A.Rectangle.Left := 50; A.Rectangle.Top := 700; // 包住四邊形
A.Rectangle.Right := 250; A.Rectangle.Bottom := 680;
A.ContentsText := 'Highlighted region';
Pdf.CreateAnnotation(A);
Pdf.SaveAs('highlighted.pdf');
finally
Pdf.Free;
end;
end;
換一種裝飾只花一行。anUnderline、anStrikeout 和 anSquiggly 吃的記錄完全相同,四邊形照收;ISO 32000-1 把這四種放在一起描述,差別只在四邊形區域怎麼畫。這一族之外的子類型,例如 anSquare、anCircle 和 anText,只憑 Rectangle 定位;那些請把 HasAttachmentPoints 留在 False、AttachmentPointSets 留空,就不會寫入任何四邊形
跨行選取:一個註解,多個四邊形
跨三行的選取需要三個四邊形,每行一個,因為橫跨三行的單一四邊形會連第一行右端和第三行左端一起塗滿。TPdfAnnotation 用 AttachmentPointSets——一個 TQuadrilateralPoint 動態陣列——裝下所有四邊形;單數的 AttachmentPoints 欄位保留為第一個條目的別名。AttachmentPointSets 非空時,CreateAnnotation 按序寫入其中每一項,單數欄位則被忽略
你也可以改成每行建一個註解。渲染結果一樣,但審閱者看到的是三則評論、三個彈出視窗、三個要刪的項目——為的只是一次螢光筆。把幾行放進同一個註解吧。幾何資料從搜尋取得很方便,因為 TPdf.CreateDocumentSearch 回傳的每個命中都帶 Rectangles 陣列,一行裡每段文字一個矩形,而且已是頁面座標:
function QuadFromRect(const R: TPdfRectangle): TQuadrilateralPoint;
begin
Result[1].X := R.Left; Result[1].Y := R.Top; // 左上
Result[2].X := R.Right; Result[2].Y := R.Top; // 右上
Result[3].X := R.Left; Result[3].Y := R.Bottom; // 左下
Result[4].X := R.Right; Result[4].Y := R.Bottom; // 右下
end;
// 你自己的輔助函式,不是函式庫的一部分:行矩形的聯集
function UnionRect(const Rects: TPdfRectangles): TPdfRectangle;
var
I: Integer;
begin
Result := Rects[0];
for I := 1 to High(Rects) do
begin
if Rects[I].Left < Result.Left then Result.Left := Rects[I].Left;
if Rects[I].Right > Result.Right then Result.Right := Rects[I].Right;
if Rects[I].Top > Result.Top then Result.Top := Rects[I].Top;
if Rects[I].Bottom < Result.Bottom then Result.Bottom := Rects[I].Bottom;
end;
end;
procedure HighlightMatches(Pdf: TPdf; const Needle: WString);
var
Search: TPdfDocumentSearch;
Match: TPdfDocumentSearchResult;
Found: array of TPdfDocumentSearchResult;
A: TPdfAnnotation;
I, J: Integer;
begin
// 動任何頁面之前,先收齊每個命中
Search := Pdf.CreateDocumentSearch(Needle, [seWholeWord]);
try
while Search.Next(Match) do
if Length(Match.Rectangles) > 0 then
begin
SetLength(Found, Length(Found) + 1);
Found[High(Found)] := Match;
end;
finally
Search.Free;
end;
for I := 0 to High(Found) do
begin
Pdf.PageNumber := Found[I].PageNumber;
A := Default(TPdfAnnotation);
A.Subtype := anHighlight;
A.HasColor := True;
A.Color := clYellow;
A.ColorAlpha := $80;
SetLength(A.AttachmentPointSets, Length(Found[I].Rectangles));
for J := 0 to High(Found[I].Rectangles) do
A.AttachmentPointSets[J] := QuadFromRect(Found[I].Rectangles[J]);
A.Rectangle := UnionRect(Found[I].Rectangles);
A.ContentsText := Found[I].Text;
Pdf.CreateAnnotation(A);
end;
end;
搜尋回來的矩形都是軸對齊的,每個四個數字,所以遇到旋轉文字,產生的四邊形蓋住的是該段文字的邊界框,而不是順著斜度走。對絕大多數被螢光筆劃過的水平文字來說,邊界框和字形區域正好重合。若你需要逐字元的幾何,PDFium Component 文字擷取指南介紹 CharacterRectangle 和相關的文字頁呼叫;文字量測與自動換行一文則示範怎麼為即將產生的文字計算行範圍
編輯既有標記註解走 Pdf.Annotation[Index] := A,它內部呼叫 SetAnnotation;記錄裡的子類型必須與儲存的一致,否則呼叫拋出 'Incorrect annotation subtype'。四邊形按索引逐一改寫,AttachmentPointSets 裡多出來的條目則被附加。PDFium 沒有提供移除單一四邊形的呼叫,所以從三個縮到兩個,第三個仍留在檔案裡。想縮小螢光範圍,請用 DeleteAnnotation 刪掉再用較短的陣列重建
AttachmentPoints 從 1 起算,C++ 除外
TQuadrilateralPoint 宣告為 array [1..4] of TPdfPoint,編號對應規範裡的角點號碼:元素 1 是 (x1, y1),元素 4 是 (x4, y4)。憑零起始的肌肉記憶寫出來的程式碼,錯法是編譯器未必擋得住的那種。for I := 0 to 3 do A.AttachmentPoints[I] := ... 這種迴圈在 Delphi 和 Free Pascal 都編得過,因為索引要到執行期才確定。範圍檢查關閉時(Delphi 專案預設如此),寫索引 0 會落在陣列前面那幾個位元組上,鑽進前一個欄位裡,四邊形本身則留著一個零角。什麼都不會拋出
常數索引是另一回事。編譯器在任何東西執行前就能拿它對宣告邊界比較,fpc 之類的編譯器會直接以範圍錯誤拒收字面上的 AttachmentPoints[0]。會溜過去的是計算出來的索引。信任註解程式碼之前,至少用 {$R+} 在 Delphi 建置一次,或用 fpc 建置一次;範圍檢查開啟時,上面的執行期迴圈會在索引 0 處拋出 ERangeError
C++Builder 把規則反過來。產生的 PDFium.hpp 把 TQuadrilateralPoint 宣告成 System::StaticArray<TPdfPoint, 4>,而 C++ 靜態陣列無論 Pascal 下界是幾都從零起算。所以在 C++ 裡角點是 AttachmentPoints[0] 到 AttachmentPoints[3],仍是 Z 順序。逐行移植 Delphi 範例會保留 1 到 4 的索引,每個角點都錯位一格,最後一個還寫過陣列末端
把四邊形讀回來
驗證標記註解是否落點正確,最快的辦法是用同一套 API 讀回來。Pdf.Annotation[Index] 會把註解上儲存的每個四邊形填進 AttachmentPointSets,至少有一個時 HasAttachmentPoints 為 True:
var
I, Q: Integer;
B: TPdfAnnotation;
begin
Pdf.PageNumber := 1;
for I := 0 to Pdf.AnnotationCount - 1 do
begin
B := Pdf.Annotation[I];
if B.Subtype in [anHighlight, anUnderline, anStrikeout, anSquiggly] then
for Q := 0 to High(B.AttachmentPointSets) do
Writeln(Format('annot %d quad %d: TL (%.1f, %.1f) BR (%.1f, %.1f)',
[I, Q,
B.AttachmentPointSets[Q][1].X, B.AttachmentPointSets[Q][1].Y,
B.AttachmentPointSets[Q][4].X, B.AttachmentPointSets[Q][4].Y]));
end;
end;
對先前建立的那個螢光筆,預期輸出是 annot 0 quad 0: TL (50.0, 700.0) BR (250.0, 680.0);左上的 Y 若低於右下的 Y,代表角點以顛倒的上下送進去了。與其他工具交換標記時四邊形也跟著走:XFDF 的 coords 屬性裝著它們全部,每個四邊形八個數字,XFDF 匯出與匯入一文有完整說明。之後請用第二個檢視器開啟存好的檔案,確認顏色落在字形上而不是旁邊——自行從 QuadPoints 建外觀的檢視器,正是會暴露錯誤角點順序的那一個
本文用到的註解記錄、多四邊形陣列和感知計數的寫入器,都隨 PDFium Component for Delphi, C++Builder and Lazarus 出貨,完整的註解 API 參考就在這些範例依賴的文字搜尋與擷取呼叫旁邊