בדף הזה מתוארות שיטות מומלצות לקריאה לפונקציות ולגישה למאפיינים ב-Blockly Core. העקרונות האלה חלים על יצירת יישומי פלאגין ל-Blockly ועל שילוב של Blockly באפליקציה עצמאית.
חשיפה
אנחנו משתמשים במפעילי גישה של TypeScript כדי לסמן את החשיפה בספריית הליבה כ-public, private או protected.
יכול להיות שחלק מהנכסים יסומנו ב-@internal בתגובות שלהם ב-TsDoc.
כל המאפיינים public ו-protected מתועדים בקטע References באתר Blockly. אפשר גם לבדוק את החשיפה על ידי קריאת הקוד.
ציבורי
כל מה שמסומן ב-public הוא חלק מממשק ה-API הציבורי שלנו. כל נכס במודול שאין לו משתנה לשינוי רמת החשיפה נחשב לציבורי.
אנחנו מנסים לא לשנות את ממשק ה-API הציבורי לעיתים קרובות או ללא סיבה טובה ואזהרה. היוצא מן הכלל: יכול להיות שנחשוף ממשק API חדש בגרסה אחת ונשנה אותו בגרסה הבאה בתגובה למשוב מוקדם. לאחר מכן תוכלו להתייחס לפונקציה או לנכס הציבוריים כיציבים.
אפשר להפעיל פונקציות ציבוריות מכל מקום, ולשנות אותן בסוגי משנה כל עוד החתימה לא משתנה.
מוגן
רק לכיתה המגדירה או לתת-כיתה יש גישה לפונקציות ולמאפיינים המוגנים.
בכיתות משנה מותר לשנות את הגדרות ברירת המחדל של פונקציות ומאפיינים מוגנים, בלי לשנות את חתימות הסוגים.
לדוגמה, למעבד גרפיקה מותאם אישית שמרחיב את סוג מעבד הגרפיקה הבסיסי יכולה להיות גישה למאפיינים המוגנים שלו.
בכל מקרה, חשוב לוודא שאתם מבינים איך הפונקציה או המאפיין משמשים בשאר הקוד.
פרטי
אפשר לגשת אליהם רק באמצעות קוד שנמצא באותו קובץ שבו מופיעה ההגדרה. גישה ישירה למאפיינים האלה עלולה לגרום להתנהגות לא מוגדרת.
לא ניתן לשנות את הגדרות ברירת המחדל של פונקציות ומאפיינים פרטיים בסוגי משנה.
נכסים פרטיים עשויים להשתנות ללא אזהרה, כי הם לא נחשבים לחלק מה-API הציבורי של Blockly.
לחלק מהפונקציות ב-Blockly אין הערות לגבי רמת החשיפה כי הן לא מיוצאות מהמודול שלהן. הפונקציות האלה הן למעשה משתנים מקומיים, ואי אפשר להשתמש בהן מחוץ למודול שמגדיר אותן. צריך להתייחס אליהם כאל נכסים פרטיים.
פנימי
פונקציות ומאפיינים פנימיים מיועדים לשימוש בספריית הליבה, אבל לא לשימוש חיצוני. הם מסומנים באמצעות ההערה @internal של TsDoc.
נכסים פנימיים עשויים להשתנות ללא אזהרה, כי הם לא נחשבים לחלק מממשק ה-API הציבורי של Blockly.
אפשר לגשת למאפיינים פנימיים מכל מקום בתוך הליבה, ולשנות אותם בסוגי משנה בליבה כל עוד החתימה לא משתנה. אסור לגשת אליהם מחוץ לספרייה הליבה.
הוצא משימוש
אין להשתמש בפרטים שמסומנים ב-@deprecated. רוב ההוצאות משימוש כוללות הוראות לגבי הקוד המועדף, באזהרה במסוף או ב-TSDoc.
במקרים שבהם הדבר אפשרי, פונקציות שהוצאו משימוש יירשמו ביומן עם אזהרה שכוללת את תאריך המחיקה המיועד והמלצה לפונקציית החלפה שאפשר להפעיל.
שאלות נפוצות
ריכזנו כאן כמה שאלות נפוצות שבהן נתקל צוות Blockly.
מה קורה אם הפונקציה שאליה רוצים להפנות לא ציבורית?
שליחת בקשה להוספת תכונה ב-Blockly. יש לכלול תיאור של תרחיש השימוש שלכם וכן הצהרה על מה שאתם רוצים שנחשוף.
אנחנו נשתמש בתכונה הזו כדי לבקש לדבר איתכם על האפשרות להפוך את המידע הזה לציבורי, או על דרכים אחרות לקבל את אותו מידע.
אם נחליט להפוך אותו לציבורי, אתם או צוות Blockly תבצעו את השינוי המתאים והוא ייכנס לתוקף במהדורה הבאה של Blockly.
אם בחרתם להשתמש במשתמש לא ציבורי בפלאגין, כדאי לסמן את הפלאגין כגרסת בטא ולכלול את המידע ב-README.
מה לגבי תיקון שגיאות בקוד (monkeypatching)?
מידע נוסף על תיקון קוד במקום הקוד המקורי
שימוש ב-Monkeypatching הוא לא בטוח, כי תיקונים עלולים להפסיק לפעול ללא הודעה מראש בגלל שימוש בחלקים לא ציבוריים של Blockly API. תיקון בפלאגין מסוכן במיוחד, כי יכול להיות שהקוד יתנהג בצורה לא טובה עם כל פלאגין אחר שמטפל באותו קוד. לכן אנחנו ממליצים מאוד לא להשתמש ב-monkeypatching באפליקציות ובפלאגינים של צד שלישי, ולא נקבל זאת בפלאגינים של צד ראשון.
האם אפשר לשנות את הגדרות ברירת המחדל של פונקציות ציבוריות?
כשיוצרים צאצא: כן. אחרת: לא, זה תיקון 'על הדרך'.
האם אפשר לשנות פונקציות מוגנות?
כשיוצרים צאצא: כן. אחרת: לא, זה תיקון 'על הדרך'.
האם אפשר לשנות את הגדרות ברירת המחדל של פונקציות פנימיות או פרטיות?
לא, זה תיקון קוד במקום הקוד המקורי.
מתי אפשר לגשת ישירות לנכסים? מתי כדאי להשתמש ב-getter או ב-setter?
אם אנחנו מפרסמים פונקציית getter או setter, צריך להשתמש בהן במקום לגשת ישירות למאפיין. אם המאפיין לא ציבורי, מומלץ להשתמש ב-getters וב-setters.
מה קורה אם לנכס אין הערה?
כברירת מחדל, הוא גלוי לכולם, אבל אפשר לכתוב לנו אם רוצים להוסיף לו זוג getter/setter.
מה קורה אם לפונקציה אין הערה?
הסטטוס הזה הוא 'גלוי לכולם' כברירת מחדל.
מה קורה אם עדיין לא בטוחים?
אפשר לשאול שאלה בפורום ונחזור אליך תוך כמה ימים.