מבוא
בדף הזה מפורטות שיטות מומלצות לקריאה לפונקציות ולגישה למאפיינים ב-Blockly. העקרונות האלה חלים על יצירת יישומי פלאגין ל-Blockly או לשילוב של Blockly באפליקציה עצמאית.
סיווג משנה והרחבה
ב-Blockly יש כמה פרדיגמות להוספת פונקציונליות, ביניהן:
- מחלקות משנה (למשל, יצירת כלי חדש לרינדור)
- תערובות (למשל, הוספת תוסף בלוק או מוטציה)
- הגדרות חסימה (למשל, הגדרות חסימה של נוהל)
למטרות המסמך הזה, כל שלושת המקרים מקבילים לסיווג משנה.
הזרקת מחלקות משנה
אנחנו תומכים בהחלפת מחלקות מסוימות באמצעות השיטה Blockly.inject. מחלקות המשנה האלה צריכות להרחיב את מחלקת הבסיס או להטמיע את הממשק התואם שלהן.
אפשר להעביר את המחלקה המשנית לשיטת ההזרקה.
Blockly.inject('blocklyDiv', {
plugins: {
'metricsManager': CustomMetricsManagerClass
}
}
לחלופין, תוכלו לרשום את הכיתה באמצעות Blockly.registry ולהשתמש בשם של רשם הרישום כדי להחדיר את המחלקה. זו אפשרות שימושית אם אתם מאחסנים את אפשרויות ההזרקה כ-JSON טהור.
Blockly.registry.register(Blockly.registry.Type.METRICS_MANAGER, 'YOUR_NAME', SubClass);
Blockly.inject('blocklyDiv', {
plugins: {
'metricsManager': 'YOUR_NAME'
}
}
אפשר להחליף את המחלקות הבאות:
| שם הרישום | ממשק/מחלקת בסיס |
|---|---|
blockDragger |
Blockly.IBlockDragger |
connectionChecker |
Blockly.IConnectionChecker |
connectionPreviewer |
Blockly.IConnectionPreviewer |
flyoutsVerticalToolbox |
Blockly.IFlyout |
flyoutsHorizontalToolbox |
Blockly.IFlyout |
metricsManager |
Blockly.IMetricsManager |
renderer |
Blockly.blockRendering.Renderer |
toolbox |
Blockly.IToolbox |
מידע נוסף על השימוש בממשקים זמין בקטע 'ממשקים' במסמכי התיעוד.
ראות
אנחנו משתמשים במגבילי גישה של TypeScript
כדי לסמן את החשיפה בספריית הליבה בתור public, private או protected.
ייתכן שלחלק מהמאפיינים יהיו הערות עם @internal בהערות TsDoc שלהם.
כל המאפיינים public ו-protected מתועדים בקטע References באתר של Blockly. אפשר לבדוק את הרשאות הגישה גם על ידי קריאת הקוד.
גלוי לכולם
כל מה שמסומן בתור public הוא חלק מה-API הציבורי שלנו. כל נכס במודול שלא כולל התאמת חשיפה נחשב כציבורי.
אנחנו משתדלים לא לשנות את ה-API הציבורי שלנו לעיתים קרובות או בלי סיבה טובה ואזהרה. יוצא מן הכלל: ייתכן שנפרסם ממשק API חדש בגרסה אחת באופן ציבורי ונשנה אותו בגרסה הבאה, בתגובה למשוב מוקדם. לאחר מכן, יכול להיות שתוכלו לראות שפונקציה ציבורית או יציבה בנכס.
אפשר לקרוא לפונקציות ציבוריות מכל מקום, ולשנות אותן במחלקות משנה, כל עוד החתימה לא משתנה.
מוגן
רק המחלקה שמגדירים או מחלקת משנה יכולה לגשת לפונקציות ולמאפיינים מוגנים.
מחלקות משנה יכולות לבטל פונקציות ומאפיינים מוגנים, בלי לשנות את החתימות הסוגים.
לדוגמה, כלי רינדור בהתאמה אישית שמרחיב את מחלקת הרינדור הבסיסי יכול לגשת למאפיינים המוגנים שלו.
בכל מקרה, עליכם לוודא שאתם מבינים את האופן שבו נעשה שימוש בפונקציה או במאפיין בשאר הקוד.
private
ניתן לגשת לאפשרויות האלה רק באמצעות קוד באותו קובץ כמו ההגדרה. גישה ישירה למאפיינים האלה עלולה לגרום להתנהגות לא מוגדרת.
מחלקות משנה לא יכולות לשנות פונקציות ומאפיינים פרטיים.
נכסים פרטיים עשויים להשתנות ללא אזהרה, כי הם לא נחשבים לחלק מה-API הציבורי של Blockly.
לחלק מהפונקציות ב-Blockly אין הערות של הרשאות גישה כי הן לא מיוצאות מהמודול שלהן. הפונקציות האלה הן למעשה משתנים מקומיים ואי אפשר להשתמש בהן מחוץ למודול ההגדרה. הם צריכים להיות מקבילים לנכסים פרטיים.
פנימי
הפונקציות והמאפיינים הפנימיים נועדו לשימוש בתוך ספריית הליבה, אבל לא באופן חיצוני. הן מסומנות באמצעות ההערה @internal של ה-TsDoc.
נכסים פנימיים עשויים להשתנות ללא אזהרה, כי הם לא נחשבים לחלק מה-API הציבורי של Blockly.
אפשר לגשת למאפיינים הפנימיים מכל מקום בתוך הליבה, ולשנות אותם במחלקות משנה בליבה, כל עוד החתימה לא משתנה. אסור לגשת אליהם מחוץ לספרייה העיקרית.
הוצא משימוש
אין להשתמש בכל מה שמסומן בתווית @deprecated. רוב המוציאים משימוש כוללים הוראות לקוד המועדף, באזהרה במסוף או ב-TSDoc.
כשהדבר אפשרי, פונקציות שהוצאו משימוש יתעדו אזהרה שכוללת את תאריך המחיקה המתוכנן והמלצה לפונקציה חלופית להפעיל.
שאלות נפוצות
מה אם הפונקציה שבה אני רוצה להשתמש אינה ציבורית?
שלחו בקשה להוספת תכונה ב-blockly. עליכם לכלול תיאור של התרחיש לדוגמה שלכם והצהרה לגבי מה שאתם רוצים שנפרסם כציבורי.
נשתמש בתכונה כדי לבקש ממך להחליט אם להפוך אותה לגלויה לכולם או אם יש דרכים אחרות לקבל את אותו המידע.
אם נחליט שהוא גלוי לכולם, אתם או הצוות של Blockly תבצעו את השינוי המתאים, והוא יהיה זמין בגרסה הבאה של Blockly.
אם אתם בוחרים להשתמש בפלאגין לא ציבורי בפלאגין, כדאי לסמן את הפלאגין כגרסת בטא ולכלול את המידע הזה ב-README.
מה לגבי תיקון קופים?
כדאי לקרוא על תיקון קופים.
Monkeypatching הוא לא בטוח כי ייתכן שהתיקונים יפסיקו לפעול ללא הודעה מוקדמת בגלל שימוש בחלקים לא ציבוריים של ה-API של Blockly. תיקון בפלאגין הוא מסוכן במיוחד, כי הקוד עלול לקיים אינטראקציה באיכות נמוכה עם כל פלאגין אחר שמתקן את אותו הקוד. לכן אנחנו ממליצים מאוד נגד תיקונים קופים באפליקציות וביישומי פלאגין של צד שלישי, ולא נקבל זאת ביישומי פלאגין של צד ראשון.
האם אפשר לשנות פונקציות ציבוריות?
כאשר סיווג משנה: כן. אחרת: לא, מדובר בתיקון קופים.
האם אפשר לבטל פונקציות מוגנות?
כאשר סיווג משנה: כן. אחרת: לא, מדובר בתיקון קופים.
האם אפשר לשנות פונקציות פנימיות או פרטיות?
לא, מדובר בתיקון קופים.
מתי אפשר לגשת ישירות לנכסים? מתי כדאי להשתמש במקלף או בממיר?
אם אנחנו מפרסמים getter או מגדיר, יש להשתמש בהם במקום לגשת ישירות לנכס. אם הנכס לא ציבורי, בהחלט כדאי להשתמש במקבלים ובממירים.
מה אם לנכס אין הערה?
כברירת מחדל הוא ציבורי, אבל נשמח אם תכתבו לנו הנחיה למקרה שנרצה למצוא צמד של getter/setter בשבילכם.
מה אם לפונקציה אין הערה?
הוא גלוי לכולם כברירת מחדל.
מה לעשות אם אני עדיין לא בטוח?
אפשר לשאול שאלה בפורום, ונחזור אליכם בדרך כלל תוך יום עסקים.