GetPDFUADiagnostics

PDF/UA & Accessibility

Description

傳回目前文件中偵測到的潛在 PDF/UA-1 (ISO 14289-1) 合規性問題以換行字元分隔的清單；每行包含一個問題代碼，後跟冒號和易讀描述；未偵測到問題時傳回空字串

Syntax

Delphi

Function TPDFlib.GetPDFUADiagnostics: WideString;

ActiveX

Function PDFlib::GetPDFUADiagnostics() As String

DLL

const wchar_t * DLGetPDFUADiagnostics(int InstanceID);

Issue codes

PDF-VERSION-LOW	文件的 PDF 版本（如檔案標頭中所記錄）低於 1.7，PDF/UA-1 是針對 ISO 32000-1:2008 (PDF 1.7) 定義的，呼叫 SetPDFUAMode 以自動將版本提升至 1.7
MARKED-FALSE	MarkInfo/Marked 未設定為 true；文件不是標記的 PDF
LANG-MISSING	文件 catalog /Lang 項目不存在或為空，ISO 14289-1 §7.3 要求自然語言宣告
DISPLAYDOCTITLE-FALSE	ViewerPreferences/DisplayDocTitle 不為 true；此為 ISO 14289-1 §7.1 所要求，以便在標題列中顯示文件標題
DOCINFO-TITLE-MISSING	文件資訊字典的 /Title 項目不存在或為空，PDF/UA-1 需要文件標題，以便輔助技術在開啟文件時進行宣告，此檢查與 DISPLAYDOCTITLE-FALSE 互補：該檢查驗證標題是否呈现在檢視器中；此檢查則驗證標題值本身是否存在，呼叫 SetInformation 並帶入鍵值 `Title` 以進行設定
XMP-NO-PDFUAID	XMP 中繼資料流不包含 pdfuaid:part 項目，為 ISO 14289-1 §7.2 所要求
ANNOT-NO-CONTENTS:N	N 個非免除註解（不包括 Widget, PrinterMark, 和 TrapNet 子類型）缺少 Contents 項目；這是 ISO 14289-1 §7.18.1 所要求的
EMBED-NO-AFR:N	N 個內嵌檔案在其檔案規格字典中缺少 AFRelationship 項目；這是 ISO 14289-1 §7.11 所要求的
FIGURE-NO-ALT:N	N 個 Figure 或 Formula 結構元素沒有 Alt 文字值；ISO 14289-1 §7.5 和 ISO 32000-1 §14.9.3 要求圖形和數學公式都必須有替代描述
HEADING-LEVEL-SKIP:N	在文件順序中偵測到 N 次標題階層跳躍（例如 H1 後面直接跟著 H3，跳過了 H2）；ISO 14289-1 §7.1 和 WCAG 2.x 成功準則 1.3.1 要求標題的巢狀結構不得有間隔
STRUCT-UNCLOSED:N	N 個結構元素仍然開啟，因為 EndTag 的呼叫次數不正確；這些元素將在結構樹根部中缺失
TABLE-TH-NO-SCOPE:N	N 個 TH (表格標頭儲存格) 結構元素沒有 Scope 屬性；ISO 32000-1 §14.8.4.3.4 Table 337 將 Scope (Row、Column 或 Both) 定義為描述每個標頭儲存格適用於哪些資料儲存格的屬性；若沒有它，輔建立關聯；請在標記每個 TH 元素後立即呼叫 SetStructElemScope（或使用 `Owner='Table'`, `Name='Scope'` 的 AddTagAttribute）
FORM-NO-TOOLTIP:N	N 個互動式表單欄位（Widget 註解）缺少 TU（工具提示 / 無障礙名稱）項目；ISO 14289-1 §7.18.4 要求所有互動式表單欄位都必須攜帶 TU 項目，以便輔助技術向使用者朗讀該欄位的用途；/TU 是螢幕閱讀器朗讀的無障礙名稱；它與以程式方式使用的 /T（部分欄位名稱）不同；請在建立或載入表單欄位時設定 TU 值
LIST-STRUCT:N	N 個 LI 或 LBody 結構元素出現在其必要父代之外；ISO 32000-1 §14.8.4.4 要求 LI 必須是 L (清單) 的直接子代，且 LBody 必須是 LI (清單項目) 的直接子代；格式錯誤的清單巢狀結構會使輔助技術無法正確導覽清單；請檢查所有清單相關元素的 BeginTag / EndTag 呼叫順序
ROLEMAP-UNMAPPED:N	文件中出現了 N 個自訂結構元素類型，但在 /RoleMap 字典中沒有對應的項目；ISO 14289-1 §7.1 和 ISO 32000-1 §14.7.3 要求每個非標準結構類型都必須對應到標準 PDF 類型，以便輔助技術能夠判斷如何處理該元素；請在儲存前為每個自訂類型呼叫 AddRoleMap；問題說明中列出了未對應的類型名稱
SUSPECTS-TRUE	MarkInfo/Suspects 設定為 true；ISO 14289-1 §7.1 要求聲明符合 PDF/UA 的檔案其 Suspects 值必須為 false；true 值表示已知標記中包含錯誤；在文件完全標記後呼叫 SetMarkInfo 以將 Suspects 重設為 false
ROLEMAP-STANDARD-REMAP:N	N 個標準結構類型作為 /RoleMap 中的「自訂」鍵出現，並將在儲存時被重新對應；ISO 14289-1 §7.1 禁止重新對應 ISO 32000-1 §14.8.4 中定義的標準標記（P, H1..H6, Figure, Table 等）；詳細資料行中列出了違規的標準標記名稱；請移除受影響的 AddRoleMap 呼叫
DC-TITLE-MISSING	XMP 中繼資料流的 Dublin Core dc:title 遺失或為空，ISO 14289-1 §7.1 要求中繼資料流包含明確識別文件的 dc:title 項目，此檢查與 DOCINFO-TITLE-MISSING 分開，後者僅檢查 /Info /Title 項目，呼叫 SetPDFUAMode 以將 /Info 標題複製到 XMP 封包中
TRAPNET-ANNOT:N	在文件頁面上找到 N 個 TrapNet 註解；ISO 14289-1 §7.18.2 明確禁止在符合 PDF/UA-1 的檔案中使用 TrapNet；請在儲存前移除有問題的註解
ANNOT-PAGE-NO-TABS-S:N	N 個頁面包含一個或多個註解，但其頁面字典未設定 /Tabs /S；ISO 14289-1 §7.18.3 要求此類頁面上的定位字元順序必須遵循結構樹，以 /Tabs /S 信號表示；請在包含註解的每個頁面之頁面字典中設定 `/Tabs /S`
ENCRYPT-NO-ACCESS	文件已加密且 PDFUAMode 處於啟用狀態，但加密 `/P` 權限鍵值（遮罩 `$200`，無障礙功能擷取）的位元 10 已清除，ISO 14289-1 §7.16 要求每個符合規範的加密檔案都必須允許無障礙功能擷取，在呼叫 Encrypt 之前設定 PDFUAMode 時，會自動強制啟用該位元，當呼叫順序相反時，加密字典已經存在舊的 `/P` 值 — 請再次呼叫 Encrypt 以便重新發出字典
FIRST-HEADING-NOT-H1	文件順序中的第一個標題元素不是 H1（強結構化的 H 哨兵亦算作等級 1），ISO 14289-1 §7.4.2 要求非強結構化文件中的第一個標題標記為 H1，詳細資料行命名了違規的等級
WIDGET-NO-STRUCTPARENT:N	N 個 Widget 註解缺少 `/StructParent` 項目；ISO 14289-1 §7.18.4 要求 Widget 註解必須巢狀放在 `Form` 結構標記中；若沒有 `/StructParent`，則完全無法從結構樹存取 Widget；詳細資料行會回報計數；這是一項局部檢查 —— 尚未實作解析出的父代 `/S` 是否為 `Form` 的完整驗證
LIST-NO-NUMBERING:N	N 個 L (清單) 結構元素缺少 `ListNumbering` 屬性；ISO 14289-1 §7.6 要求每個 L 標記都必須透過此屬性宣告其編號樣式（依據 ISO 32000-1 Table 347，有效值為 `None`, `Disc`, `Circle`, `Square`, `Decimal`, `UpperRoman`, `LowerRoman`, `UpperAlpha`, `LowerAlpha`）；請在開啟每個 L 標記後呼叫 SetStructElemListNumbering
MULTIPLE-H-CHILDREN:N	N 個結構樹節點包含多個直接 H (通用標題) 子代；ISO 14289-1 §7.4.4 禁止此行為 —— 請分割父區段，或以有編號的 H1..H6 序列取代 H 標記

Return value

以換行符號分隔的問題描述字串，若未偵測到合規性問題則為空字串

Remarks

此函數旨在作為開發人員的診斷輔助工具；它會檢查記憶體中文件的目前狀態，並報告可能導致 PDF/UA-1 驗證失敗的問題；請在載入或建置文件後呼叫它，以便在儲存前識別問題

當 SetPDFUAMode 處於作用狀態且文件已儲存時，儲存期間會自動修正數個問題（ANNOT-NO-CONTENTS、EMBED-NO-AFR）；GetPDFUADiagnostics 會報告儲存前狀態；在儲存前若存在，仍會列出將在儲存時自動修正的問題

此函數不會修改文件

Example

var
  Diag: WideString;
begin
  PDFlib.SetPDFUAMode('en-US');
  // ... build document
  Diag := PDFlib.GetPDFUADiagnostics;
  if Diag <> '' then
    ShowMessage('PDF/UA issues found:'#10 + Diag);
end;