التخصيص في وقت التشغيل

التخصيص في وقت التشغيل هو القدرة الأساسية لنظام السمة في lh-ui: تغيير مظهر المكوّنات في وقت التشغيل دون إعادة ترجمة الأنماط. وكل واجهة برمجة تطبيقات من الثلاث تدير طبقة.

أولًا: themeVars —— تجاوز الرموز العامة

يستقبل ConfigProvider خاصية themeVars بمفاتيح مختصرة:

<lh-config-provider
  :theme-vars="{
    'primary-color': '#1677ff',
    'border-radius-base': '8px',
  }"
>
  <App />
</lh-config-provider>

إضافة البادئة للمفتاح المختصر

يُحوَّل 'primary-color' تلقائيًا إلى --lh-primary-color. ويقوم بهذا التحويل toCssVarName، وهو مُساوٍ تمامًا (idempotent) (تُعاد المفاتيح التي تحمل البادئة كما هي، دون أن تصبح --lh---lh-...).

ويمكن أيضًا كتابة الاسم الكامل مباشرةً:

{ '--lh-primary-color': '#1677ff' }   // مكافئ

والتنفيذ الأساسي هو cssVars(themeVars)، الذي يحوّل أزواج المفاتيح/القيم إلى كائن متغيرات CSS قابل للربط مباشرةً مع :style.

النطاق هو شجرة DOM الفرعية

تتسلسل متغيرات CSS بطبيعتها: يحقنها ConfigProvider في العنصر الملفوف، ولا يستهلك قيمها الجديدة إلا المكوّنات السليل له. وهذا يتيح لك تبديل السمة جزئيًا:

<lh-config-provider :theme-vars="brandVars">
  <Header />
</lh-config-provider>

<lh-config-provider :theme-vars="neutralVars">
  <Content />
</lh-config-provider>

ما يُصدِّره موقع docs هو الشيء نفسه

النص :root { --lh-*: ... } الذي تُصدِّره صفحة تخصيص السمة في docs وthemeVars هما الشيء نفسه متنزلًّا في ملف — يمكنك لصقه مباشرةً في مدخل المشروع:

/* مدخل المشروع */
:root {
  --lh-primary-color: #2B4C7C;
  --lh-primary-color-hover: #3D649E;
  /* ... */
}

ثانيًا: componentTheme —— التجاوز حسب المكوّن

themeVars عامة؛ أحيانًا تريد تغيير رموز مكوّن واحد فقط (مثلًا زوايا استدارة جميع الأزرار مع إبقاء بقية المكوّنات كما هي).

<lh-config-provider
  :component-theme="{
    button: { 'border-radius': '20px' },
    input: { 'control-height-medium': '40px' },
  }"
>
  <App />
</lh-config-provider>

المفتاح هو اسم المكوّن (اسم الدليل ضمن styles/)، والقيمة هي themeVars داخل نطاق ذلك المكوّن. وعند الحقن تأخذ المتغيرات بادئة نطاق المكوّن، فلا تؤثر إلا على المكوّن المحدد. ويجب أن يتطابق اسم المفتاح مع اسم الرمز (control-height-medium → --lh-control-height-medium) — فدرجة input الافتراضية هي medium، ولا يستهلك أحد control-height دون لاحقة الدرجة.

ملاحظة: يعتمد الرمز على مستوى المكوّن على أن يكون SCSS المكوّن قد استهلك الرمز المقابل عبر var(--lh-<name>-*) — فليست كل المكوّنات تجعل كل نقاط الأنماط رموزية، والمرجع لما يمكن تغييره هو سلوك المكوّن في جدول رموز التصميم.

ثالثًا: patternComponents —— القائمة البيضاء للزخارف

الزخارف الصينية (انظر الزخارف الصينية) غير مُفعَّلة افتراضيًا. وعند تفعيلها تؤثر على الخلفية، وليست كل المكوّنات مناسبة لها (طباعة أزهار البرقوق على خلفية جدول مزعجة بصريًا).

يتحكم patternComponents في المكوّنات التي تُطبَّق عليها الزخارف:

<lh-config-provider
  :pattern-components="['card', 'dialog', 'drawer']"
  pattern="plum"
>
  <App />
</lh-config-provider>

فقط المكوّنات الموجودة في القائمة البيضاء تحمل الزخرفة. والمرجع لأسماء الخصائص الصريحة هو وثائق ConfigProvider في كل مكتبة واجهة.

رابعًا: تركيب المسبقة + التخصيص

يمكن تركيب الثلاثة معًا، والأولوية هي «السليل يكتب فوق السلف، والمحدد يكتب فوق العام»:

<lh-config-provider
  theme="cerblue"
  :theme-vars="{ 'border-radius-base': '4px' }"
>
  <!-- تُطبَّق مسبقة 青花瓷 (الخزف الأزرق) أولًا، ثم يُعدَّل زاوية الاستدارة عبر themeVars -->
  <App />
</lh-config-provider>

خامسًا: الوضع الداكن والتخصيص

أينما حُقنت themeVars المخصصة، لا يؤثر إلا على تلك الشجرة الفرعية فاتحةً أو داكنة:

<!-- تُجبَر هذه الكتلة على الوضع الداكن -->
<div data-theme="dark">
  <lh-button>زر داكن</lh-button>
</div>

• مفتاح تبديل الوضع الداكن هو السمة [data-theme='dark'] أو الصنف .dark (محدِّدات var-dark.scss).
• لا تكتب themeVars على style مضمَّن في documentElement — فخصوصيةstyle المضمَّن أعلى من كتلة متغيرات الوضع الداكن الكاملة في var-dark.scss، مما يُفسد ألوان الوضع الداكن (لمزيد من التفاصيل انظر قيد الحقن في النظرة العامة على السمة).

سادسًا: ما لا يمكن تغييره في وقت التشغيل

ما تريد تغييره	هل يمكن	البديل
الرموز: اللون الرئيسي، لون النص، زاوية الاستدارة، المسافات	✅ themeVars	—
رموز مكوّن واحد	✅ componentTheme	—
الزخارف	✅ pattern + patternComponents	—
ارتفاع المكوّن (مثلًا input 37px)	⚠️ محدود	لم تُوحَّد رموز الارتفاع بعد، انظر الفجوات المعروفة
بنية DOM للمكوّن / أسماء الأصناف	❌	استخدم التمرير pt أو الفتحات
تركيب مستويات الظل	❌ وقت الترجمة	تجاوز متغيرات SCSS $lh-* وإعادة الترجمة
منحنى التحريك	✅ --lh-animation-timing-function	—

مثال: تكوين سمة كامل

<template>
  <lh-config-provider
    theme="songhua"
    :theme-vars="{
      'border-radius-base': '8px',
      'font-size-base': '15px',
    }"
    :component-theme="{
      button: { 'border-radius': '999px' },
    }"
    :pattern-components="['card', 'dialog']"
  >
    <App />
  </lh-config-provider>
</template>

ملاحظات

• لا تكرر البادئة في المفاتيح المختصرة: اكتب 'primary-color' لا '--lh-primary-color' (رغم خاصية التساوي التام، فإن توحيد المفاتيح المختصرة أنظف).
• تسرُّب النطاق: لا تؤثر themeVars إلا على المكوّنات السيلية؛ وبالعكس، تُكتب فوق متغيرات السلف ConfigProvider بواسطة السليل (قواعد تسلسل CSS).
• موقع الحقن: يحقن ConfigProvider في العنصر الملفوف (لا في documentElement)، ليضمن قابلية الإزالة والتحديد الموضعي.
• SSR: ما يُحقن هو متغيرات CSS عادية، فيُخرج عرض الخادم styleًا مضمَّنًا، ويتطابق بعد الإعادة على العميل.

وثائق ذات صلة

• نظرة عامة على نظام السمة
• مسبقات السمة
• رموز التصميم
• الزخارف الصينية
• دوال cssVars