במאמר הזה נסביר איך ליצור פלאגין חדש. התהליך שמתואר במאמר מתייחס ליצירת תוספים מאינטראקציה ישירה, אבל אפשר להשתמש בו כהנחיה ליצירת תוספים של צד שלישי.
סקירה כללית על פלאגינים זמינה במאמר פלאגינים.
למבוא מהיר ליצירת פלאגין, אפשר לצפות בהרצאה שלנו בנושא יצירת פלאגין (2021).
צד ראשון לעומת צד שלישי
משתמש היעד של תוסף הוא מפתח שמוצא את התוסף ומשתמש בו דרך npm.
תוספים מהדומיין הנוכחי נתמכים על ידי צוות Blockly ומפורסמים בהיקף @blockly ב-npm. הם מיועדים לשימוש במגוון רחב של אפליקציות Blockly, והם יציבים וקלים לשימוש. הם מאוחסנים בתיקייה blockly-samples. אפשר להשתמש בשדה להגדרת מהירות המנוע בפרויקטים רבים של רובוטיקה, והוא מועמד טוב לפלאגין מהדומיין הנוכחי.
תקעים של צד שלישי מתוחזקים ומפורסמים באופן עצמאי. יכול להיות שהם מורכבים יותר, ניסיוניים יותר או מיועדים לטווח מצומצם יותר של אפליקציות Blockly. עדיף להשתמש בתוסף של צד שלישי כדי לערוך שדה של אובייקט ספציפי שמוגדר בסכימת מסד הנתונים.
קריטריונים מאינטראקציה ישירה
תוספים של צד ראשון חייבים לעמוד בדרישות הבאות:
- פועל בכל הפלטפורמות העיקריות, אלא אם צוות Blockly העניק פטור.
- Chrome, Firefox, Safari, Edge
- להיות מוכנים לטפל בבאגים בשנה הראשונה.
- אסור לבצע monkeypatching ב-Blockly.
- יש לכם API מוגדר ומתועד בצורה ברורה.
- אסור לקרוא לפונקציות פרטיות או לפונקציות של חבילות מ-Blockly core, אלא אם צוות Blockly העניק לכם פטור.
- מותר להגדיר מחדש פונקציות של חבילה במחלקת משנה שהגדרתם.
- אם אתם רוצים לקבל פטור, אתם יכולים לשלוח לנו בקשה בבעיה ב-blockly-samples.
- יש מבחנים.
התהליך
יש ארבעה שלבים בתהליך הפיתוח של תוספים: הצעה, דיון, הטמעה ופרסום.
הצעה
תוסף מתחיל כהצעה. כדי להציע פלאגין, צריך ליצור בעיה חדשה באמצעות התבנית בקשה לתכונה. מידע נוסף מופיע במאמר איך כותבים בקשה לתכונה.
בנוסף למידע הבסיסי על בקשת התכונה, הצעה לתוסף צריכה לכלול:
- ה-API שהפלאגין יחשוף.
- ממשקי API שצריך להוסיף או לשנות ב-Blockly כדי לתמוך בפלאגין.
- צילומי מסך, קובצי GIF או מוקאפים אם הפלאגין כולל תכונות של ממשק משתמש.
- הסבר למה הפלאגין צריך להיות פלאגין צד ראשון ולא פלאגין צד שלישי.
צוות Blockly בודק את ההצעות שמגיעות אליו, ואז סוגר את הבעיה או מסכים שזו תהיה תוסף טוב של צד ראשון.
קבוצת הדיון
לאחר מכן, תוסף עובר לשלב הדיון. השלב הזה כולל:
- הבהרה לגבי הפונקציונליות הרצויה.
- הבהרה לגבי ה-API של הפלאגין.
- תכנון ההטמעה.
- תכנון הבדיקות.
- דיון בשינויים ב-API ב-Blockly הליבה.
- פירוק של תוספים גדולים לשלבי הטמעה.
- מתן שמות לתוספים, בהתאם למוסכמות שלנו למתן שמות.
- לוודא שמתקיימים כל הקריטריונים של צד ראשון.
הדיון הזה מתנהל בדרך כלל בבעיה ב-GitHub. ככל שההיקף של הפלאגין קטן יותר, כך שלב הדיון יכול להיות מהיר יותר. תוספים גדולים יותר עשויים למשוך את תשומת הלב של הקהילה ולעורר דעות נחרצות לגבי הפתרון הנכון. אם זה קורה בבעיה שלכם, מצוין! מצאתם משהו שאנשים מתעניינים בו.
המטרה היא שבסוף שלב הדיון, כל ההחלטות העיצוביות העיקריות יתקבלו ותהיה רשימה ברורה של שלבי ההטמעה. שני המקרים צריכים להיות מתועדים בהערות על הבעיה.
במהלך הדיון, יכול להיות שנחליט שפלאגין צריך להיות פלאגין של צד שלישי, ולא להתפרסם במסגרת @blockly. במקרה כזה, נסביר למה ונסגור את הבעיה.
כשדיון מסתיים, חבר צוות Blockly מציין שהקוד מוכן להטמעה.
הטמעה
שלבי ההטמעה כוללים:
- מריצים את הפקודה
npx @blockly/create-packageכדי להגדיר את הפלאגין ואת הספרייה שלו מתבנית. מידע נוסף - הטמעה של לוגיקת ליבה לפלאגין.
- הטמעה של ממשק משתמש, אם צריך.
- בדיקת הפלאגין באמצעות Mocha.
- תיעוד הפלאגין, כולל
README.
אם תוסף מוצע אושר להטמעה ואתם רוצים לעבוד עליו, תוכלו להוסיף תגובה לבעיה ולשאול אם היא עדיין פתוחה לתרומות.
יכול להיות שכמה אנשים יטמיעו את התכונה במקביל. אתם יכולים להטמיע פלאגין בשיתוף פעולה במזלג משלכם, או באמצעות בקשות משיכה (pull requests) מול המאגר הזה. אם אתם רוצים לשתף פעולה בפלאגין במאגר הזה, אתם יכולים לבקש מצוות Blockly ליצור בשבילכם ענף תכונות.
צריך להוסיף את הפלאגינים לקובץ
gh-pages/index.md
בסניף master של blockly-samples. הם יופיעו באתר הפלאגינים שלנו. פלאגינים של צד ראשון צריכים להפנות לדף הבדיקה שלהם. אפשר גם להוסיף לדף הזה תוספים של צד שלישי, שיפנו לקישור לפי בחירת הבעלים שלהם, כמו הדגמה מאוחסנת או הדף של npm.
פרסום
לבסוף, פרסום. צוות Blockly משתמש ב-Lerna כדי לנהל את הגרסאות ואת הפרסום של כל הפלאגינים.
בכל יום חמישי, כל התוספים שהשתנו מאז הגרסה האחרונה שלהם מתפרסמים. אם אתם רוצים שהשינוי יפורסם מוקדם יותר, ציינו זאת בבקשת המיזוג.
האתר Plugins מתעדכן גם בכל פעם שמפרסמים פלאגינים.
תוספים שלא מוכנים לפרסום צריכים להיות מסומנים בסימן private ב-package.json שלהם. זה יכול לקרות אם תוסף מסתמך על שינוי בליבת Blockly שעדיין לא פורסם. Core Blockly מתפרסם בשבוע האחרון של כל רבעון (פעם בשלושה חודשים).