> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kayanos.com/llms.txt
> Use this file to discover all available pages before exploring further.

# دوال المعرّفات التسلسلية وأرقام النماذج

> الدالتان المخصصتان لمعرّفات الكيانات التسلسلية وتنسيقات ترقيم النماذج، مع مفردات رموز التاريخ المحدودة.

## متى تستخدم هذه الدوال؟

استخدم هذه الدوال فقط في إعداد معرّف كيان تسلسلي أو إعداد ترقيم نموذج. وهي ليست واجهة عامة للحقول المحسوبة.

## طريقة الكتابة

استخدم الدالة بصيغة `serialPad($sequence, 5)`. يعرّف الإكمال التلقائي في محرري معرّف الكيان التسلسلي وترقيم النموذج الدالتين كدوال قابلة للاستدعاء ويعرض التوقيع أدناه؛ وبعد `|` يعرّف صيغة التحويل لكل منهما. لا تكون كل دالة متاحة في كل مكان: دوال التحقق ودوال النموذج ودوال قالب المستند لها عقود سياق مختلفة. لا تفترض أن اقتراح المحرر يعني أن الدالة مدعومة وقت التشغيل.

## مرجع الدوال الكامل

### `serialDate`

ينسق تاريخاً في معرّف تسلسلي باستخدام الرموز المحدودة `yyyy` و`yy` و`MM` و`dd` فقط. يعيد نصاً فارغاً عند التاريخ غير الصالح.

**التوقيع:** `serialDate(format, value = $now, timezone = $timezone)`

**مثال:**

```txt theme={null}
serialDate("yyyy-MM", $now, $timezone) // "2026-07"
```

**التوافر:** متاحة في معرّفات الكيانات التسلسلية وتنسيقات ترقيم النماذج فقط. تسجل فيها صيغتا الدالة والتحويل.

**ملاحظة:** عند استخدامها كتحويل، تكون القيمة الواقعة قبل الأنبوب هي **صيغة** التاريخ: `"yyyy-MM" | serialDate($now, $timezone)`.

### `serialPad`

يملأ تسلسل المعرّف من اليسار حتى العرض المطلوب. لا يستخدم من رمز الحشو إلا حرفه الأول، لذلك اختبر النتيجة النهائية لا المقطع وحده.

**التوقيع:** `serialPad(value, width, char = "0")`

**مثال:**

```txt theme={null}
"CSR-" + serialPad($sequence, 5) // "CSR-00042"
```

**التوافر:** متاحة في معرّفات الكيانات التسلسلية وتنسيقات ترقيم النماذج فقط. تسجل فيها صيغتا الدالة والتحويل.

**ملاحظة:** عند استخدامها كتحويل، تكون القيمة الواقعة قبل الأنبوب هي القيمة المراد تعبئتها: `$sequence | serialPad(5)`.

## التفاصيل التشغيلية والحالات الطرفية

### قواعد `serialDate`

الرموز المدعومة للتاريخ هي فقط `yyyy` و`yy` و`MM` و`dd`. تُعامل أي رموز أخرى أو اختلاف في حالة الحروف كنص عادي؛ فلا تتوقع أن يعمل `YYYY` أو رموز الساعة كما تعمل في مكتبات تنسيق أخرى. يحول KayanOS قيمة الإدخال إلى تاريخ، ويعيد سلسلة فارغة إن لم تشكل القيمة تاريخاً صالحاً. استخدم `$timezone` الذي يقدمه إعداد المعرّف بدلاً من تمرير منطقة زمنية حرة غير مراجعَة؛ فالتاريخ نفسه قد يقع في يوم مختلف عند الحد بين يومين محليين.

استخدم استدعاء الدالة عندما تريد أن يظهر ترتيب الوسائط صراحةً:

```txt theme={null}
serialDate("yyMMdd", $now, $timezone) + "-" + serialPad($sequence, 4)
// مثال: "260712-0042"
```

تذكّر أن شكل التحويل له ترتيب مختلف بصرياً: صيغة التاريخ، لا التاريخ نفسه، هي القيمة الواقعة قبل الأنبوب. لذلك اكتب `"yyyy-MM" | serialDate($now, $timezone)` ولا تكتب `$now | serialDate(...)`.

### قواعد `serialPad`

تحول الدالة القيمة إلى نص؛ فتُعرض القيمة الرقمية `42` على أنها `"42"`. يُحوّل العرض إلى رقم، وعرض يساوي صفراً أو أقل أو غير قابل للتحويل يترك النص بلا تعبئة. لا تقطع الدالة قيمة أطول من العرض المطلوب. تستخدم أول محرف فقط من `char`، ويعود المحرف المفقود أو الفارغ إلى `0`. لذلك يعطي `serialPad(42, 5, "AB")` القيمة `"AAA42"`، بينما يعطي `serialPad("123456", 5)` القيمة `"123456"`.

### ما الذي يضمنه الترقيم وما الذي لا يضمنه

لا تنشئ هاتان الدالتان رقماً ولا تحجزان تسلسلاً ولا تتحققان من التفرد. يقدمهما إعداد المعرّف فقط لتنسيق `$sequence` الذي خصصه مسار إصدار المعرّف. أبقِ `$sequence` في الصيغة ما لم يكن لديك تصميم معتمد يمنع التصادمات بوسيلة أخرى، واختبر التعبير في المعاينة ثم في عملية إصدار فعلية. راجع [المعرّفات التسلسلية](/ar/build/serial-ids) للسياق والمتغيرات وسياسة النطاق والتصحيح.

## قائمة تحقق قبل النشر

* ابدأ بقيمة معروفة وتحقق من النتيجة المتوقعة.
* تعامل صراحةً مع القيم الفارغة وnull والقوائم الفارغة.
* لا تضع أسراراً أو رموز وصول أو بيانات شخصية حساسة داخل تعبير.
* راجع [سياقات وتوافر التعبيرات](/ar/reference/expressions/contexts) قبل نسخ تعبير بين ميزتين.

![دوال المعرّفات التسلسلية وأرقام النماذج في KayanOS](https://kayanos.app/docs-images/ar/reference/expressions-helpers-serial.png)