format —— إقحام النص

إجمالي {total} عنصر، و{n} نجمة، والخطوة {index}——قوالب النص في حزمة اللغة تحتاج إلى استبدال العناصر النائبة بالأرقام وقت التشغيل. وكانت هذه القدرة على الإقحام في الأصل مدمجة في singleton الخاص بـ locales، ولكن عندما تستخدمها مكوّنات core (عدد نجوم rate، وعدد صفحات pagination) فإنها تجعل core تعتمد عكسيًا على التأثيرات الجانبية لـ singleton على مستوى الوحدة في locales. وبإنزالها إلى دالة نصية نقية، توقّفت كتابة نصوص مكوّنات core عن الاعتماد على أي singleton.

طريقة الاستيراد

// من النواة المشتركة (موصى به)
import { formatMessage } from '@lh-ui/share/core/shared/format'

// أو من مدخل locales (تبقى واجهة التصدير كما هي)
import { formatMessage } from '@lh-ui/share/locales'

جدول الدوال

الدالة	التوقيع	الدور
formatMessage	(template: string, params?: Record<string, unknown>) => string	استبدال العنصر النائب '{key}' بقيم params

تفاصيل السلوك

formatMessage('إجمالي {total} عنصر', { total: 42 })   // 'إجمالي 42 عنصر'
formatMessage('{n} نجمة', { n: 5 })               // '5 نجمة'
formatMessage('لا يوجد عنصر نائب')                      // 'لا يوجد عنصر نائب'
formatMessage('عنصر نائب مجهول {missing}')               // 'عنصر نائب مجهول {missing}'

ثلاث قواعد:

1. العناصر النائبة المجهولة تبقى كما هي. فلا خطأ يُرفع، ولا استبدال بسلسلة فارغة—فالمستدعي يكون عادةً قد أخذ القالب الذي يحوي عناصر نائبة من حزمة اللغة، وعدم وجود معامل يقابل العنصر النائب يعني أن المصدر أهمله، فبقاءه كما هو يجعل المشكلة مرئية في واجهة المستخدم (بدلًا من ابتلاعها بصمت).
2. القيم تُمر عبر String(...) موحدة: الأرقام والقيم المنطقية يمكن إقحامها.
3. params افتراضيًا {}: عند عدم تمرير معاملات يُمرَّر القالب نقياً.

العلاقة مع lhlocale

داخل lhlocale.t(path, params) هو «البحث في حزمة اللغة ← الحصول على القالب ← استدعاء formatMessage»:

// التنفيذ الداخلي لـ locales (مبسط)
t(path, fallbackOrParams) {
  const template = resolve(path) ?? fallback
  return typeof fallbackOrParams === 'object'
    ? formatMessage(template, fallbackOrParams)
    : template
}

وإعادة تصدير formatMessage من @lh-ui/share/locales مقصودة—فهو حاضر في واجهة التصدير القديمة، وبعد إنزاله إلى core يبقى مسار الاستيراد كما هو، وبقي المصب بلا أي تعديل.

متى يُستخدم ومتى لا يُستخدم

السيناريو	يُستخدم؟
إقحام النص داخل مكوّنات core	✅ استخدم formatMessage مباشرةً (دون سحب singleton الخاص بـ locales)
إقحام النص في كود الأعمال	✅ أكثر أمانًا من str.replace (العنصر النائب المجهول يبقى)
يحتاج إلى البحث في حزمة اللغة + الإقحام	❌ استخدم lhlocale.t(path, params) دفعة واحدة
القالب يحتاج إلى شرط / جمع تكسير	❌ هذه الدالة تقوم بالاستبدال البسيط فقط؛ فالنصوص الشرطية تُقسم إلى مفاتيح متعددة داخل حزمة اللغة

أمثلة الاستخدام

نص الإجمالي في pagination

// داخل المكوّن
const totalText = computed(() =>
  formatMessage(lhlocale.t('pagination.total'), { total: props.total }),
)
// حزمة اللغة: 'إجمالي {total} عنصر'  →  'إجمالي 42 عنصر'

إذاعة عدد النجوم في rate

const ariaLabel = formatMessage(lhlocale.t('rate.stars'), { n: currentValue.value })
// حزمة اللغة: '{n} نجمة'  →  '3 نجمة'

أداة سلاسل عامة

// إقحام نقي بلا حزمة لغة
formatMessage('الخطوة {index} / إجمالي {total} خطوة', { index: 2, total: 5 })
// 'الخطوة 2 / إجمالي 5 خطوة'

ملاحظات

• صيغة العنصر النائب هي {key} (قوس مفرد)، لا ${key} ولا {{key}}.
• لا دعم للقوالب المتداخلة: تُمرر قيم params عبر String() مرة واحدة دون تحليل متكرر.
• الأداء: ما يفعله الاستدعاء الواحد هو حلقة String.replace، فلا تكرر استدعاءه على القالب نفسه داخل حلقة عالية التردد—يكفي أن تصنع طبقة واجهة المستخدم ذاكرة computed واحدة.

@lh-ui/share/core/format → formatMessage( )

运行重置

返回值

（填好参数后点运行）