المساهمة

مرحبًا بكم في المساهمة في @lh-ui/share. وهذا المقال هو القيود الصارمة للمشاركة—فمعظم الاتفاقات ليست تفضيلات أسلوبية، بل هي شروط عمل صحيحة عبر مكتبات واجهة المستخدم الأربع.

الخطوط الحمراء الستة

1. يُمنع أي تبعية لإطار في src/

// ❌ ممنوع منعًا مطلقًا
import { ref } from 'vue'
import { useState } from 'react'
import { ... } from '@dcloudio/uniapp'

// ✅ لا يُسمح إلا بالدوال النقية والأنواع
export function computeSomething(input: Foo): Bar { ... }

لماذا: فـ share هو الطبقة المشتركة الوحيدة المستقلة عن الإطار في الأسرة. وبوجود import 'vue' واحد فقط، يبطل الإصداران React وuniapp. ويوجد لدى CI بوابة grep.

أما توصيل التفاعلية فيعود إلى كل طبقة من طبقات واجهة المستخدم (ref() / useState() / useSyncExternalStore())، ولا تُخرج core سوى البيانات النقية. وراجع تصميم lhlocale: باعث أحداث نقي، يحوله كل طرف إلى إعادة عرض.

2. styles/ هو المصدر الوحيد لأنماط المكوّن

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

تكفلت ثلاثة transition mixin باجمع اختلافات أصناف الانتقال بين الأطراف، ويُمنع كتابة صنفين مزدوجين يدويًا في أنماط المكوّن، بل @include حصرًا. وعند الحاجة لتعليق الحالة على عقدة سليل، يُمرَّر المعامل الثاني.

3. اختبارات core الوحدة في نسخة واحدة

tests/unit/ هي نتائج الاختبار المشتركة بين المستودعات الثلاثة. ولا يحق لأي مكتبة واجهة نسخ اختبارات core من هذا المستودع.

4. كان يجب وضع العلامة /* hairline */ على الحد الرفيع 1px —— مُلغى

يُخرج uniapp v3 قيم px مباشرةً، ولا يحوّلها إلى rpx بعد الآن، ففقدت علامة hairline غرضها (راجع docs/bugfix-log.md D-02). وتُحتفظ بـ 65 علامة تاريخية موجودة داخل styles/ كتعليقات عادية، وليس هناك حاجة لوضع علامة على حدود 1px الجديدة. أما الحدود الهيكلية (2px / 3px) فلم تكن تُعلَّم أصلًا.

5. ترتيب إصدار الإصدارات: share أولًا، ثم مكتبات واجهة المستخدم

تعديل share ← changeset ← النشر ← تقوم كل مكتبة بترقية pnpm up @lh-ui/share والتحقق. لا يمكن تخطيه—فإصدار مكتبات واجهة يعتمد على tarball الخاص بـ share المنشور مسبقًا.

6. يجب أن تحمل الرموز المطوَّرة ذاتيًا البادئة LH

عند إضافة ثابت / نوع / واجهة جديد، التزم بذلك فورًا، ولا تؤجله إلى تعديل موحد لاحق (راجع changeset الخاص بإعادة التسمية lh-prefix-naming).

اصطلاحات التسمية

منسقة مع docs/project/development-guide.md في مستودع plus، وموحدة لأسرة كاملة:

الطبقة	الاصطلاح	مثال
جذر النطاق العكسي	top.lhgb (عكس www.lhgb.top)	جذر التسمية لجميع مستودعات الأسرة؛ ويستخدم package.json قيم lhgb.top في homepage / repository / author
أسماء حزم JS / npm	النطاق @lh-ui/*	لا تسمح أسماء حزم npm بوجود نقطة، فيقع النطاق العكسي في طبقة البيانات الوصفية
الثوابت	LH_XXX، وLH_<الوحدة>_<المفهوم>	LH_SIZE_DEFAULT، وLH_THEME_PRESETS
ثوابت القيمة الافتراضية	لاحقة DEFAULT	LH_DRAWER_DIRECTION_DEFAULT
الأنواع / الواجهات	LhXxx	LhThemePreset، وLhSxProps
الحالات المفردة على مستوى الوحدة / الكائنات الصغيرة	lhXxx	lhlocale
أسماء أصناف BEM	lh-xxx	lh-button__text--disabled
اسم المكوّن	LhXxx	name: 'LhButton'

تسجيلات الإعفاء

متعارف عليها، ولا تُلزم بالبادئة (سجِّل السبب هنا قبل التعديل):

• تصدير حزم اللغة zhCN / enUS —— اصطلاح معياري لتسمية locale، وتُعيد ثلاث مكتبات واجهة تصديره كواجهة API عامة، فحجم أضرار إعادة التسمية كبير جدًا.
• القيم النصية لأسماء مفاتيح السمات (name: 'cerblue' ونحوها) —— فهذه قيمة تكوين يكتبها المستخدم في theme الخاص بـ ConfigProvider، فإن تغيّرت انكسرت تكوينات جميع المستخدمين المصب؛ بينما معرّف TS المقابل يبقى مُقدَّمًا بالبادئة (LhCerblue).
• رموز التصدير للاعتمادات الخارجية لا تُلزم.

مسؤوليات الأدلة

الدليل	المسؤولية
src/core/<name>/	منطق الدوال النقية للمكوّن (logic.ts / types.ts / index.ts)، بلا أي استيراد لإطار
src/core/shared/	النواة المشتركة بين المكوّنات (12 وحدة، راجع النظرة العامة)
src/theme/	جانب TS للسمة (الأنواع + خمس مفاتيح مسبقة)
src/constants/ / src/locales/ / src/types/ / src/utils/	الثوابت / حزم اللغة / الأنواع / الأدوات النقية
styles/	المصدر الوحيد لأنماط BEM للمكوّنات (<name>/index.scss + theme/common/*.scss)
tests/unit/	اختبارات core الوحدة في نسخة واحدة
scripts/	سكربتات البناء والتحقق
docs/	موقع الوثائق (Astro Starlight)، ولا يدخل ناتج npm

اتفاقيات رسائل الالتزام

• تكتب التعليقات ورسائل الالتزام باللغة الصينية.
• تكتب رسالة الالتزام بمصدر markdown وبتفصيل كبير: سطر العنوان + نطاق التغيير + قائمة الملفات المضافة / المعدلة + جدول النقاط التصميمية + حالة التحقق.
• إعدادات Prettier: علامات اقتباس مفردة، بلا فاصلة منقوطة، مسافتان، printWidth 100. ولا يغطي pnpm format سوى ملفات الإعدادات، فالباقي يُمحاذا يدويًا.

قائمة إضافة مكوّن core جديد

1. الثلاثي src/core/<name>/{logic,types,index}.ts
2. tests/unit/core/<name>.spec.ts
3. إضافة التصدير في src/core/index.ts
4. styles/<name>/index.scss (وإلا فلا ناتج أنماط لأحد الأطراف، تجاوز صامت)
5. changeset (minor)

ثم شغّل:

pnpm test && pnpm lint && pnpm typecheck
pnpm build                    # يولد sync:exports مفتاح exports جديدًا
pnpm verify:dts && pnpm verify:styles

قائمة الفحص الذاتي قبل تقديم PR

• لا يوجد داخل src/ أي import 'vue' | 'react' | '@dcloudio/*' (الخط الأحمر 1)
• تعديلات الأنماط في styles/ فقط (الخط الأحمر 2)
• الألوان كلها var(--lh-*, fallback)، بلا قيم لونية مُرمَّزة جديدة
• أصناف الانتقال الجديدة تستخدم mixin، دون كتابة -enter-from / -leave-from مكشوفة
• الرموز الجديدة في var.scss؛ وإن كانت القيمة إقحام #{$lh-*} فلها تغطية مقابل في var-dark.scss
• الرموز الجديدة تحمل البادئة LH / Lh (الخط الأحمر 6)
• pnpm test / pnpm lint / pnpm typecheck تمر
• بعد pnpm build، يمر pnpm verify:dts / pnpm verify:styles
• يوجد changeset بمستوى صحيح
• للمكوّن الجديد styles/<name>/index.scss وtests/unit/core/<name>.spec.ts (الخط الأحمر 3)
• إن عُدِّلت الرموز / أسماء الأصناف / الأيقونات، شُغِّل pnpm docs:data لتحديث بيانات الوثائق

مهام معلومة قائمة (مُسجَّلة كـ changesets لاحقة، مرحبًا بالتطوع)

«ملف رموز الارتفاع»:

1. اختلاف ارتفاعات عناصر التحكم (input 37 / select 32 / cascader 27←32 / date-time 33 / input-number 32)، والسبب الجذري غياب رمز --lh-control-height-* في var.scss
2. padding-top: 16px غير المتماثل في input ذي --has-label
3. عدم تطابق درجات الحجم الاسمي بين spinner وicon (small 16 مقابل 14)
4. علامة checkbox المثبَّتة عند top:2/left:5 بدلًا من التوسيط عند 50% (صحيحة عند صندوق 16px، وتنحرف عند تغيير الحجم)
5. تكرار translate(-50%,-50%) الخاص بـ switch بشكل مُرمَّز ثابت في base وkeyframes

وثائق ذات صلة

• مقدمة المشروع —— موقع share في الأسرة
• اصطلاحات التسمية —— النسخة الكاملة لاصطلاحات التسمية
• استراتيجية حقن الأنماط في كل طرف —— آلية تطبيق الخط الأحمر 2
• نظام التحقق —— التحققات الواجب تشغيلها قبل PR
• عملية الإصدار —— الخطوات الكاملة للخط الأحمر 5