if أو each أو else أو تضمين.
يعالج العارض المستند الرئيسي ورؤوس Word وتذييلاته وحواشيه السفلية وحواشيه الختامية وتعليقاته. احتفظ بملف DOCX مصدر واحد مراجع، واختبر كل موضع يحوي وسماً؛ فالوسم في الرأس يملك قواعد التعبير نفسها الموجودة في متن المستند، لكنه يحتاج إلى مراجعة تخطيط مرئية في الملف النهائي.
تأليف الوسوم بمساعد الذكاء الاصطناعي
يمكن الوصول إلى مساعد DOCX من Create with AI helper عند إنشاء قالب، أو من Versions → Revise with AI helper لمراجعة الإصدار المُدار الحالي. لا يستخدم مسار Versions ملف DOCX بديلاً محدداً بوصفه مصدر AI؛ يبقى اختيار الملف محفوظاً عند العودة، ويظل Validate and upload مسار التحقق والرفع المباشر المنفصل لذلك الملف. قبل التوليد يجب اختيار كيان صالح أو تقديم كائن JSON يدوي صالح؛ السجل الممثل اختياري، وعند غيابه تستخدم المعاينة عينة حتمية معلّمة بحسب نوع الحقل لا تحفظ في الوسوم أو البيانات الوصفية. تنطبق على JSON اليدوي حدود 256 KiB و12 مستوى و1,000 عنصر لكل مصفوفة و32 KiB لكل سلسلة، وترفض مواد المصادقة المعروفة. يتطلب أول طلب إقراراً بأن نص المستند المطبّع والسياق أو العينة المصرح بهما والتعليمة ستذهب إلى مزود AI المضبوط. لا يستلم النموذج أرشيف DOCX أو XML الخام. ويحافظ المساعد افتراضياً على الصياغة والترتيب والتنسيق والتخطيط؛ ولا يسمح بإعادة صياغة أو نقل أو حذف أو تكرار أو إنشاء بنية إلا بطلب صريح يحدد فقرة أو خلية أو صفاً أو كتلة محدودة، أو يصرح بوضوح بإعادة كتابة المستند كله. لا يملك المساعد لغة قوالب ثانية. يمكنه إنشاء تعبيرات JEXL المضمنة، وif/else، وeach، والصور، والروابط، ورموز QR، وفواصل الصفحات، وتضمينات قوالب مُدارة متاحة، وgetRecords محدوداً بكيان مصرح به و500 صف كحد أقصى لكل استدعاء. تخضع كل نتيجة للقواعد اليدوية في هذا الدليل؛ لا تجعل التعليمة محتوى خاماً أو علاقة غير آمنة أو بحثاً غير محدود صالحاً.
راجع إنسانياً مواضع الوسوم وملخص التغيير والمخرج. تعيين reviewable أو ambiguous يمنع الاعتماد حتى يحسمه المستخدم، حتى إذا نجح العرض. وإذا تعذر PDF، يجب تنزيل DOCX ومراجعته والإقرار صراحة بمراجعة DOCX فقط. لا يوسع AI صلاحيات القراءة أو الإدارة، ولا يغير ارتباط إجراء أو نمط تنفيذ أو قائمة كيانات مسموح بها؛ ويحافظ اعتماد إصدار موجود على إعداداته، بينما يتطلب القالب الجديد تأكيد بياناته الوصفية المعروضة صراحة.
المسودة مؤقتة: تنتهي بعد 24 ساعة من آخر نشاط ولا تتجاوز سبعة أيام من الإنشاء. يؤدي الإهمال أو Discard draft إلى تنظيفها، ويمحو الاعتماد الناجح السياق اليدوي والتعليمات والملفات المؤقتة مع إبقاء ملخص تدقيق غير حساس. لمشكلات بدء التوليد أو نطاق التغيير أو تعيين المسارات أو PDF أو انتهاء الجلسة، راجع جدول استكشاف أخطاء مساعد AI ولا تتجاوز المشكلة بتوسيع الصلاحيات أو إزالة حدود العارض.
متى تستخدمه
استخدم الوسوم عندما يجب أن تعكس جملة أو جدول أو صورة أو رابط أو رمز QR أو كتلة متكررة بيانات مخزنة. من الأمثلة مرجع الطلب واسم المقيم وقائمة المستندات المقدمة ورابط حالة عام وشعار مكتب الخدمة وجدول زيارات المعاينة. احتفظ بقرارات السياسة في السجل، واستخدم الوسم فقط لإظهار النتيجة المعتمدة فعلاً. لا تستخدم وسم قالب لتجاوز إجراء أو اختراع مرجع تسلسلي أو استعلام مجموعة كبيرة «للاحتياط». عندما يلزم أن يقرر المراجع النتيجة، نمذج القرار بحقول مضبوطة ثم اعرض النتيجة المختارة. وإذا صار التعبير صعب القراءة، فخزن أو احسب قيمة المصدر المعتمدة أولاً واعرض المفتاح البسيط.الإعداد
قواعد التأليف في Word
اكتب الوسم بقوسين مزدوجين:{{ expression }}. يمكن أن يشترك النص والوسم المضمن في فقرة Word واحدة، مثل المرجع: {{ $record.request_reference }}. يجمع العارض النص الذي قد يوزعه Word على تشغيلات تنسيق مختلفة، ولذلك يستطيع التعبير البسيط أن يحل حتى لو قسم Word حروفه أثناء التنسيق. ومع ذلك أبقِ الوسم بسيطاً بصرياً: لا تخفِ علامات الترقيم في تشغيل ملوّن أو منسق، وأعد كتابة الوسم بدلاً من لصق تنسيق غير مرئي إذا كان التحقق غير متوقع.
تختلف وسوم التحكم. عند العرض، يجب أن تكون وسوم فتح وإغلاق if أو each وelse ووسم التضمين هي المحتوى الوحيد لفقرة Word كاملة أو صف جدول كامل. بهذه البنية يختار العارض عقد Word كاملة أو يحذفها أو يكررها أو يستوردها. ضع وسم فتح الحلقة في فقرة أو صف مستقل، وضع الفقرة أو الصف القابل للتكرار بينه وبين وسم الإغلاق، ثم ضع وسم الإغلاق في فقرة أو صف مستقل. يرفض وسم التضمين إذا احتوت فقرته أو صفه أي نص آخر. لا يستطيع تحقق الرفع اعتماد هذا الموضع، لذا اعرض سجلاً محفوظاً بعد كل تعديل بنيوي.
استخدم هذا التخطيط لفقرة شرطية:
السياق والتعبيرات المضمنة
يوفر عرض سجل الكيان الجذور التالية:
يقيم أي وسم عادي بوصفه JEXL ثم يحول إلى نص مستند. تصبح نتيجة
null أو undefined سلسلة فارغة. احمِ البيانات الاختيارية حتى يظل المستند مفهوماً:
if وeach. تحتاج if إلى تعبير، ويجب أن تستخدم each القاعدة الدقيقة {{#each expression as item}}. يعامل العارض تعبير حلقة ليس مصفوفة كمجموعة فارغة، ولذلك قد ينتج مفتاح مكتوب خطأ صفوفاً معدومة من دون خطأ ظاهر؛ اختبر سجلاً ممتلئاً وسجلاً فارغاً.
تكرار الفقرات وصفوف الجداول
داخل كتلةeach يكون الاسم المستعار للعنصر الحالي. ويضبط KayanOS أيضاً $index وهو يبدأ من الصفر، و$first و$last وهما قيمتان منطقيتان لكل تكرار. تكرر الحلقة فقرات Word الكاملة أو صفوف الجدول الكاملة الموجودة بين وسم الفتح والإغلاق. وهذا مناسب لإشعار فيه مستندات مطلوبة متعددة أو جدول فيه معاينات متعددة.
في الجدول استخدم صفوفاً مستقلة للتحكم:
$first أو $last للعرض فقط، مثل إدراج فاصل أو تعليمات نهائية؛ فهما لا يغيران وصول السجل.
الوسوم الغنية والتضمينات
تعمل الوسوم الغنية فقط باسم الأمر وخياراته الدقيقين. الخيارات رموزkey=value تفصلها مسافات، لذلك استخدم قيماً بسيطة بلا مسافات أو أعد قيمة قصيرة مخزنة مسبقاً.
في العرض المُدار، يمكن أن تكون قيمة الصورة رابطاً عاماً معتمداً ببروتوكول HTTPS أو كائناً مرجعياً يحوي
fileId أو رابط بيانات base64 بصيغة data:image/png|jpeg|jpg|webp;base64,.... أنواع الصور النقطية المدعومة JPEG وJPG وPNG وWebP، وحد البايتات 10 MiB. توقف القيمة الناقصة غير الاختيارية العرض. استخدم optional=true فقط عندما قد لا تعيد القيمة الغائبة صورة من الأصل؛ فهو لا يحول رابطاً مكسوراً أو تنزيلاً فاشلاً أو نوع محتوى غير مدعوم أو رابط بيانات غير صالح أو صورة غير قابلة للقراءة أو صورة تتجاوز الحد إلى حذف آمن. اختبر المصدر الفعلي الذي يستخدمه القالب.
استخدم وجهات عامة معتمدة للروابط ورموز QR:
البحث عن سجلات بقصد
تقبل دالة JEXL المسماةgetRecords كائناً فيه entityKey إلزامي وq وfilters وlimit وsorting وsearch اختيارية. خزن كائن البحث في سياق السجل المختار واستخدمه في حلقة بنيوية:
getRecords بحد أدنى 1 وحد أقصى 500 صف؛ وتسجل الخدمة أعداد الصفوف المعادة في تدقيق العرض. استخدم حداً صغيراً ومرشحاً محدداً. في نمط caller يعمل الاستعلام بوصول العضو الطالب. وفي نمط admin يعمل بوصفه مسؤول النظام؛ وعندما يحوي إعداد الإجراء كيانات مسموحاً بها يرفض أي مفتاح كيان آخر. لا تقدم حقل 5,000 صف المعلن في نوع العارض بوصفه حداً إجمالياً مفروضاً للبحث: الضابط المثبت المصدر في إجراءات KayanOS هو حد 500 صف لكل استدعاء.
المحتوى غير المدعوم والحدود الصارمة
يرفض KayanOS إدراج XML الخام، بما فيه{{@rawXml ...}} أو {{rawXml ...}}. كما يبلغ أن وسمي @html و@chart غير مدعومين. لا تحاول تجاوز ذلك بإدراج XML أو HTML أو محتوى شبيه بالبرامج النصية في التعبير؛ استخدم محتوى DOCX عادياً أو صورة مدعومة أو قيمة مراجعـة من المنبع.
يفرض العارض أيضاً مهلة عرض قدرها 15 ثانية وحد مخرج معروض قدره 80 MiB وحد صورة 10 MiB ومجموع حلقات 10,000 ومستويات تداخل بنيوي 20 وخمسة مستويات تضمين متداخلة. هذه حدود أمان وليست أهداف أداء؛ صمم مستندات أصغر بكثير من كل حد.
يحمي تحقق الرفع حزمة DOCX نفسها أيضاً. فهو يرفض ملف ZIP غير المقروء ومسارات الإدخالات غير الآمنة وأكثر من 2,000 إدخال وأكثر من 80 MiB من المحتوى غير المضغوط أو نسبة ضغط تتجاوز 100:1. كما يرفض الأجزاء الممكّنة للماكرو وأجزاء OLE أو الثنائيات المضمّنة وإعلانات DTD/entity في XML والعلاقات الخارجية غير الآمنة؛ وتعد ارتباطات http وhttps وmailto العادية حالة العلاقة الخارجية المسموح بها. ابدأ بملف .docx نظيف بدلاً من محاولة إزالة ماكرو أو كائن مضمّن بعد رفضه.
مثال عملي
تصدر جهة خدمة عامة سورية إقراراً لطلب خدمة مقيم. يعرض الخطاب مرجع الطلب التسلسلي ويسرد المستندات المطلوبة التي استلمت ويضع شعار مكتب اختيارياً ويربط بصفحة الحالة العامة ويبدأ صفحة منفصلة لعبارة الخطوات التالية القياسية. لا يجب أن يعرض القالب قرار موافقة ما لم تكن حالة السجل المضبوطة تشير إليه بالفعل. يجهز المالك$record.required_documents كمصفوفة كائنات فيها name وstatus. وفي Word ينشئ جدولاً بثلاثة أعمدة ويضع وسم each الافتتاحي في صف تحكم فارغ والصف المتكرر في الصف التالي ووسم الإغلاق في صف تحكم أخير. ثم يضيف فقرة شرطية للموعد الغائب ورابط حالة مضمن. يضم المستند ثلاث حالات اختبار ذات معنى: بلا مستندات ومستند واحد وعدة مستندات.
لشعار اختياري آمن يستخدم المؤلف:
الاختبار
اختبر سلوك الوسوم ببنى Word فعلية، لا بنسخة نصية عادية من القالب. يكتشف تحقق الرفع مشكلات الحزمة وبعض القواعد الخاطئة، بينما يكتشف العرض موضع وسوم التحكم والقيم المفقودة وعمليات البحث غير المتاحة والأصول غير المحلولة ومشكلات التخطيط.
عندما يبلغ التحقق عن مشكلة، صحح مصدر Word وارفع إصدار قالب جديد. لا تخفِ وسماً مكسوراً بنص أبيض، ولا تضع علامة تحكم في خلية جدول تحوي نصاً آخر، ولا تعتمد على أن العارض سيتجاهل محتوى غير صالح.
استكشاف الأخطاء وإصلاحها
الأذونات وحدود جودة البيانات
لا يمنح تأليف الوسم وصولاً. إدارة القوالب المُدارة قدرة إدارية مستقلة على مستوى البناء تتحكم بملفات القوالب وإصداراتها وإعدادات الإجراءات والتحقق والعرض التجريبي. أما نمطcaller أو admin لإجراء المستند فيتحكم بكيفية تشغيل عمليات البحث وقت العرض. افصل بين المسألتين في المراجعة: قد يسمح لشخص باستخدام إجراء معتمد بنمط الطالب من دون السماح له برفع قالب جديد أو تحويل إجراء إلى نمط المسؤول.
استخدم caller كلما كان ينبغي أن يعكس المستند فقط السجلات التي يستطيع العضو الطالب قراءتها. يحتاج إجراء admin إلى حوكمة صريحة لأنه يمكن أن يستعلم بصفة مسؤول النظام؛ قيد الكيانات المسموح بها واضبط مرشحات ضيقة وراجع كل حقل مطلوب وتعامل مع المخرج بوصفه حساساً. قد يكشف المخرج معلومات مشتقة حتى لو لم يعرض الحقل مباشرة، لذا طبق مراجعة الكشف نفسها على الأعداد والتسميات ووجهات الروابط وقيم QR.
تجنب الأسرار ومواد المصادقة والمعرفات غير المراجعة والملاحظات الداخلية الحساسة في التعبيرات ورموز QR والروابط والنص البديل وقواعد اسم الملف ومرشحات البحث. يفيد تدقيق العرض في التشخيص، لكنه لا يحل محل مراجعة الصياغة القانونية أو ضوابط الموافقة أو قواعد حفظ المؤسسة.
أدلة ذات صلة
- أنشئ وأطلق القالب المُدار في قوالب المستندات.
- تعلّم عوامل JEXL وشروطه ودواله في صياغة لغة التعبيرات.
- اختر حقولاً مستقرة لبيانات المستند في حقول الكيانات وتخطيطاتها.
- أنشئ مراجع مستندات قابلة للتتبع في المعرّفات التسلسلية.