מדריך סגנון לממשק המשתמש של תוספים לעורכים

תוספים לעורכים מאפשרים ליצור ממשקי משתמש (תפריטים, סרגל צד ותיבות דו-שיח) באמצעות שירות ה-HTML של Apps Script. הממשקים מפותחים ב-HTML וב-CSS, ולכן אפשר להתאים אותם אישית במידה רבה. עם זאת, כשאתם יוצרים את הממשק של התוסף, כדאי לתכנן אותו כך שיעניק חוויית משתמש מעולה.

התוספים הטובים ביותר מוסיפים תכונות לכל אחד מהעורכים באופן טבעי, באמצעות אמצעי בקרה והתנהגויות מוכרים. כשיוצרים תוסף חדש:

טקסט

שם התוסף

צריך להגדיר את שם התוסף בזמן פרסום שלו. השם מופיע במקומות רבים, כמו חנות התוספים ובתפריטים.

  • חשוב להשתמש באותיות רישיות בתחילת כל מילה.
  • הימנעו משימוש בסימני פיסוק, במיוחד בסוגריים, אלא אם הם חלק מהמותג.
  • כדאי שהשם יהיה קצר – 30 תווים או פחות. שמות ארוכים עשויים להיות קטועים באופן אוטומטי.
  • אין לכלול את שם המוצר של Google שאליו מיועד התוסף (או להשתמש במילה Google).
  • לא לכלול את פרטי הגרסה.
  • חשוב לוודא שהשם שפורסם של התוסף זהה לשם הקובץ של פרויקט הסקריפט. שם הפרויקט מופיע בתיבת הדו-שיח של ההרשאה.
לא מומלץ מה צריך לעשות
שמות שגויים של תוספים שמות טובים לתוספים

סגנון כתיבה

לא צריך לכתוב הרבה. רוב הפעולות צריכות להיות ברורות באמצעות סמלים, פריסה ותוויות קצרות. אם חלק מהתוסף שלכם צריך הסבר מפורט יותר ממה שתוויות קצרות יכולות לספק, מומלץ ליצור דף אינטרנט נפרד שמתאר את התוסף ולקשר אליו.

כשכותבים טקסט בממשק המשתמש:

  • חשוב להשתמש באות גדולה בתחילת המשפט (באנגלית) (במיוחד בלחצנים, בתוויות ובפריטי תפריט).
  • מומלץ להשתמש בטקסט קצר ופשוט ללא מונחים מקצועיים או ראשי תיבות.
לא מומלץ מה צריך לעשות

טיפ אחרי ההתקנה

הטיפים לאחר ההתקנה מופיעים מיד אחרי שמשתמש מתקין את התוסף, וגם מופיעים בקטע העזרה. יש לכם כמה משפטים שיעזרו למשתמשים להתחיל במהירות.

  • מתחילים במילה שמציינת פעולה.
  • מתארים את השלב הראשון לשימוש בתוסף.
  • אם יש ממשק משתמש ראשי, כמו סרגל צד, צריך להסביר איך לפתוח אותו.
  • אין לקדם את התוסף כאן – הוא כבר מותקן.
לא מומלץ מה צריך לעשות
טיפ שגוי לאחר ההתקנה טיפ טוב אחרי ההתקנה

בניגוד לפרויקטים רגילים של Apps Script, תוספים לא מופיעים בעורך הסקריפטים או במנהל הסקריפטים, והמשתמשים לא יכולים להריץ סקריפטים של תוספים ישירות. במקום זאת, לכל תוסף יש מקום בתפריט התוספים. התפריט (ואולי גם תיבת דו-שיח או סרגל צד) מאפשרים למשתמשים לבצע פעולות בתוסף.

  • התפריט הוא חלק מרכזי בשליטה של המשתמשים בתוסף, לכן חשוב לתכנן את המבנה והניסוח שלו בקפידה.
  • כדאי להימנע מפריטי תפריט שפשוט חוזרים על שם התוסף. במקום זאת, כדאי להתחיל במילה שמציינת פעולה.
  • אם פריט התפריט הראשי מתחיל תהליך עבודה ואין פועל יחיד שמתאר את הפעולה שלו, אפשר לקרוא לו 'התחלה'. התבנית הזו משמשת במדריך למתחילים בנושא תוספים ל-Docs.
  • אם התפריט לא מכיל יותר משישה פריטים, נסו להימנע משימוש בתפריטי משנה. הן יכולות להיות קטנות וקשות לבחירה.
  • תארו את המשימה, ולא את רכיב ממשק המשתמש שמוצג באפשרות בתפריט.
לא מומלץ מה צריך לעשות
תוויות שגויות של אפשרויות בתפריט תוויות טובות לפריטי תפריט

הודעות שגיאה

כשמשהו משתבש, חשוב להשתמש בשפה פשוטה. צריך להסביר את הבעיה מנקודת המבט של המשתמש ולהציע איך לפתור אותה.

  • אל תאפשרו למשתמש לראות חריגות שהקוד שלכם גורם להן. במקום זאת, צריך להשתמש במשפטי try...catch כדי ליירט חריגות, ואז להציג הודעת שגיאה ידידותית למשתמש עם טקסט בתוך שורת טקסט בסגנון הכיתה error מחבילת ה-CSS של התוספים, או תיבת דו-שיח של אזהרה.
  • לפני הפרסום, צריך לוודא שהתוסף לא מתעד ביומן את פרטי ניפוי הבאגים במסוף JavaScript. במקום זאת, צריך להשתמש ביומני Stackdriver.
לא מומלץ מה צריך לעשות
הודעת שגיאה שגויה הודעת שגיאה טובה

תוכן העזרה

התפריט של כל תוסף כולל תיבת עזרה אוטומטית. אם תספקו כתובת URL לעזרה בזמן הפרסום, הקישור ללחצן 'מידע נוסף' יוביל לדף הזה. אם התוסף שלך ברור מאליו, אין צורך לצרף דף הסבר.

  • כשאפשר, כדאי להציג את ההוראות ברשימת תבליטים או ברשימת מספרים. להנחות את המשתמשים עד לתוצאה הסופית, עם הפניות ברורות לרכיבי ממשק המשתמש שצוינו בשמות.
  • חשוב להסביר בבירור את כל הדרישות בהוראות, למשל הגדרת גיליון אלקטרוני באופן מסוים.
  • אפשר גם לקשר לתוכן העזרה מממשק המשתמש הראשי. אם התוסף יוצר מסמך חדש, אפשר גם להציג את ההוראות בגוף המסמך.

ממשקי משתמש בהתאמה אישית

אפשר לשלוט בחלק מהתוספים הפשוטים של ה-Editor רק דרך התפריט שלהם, אבל רוב התוספים מציגים סרגל צד או תיבת דו-שיח עם תוכן מותאם אישית.

  • עמודות צד מתאימות במיוחד לכלים קבועים שסביר להניח שהמשתמשים ישתמשו בהם שוב ושוב בזמן שהם יעבירו את העין על תוכן המסמך או הגיליון האלקטרוני.
  • תיבת דו-שיח מתאימה במיוחד לכלים לשימוש חד-פעמי, לדפי הגדרות ולהודעות חשובות.

טקסט של ממשק משתמש

בכל תיבת דו-שיח או סרגל צד, צריך להניח שאנשים קוראים רק את הכותרת ואת תוויות הלחצנים. האם הם עדיין יכולים להבין מה הממשק עושה ולבחור את האפשרות המתאימה?

  • להשתמש בכותרת ובתוויות לחצן שעומדות בפני עצמן.
  • מומלץ להימנע מקטעי טקסט ארוכים עם תיאורים.

תיבות דו-שיח

תיבת דו-שיח היא פתרון מצוין לכלים שבהם אנשים משתמשים פעם אחת ואז עוברים הלאה. לדוגמה, אם התוסף מאפשר למשתמשים להוסיף גרפיקה, תוכלו להציג תיבת דו-שיח עם אפשרויות להוספה, ולאחר מכן לסגור את תיבת הדו-שיח כשהגרפיקה תתווסף. תיבת דו-שיח גם עוזרת להציג את ההגדרות של התוסף או להעביר הודעה חשובה.

  • אין לפתוח תיבת דו-שיח (כולל התראה או הנחיה) מתיבת דו-שיח אחרת – אפשר להציג רק תיבת דו-שיח אחת בכל פעם.
  • בשם של תיבת הדו-שיח, כדאי להשתמש במילה או בביטוי קצר, ולהתחיל במילה החשובה ביותר.
  • תוויות הלחצנים צריכות להיות קשורות לכותרת של תיבת הדו-שיח.
  • מומלץ להשתמש בשני לחצנים, בדרך כלל פעולה ראשית ו'ביטול'. במקרים מיוחדים שבהם נדרש לחצן שלישי, מומלץ להציב אותו בפינה השמאלית התחתונה.
  • כדאי למקם את הלחצנים בפינה השמאלית התחתונה של תיבת הדו-שיח. הלחצן הראשי הכחול אמור להיות בצד ימין, והלחצנים המשניים האפורים בצד ימין.
לא מומלץ מה צריך לעשות
כותרת שגויה של תיבת דו-שיח כותרת טובה של תיבת דו-שיח

חלוניות הצד מאפשרות לאנשים לחזור למסמך, לגיליון האלקטרוני, למצגת או לטופס בזמן שהם מבצעים בחירות. הם גם מאפשרים לאנשים להשתמש בתוסף שלכם שוב ושוב. בכל פעם שפותחים סרגל צד חדש, כל סרגל צד קודם נסגר באופן אוטומטי. הן מתאימות במיוחד למצבים זמניים שהמשתמש יוצא מהם בסיום.

  • יכול להיות שלמשתמשים יש תוספים אחרים עם סרגל צד משלהם. אם שני תוספים מנסים לפתוח סרגל צד בו-זמנית, רק אחד מהם יוצג.
  • לא להציג סרגל צד או תיבת דו-שיח כשמסמך נפתח בפעם הראשונה.
  • רק תוספים שפועלים ב-AuthMode.FULL יכולים לפתוח סרגל צד או תיבת דו-שיח. אפשר להשתמש בפריט תפריט כדי לפתוח סרגל צד, כי הפעולה הזו מחייבת את המשתמש לספק הרשאה מלאה.

פקדים

ממשקי משתמש של תוספים מעולים משאירים מקום לתנועה בין הפקדים. שוליים וריווח מתאימים יכולים להועיל מאוד, בעוד שפקדים צפופים עלולים להיראות מרתיעים. אם אתם לא בטוחים, תוכלו להיעזר בתבנית מהכלי עצמו. לדוגמה, כשאתם יוצרים תיבת דו-שיח משלכם, כדאי לעיין בתיבת דו-שיח קיימת ב-Google Docs, כמו קובץ > הגדרת דף.

במסמכי העזרה של חבילת ה-CSS של התוספים מופיעה תבנית לדוגמה לכל אחד מסוגי אמצעי הבקרה שמפורטים בהמשך.

לחצנים

כדאי להשתמש בלחצנים כדי לשלוט בפעולות הראשיות של ממשק המשתמש, במקום קישורים פשוטים או רכיבים אחרים.

  • מומלץ להימנע מהצגה של יותר מלחצן כחול, אדום או ירוק אחד בכל פעם. יכול להיות שיהיו לחצנים אפורים שיופיעו שוב ושוב.
  • רוב תוויות הלחצנים צריכות להיות באותיות רישיות ולהתחיל בפעולה. לחצנים אדומים, בדרך כלל של פעולות יצירה, צריכים להיות באותיות רישיות.
לא מומלץ מה צריך לעשות

תיבות סימון ולחצני בחירה

כדאי להשתמש בתיבות סימון כשאנשים יכולים לבחור כמה אפשרויות, או לא לבחור אף אפשרות. כדאי להשתמש בלחצני בחירה (או בתפריט בחירה) כשצריך לבחור רק אפשרות אחת.

  • לא לשנות את ההתנהגות של תיבות סימון כדי לחקות לחצני בחירה.
  • אל תעשו שום דבר מיד אחרי שהם מסומנים. אנשים טועים. ממתינים עד שהמשתמשים ילחצו על לחצן כדי לאשר את הבחירות שלהם.

בחירת תפריטים

'אפשרויות' היא דרך מצוינת להציע רשימה קצרה של חלופות.

  • ממיינים את האפשרויות לפי סדר אלפביתי או לפי סכימה לוגית שכל המשתמשים יכולים להבין (למשל ימי השבוע, החל מיום ראשון).
  • אם הרשימה תהיה ארוכה מדי, כדאי להשתמש באמצעי בקרה אחר. לדוגמה, תוכלו להציג רשימה שניתן לגלול בה כדי ליצור יותר מקום בתפריט ולאפשר ניווט קל יותר.

אזורי טקסט

אם אנשים צריכים להקליד יותר ממספר מילים, כדאי להשתמש באזור טקסט.

  • כדאי להגדיר לאזורי הטקסט גובה של לפחות שתיים שורות, כדי שיהיה קל יותר להשתמש בהם והם לא ייראו כמו שדות טקסט.
  • מניחים את התוויות בחלק העליון.

שדות טקסט

כדאי להשתמש בשדות טקסט אם אנשים צריכים להקליד רק מילה או שתיים.

  • רוחב שדה הטקסט צריך להעיד על מה שאתם מצפים שאנשים יקלידו בו.
  • מומלץ לא להשתמש בטקסט של placeholder כתוויות, כי הוא נעלם כשממקדים אותו. טקסט ממלא-מקום שימושי להצגת דוגמאות או פרטים נוספים.
  • כדאי למקם את התוויות בחלק העליון, אבל אפשר גם למקם שדות טקסט קצרים זה לצד זה.

מיתוג

בתוסף

אם רוצים לכלול מיתוג, חשוב לשמור על מיתוג קצר וקל. כך המשתמשים יוכלו להתמקד בממשק המשתמש, והתוסף ייראה כחלק מהעורך.

  • כל ההיבטים של התוסף חייבים לעמוד בהנחיות למיתוג.
  • אין לכלול את המילה 'Google' או להשתמש בסמלי מוצרים של Google.
  • הטקסט צריך להיות באורך של כמה מילים בלבד, עם סגנון של הכיתה gray מחבילת ה-CSS של התוספים.
  • הגרפיקה צריכה להיות על רקע לבן ובגודל של עד 200px x 60px.
  • בתיבת דו-שיח, הלוגו צריך להופיע בפינה השמאלית התחתונה.
  • בסרגלי צד, הלוגו יכול להופיע בחלק העליון או התחתון.

בחנות

כדי לפרסם תוסף לעריכה, צריך כמה נכסי תמונה. הנכסים האלה משמשים ליצירת דף המוצר של התוסף בחנות.

נגישות

כולם צריכים ליהנות מהתוסף, גם אם הם רואים צבעים בצורה שונה, משתמשים בקורא מסך או שיש להם צרכים אחרים. נגישות היא נושא רחב שאי אפשר לכסות אותו במלואו במדריך הסגנון הזה. אחד מהמקורות המועילים הוא האתר Google Accessibility. אבל ריכזנו כאן כמה טיפים שיעזרו לכם להתחיל:

  • מוודאים שאפשר לנווט לכל הפקדים בממשק המשתמש באמצעות המקלדת. מוסיפים את tabindex=0 לפקדים מותאמים אישית (כמו אלה שנוצרו באמצעות <div>) כדי שאנשים יוכלו לעבור אליהם באמצעות מקש Tab. כדאי לשקול אם כדאי לכלול תמיכה במפתחות אחרים, כמו החצים לרשימה.
  • יכול להיות שחלק מהאנשים ישתמשו בקורא מסך עם התוסף שלכם. לכן, צריך להוסיף לתמונות את המאפיין alt, ולפקדים מותאמים אישית צריך להוסיף מאפייני ARIA כדי לתאר את השימוש בהם.
  • אל תסתמכו רק על צבע כדי להעביר מצב. כדאי להשתמש גם בסמלים ובטקסט.

אם משתמשים באמצעי בקרה רגילים לאינטרנט, כמו אלה שמתוארים למעלה במדריך הזה, קל יותר להפוך את התוסף לנגיש.