BeginTagEx2

PDF المُعلَّم وإمكانية الوصول

الوصف

يفتح عنصر بنية جديدًا ويدفعه إلى رصة الوسوم مضبوطًا جميع خصائص العنصر الرئيسة في استدعاء واحد. BeginTagEx2 غلاف ميسر لـ BeginTagEx يليه SetStructElemTitle وSetStructElemID وSetStructElemExpansion. وسيؤدي تمرير سلسلة فارغة لأي من Title أو ElemID أو Expansion إلى تخطي الضابط المقابل؛ وتتصرف المعاملات الأخرى مطابقةً لـ BeginTagEx

استخدم BeginTagEx2 عندما تعرف سلفًا جميع الخصائص الوصفية للعنصر لحظة فتحه، لتجنب عدة استدعاءات ضبط متتالية. وإذا تحددت أي خاصية لاحقًا (مثلًا يصل AltText بشكل غير متزامن)، فاستخدم BeginTag أو BeginTagEx واستدعِ التوابع الفردية بعدها

الصيغة

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` في PDF). مرِّر سلسلة فارغة إن لم يكن مطلوبًا
ActualText	يفعّل وضع الامتثال لمعيار PDF/UA-1 (ISO 14289-1:2014) للمستند المحدد. يؤدي هذا الاستدعاء الواحد كل الإعداد على مستوى المستند الذي يطلبه المعيار: يُرفع إصدار المستند إلى PDF 1.7 على الأقل، ويُكتب MarkInfo.Marked وMarkInfo.Suspects، ويُفعَّل DisplayDocTitle في ViewerPreferences، ويُضبط Catalog/Lang عند توفير لغة، ويُكتب مدخل نطاق الأسماء pdfuaid:part=1 في XMP. وإذا شُفّر المستند بعد تفعيل SetPDFUAMode فسيُفرض تفعيل CanCopyAccess (البت 10 من مفتاح التشفير `/P`) تلقائيًا بغض النظر عن قناع `TPDFExtraPermissions` الذي يمرره المستدعي، استيفاءً لـ ISO 14289-1 §7.16. أما إذا كان المستند مشفرًا قبل استدعاء SetPDFUAMode فيُترك قاموس التشفير الحالي دون تغيير — استدعِ Encrypt مجددًا بعد SetPDFUAMode لتحديث قيمة `/P`. ويُبلغ GetPDFUADiagnostics عن هذه الحالة بالرمز `ENCRYPT-NO-ACCESS`
Lang	وسم لغة BCP 47 للغة المستند الافتراضية، مثل `"en-US"` و`"de"`. مرِّر سلسلة فارغة لحذف مدخل Catalog /Lang
Title	تسمية مقروءة للإنسان تُكتب في مدخل /T (ISO 32000-1 §14.7.2). تظهر في لوحة تنقل الوسوم. مرِّر سلسلة فارغة لحذفها
ElemID	معرّف عنصر فريد يُكتب في مدخل /ID‏ (ISO 32000-1 §14.7.4). يجب أن يكون فريدًا داخل المستند إذا ضُبط. مرِّر سلسلة فارغة لحذفه
Expansion	توسيع لاختصار أو اختصار حروفي يُكتب في الإدخال /E ‏(ISO 32000-1 §14.9.5). مرر سلسلة فارغة لحذفه

قيمة الإرجاع

تُرجع 1 عند النجاح، و0 إذا لم يكن هناك مستند محدد

ملاحظات

استدعِ AddEmbeddedFile أولًا لنسخ بايتات الملف إلى المستند والحصول على EmbeddedFileID. ثم يضيف AddFileAttachment مواصفة الملف تلك إلى شجرة الأسماء /Names /EmbeddedFiles في الكتالوج دون تكرار البايتات المضمّنة

التنفيذ الداخلي مطابق تمامًا لـ:

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

تبقى التوابع الفردية متاحة للخصائص التي تتحدد بعد فتح العنصر، أو للخصائص التي لا يغطيها BeginTagEx2 (مثل AddTagAttribute لخصائص خلايا الجداول)

مثال

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