BeginTagEx2

標籤式 PDF 與無障礙

描述

開啟新的結構元素並推上標籤堆疊，一次呼叫就設好所有主要元素屬性。BeginTagEx2 是 BeginTagEx 之後接 SetStructElemTitle、SetStructElemID 與 SetStructElemExpansion 的便捷包裝。Title、ElemID 或 Expansion 傳入空字串就跳過對應的 setter；其他參數行為與 BeginTagEx 相同。

開啟元素當下就知道全部描述性屬性時，用 BeginTagEx2 可以省去連續多次 setter 呼叫。若有屬性之後才會確定（例如 AltText 非同步送達），請用 BeginTag 或 BeginTagEx，之後再呼叫個別 setter。

語法

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);

參數

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）。若要省略，請傳入空字串。

傳回值

成功傳回 1；未選取任何文件時傳回 0

備註

每次成功呼叫 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），仍可用各自的 setter 設定。

範例

// 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;

另見

BeginTag, BeginTagEx, EndTag, SetStructElemTitle, SetStructElemID, SetStructElemExpansion