BeginTagEx2

Tagged PDF & Accessibility

Description

打开一个新的结构元素并将其推送到标记栈上，在单个调用中设置所有主要元素属性；BeginTagEx2 是 BeginTagEx 的便利包装器，后接 SetStructElemTitle、SetStructElemID 和 SetStructElemExpansion；为 Title、ElemID 或 Expansion 中的任何一个传递空字符串将跳过相应的 setter，其他参数的行为与 BeginTagEx 完全相同

如果打开元素时已知道其所有描述性属性，请使用 BeginTagEx2，以避免多次连续的设置器调用；如果稍后确定任何属性（例如，AltText 异步到达），请使用 BeginTag 或 BeginTagEx 并在随后调用各个设置器

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），显示在标签导航面板中；传递空字符串可省略
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），单独的 setter 仍然可用

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;