lovelace card mod

مود البطاقة 3

يتيح لك تطبيق أنماط CSS على عناصر مختلفة في الواجهة الأمامية لـ Home Assistant.

التثبيت

قم بالتثبيت باستخدام HACS أو راجع هذا الدليل.

تحسينات في الأداء

على الرغم من أنه يمكن تثبيت Card-mod كمورد lovelace، إلا أن بعض الوظائف ستستفيد بشكل كبير من تثبيته كوحدة واجهة أمامية بدلاً من ذلك.

للقيام بذلك، أضف ما يلي إلى ملف configuration.yaml الخاص بك وأعد تشغيل Home Assistant:

 frontend :
  extra_module_url :
    - /local/card-mod.js

ستحتاج إلى ضبط هذا المسار وفقًا للمكان الذي قمت بتثبيت card-mod.js فيه. إذا قمت بالتثبيت من خلال HACS، فمن المحتمل أن يكون هذا /hacsfiles/lovelace-card-mod/card-mod.js .

يمكن الاحتفاظ بأي تعريفات موارد تمت إضافتها تلقائيًا بواسطة HACS كما هي حتى بعد إضافة extra_module_url .

بداية سريعة

• افتح بطاقتك في محرر واجهة المستخدم الرسومية
• انقر فوق الزر "إظهار محرر الكود" في الأسفل
• أضف ما يلي إلى أسفل الكود:

 card_mod :
  style : |
    ha-card {
      color: red;
    }

من المفترض أن تشاهد نص البطاقة يتحول إلى اللون الأحمر أثناء الكتابة.
يجب أن تشاهد أيضًا أيقونة فرشاة صغيرة تظهر بالقرب من زر "إظهار المحرر المرئي". يشير هذا إلى أن هذه البطاقة تحتوي على كود تعديل البطاقة والذي لن يظهر في المحرر المرئي.

الاستخدام

بطاقات التصميم

يتم تصميم البطاقات بإضافة ما يلي إلى تكوين البطاقة:

 card_mod :
  style : <STYLES>

إذا كان النموذج الأبسط، فإن <STYLES> عبارة عن سلسلة من CSS سيتم حقنها في عنصر <ha-card> في البطاقة.

ملاحظة: يعمل Card-Mod فقط على البطاقات التي تحتوي على عنصر ha-card. يتضمن هذا تقريبًا كل البطاقات التي يمكن رؤيتها ، ولكن ليس على سبيل المثال conditional ، entity_filter ، vertical-stack ، horizontal-stack ، grid .

لاحظ، على الرغم من أن هذه البطاقات غالبًا ما تتضمن بطاقات أخرى، والتي يمكن أن يعمل عليها تعديل البطاقة.
راجع الدليل الخاص بكل بطاقة لمعرفة كيفية تحديد المعلمات للبطاقة (البطاقات) المضمنة.

العنصر السفلي الذي يمكن تصميمه هو <ha-card> .

لقطة شاشة لعنصر ha-card في مفتش Chrome DOM

نصيحة: تستخدم سمات Home Assistant متغيرات CSS. يمكن ضبطهما واستخدامهما في وضع البطاقة - مسبوقين بشرطتين:

 card_mod :
  style : |
    ha-card {
      --ha-card-background: teal;
      color: var(--primary-color);
    }

كيانات التصميم والشارات والعناصر

في entities وبطاقات glance ، يمكن أن يكون لكل كيان خيارات. يمكن تصميم هذه العناصر بشكل فردي عن طريق إضافة معلمة card_mod إلى تكوين الكيان.

في تلك الحالات، يتم إدخال الأنماط في ShadowRoot، وبالتالي يتم الوصول إلى العنصر السفلي من خلال :host .

ينطبق هذا أيضًا على عرض الشارات والعناصر الموجودة في بطاقات picture-elements .

 type : entities
entities :
  - entity : light.bed_light
    card_mod :
      style : |
        :host {
          color: red;
          }
  - entity : light.ceiling_lights
    card_mod :
      style : |
        :host {
          color: green;
        }
  - entity : light.kitchen_lights
    card_mod :
      style : |
        :host {
          color: blue;
        }

تغيير الرموز

بعد تثبيت Card-mod، فإن عنصر <ha-icon> - المستخدم على سبيل المثال بواسطة entities glance والعديد من البطاقات الأخرى - سيضبط الرمز الخاص به على القيمة الموجودة في متغير CSS --card-mod-icon (إذا كان موجودًا).

سيقوم أيضًا بتعيين لون الرمز على القيمة الموجودة في متغير CSS --card-mod-icon-color إذا كان موجودًا. يتجاهل هذا حالة الكيان، لكنه سيظل خافتًا ما لم تقم أيضًا بتعيين --card-mod-icon-dim على none .

- entity : light.bed_light
  card_mod :
    style : |
      :host {
        --card-mod-icon: mdi:bed;
      }

قوالب

قد تحتوي جميع الأنماط على قوالب jinja2 التي ستتم معالجتها بواسطة الواجهة الخلفية لـ Home Assistant.

يوفر Card-mod أيضًا المتغيرات التالية للقوالب:

• config - التكوين الكامل للبطاقة أو الكيان أو الشارة - (قد يكون config.entity ذا أهمية خاصة)
• user - اسم المستخدم الذي قام بتسجيل الدخول حاليًا
• browser - browser_id المتصفح الخاص بالمتصفح الخاص بك، إذا كان browser_mod مثبتًا لديك
• hash - أي شيء يأتي بعد # في عنوان URL الحالي (يؤخذ هذا في الاعتبار عند التحميل الأول فقط. ولا يتم تحديثه ديناميكيًا)

التنقل في DOM

يستخدم Home Assistant على نطاق واسع ما يسمى Shadow DOM. يسمح هذا بإعادة استخدام المكونات بسهولة (مثل ha-card أو ha-icon ) ولكنه يسبب بعض المشاكل عند محاولة تطبيق أنماط CSS على الأشياء.

عند استكشاف البطاقات في أداة فحص العناصر في متصفحك، ربما تكون قد صادفت سطرًا يقول شيئًا مثل " #shadow-root (open) " (يعتمد بالضبط ما يقوله على متصفحك) ولاحظت أن العناصر الموجودة بداخله لا ترث الأنماط من الخارج.

من أجل تصميم العناصر داخل جذر الظل، سوف تحتاج إلى إنشاء style: قاموس بدلاً من سلسلة.

لكل إدخال في القاموس سيتم استخدام المفتاح لتحديد عنصر واحد أو عدة عناصر من خلال وظيفة querySelector() المعدلة. سيتم بعد ذلك حقن قيمة الإدخال في تلك العناصر.

ملاحظة: ستستبدل الدالة querySelector() ‎ المعدلة علامة الدولار ( $ ) بـ #shadow-root في المحدد.

هذه العملية متكررة، لذا قد تكون القيمة أيضًا قاموسًا. سيحدد مفتاح " . " (نقطة) العنصر الحالي.

مثال:

دعونا نغير لون جميع عناوين المستوى الثالث ( ### like this ) في بطاقة تخفيض السعر، ونغير أيضًا خلفيتها.

إذا نظرنا إلى البطاقة في عنصر مفتش الكروم، فإنها تبدو كما يلي:

عنصر <ha-card> هو الأساس، ومن هناك نرى أننا بحاجة إلى المرور عبر #shadow-root واحد للوصول إلى <h3> . هذا #shadow-root موجود داخل عنصر <ha-markdown> ، لذلك سيكون محددنا:

 ha-markdown$

والتي سوف تجد أول عنصر <ha-markdown> ثم كل #shadow-root s بداخله.

لإضافة الخلفية إلى <ha-card> ، نريد تطبيق الأنماط على العنصر الأساسي مباشرةً، والذي يحتوي على المفتاح

 .

وهذا يعطي النمط النهائي:

 card_mod :
  style :
    ha-markdown$ : |
      h3 {
        color: purple;
      }
    . : |
      ha-card {
        background: teal;
      } 

ملاحظة: ستبحث سلسلة المحدد في قائمة الانتظار عن عنصر واحد في كل مرة مفصولاً بمسافات أو " $ ".
لكل خطوة، سيتم تحديد المطابقة الأولى فقط.
ولكن بالنسبة للمحدد النهائي للسلسلة (أي في مفتاح قاموس معين) سيتم تحديد جميع العناصر المطابقة. تعتبر السلاسل التي تنتهي بـ $ حالة خاصة للراحة، حيث يتم تحديد جذور الظل لجميع العناصر.

على سبيل المثال، سيقوم ما يلي بتحديد عناصر div في العلامة الأولى على بطاقة الخريطة:

 "ha-map $ ha-entity-marker $ div" : |

لكن ما يلي سيحدد عناصر div في جميع علامات الخريطة على بطاقة الخريطة (لأننا ننهي المفتاح الأول في محدد ha-entity-marker $ ونبدأ بحثًا جديدًا داخل كل نتيجة لـ div ):

 " ha-map $ ha-entity-marker $ " :
  "div" : |

الملاحظة 2: متابعة للملاحظة أعلاه؛ نظرًا للمستوى العالي لتحسين ترتيب التحميل المستخدم في Home Assistant، فليس من المضمون وجود عناصر ha-entity-marker في الوقت الذي يبحث فيه Card-Mod عنها. إذا كسرت السلسلة مرة أخرى:

 " ha-map $ " :
  " ha-entity-marker $ " :
    "div" : |

بعد ذلك، سيتمكن Card-Mod من إعادة محاولة البحث من نقطة ha-map $ في وقت لاحق، مما قد يؤدي إلى نتائج أكثر استقرارًا.

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

نصائح التصحيح

قد يكون التنقل في DOM أمرًا صعبًا في المرات القليلة الأولى، ولكنك ستتقنه في النهاية.

ولمساعدتك، يمكنك استخدام Element Inspector في متصفحك لمعرفة الخطوات التي يتخذها Card-Mod.

• افتح أداة فحص العناصر وابحث عن العنصر الأساسي (على سبيل المثال <ha-card> ). يجب أن يحتوي هذا على عنصر <card-mod> سواء قمت بتحديد نمط أم لا.
• تأكد من تحديد عنصر <card-mod> .
• افتح وحدة تحكم المتصفحات (في Chrome يمكنك الضغط على Esc لفتح وحدة التحكم والمفتش في نفس الوقت).
• اكتب $0.card_mod_input ثم اضغط على زر الإدخال.
  هذه هي معلومات النمط التي تم تقديمها لتلك الخطوة من السلسلة. إذا كانت هذه سلسلة، فأنت في نهاية السلسلة. إذا كان كائنًا، فيمكنك الانتقال إلى الخطوة التالية.
• اكتب $0.card_mod_children واضغط على زر الإدخال.
  هذه مجموعة من عناصر <card-mod> في الخطوة التالية لأي سلسلة. سيؤدي النقر فوق "card-mod" في value: من العناصر المحددة إلى نقلك إلى عنصر <card-mod> في المفتش، ويمكنك الاستمرار في فحص بقية السلسلة.
• يمكنك أيضًا استخدام $0.card_mod_parent للعثور على الأصل لأي عنصر <card-mod> في السلسلة.

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

 card_mod :
  debug : true

بطاقات التصميم بدون عنصر <ha-card>

لا يزال من الممكن تصميم البطاقات التي لا تحتوي على <ha-element> باستخدام بطاقة custom:mod-card المتوفرة.

وهذا ضروري فقط في حالات قليلة جدًا ، ومن المحتمل أن يؤدي إلى مشاكل أكثر مما يحل.

على الأرجح أن بطاقتك تحتوي على بطاقة أخرى، وفي هذه الحالة هي البطاقة التي يجب عليك تطبيق الأنماط عليها.

كفى تحذيرات.

أنا أعرف ما أفعله

 type : custom:mod-card
card :
  type : vertical-stack # for example
  ...
card_mod :
  style : |
    ha-card {
      ...
    }

ستقوم بطاقة التعديل بإنشاء عنصر <ha-card> - مع إزالة الخلفية والحدود - ووضع بطاقتك بداخله.

المزيد من الأمثلة

جميع حالات الاختبار الخاصة بي متوفرة في دليل test/views .

يمكنك عرضًا توضيحيًا في عامل الإرساء بالانتقال إلى دليل test وتشغيل:

 docker-compose up

ثم انتقل إلى http://localhost:8125 وقم بتسجيل الدخول باستخدام اسم المستخدم dev وكلمة المرور dev .

أو يمكنك استخدام vscode devcontainer وتشغيل المهمة " Run hass ".

المواضيع

للحصول على إرشادات حول كيفية تطوير سمة تعديل البطاقة، راجع README-themes.md.

تطوير

لإضافة إمكانات تصميم تعديلات البطاقة إلى بطاقتك المخصصة، راجع README-developers.md.

---