مرجع API

تستخدم الأجهزة المخصصة main() لإرجاع شجرة View. نقدم هنا بنية البرنامج النصي، وواجهة التشغيل ومكونات الرسم، ونوفر مداخل لواجهات برمجة التطبيقات المختلفة.

كائن عالمي

يوفر CapDrive الكائنات العامة التالية مباشرة في البرنامج النصي للأجهزة، دون الحاجة إلى استيرادها أو إنشائها بنفسك. يمكن قراءتها في main() واستخدامها للحصول على البيانات والتكيف مع بيئة العرض وحفظ الحالة المؤقتة وسجلات الإخراج.

هدف	الغرض وطرق الوصول المشتركة
$data	بيانات القيادة. اقرأ النموذج الحالي من خلال `$data.current`، واقرأ نماذج آخر 30 ثانية من هذه الرحلة من خلال `$data.history`.
$env	بيئة عرض الأداة الحالية، بما في ذلك الأحجام المتاحة وألوان السمات والوحدات واللغة ووضع العرض، مثل `$env.width`، `$env.foreground`.
$sessionStorage	الحالة المؤقتة لمثيل الأداة الحالية خلال الرحلة الحالية. استخدم `get(key)` للقراءة و`set(key, value)` للحفظ؛ واضحة عند إنهاء الرحلة أو إعادة تحميل الجهاز.
console	سجل البرنامج النصي. استخدم `console.log(...)`، `console.warn(...)` وطرق أخرى لإخراج البيانات والمعلومات التشخيصية.

يتم تحديث $data و$env بواسطة التطبيق وهما مدخلات للقراءة فقط. تتم قراءة هذه القيمة في كل مرة يتم فيها استدعاء main()؛ لن يؤدي تعديل النسخة المقروءة من البيانات إلى تغيير بيانات القيادة الفعلية. $ جزء من اسم الكائن، استخدم $env.width مباشرة ولا تحتاج إلى كتابته كاستدعاء دالة.

تحديد محتوى الرسم

يقوم main() في البرنامج النصي للأداة بإرجاع الشاشة الموصوفة بواسطة JSX. كل عقدة JSX عبارة عن View مضمنة، مع سمات تتحكم في الحجم واللون وسلوكيات الرسم الأخرى، والعلاقات المتداخلة التي تشكل الصورة النهائية.

يرسم النص الكامل أدناه عددًا وصفًا من الوحدات. VStack يرتب اثنين Text لأعلى ولأسفل، spacing يضبط التباعد، fontSize يضبط حجم الخط، ويتم توفير اللون بواسطة بيئة العرض الحالية.

function main() {
  return (
    <VStack spacing={6}>
      <Text fontSize={48} color={$env.foreground}>
        78
      </Text>
      <Text fontSize={14} color={$env.accent}>
        km/h
      </Text>
    </VStack>
  );
}

يمكن استخدام التعبير JavaScript في {} الخاص بـ JSX. استبدل 78 الثابت بنتيجة الحساب، وسيتغير النص مع الإدخال؛ يمكن أيضًا تمرير نتيجة الحساب إلى سمات مثل اللون أو الحجم أو زاوية القوس.

$data: بيانات القيادة

تأتي حقول $data.current من معرف الإدخال لهذا الجهاز. املأ القيمة الأصلية في إعدادات العداد → ربط المدخلات أو حدد المعلمة OBD وقم بالترس في تعريف إدارة تكوين المعلمات. يفترض ما يلي أنه تم تعريف المعرف المقابل.

طريقة الوصول سبيل المثال	تعريف الإدخال وإرجاع المحتوى
`$data.current.speed`	إدخال السرعة الأساسية، يُرجع `{ value, unit }`.
`$data.current.gForce`	إدخال قيمة G الأساسية، بما في ذلك `longitudinal`، `lateral`، `combined` والوحدات.
`$data.current.location`	إدخال الموقع الأساسي، بما في ذلك خطوط الطول والعرض والوحدات.
`$data.current.elapsed`	إدخال المدة الأساسية المسجلة، بالثواني.
`$data.current.recording`	إدخال حالة السجل الأساسية، وإرجاع قيمة منطقية.
`$data.current.coolant`	يتم إدخال OBD وإرجاع `{ value, unit }` أو `null` بعد ربط معلمات السيارة.
`$data.current.limit`	يقوم الإدخال الرقمي بإرجاع رقم مباشرة.
`$data.current.label`	يقوم إدخال النص بإرجاع سلسلة مباشرة.
`$data.current.showUnit`	قم بتبديل الإدخال وإرجاع قيمة منطقية مباشرة.
`$data.current.style`	حدد عنصرًا وقم بإرجاع السلسلة المحددة.

يغطي $data.history آخر 30 ثانية من الرحلة الحالية، مرتبة من القديم إلى الجديد، ويتوافق حقل أخذ العينات مع current؛ يستخدم الإدخال الثابت التكوين الحالي. قد تكون النافذة فارغة أو تحتوي على اختبارات مفقودة. قد تكون قيمة OBD عبارة عن خريطة حرفية، ويجب التحقق من النوع أولاً. الصفر له معنى مختلف عن null. المدخلات الكاملة والوحدات وقواعد التاريخ.

$env: بيئة العرض

يصف $env منطقة العرض التي يوجد بها الجهاز الحالي. بعد تغيير حجم البطاقة، أو تبديل السمات، أو إدخال HUD، يوفر التطبيق بيئة محدثة. يجب وضع الحسابات التي تعتمد على هذه القيم في main().

مجال	المعنى والاستخدام
`$env.width`、`$env.height`	العرض والارتفاع المتوفران للأداة الحالية موجودان في نقاط الشاشة. يمكن استخدامه لحساب حجم الخط أو القطر أو إحداثيات نقطة النهاية.
`$env.foreground`、`$env.accent`	يمكن تمرير لون النص ولون التمييز للموضوع الحالي مباشرة إلى `color`، `stroke`، `background` وسمات الألوان الأخرى.
`$env.dark`	ما إذا كان سيتم استخدام المظهر الداكن أم لا، فإن الكتابة تكون منطقية.
`$env.mode`	وضع العرض، القيمة هي `'instruments'` أو `'hud'`.
`$env.speedUnit`	وحدة عرض السرعة الحالية، القيمة هي `'km/h'` أو `'mph'`. عندما يكون للقراءة وحدة خاصة بها، يتم استخدام `unit` للقراءة أولاً.
`$env.language`	معرف اللغة الحالي للتطبيق، مثل `'zh-Hans'`.
`$env.reduceMotion`	سواء كان النظام قد تم تمكين التأثيرات الديناميكية المخفضة، فيمكنك ضبط تكرار الرسوم المتحركة وفقًا لذلك.
`$env.obdDevice`	`{ id, name }` للجهاز المتصل حاليًا، أو `null` إذا لم يكن هناك جهاز جاهز.

على سبيل المثال، استخدم Math.min($env.width, $env.height) للحصول على الحد الأقصى للقطر المناسب لوضع دائرة مثالية، واستخدم $env.foreground لجعل النص يتبع السمة. تعريف بيئة العرض الكاملة.

مثال: العمل مع البيانات وبيئات العرض

حدد السرعة في إعدادات العداد. يقرأ البرنامج النصي التالي السرعة الحالية، ويحسب حجم الخط استنادًا إلى عرض البطاقة وارتفاعها، ويستخدم ألوان السمات، ويعرض الوحدات التي توفرها القراءة. يتم عرض خط أفقي عندما تكون السرعة مفقودة؛ يتم عرض صفر صالح كـ 0.

function main() {
  const speed = $data.current.speed;
  const fontSize = Math.min(64, $env.width * 0.25, $env.height * 0.5);

  return (
    <VStack spacing={6}>
      <Text fontSize={fontSize} color={$env.foreground}>
        {speed?.value == null ? '—' : Math.round(speed.value)}
      </Text>
      <Text fontSize={14} color={$env.accent}>
        {speed?.unit ?? $env.speedUnit}
      </Text>
    </VStack>
  );
}

عند تحديث البيانات، سيتم استخدام السرعة الجديدة للمكالمة التالية؛ عندما يتغير حجم البطاقة أو السمة، سيستخدم حجم الخط ولونه قيم البيئة الجديدة. إذا كنت بحاجة إلى تجميع قيم الذروة والحالات الأخرى في نفس الرحلة، فيمكنك الاستمرار في استخدام $sessionStorage؛ إذا كنت بحاجة إلى التحقق من الإدخال الفعلي، فيمكنك استخدام console.log('speed', speed) لإخراج السجل أثناء تصحيح الأخطاء.

تحديث الشاشة

عندما يتغير الإدخال الحالي أو تعريف الإدخال أو بيئة العرض، يوفر CapDrive أحدث $data و$env، وينفذ الملف بأكمله في النطاق المحلي الجديد، ثم يستدعي main() المحدد هذه المرة. يتم أيضًا إعادة تنفيذ حسابات المستوى الأعلى، ولا يتم الاحتفاظ بالمتغيرات العادية عبر الأوقات. يتم تخطي المدخلات المتطابقة؛ يتم الاحتفاظ فقط بأحدث المدخلات المعلقة قيد المعالجة. صيانة نافذة التاريخ وتغييرات وقت العينة الداخلية وحدها لا تؤدي إلى التنفيذ؛ تغييرات إدخال الوقت المحددة بشكل صريح تفعل ذلك.

لا يوجد تردد ثابت للنصوص البرمجية؛ تعتمد التحديثات الفعلية على وقت الإدخال والمعالجة. استخدم $sessionStorage لحالة الامتداد؛ استخدم animations لانتقال السمة، والذي يتم تنفيذه بشكل مستقل عن طريق نهاية الرسم. يجب إكمال main() بشكل متزامن لتجنب الحلقات المستمرة أو حظر الانتظار.

واجهات التشغيل ذات الصلة

main(): إدخال البرنامج النصي. اقرأ هذا الإدخال وقم بإرجاع View أو المصفوفة أو المحتوى الفارغ بشكل متزامن ليتم رسمه.
animations: قم بتعيين سلوكيات الانتقال مثل المدة والمنحنى والتكرار لتغييرات سمات View.
Color / Gradient: إنشاء اللون، HDR اللون، التدرج الخطي، التدرج الشعاعي، والتدرج الزاوي.
استيراد ومشاركة: فهم التكوين والبرامج النصية والموارد وطرق التصدير لحزمة الأداة.

ارسم المكونات

قم بتنظيم الشاشات من خلال الحاويات ووضع طرق عرض النصوص والرسومات والبيانات فيها. يسرد ما يلي كافة المدمج في View حسب الغرض؛ تشرح كل صفحة مكونة الاستخدام والخصائص والسلوك الافتراضي وأمثلة المجموعة.

محتوى

عرض القراءات والوحدات والأيقونات والصور، أو استخدام منطقة محتوى المقياس بعنوان.

Text

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

Symbol

استخدم SF Symbols لرسم أيقونات النظام، مثل عداد السرعة ومقياس الحرارة. يمكن ضبط حجم خط الرمز ووزن الخط وطريقة التلوين. يعتمد توفر الرمز المحدد على نظام الجهاز.

Image

يعرض صورة من مصدر مقياس، مثل شعار، أو خلفية مزخرفة، أو نسيج متجانب. source استخدم اسم المورد لتعيين أسلوب القياس أو الاقتصاص أو التكرار للأحجام المتوفرة.

CardContent

يوفر بنية الأداة مع العنوان والمحتوى الصحيح والنص الأساسي. سيحصل النص renderer على contentSize مطروحًا منه العنوان والهوامش، والتي يمكن استخدامها لترتيب الأشكال أو الرسوم البيانية أو المخططات.

تَخطِيط

قم بترتيب View المتعددة، وتخصيص المساحة المتبقية، وإنشاء تخطيطات أفقية ورأسية ومكدسة ومقياس حجمها.

HStack

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

VStack

قم بترتيب الترجمات View من الأعلى إلى الأسفل، بما يتناسب مع المجموعة الرأسية للعناوين والأرقام الرئيسية والوحدات. يقوم spacing بتعيين التباعد المجاور، ويقوم alignment بتعيين المحاذاة اليسرى واليمنى داخل هذا العمود.

ZStack

قم بتجميع عدة View في نفس المنطقة، وهي مناسبة للقراءات الخلفية والمقياس والمركز. يتم رسم الأطفال View بشكل تسلسلي، ويقوم alignment بتعيين موضع المحاذاة المشترك الخاص بهم داخل الحاوية.

Spacer

قم بتخصيص المساحة المتبقية في Stack لدفع المحتوى على كلا الجانبين أو حجز مسافة مرنة للمحتوى. minLength يضبط الحد الأدنى للطول، ويمكن لـ width أو height تحديد الحجم في الاتجاه المقابل.

RadialLayout

توزيع المقاييس أو الأرقام أو الرموز حول دائرة. يتحكم radius في المسافة من المركز إلى مركز تخطيط View، ويتحكم startAngle وsweepAngle في نطاق التوزيع.

RepeatedLayout

يكرر بشكل دوري نمطًا في نافذة الاقتصاص، وهو مناسب لتحريك المقاييس والبوصلات بشكل مستمر. يقوم period بتعيين الفاصل الزمني للتكرار، ويحدد value وanchor مكان محاذاة القيمة الحالية.

الرسومات

ارسم علامات التجزئة والتقدمات والخطوط والمخططات التفصيلية المخصصة، وتحكم في المظهر باستخدام خصائص مثل الخلفية والحدود والزاوية.

Rectangle

يرسم مستطيلاً بزوايا دائرية اختيارية لاستخدامه مع الخلفيات وأشرطة التقدم والحدود. background يملأ الجزء الداخلي، stroke حدود، lineWidth و strokePosition يتحكم في عرض وموضع الحد.

Circle

يرسم دائرة أو قوسًا مثاليًا ضمن المساحة المتاحة، وهو مناسب للتقدم الدائري والمقاييس المترية. يأخذ القطر القيمة الأصغر للعرض والوسط. يتحكم startAngle وsweepAngle في نطاق العرض. عندما يتم إغلاق الدائرة بأكملها، يمكن ملء الخلفية.

Ellipse

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

Arc

ارسم قوسًا بيضاويًا وفقًا لزاوية البداية والزاوية الشاملة، وهو مناسب لأقواس المقياس وعرض التقدم. يتم تحديد الحدود حسب العرض والارتفاع. يمكن تكوين العرض ونقطة النهاية وموضع الحد، ويُسمح للخلفية بالملء عند إغلاقها بالكامل.

Line

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

Polyline

ارسم خطًا متعدد الخطوط من خلال توصيل مجموعة من النقاط بالتسلسل. closed يمكنه توصيل النقطة الأخيرة والنقطة الأولى لتكوين محيط مغلق، ويسمح بالملء؛ تستخدم الإحداثيات عدد النقاط الموجودة في View الحالي.

Path

أنشئ مسارات باستخدام أوامر مثل النقل والخط والرباعي والمكعب والقوس والإغلاق. مناسب لتخصيص المؤشرات والمنحنيات والمخططات التفصيلية المدمجة وتعيين قواعد التعبئة والحدود.

تركيبات والمواد

قم بتطبيق التأثيرات العالمية على المحتوى المدمج، أو قم برسم سطح مادة زجاجية بلوري.

Group

قم بدمج عدة View في الكل، مع تطبيق الشفافية أو التدوير أو المؤثرات الخاصة الأخرى بشكل موحد. يتبع الطفل View قواعد ترتيب الحاوية الخارجية، ويتم تطبيق التأثيرات الخاصة على مجموعة النتائج المركبة بأكملها.

Material

ارسم سطح مادة الزجاج المصنفر، والتي يمكن أن تتداخل مع النص والرسومات لتكوين منطقة محتوى. type يدعم حاليا التجميد، style يتحكم في سمك المادة؛ يعتمد التأثير المرئي على المحتوى الذي يقف خلفه.

الرسوم البيانية والخرائط

قم برسم سلسلة البيانات في منحنيات ورسوم بيانية، أو اعرض المواقع والمسارات.

LineChart

قم برسم سلسلة البيانات بقيم x/y الفعلية كمنحنى. مناسبة لاتجاهات مثل السرعة والوقت، وتدعم نطاقات الإحداثيات والمحاور والتسميات؛ سيؤدي فقدان قيم y إلى كسر أجزاء الخط.

BarChart

ارسم كل عنصر بيانات كشريط، مناسب لمقارنة القيم الفئوية. يمكن ترتيبه أفقيًا أو رأسيًا، وتعيين النطاقات الرقمية، وتسميات الفئات، والتسميات الرقمية، ويدعم القيم الإيجابية والسلبية.

Map

عرض الخرائط والمواقع والطرق داخل العداد. يمكن ضبط مركز الكاميرا والاتجاه والتكبير ونمط الخريطة باستخدام path لتوفير نقاط المسار؛ يتطلب تتبع موقع المستخدم بيانات تحديد المواقع الصحيحة.

نوع الملفات والإعلان

تحدد الأنواع الشائعة الهياكل بشكل مركزي، مثل الأبعاد والهوامش والتحويلات والحدود والرسوم المتحركة وبيانات المخطط. يوفر المحرر تلميحات للكتابة لنفس واجهة برمجة التطبيقات (API)، ويمكن أيضًا تنزيل ملفات التصريح لاستخدامها بواسطة المحررين الخارجيين.

الأنواع المشتركة

capdrive.d.ts