一個需求落到了您的辦公桌上:拿一批已經渲染好的對帳單,將帳號塗黑,然後為了節省紙張,每張紙印兩頁。這個任務的兩個部分,都是對一份不是您所建立的 PDF 進行內容串流 (content-stream) 的外科手術,因此沒有友善的頁面畫布可供繪製,也沒有字型管理員可以依賴。您是直接在編輯已載入文件的物件圖 (object graph),將原始的繪圖運算子附加到由其他工具所佈局的頁面上。HotPDF 針對此需求恰好暴露了兩個進入點,而其中比較危險的那一個,看起來卻似乎毫無害處
HotPDF 是一款適用於 Delphi 與 C++Builder 的原生 VCL PDF 元件,其已載入文件 API 提供了能在「您從磁碟開啟、而非從零建置」的頁面上創造全新內容的方法。這裡要談的是其中兩個:RedactLoadedRect 在某個區域上蓋一層不透明矩形,StitchLoadedPage 則把一個頁面縮放後繪製到另一個頁面上。兩者的原理,都是把 ISO 32000-1 §8.5 的內容串流運算子寫進該頁的 /Contents 串流。搞懂這些運算子做了什麼——更重要的是它們沒做什麼——就是「工具堪用」與「資料外洩」之間的分別
將運算子附加至已載入的頁面
當您使用一般的 HotPDF API 建立頁面時,該元件擁有內容串流,並會為您序列化您的 TextOut 與向量呼叫。但已載入的頁面則不同:其 /Contents 是一個現有的串流物件,可能是共用的,也可能是內容陣列的一部分,而您必須在不破壞原有內容的情況下,將內容接入其中。三個小型輔助函式讓這件事變得安全:NewIndirectStream 配置了一個全新的間接 THPDFStreamObject,帶有空的緩衝區以及 /Length 0 的條目;ResolveLoadedStream 沿著間接參考一路追蹤到底層的串流;而 AppendLoadedStream 則在串流的結尾寫入原始位元組,並覆寫 /Length,讓儲存後的物件保持格式正確
兩個公開方法遵循的模式相同:找到頁面的 /Contents,把它解析成串流;若沒有可用的串流,就建立一個並接上去;然後附加運算子。因為新位元組落在串流的尾端,繪圖者模型 (painter's model) 保證它們渲染在原始版面所畫的一切之上。這個先後順序既是遮蔽矩形背後的完整機制,也是這個矩形不如多數人所想的原因
RedactLoadedRect:是不透明覆蓋,而不是刪除
RedactLoadedRect 接收一個以零起始的頁面索引、四個使用者空間座標,以及 0 到 1 範圍內的三個色彩元件:
var
Pdf: THotPDF;
begin
Pdf := THotPDF.Create(nil);
try
if Pdf.LoadFromFile('statement.pdf') > 0 then
begin
// 用純黑蓋住第 1 頁上的帳號條帶。
// 座標是 PDF 使用者空間:原點在左下,單位為點。
Pdf.RedactLoadedRect(0, 56, 690, 320, 706, 0, 0, 0);
Pdf.SaveLoadedDocument('statement-covered.pdf');
end;
finally
Pdf.Free;
end;
end;
在底層,這個方法會向內容串流送出三個運算子:以 DeviceRGB 設定的填充色(r g b rg)、矩形路徑(x y w h re),以及填充(f)。寬與高由 X2 - X1 與 Y2 - Y1 推得,所以您只要傳入兩個相對的角點,讓方法自行算出範圍。顏色傳 0, 0, 0 就得到一條黑槓;傳 1, 1, 1 則是能融入白頁的白槓。座標使用已載入頁面自己的使用者空間:原點在左下角、單位為點;這也代表要精準放置任何東西,都得依靠頁面的 /MediaBox——用 pbMediaBox 呼叫 GetLoadedPageBox 便能取得
這段請讀兩遍:填滿的矩形只是把內容蓋住,並沒有移除它。矩形底下的文字、影像或向量圖仍然存在於 PDF 裡、存在於物件圖中,任何人複製該頁、跑一次文字擷取器,或直接從內容串流刪掉您的矩形,都照樣拿得到。這是視覺遮蓋,不是法律或資安意義上的遮蔽 (redaction)。若您藏的是真正敏感的資料——帳號、病歷、身分、任何受監管的資訊——蓋個黑箱子就把檔案交出去,等於埋了一顆遲早被發現的資料外洩地雷。真正的遮蔽必須刪除底層的內容物件,而不是把它們塗掉
方法名稱裡有個「Redact」,這是個有用的警示:人們會誤讀這個結果,但它並不是對刪除行為的承諾。RedactLoadedRect 按設計就是一個視覺遮蔽工具;會移除內容的遮蔽是另一種操作——必須走訪並改寫內容串流裡現有的運算子。所以安全的使用法則很窄:只把 RedactLoadedRect 用在非敏感的表面遮蓋——藏起草稿浮水印、截圖前清空某個區域、蓋住內部校樣上的過時 logo。只要黑箱子底下的東西一旦外洩就會釀成問題,這個方法就是錯的工具;正確答案是重新產生不含該資料的文件,或改用真正的內容移除管線
StitchLoadedPage:縮放、平移、繪製
N-up 拼版 (imposition) 是一個比較友善的問題,因為沒有任何東西被隱藏,只有被重新排列。StitchLoadedPage 接收一個目標頁面索引、一個來源頁面索引、一個 X/Y 偏移量,以及一個縮放比例,然後它會將來源頁面以該位置與大小繪製到目標頁面上:
// 將第 2 頁(索引 1)疊到第 1 頁(索引 0)上,
// 縮放至 70% 並向右上方微移。
Pdf.StitchLoadedPage(0, 1, 40, 380, 0.7);
// 便捷的 2-up:來源頁放在目標頁的右半部。
Pdf.StitchLoadedPageSideBySide(0, 1);
它所附加的運算子字串是一個標準的轉換與繪製序列:q 用以儲存圖形狀態,一個在對角線上帶有縮放比例、平移插槽中帶有偏移量的 cm 矩陣,/StitchSrc Do 用以呼叫外部物件,然後 Q 用以還原狀態。這對 q/Q 很重要:它隔離了轉換,這樣被拼貼的頁面就不會將其座標系統滲透到之後附加的任何東西上。該方法也防範了明顯的錯誤——索引超出範圍、目標等於來源、非正數的縮放比例(它會被箝制為 1.0)——並且會安靜地退出而不是引發例外,因此請檢查您的輸入,因為靜默的無操作 (no-op) 看起來和成功一模一樣
StitchLoadedPageSideBySide 是建構在一般方法之上、單薄的便利函式。它讀取目標頁面媒體框的寬度,將其減半,然後以該半寬作為 X 偏移量、固定縮放比例為 0.5 來呼叫 StitchLoadedPage,將來源頁面放在右半邊。這個寫死的 0.5 假設了來源與目標共用相同的寬度;如果不是,來源頁面將無法完美地填滿它的半邊,此時您會需要使用一般的 StitchLoadedPage,並帶入您自己從兩個媒體框計算出來的縮放比例
拼版如何參考來源頁面
這是您在跨檢視器信任輸出之前,必須先知道的細節。經典的 N-up 拼版會把來源頁面的內容包進 Form XObject——一個自給自足的可繪製物件,ISO 32000-1 §8.10.1 規定它必須帶有 /Type /XObject、/Subtype /Form,以及自己的 /BBox 裁剪框。StitchLoadedPage 走的是輕量路線:它把來源頁面字典本身直接以 StitchSrc 這個名稱註冊進目標頁的 /Resources /XObject,再用 Do 繪製它。頁面字典與 Form XObject 在內容模型上重疊得足夠多——兩者都參考一個內容串流與一個資源字典——因此許多閱讀器仍會把結果渲染出來
由於被註冊的物件沒有 /Subtype /Form 標記、也沒有自己的 /BBox,嚴格的消費端有權忽略這個 Do,或以不同於您預期的方式裁剪它。所以請在客戶實際使用的檢視器中驗證拼版輸出,別只驗您自己機器上的那一個;若要製作封存用或必須通過嚴格驗證器的 PDF,請在上游以完整的 Form XObject 包裝來拼版。這條紀律同樣適用於您在已載入物件圖上建構的一切,這也是為什麼每當您以程式方式變更文件時,在 Delphi 中執行 PDF preflight 檢查就值得在發佈管線中佔有一席之地
它們適合與不適合的地方
這兩個方法都是內容串流工具,因此其心智模型與您進行直接繪圖時所使用的模型相同。如果您曾經使用該元件從頭建立過頁面,那麼這些呼叫背後的向量與色彩運算子,您在在 Delphi 中進行 HotPDF 畫布繪圖中應該會覺得很眼熟;唯一的差別在於,這裡您是附加在別人編寫的串流上,而不是您自己擁有的串流上。請記住三個界線:
- 遮蔽是表面功夫。
RedactLoadedRect會在內容上塗色,永遠不會刪除它。對於任何敏感資訊,請重新產生來源或使用真正的內容移除——黑盒子不是安全性 - 請在目標檢視器中驗證拼版頁面。來源頁面是被直接參考,而不是透過帶有
/Subtype /Form與/BBox的 §8.10.1 Form XObject,因此請在目標檢視器中確認渲染結果,需要嚴格驗證時改在上游拼版 - 座標是頁面使用者空間。左下角為原點,單位為點,由頁面本身的媒體框所驅動。在放置任何東西之前,請先使用
GetLoadedPageBox讀取框線,因為您載入的頁面大小,可能並不是您所假設的那樣
在這些界線內使用,這對工具涵蓋了一個真實的工作流程:重新排列頁面以進行列印、遮蓋非機密區域,然後用 SaveLoadedDocument 把結果寫回——全程不需要完整重繪。內含這些拼版與遮蔽能力的已載入文件 API,連同其表單欄位、註解與 FDF 方法,一併隨適用於 Delphi 與 C++Builder 的 HotPDF Delphi Component 出貨