برمجة عناصر الاختيار في XFA

الوحدة: HPDFXFARuntime

حقل ذو ui.choiceList يكشف أساليب عناصر الاختيار أثناء تنفيذ أحداث JavaScript وFormCalc الأصلية، بما يشمل نسخ الحقول المتكررة والaliases المحفوظة بكائنات سكربت

الأساليب والخصائص

العضو	السلوك
`length`	عدد عناصر التصدير الحالي للقراءة فقط
`selectedIndex`	أول فهرس مختار ذي أساس صفري أو -1 عندما لا شيء مختار؛ وإسناد أي عدد صحيح سالب يمسح الاختيار، بينما قيمة غير سالبة خارج النطاق أو غير صحيحة تُلقي قبل تغييره
`getDisplayItem(index)`	نص العرض عند الفهرس، أو null عندما يكون الفهرس غير صالح
`getSaveItem(index)`	نص التصدير عند الفهرس، أو null عندما يكون الفهرس غير صالح
`boundItem(display)`	نص التصدير لأول نص عرض مطابق تمامًا، أو null عندما لا يطابق أي نص عرض
`getItemState(index)`	ما إذا كان العنصر مختارًا؛ والفهرس غير الصالح يُلقي
`setItemState(index, selected)`	تحديث اختيار العنصر؛ وانتقاء عنصر يستبدل الاختيار السابق لحقل أحادي الانتقاء ويحفظ بقية الفهارس المختارة لحقل متعدد الانتقاء
`addItem(display, bound)`	إلحاق عنصر دون تغيير العناصر المختارة القائمة؛ وإغفال الوسيط الثاني يستخدم سلسلة تصدير فارغة
`deleteItem(index)`	حذف عنصر وإزاحة الفهارس اللاحقة مع حفظ هوية aliases العناصر الناجية؛ وتعيد false لفهرس غير صالح
`clearItems()`	إزالة العناصر الحالية ومسح الاختيار؛ وقائمة runtime فارغة صريحة تبقى فارغة بعد الحفظ وإعادة التحميل
`setItems(text, columns)`	استبدال العناصر الحالية من أعمدة مفصولة بفواصل ومسح الاختيار؛ وcolumns تقصّر افتراضيًا إلى 1، وصف عمود واحد يزوّد نص العرض والتصدير معًا، والصف الأطول يستخدم عموده الأول نص عرض وعموده الأخير نص تصدير؛ وتعيد false إذا كان عدد الأعمدة غير صالح أو لا يقسم عدد حقول الإدخال

الفهارس أعداد صحيحة ولا تُكرَه أبدًا من سلاسل؛ وأساليب العناصر تتطلب عدد وسائطها الموثقة، مع قبول الوسيط الثاني الاختياري من addItem وsetItems

قيم العناصر تحفظ Unicode والفراغات الرائدة والختامية والصادرات الفارغة الصريحة وفواصل الأسطر؛ ومحارف تحكم XML غير الصالحة والثنائيات surrogate غير المقترنة في UTF-16 تُرفضان قبل تحويل القائمة

الحالة الفورية وaliases

العناصر الجديدة مرئية فورًا عبر أساليب العناصر وProperty DOM، وalias عنصر محذوف لا يمكنه إعادة التوجيه إلى عنصر ناجٍ انتقل إلى الفهرس المحذوف

استبدال القائمة أو مسحها ينشئ هويات استبدال مميزة؛ وaliases كائنات السكربت المحفوظة إلى عناصر مُزالة تفشل في القراءات والكتابات اللاحقة، بينما تواصل aliases الناجية مخاطبة العنصر نفسه عبر تنفيذات الأحداث

إسناد rawValue مباشرًا أو كتابة Data DOM مرتبطة أو إرسال قيمة widget عامًا أو تحويل scalar لـ export-item يُبطل الفهارس الصريحة المخزنة، بما يشمل الإسنادات التي تحفظ نفس السلسلة الخام

الاستمرارية والاختيار الدقيق

SaveToBytes تكتب عناصر النموذج الفعلية لكل نسخة والقيم المتزامنة؛ وتعديل نسخة متكررة يحفظ بقية النسخ ونطاقات بياناتها

الصادرات المكررة والفارغة يمكن انتقاؤها بفهارس دقيقة عبر واجهة العناصر؛ وحقل النموذج المحفوظ يسجل الفهارس المقننة وقيمة raw المطابقة في سمات اختيارية في namespace بقيمة urn:hotpdf:xfa:runtime

عناصر وعقد قيم XFA القياسية تبقى حاضرة باستقلالية عن هذه السمات الاختيارية؛ والكتابات اللاحقة للقيم تُبطل السمات كي لا تنتقي الفهارس المتقادمة تصديرًا مكررًا خاطئًا

مستهلك PDF الأصلي يكتب أزواج /Opt تصدير/عرض مطابقة وفهارس /I دقيقة وسلاسل أو مصفوفات /V ويبني المظاهر من تسميات العرض المنتقاة

المعاملات والحدود

تغييرات العناصر تدخل في معاملة الحدث وسجل السكربت القائمين؛ وفشل حد قيمة أصلي أو إلغاء مستدعي أو استثناء حدث غير معالَج يستعيد XDP المحفوظ والحالة المعجمية للسكربت والارتباطات قبل إعادة محاولة لاحقة

تخصيصات العقد وأعمدة الإدخال وقيم UTF-8 وحمولات عمليات XML وتجوال الخصائص الأصلية والاستنساخ تحفظ ميزانيات السكربت وruntime المهيأة وفحوص الإلغاء

مثال

var list = this.parent.choice;
list.clearItems();
list.addItem("Display A", "same");
list.addItem("Display B", "same");
list.selectedIndex = 1;
if (list.getDisplayItem(list.selectedIndex) !== "Display B")
    throw new Error("Unexpected selected label");

لمتغيرات FormCalc التي تحفظ حقلًا بدلًا من قيمته الـ scalar، استخدم var list = Ref($.parent.choice) قبل استدعاء أساليب العناصر

مفردات الأساليب ووسائط الأعمدة تتبعان مرجع برمجة Adobe Designer; وبيئة التشغيل تستخدم دلالات الاستبدال في setItems، كما في دعم برمجة نماذج HTML5 من Adobe