מבוא
בדף הזה מתוארות שיטות מומלצות לקריאה לפונקציות ולגישה מאפיינים ב-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 מתועדים ב-
הקטע קובצי עזר באתר Blockly. אפשר גם
לבדוק את החשיפה על ידי קריאת הקוד.
ציבורי
כל מה שמסומן בתור public הוא חלק מה-API הציבורי שלנו. כל מאפיין במודול
שאין להם הגדרת חשיפה נחשבת כציבורית.
אנחנו משתדלים לא לשנות את ה-API הציבורי שלנו לעיתים קרובות או בלי סיבה טובה, אזהרה. היוצא מן הכלל: ייתכן שנהפוך API חדש לגלוי לכולם בגרסה אחת, ישנו אותו בגרסה הבאה בתגובה למשוב מוקדם. לאחר מכן ייתכן מתייחסים לפונקציה ציבורית או ליציבות של נכס.
ניתן לקרוא לפונקציות ציבוריות מכל מקום, ולבטל אותן במחלקות משנה בתור כל עוד החתימה לא משתנה.
מוגן
הגישה לפונקציות ולמאפיינים מוגנים יכולה להיות רק המחלקה המגדירה או תת-מחלקה.
מחלקות משנה מורשות לבטל פונקציות ומאפיינים מוגנים, ללא שינוי של סוגי החתימות.
לדוגמה, כלי לרינדור בהתאמה אישית שמרחיב את מחלקת הרינדור הבסיסי יכול לגשת את הנכסים המוגנים.
בכל מקרה, חשוב להבין איך הפונקציה או המאפיין שבו נעשה שימוש בשאר הקוד.
פרטי
אפשר לגשת אליהם רק באמצעות קוד שנמצא בקובץ ההגדרה. באופן ישיר גישה לנכסים האלה עלולה לגרום להתנהגות לא מוגדרת.
למחלקות משנה אסור לבטל פונקציות ומאפיינים פרטיים.
הנכסים הפרטיים כפופים לשינויים ללא אזהרה, כי הם לא נחשב לחלק מה-API הציבורי של Blockly.
לחלק מהפונקציות ב-Blockly אין הערות חשיפה כי לא מיוצאות מהמודול שלהם. הפונקציות האלה הן בעצם משתנים מקומיים ולא ניתן להשתמש בהם מחוץ למודול ההגדרה שלהם. צריך להביא בחשבון את האפשרויות האלה מקביל לנכסים פרטיים.
פנימי
פונקציות ומאפיינים פנימיים מיועדים לשימוש במסגרת הליבה
אבל לא באופן חיצוני. הם מסומנים באמצעות @internal ב-TsDoc
הערה.
נכסים פנימיים עשויים להשתנות ללא אזהרה, כי הם לא נחשב לחלק מה-API הציבורי של Blockly.
ניתן לגשת למאפיינים פנימיים מכל מקום בתוך הליבה, ולשנות את ההגדרות בהתאם מחלקות משנה בליבה, כל עוד החתימה לא משתנה. אסור שיהיו שאליו בוצעה גישה מחוץ לספריית הליבה.
הוצא משימוש
אין להשתמש בכל פריט שמסומן בתור @deprecated. רוב הגורמים שהוצאו משימוש כוללים
הוראות לקוד המועדף, באזהרה של מסוף או ב-TSDoc.
כשהדבר אפשרי, פונקציות שהוצאו משימוש יתעדו אזהרה שכוללת את את התאריך המיועד למחיקה והמלצה לפונקציה חלופית להפעיל.
שאלות נפוצות
מה אם הפונקציה שבה רוצים להשתמש לא ציבורית?
להגיש בקשה להוספת תכונה ב- Core Blockly. צריך להוסיף תיאור של התרחיש לדוגמה והצהרה שברצונך שנפרסם באופן ציבורי.
נשתמש בתכונה כדי לבדוק אם להפוך אותה לגלויה לכולם, או אם יש דרכים אחרות שבהן תוכל לקבל את אותו מידע.
אם נחליט להפוך אותו לגלוי לכולם, אתם או הצוות של Blockly יעבירו את לצורך השינוי, והוא ייכנס לתוקף בגרסה הבאה של Blockly.
אם בחרת להשתמש במשתמש לא ציבורי בפלאגין, כדאי לסמן את
את הפלאגין בתור בטא ולכלול את המידע בREADME.
מה לגבי תיקון קופים?
קוראים את המאמר תיקון קופים.
תיקון קופים אינו בטוח כי התיקונים עלולים להפסיק לפעול ללא התראה לשימוש בחלקים לא ציבוריים של Blockly API. ביצוע התיקונים בפלאגין הוא מסוכן במיוחד, מפני שהקוד עלול ליצור אינטראקציה גרועה עם בפלאגין שמפענח את אותו קוד, לכן אנחנו מאוד לא ממליצה על תיקון קופים באפליקציות וביישומי פלאגין של צד שלישי, לא יקבל אותה ביישומי פלאגין של צד ראשון.
האם אפשר לשנות פונקציות ציבוריות?
בסיווג משנה: כן. אחרת: לא, מדובר בתיקון קופים.
האם אפשר לבטל פונקציות מוגנות?
בסיווג משנה: כן. אחרת: לא, מדובר בתיקון קופים.
האם אפשר לשנות פונקציות פנימיות או פרטיות?
לא, מדובר בתיקון קופים.
מתי אפשר לגשת ישירות לנכסים? מתי כדאי להשתמש במנגנון מכוונן או בממיר?
אם אנחנו מפרסמים מקודד או מגדיר, צריך להשתמש בהם במקום באופן ישיר גישה לנכס. אם הנכס לא ציבורי, בהחלט צריך להשתמש ב-geters ומסדרים.
מה קורה אם בנכס אין הערה?
כברירת מחדל הוא ציבורי, אבל נשמח אם תוכלו לכתוב לנו אם נרצה להוסיף מותאם לכם.
מה קורה אם לפונקציה אין הערה?
כברירת מחדל, הוא גלוי לכולם.
מה אם עדיין קשה לי לומר בוודאות?
אפשר לשאול שאלה בפורום ונחזור אליך, בדרך כלל תוך יום עסקים.