BeginTagEx2

Tagged PDF & Accessibility

Description

開啟一個新的結構元素並將其推送到標記堆疊上，在單次呼叫中設定所有主要元素屬性；BeginTagEx2 是對 BeginTagEx 的便利包裝，後跟 SetStructElemTitle、SetStructElemID 和 SetStructElemExpansion；為 Title, ElemID 或 Expansion 中的任何一個傳遞空字串將跳過對應的設定方法；其他參數的行為與 BeginTagEx 相同

當您在開啟元素時已知道其所有描述性屬性，請使用 BeginTagEx2，以避免多次連續的 setter 呼叫；如果稍後才決定任何屬性（例如，AltText 非同步到達），請在之後使用 BeginTag 或 BeginTagEx 並呼叫個別的 setter

Syntax

Delphi

Function TPDFlib.BeginTagEx2(Const TagType, AltText, ActualText, Lang, Title, ElemID, Expansion: WideString): Integer;

ActiveX

Function PDFlib::BeginTagEx2(TagType As String, AltText As String, ActualText As String, Lang As String, Title As String, ElemID As String, Expansion As String) As Long

DLL

int DLBeginTagEx2(int InstanceID, const wchar_t * TagType, const wchar_t * AltText, const wchar_t * ActualText, const wchar_t * Lang, const wchar_t * Title, const wchar_t * ElemID, const wchar_t * Expansion);

Parameters

TagType	結構元素類型名稱，例如 `Figure`、`Table`、`Span`、`P`，與 BeginTag 接受的相同類型
AltText	寫入到 /Alt 項目的替代文字 (ISO 32000-1 §14.9.3)；傳入空字串可省略
ActualText	寫入到 /ActualText 項目的實際文字 (ISO 32000-1 §14.9.4)；傳入空字串可省略
Lang	寫入到 /Lang 項目的 BCP 47 語言標記 (ISO 32000-1 §14.9.2)，例如 `en-US`、`fr`、`zh-Hant-TW`；傳入空字串可繼承文件語言
Title	寫入 /T 條目的易讀標籤（ISO 32000-1 §14.7.2）；顯示在 Tags 導覽面板中；傳遞空字串可省略
ElemID	寫入 /ID 項目的唯一元素識別碼（ISO 32000-1 §14.7.4）；如果設定，在文件內必須是唯一的；傳遞空字串以忽略
Expansion	寫入到 /E 項目的縮寫或首字母縮寫之展開值 (ISO 32000-1 §14.9.5)；傳入空字串可省略

Return value

成功時傳回 1，未選取文件時傳回 0

Remarks

每次成功呼叫 BeginTagEx2 後，呼叫一次 EndTag，以從標記堆疊中彈出該元素；結構元素可以巢狀化：在另一個元素開啟時呼叫 BeginTagEx2 會建立一個子元素

內部實作完全等同於

BeginTagEx(TagType, AltText, ActualText, Lang);
if Title <> '' then SetStructElemTitle(Title);
if ElemID <> '' then SetStructElemID(ElemID);
if Expansion <> '' then SetStructElemExpansion(Expansion);

對於在元素開啟後確定的屬性，或 BeginTagEx2 未涵蓋的屬性（例如用於表格儲存格屬性的 AddTagAttribute），個別的設定方法仍然可用

Example

// Tag a figure with all descriptive properties in one call
PDFlib.BeginTagEx2(
  'Figure',                              // TagType
  'Bar chart: Q1 120, Q2 145, Q3 98',   // AltText
  '',                                    // ActualText (not needed for images)
  '',                                    // Lang (inherit document language)
  'Figure 3: Quarterly Sales',           // Title
  'fig-quarterly-sales',                 // ElemID
  ''                                     // Expansion (not an abbreviation)
);
PDFlib.SetStructElemBBox(x, y, x + w, y + h);
PDFlib.DrawImage(imgHandle, x, y, w, h);
PDFlib.EndTag;

// Tag an acronym span with its expansion
PDFlib.BeginTagEx2(
  'Span',
  '',                                          // AltText
  '',                                          // ActualText
  '',                                          // Lang
  '',                                          // Title
  '',                                          // ElemID
  'World Wide Web Consortium'                  // Expansion
);
PDFlib.WriteText('W3C');
PDFlib.EndTag;