שם האפליקציה

# מדריך לפיתוח אפליקציות ללוח הבקרה של Home Assistant > **הוראה ל-AI שקורא את הקובץ הזה:** המשתמש העלה לך מדריך זה כדי שתכתוב עבורו "אפליקציה" ללוח הבקרה הביתי שלו. > **התוצר שלך הוא קובץ HTML אחד, שלם ומוכן להתקנה.** המשתמש גורר אותו אל מסך הבית של הדשבורד והוא מותקן אוטומטית. > עקוב אחרי המדריך במדויק: מבנה הקובץ, הרשאות, ה-API וההתאמה הגרפית. אל תמציא פונקציות או מחלקות שלא מופיעות כאן. > כתוב את כל הטקסטים שהמשתמש רואה **בעברית**, ובכיוון **מימין לשמאל**. > **קטלוג רכיבי העיצוב עם הקוד המדויק של כל רכיב נמצא בסעיף 6. העתק ממנו את המבנה ואל תמציא עיצוב משלך.** > אם הבקשה לא ברורה (איזה מכשיר? איזו פעולה?), שאל שאלה קצרה אחת לפני הכתיבה. אחרת פשוט כתוב. **שלושה עקרונות שאסור לעבור עליהם:** 1. **עיצוב: רק מהערכה.** משתמשים אך ורק במחלקות `ha-*` ובמשתני ה-CSS (סעיף 6). אין צבעים קבועים, אין גופן משלך, אין סגנון מומצא. אם חסר רכיב, מרכיבים אותו מהמשתנים (`--sf`, `--ct`, `--r-tile`...), לא ממציאים ערכים. 2. **הרשאות: מינימום הכרחי.** מגדירים בבלוק `ha-app` רק מה שהאפליקציה צריכה. 3. **קובץ אחד שלם.** מתחיל ב-`` ונסגר ב-``, בלי קוד חסר. --- ## 1. איך זה עובד - אפליקציה = **קובץ HTML בודד** (HTML + CSS + JavaScript, הכול בתוכו). אין קבצים נוספים. - המשתמש גורר את הקובץ לדשבורד ← חלון אישור עם ההרשאות והערות על הקובץ ← "התקנה" ← אייקון במסך הבית ובמגירת האפליקציות, והאפליקציה נפתחת. - האפליקציה נפתחת **במסך מלא**. הדשבורד מצייר בעצמו שורת כותרת עם כפתור חזרה ושם האפליקציה. - האפליקציה רצה בתוך **iframe מבודד**. היא לא רואה את הטוקן של Home Assistant ולא את שאר הדשבורד. כל התקשורת עוברת דרך אובייקט אחד, **`HA`** (מוזרק אוטומטית). - הדשבורד מזריק לאפליקציה **ערכת עיצוב מלאה** (משתני צבע, מדדים ומחלקות CSS), כך שהיא נראית כמו שאר הדשבורד, בבהיר ובכהה. - **האפליקציה משתלבת בכל המערכת (הקשר דו-כיווני):** - הדשבורד נותן לאפליקציה את העיצוב, הנתונים החיים והאחסון. - האפליקציה נותנת לדשבורד: **ווידג'ט משלה** (תוכן שהיא מחשבת, והמשתמש בוחר מה יוצג בו), **תזמונים** (מופיעים במסך התזמונים, רצים אוטומטית), **שגרות** (כפתורים במסך הבית ובקיצורים), **ווידג'טים** למסך הבית, **התראות**, וכניסה למגירת האפליקציות, לחיפוש ולאפליקציות האחרונות. - כל הפעולות שהאפליקציה מבצעת נרשמות בהיסטוריית הפעולות בשם האפליקציה, והאפליקציות נכללות בגיבוי הדשבורד. - עדכון: גוררים קובץ עם אותו `id`. (כדאי להעלות את `version`.) --- ## 2. שלד חובה של הקובץ ```html שם האפליקציה

``` --- ## 3. בלוק ההגדרות (`ha-app`) | שדה | חובה | הסבר | |---|---|---| | `id` | כן | מזהה ייחודי: אותיות אנגליות קטנות, ספרות, נקודה, מקף או קו תחתון. 2–48 תווים. אותו id = עדכון. | | `name` | כן | שם מתחת לאייקון (עברית, קצר: עד ~14 תווים). | | `version` | לא | למשל `"1.2.0"`. | | `description` | לא | עד 160 תווים. מוצג בחלון ההתקנה. | | `icon` | לא | שם אייקון מהרשימה למטה, **או** path בסגנון קו 24×24. ברירת מחדל `scene`. | | `color` | לא | צבע האייקון במסך הבית, `#rrggbb`. מומלץ צבע סמנטי מהטבלה בסעיף 6. | | `entities` | לא | **קריאה:** תבניות של מזהי ישויות שהאפליקציה רואה. בלי זה היא לא רואה שום ישות. | | `services` | לא | **שליטה:** תבניות של `domain.service` שמותר להפעיל. | | `ws` | לא | סוגי בקשות מתקדמות ל-HA (`HA.request`), למשל `"history/history_during_period"`. | | `network` | לא | `true` = גישה לאינטרנט. ברירת מחדל `false`. | | `schedules` | לא | `true` = מותר ליצור תזמונים (סעיף 7). | | `routines` | לא | `true` = מותר ליצור שגרות (סעיף 7). | | `notifications` | לא | `true` = מותר לשלוח התראות (סעיף 7). | | `widgets` | לא | מערך של עד 6 ווידג'טים למסך הבית (סעיף 7). | **תבניות (glob):** `*` = כל רצף תווים. `"light.*"`, `"sensor.*temp*"`, `"vacuum.robot"`, `"*"`. **עקרון הרשאות מינימליות.** המשתמש רואה את כל ההרשאות בחלון ההתקנה. `"*"` ב-`entities`/`services` ו-`network:true` מוצגים כאזהרה, השתמש בהם רק כשבאמת צריך. **אכיפה:** כל קריאה שחורגת מההרשאות נדחית. גם תזמונים, שגרות וכפתורי ווידג'ט שהאפליקציה יוצרת נבדקים מול ההרשאות, גם בזמן יצירתם וגם בזמן ההרצה. פעולות לפי `area_id` / `device_id` / `label_id` נחסמות אלא אם `entities` הוא `"*"`. **שמות אייקונים:** `home light climate cover media_player switch sensor lock play pause next prev search cog ha vac hist bolt pen fwd clock fan scene warn bell door battery dnd chev x zin zout fit expand shrink stop locate wifi wifioff more rooms zone pin center tune trash` אייקון מותאם: path בסגנון קו, למשל `"M12 3v18M3 12h18"`. למילוי: להתחיל ב-`F:`. --- ## 4. הסביבה: מה מותר ומה חסום | ❌ לא עובד | ✅ במקום זה | |---|---| | `localStorage`, `sessionStorage`, `indexedDB`, cookies | `HA.storage.get / set / remove` | | `fetch` / XHR / WebSocket (חסום) | `HA.call`, `HA.request`. לאינטרנט: `"network": true` | | ספריות, פונטים, תמונות מכתובת חיצונית | הכול בתוך הקובץ (SVG מוטבע או `data:`). עם `network:true`: סקריפטים מ-`cdnjs.cloudflare.com` ו-`cdn.jsdelivr.net` בלבד. | | `

` | כפתורים ו-`addEventListener` | | `window.open`, `top`, `parent` | `HA.close()`, `HA.openEntity()`, `HA.openPage()` | | קבצים נוספים | קובץ אחד (עד 3MB) | מותר: `alert/confirm/prompt`, `setTimeout/setInterval`, canvas, SVG, אנימציות CSS, Web Audio. אחסון `HA.storage` עד 256KB (JSON). **בדיקת קובץ בהתקנה:** הדשבורד סורק את הקובץ ומציג "הערות על הקובץ" על צבעים קבועים, `font-family`, `left/right`, `localStorage`, `fetch` בלי `network`, ``, ו-`HA.ready` חסר. **כתוב קובץ שלא מקבל אף הערה.** --- ## 5. ה-API: אובייקט `HA` ### מצב ושליטה ```js HA.ready(fn) // fn() פעם אחת כשהנתונים הגיעו. כל הקוד שלך מתחיל מכאן. HA.states // אובייקט חי: { "light.bed": {entity_id, state, attributes, last_changed, last_updated} } // רק ישויות שתואמות ל-entities. HA.get("light.bed") // מצב של ישות אחת, או undefined HA.list("light.") // מערך כל הישויות שמתחילות ב"light." (בלי פרמטר: הכול) HA.onChange((id, newState, oldState) => {...}) // newState = null אם הישות נמחקה HA.call("light", "turn_on", { entity_id: "light.bed", brightness_pct: 60 }) // Promise. נדחה עם Error.message בעברית אם אין הרשאה / אין חיבור / HA החזיר שגיאה. HA.request("history/history_during_period", {...}) // בקשת WebSocket גולמית, רק סוגים שהוגדרו ב-"ws" ``` ### מידע נלווה ```js HA.name(id) // שם ידידותי או המזהה HA.area(id) // שם החדר בעברית או "" HA.areas // { area_id: "שם חדר" } HA.info // { id, name, version } HA.demo // true במצב הדגמה HA.connected // true כשיש חיבור (או הדגמה) ``` ### ממשק וניווט ```js HA.toast("הפעולה בוצעה") // הודעה קצרה בתחתית המסך HA.setTitle("כותרת") // משנה את הכותרת בשורה העליונה HA.close() // סוגר את האפליקציה HA.openEntity("light.bed") // סוגר את האפליקציה ופותח את חלון המכשיר המקורי של הדשבורד (נדרשת הרשאת קריאה לישות) HA.openPage("sched") // סוגר ופותח עמוד של הדשבורד: home | sched | lights | climate | covers | media | switches | sensors HA.icon("light", {size: 20}) // מחזיר מחרוזת SVG HA.theme / HA.onTheme(fn) // { dark, vars }. בדרך כלל מספיקים משתני ה-CSS ``` ### ווידג'ט שהאפליקציה מחשבת בעצמה ```js HA.mode // "app" (מסך האפליקציה) או "widget" (הקובץ רץ ברקע כדי לחשב ווידג'ט) HA.widgets.define("id", ctx => "") // מחזיר HTML לווידג'ט. ראה סעיף 7 HA.widgets.onAction("id", (action, value, ctx) => {...}) // לחיצה על אלמנט עם data-xa HA.widgets.refresh() // מבקש חישוב מחדש ``` ### אחסון ```js HA.storage.get("key", defaultValue) // סינכרוני HA.storage.set("key", anyJsonValue) HA.storage.remove("key") ``` פרטי לאפליקציה, נשמר בדפדפן, נמחק עם הסרת האפליקציה, נכלל בגיבוי. --- ## 6. התאמה גרפית (חובה, בלי חריגות) המטרה: האפליקציה זהה בעיצוב לדשבורד. **הכול מוזרק אוטומטית, אין צורך להעתיק CSS.** ### כלל ברזל > מרכיבים כל מסך **רק** מהמחלקות `ha-*` שבטבלאות. מחלקה שלא מופיעה כאן לא קיימת. צבע, רדיוס או ריווח שלא מופיעים כאן לא קיימים. בקובץ ה-`