متى تستخدم هذه الدوال؟
استخدم هذه الدوال فقط في إعداد معرّف كيان تسلسلي أو إعداد ترقيم نموذج. وهي ليست واجهة عامة للحقول المحسوبة.طريقة الكتابة
استخدم الدالة بصيغةserialPad($sequence, 5). يعرّف الإكمال التلقائي في محرري معرّف الكيان التسلسلي وترقيم النموذج الدالتين كدوال قابلة للاستدعاء ويعرض التوقيع أدناه؛ وبعد | يعرّف صيغة التحويل لكل منهما. لا تكون كل دالة متاحة في كل مكان: دوال التحقق ودوال النموذج ودوال قالب المستند لها عقود سياق مختلفة. لا تفترض أن اقتراح المحرر يعني أن الدالة مدعومة وقت التشغيل.
مرجع الدوال الكامل
serialDate
ينسق تاريخاً في معرّف تسلسلي باستخدام الرموز المحدودة yyyy وyy وMM وdd فقط. يعيد نصاً فارغاً عند التاريخ غير الصالح.
التوقيع: serialDate(format, value = $now, timezone = $timezone)
مثال:
"yyyy-MM" | serialDate($now, $timezone).
serialPad
يملأ تسلسل المعرّف من اليسار حتى العرض المطلوب. لا يستخدم من رمز الحشو إلا حرفه الأول، لذلك اختبر النتيجة النهائية لا المقطع وحده.
التوقيع: serialPad(value, width, char = "0")
مثال:
$sequence | serialPad(5).
التفاصيل التشغيلية والحالات الطرفية
قواعد serialDate
الرموز المدعومة للتاريخ هي فقط yyyy وyy وMM وdd. تُعامل أي رموز أخرى أو اختلاف في حالة الحروف كنص عادي؛ فلا تتوقع أن يعمل YYYY أو رموز الساعة كما تعمل في مكتبات تنسيق أخرى. يحول KayanOS قيمة الإدخال إلى تاريخ، ويعيد سلسلة فارغة إن لم تشكل القيمة تاريخاً صالحاً. استخدم $timezone الذي يقدمه إعداد المعرّف بدلاً من تمرير منطقة زمنية حرة غير مراجعَة؛ فالتاريخ نفسه قد يقع في يوم مختلف عند الحد بين يومين محليين.
استخدم استدعاء الدالة عندما تريد أن يظهر ترتيب الوسائط صراحةً:
"yyyy-MM" | serialDate($now, $timezone) ولا تكتب $now | serialDate(...).
قواعد serialPad
تحول الدالة القيمة إلى نص؛ فتُعرض القيمة الرقمية 42 على أنها "42". يُحوّل العرض إلى رقم، وعرض يساوي صفراً أو أقل أو غير قابل للتحويل يترك النص بلا تعبئة. لا تقطع الدالة قيمة أطول من العرض المطلوب. تستخدم أول محرف فقط من char، ويعود المحرف المفقود أو الفارغ إلى 0. لذلك يعطي serialPad(42, 5, "AB") القيمة "AAA42"، بينما يعطي serialPad("123456", 5) القيمة "123456".
ما الذي يضمنه الترقيم وما الذي لا يضمنه
لا تنشئ هاتان الدالتان رقماً ولا تحجزان تسلسلاً ولا تتحققان من التفرد. يقدمهما إعداد المعرّف فقط لتنسيق$sequence الذي خصصه مسار إصدار المعرّف. أبقِ $sequence في الصيغة ما لم يكن لديك تصميم معتمد يمنع التصادمات بوسيلة أخرى، واختبر التعبير في المعاينة ثم في عملية إصدار فعلية. راجع المعرّفات التسلسلية للسياق والمتغيرات وسياسة النطاق والتصحيح.
قائمة تحقق قبل النشر
- ابدأ بقيمة معروفة وتحقق من النتيجة المتوقعة.
- تعامل صراحةً مع القيم الفارغة وnull والقوائم الفارغة.
- لا تضع أسراراً أو رموز وصول أو بيانات شخصية حساسة داخل تعبير.
- راجع سياقات وتوافر التعبيرات قبل نسخ تعبير بين ميزتين.
