Class Ui

קל לארגן דפים בעזרת אוספים אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.
ממשק משתמש

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

// Display a dialog box with a title, message, input field, and "Yes" and "No" buttons. The
// user can also close the dialog by clicking the close button in its title bar.
var ui = SpreadsheetApp.getUi();
var response = ui.prompt('Getting to know you', 'May I know your name?', ui.ButtonSet.YES_NO);

// Process the user's response.
if (response.getSelectedButton() == ui.Button.YES) {
  Logger.log('The user\'s name is %s.', response.getResponseText());
} else if (response.getSelectedButton() == ui.Button.NO) {
  Logger.log('The user didn\'t want to provide a name.');
} else {
  Logger.log('The user clicked the close button in the dialog\'s title bar.');
}

נכסים

מאפיין (property)סוגתיאור
ButtonButtonטיפוסים בני מנייה (enum) שמייצגים לחצני תיבת דו-שיח מותאמים מראש, שהוחזרו על ידי התראה או PromptResponse.getSelectedButton() כדי לציין על איזה לחצן בתיבת דו-שיח המשתמש לחץ.
ButtonSetButtonSetEnum, שמייצג קבוצות מוגדרות מראש של לחצן תיבת דו-שיח, או יותר, שניתן להוסיף להתראה או להודעה.

שיטות

שיטהסוג הערך המוחזרתיאור קצר
alert(prompt)Buttonתיפתח תיבת דו-שיח בכלי העריכה של המשתמש' עם ההודעה הנתונה ולחצן "OK"
alert(prompt, buttons)Buttonתיפתח תיבת דו-שיח בעורך המשתמש, עם ההודעה הנתונה ורשימת הלחצנים.
alert(title, prompt, buttons)Buttonתיפתח תיבת דו-שיח בכלי העריכה של המשתמש עם הכותרות, ההודעה וקבוצה של הלחצנים.
createAddonMenu()Menuיוצר כלי שיכול לשמש להוספת תפריט משנה לתפריט התוסף של העורך.
createMenu(caption)Menuיוצר כלי שיכול לשמש להוספת תפריט לממשק המשתמש של העורך.
prompt(prompt)PromptResponseתיפתח תיבת דו-שיח להזנת העורך של המשתמש, עם ההודעה הנתונה ולחצן "OK"
prompt(prompt, buttons)PromptResponseתיפתח תיבת דו-שיח להזנת הטקסט בעורך המשתמש, עם ההודעה הנתונה וקבוצה של לחצנים.
prompt(title, prompt, buttons)PromptResponseתיפתח תיבת דו-שיח לקליטת נתונים בעורך המשתמש, עם הכותרות, ההודעה ולחצן הלחצנים.
showModalDialog(userInterface, title)voidתיפתח תיבת דו-שיח מודאלית בעורך של המשתמש עם תוכן מותאם אישית בצד הלקוח.
showModelessDialog(userInterface, title)voidתיפתח תיבת דו-שיח ללא מצב בכלי העריכה של המשתמש, עם תוכן מותאם אישית בצד הלקוח.
showSidebar(userInterface)voidפתיחת סרגל צד בעורך של המשתמש עם תוכן מותאם אישית בצד הלקוח.

תיעוד מפורט

alert(prompt)

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

// Display "Hello, world" in a dialog box with an "OK" button. The user can also close the
// dialog by clicking the close button in its title bar.
SpreadsheetApp.getUi().alert('Hello, world');

פרמטרים

שםסוגתיאור
promptStringההודעה שתוצג בתיבת הדו-שיח.

הלוך ושוב

Button — הלחצן שהמשתמש לחץ עליו.


alert(prompt, buttons)

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

// Display a dialog box with a message and "Yes" and "No" buttons. The user can also close the
// dialog by clicking the close button in its title bar.
var ui = SpreadsheetApp.getUi();
var response = ui.alert('Are you sure you want to continue?', ui.ButtonSet.YES_NO);

// Process the user's response.
if (response == ui.Button.YES) {
  Logger.log('The user clicked "Yes."');
} else {
  Logger.log('The user clicked "No" or the close button in the dialog\'s title bar.');
}

פרמטרים

שםסוגתיאור
promptStringההודעה שתוצג בתיבת הדו-שיח.
buttonsButtonSetהלחצן שהוגדר להצגה בתיבת הדו-שיח.

הלוך ושוב

Button — הלחצן שהמשתמש לחץ עליו.


alert(title, prompt, buttons)

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

// Display a dialog box with a title, message, and "Yes" and "No" buttons. The user can also
// close the dialog by clicking the close button in its title bar.
var ui = SpreadsheetApp.getUi();
var response = ui.alert('Confirm', 'Are you sure you want to continue?', ui.ButtonSet.YES_NO);

// Process the user's response.
if (response == ui.Button.YES) {
  Logger.log('The user clicked "Yes."');
} else {
  Logger.log('The user clicked "No" or the close button in the dialog\'s title bar.');
}

פרמטרים

שםסוגתיאור
titleStringהכותרת שתוצג מעל תיבת הדו-שיח.
promptStringההודעה שתוצג בתיבת הדו-שיח.
buttonsButtonSetהלחצן שהוגדר להצגה בתיבת הדו-שיח.

הלוך ושוב

Button — הלחצן שהמשתמש לחץ עליו.


createAddonMenu()

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

// Add an item to the Add-on menu, under a sub-menu whose name is set automatically.
function onOpen(e) {
  SpreadsheetApp.getUi()
      .createAddonMenu()
      .addItem('Show', 'showSidebar')
      .addToUi();
}

הלוך ושוב

Menu — בונה התפריטים החדש.


createMenu(caption)

יוצר כלי שיכול לשמש להוספת תפריט לממשק המשתמש של העורך. התפריט לא נוצר בפועל עד שמתבצעת קריאה אל Menu.addToUi(). למידע נוסף, ניתן לעיין במדריך לתפריטים. התווית של תפריט ברמה העליונה צריכה להיות באותיות רישיות (כל המילים העיקריות מודגשות) אם הסקריפט פורסם כתוסף, המערכת מתעלמת מהפרמטר caption והתפריט נוסף כתפריט משנה בתפריט התוספים, בדומה ל-createAddonMenu().

// Add a custom menu to the active document, including a separator and a sub-menu.
function onOpen(e) {
  SpreadsheetApp.getUi()
      .createMenu('My Menu')
      .addItem('My menu item', 'myFunction')
      .addSeparator()
      .addSubMenu(SpreadsheetApp.getUi().createMenu('My sub-menu')
          .addItem('One sub-menu item', 'mySecondFunction')
          .addItem('Another sub-menu item', 'myThirdFunction'))
      .addToUi();
}

פרמטרים

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

הלוך ושוב

Menu — בונה התפריטים החדש.


prompt(prompt)

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

// Display a dialog box with a message, input field, and an "OK" button. The user can also
// close the dialog by clicking the close button in its title bar.
var ui = SpreadsheetApp.getUi();
var response = ui.prompt('Enter your name:');

// Process the user's response.
if (response.getSelectedButton() == ui.Button.OK) {
  Logger.log('The user\'s name is %s.', response.getResponseText());
} else {
  Logger.log('The user clicked the close button in the dialog\'s title bar.');
}

פרמטרים

שםסוגתיאור
promptStringההודעה שתוצג בתיבת הדו-שיח.

הלוך ושוב

PromptResponse — ייצוג של תגובת המשתמש.


prompt(prompt, buttons)

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

// Display a dialog box with a message, input field, and "Yes" and "No" buttons. The user can
// also close the dialog by clicking the close button in its title bar.
var ui = SpreadsheetApp.getUi();
var response = ui.prompt('May I know your name?', ui.ButtonSet.YES_NO);

// Process the user's response.
if (response.getSelectedButton() == ui.Button.YES) {
  Logger.log('The user\'s name is %s.', response.getResponseText());
} else if (response.getSelectedButton() == ui.Button.NO) {
  Logger.log('The user didn\'t want to provide a name.');
} else {
  Logger.log('The user clicked the close button in the dialog\'s title bar.');
}

פרמטרים

שםסוגתיאור
promptStringההודעה שתוצג בתיבת הדו-שיח.
buttonsButtonSetהלחצן שהוגדר להצגה בתיבת הדו-שיח.

הלוך ושוב

PromptResponse — ייצוג של תגובת המשתמש.


prompt(title, prompt, buttons)

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

// Display a dialog box with a title, message, input field, and "Yes" and "No" buttons. The
// user can also close the dialog by clicking the close button in its title bar.
var ui = SpreadsheetApp.getUi();
var response = ui.prompt('Getting to know you', 'May I know your name?', ui.ButtonSet.YES_NO);

// Process the user's response.
if (response.getSelectedButton() == ui.Button.YES) {
  Logger.log('The user\'s name is %s.', response.getResponseText());
} else if (response.getSelectedButton() == ui.Button.NO) {
  Logger.log('The user didn\'t want to provide a name.');
} else {
  Logger.log('The user clicked the close button in the dialog\'s title bar.');
}

פרמטרים

שםסוגתיאור
titleStringהכותרת שתוצג מעל תיבת הדו-שיח.
promptStringההודעה שתוצג בתיבת הדו-שיח.
buttonsButtonSetהלחצן שהוגדר להצגה בתיבת הדו-שיח.

הלוך ושוב

PromptResponse — ייצוג של תגובת המשתמש.


showModalDialog(userInterface, title)

תיפתח תיבת דו-שיח מודאלית בעורך של המשתמש עם תוכן מותאם אישית בצד הלקוח. השיטה הזו לא משעה את הסקריפט בצד השרת כאשר תיבת הדו-שיח פתוחה. כדי לתקשר עם הסקריפט מצד השרת, הרכיב בצד הלקוח חייב לבצע קריאות חוזרות לאסינכרוניות באמצעות ממשק ה-API של google.script עבור HtmlService. כדי לסגור את תיבת הדו-שיח, יש להתקשר אל google.script.host.close() בצד הלקוח של אפליקציית אינטרנט HtmlService. מידע נוסף זמין במדריך לתיבות דו-שיח ולסרגלי צד.

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

// Display a modal dialog box with custom HtmlService content.
var htmlOutput = HtmlService
    .createHtmlOutput('<p>A change of speed, a change of style...</p>')
    .setWidth(250)
    .setHeight(300);
SpreadsheetApp.getUi().showModalDialog(htmlOutput, 'My add-on');

פרמטרים

שםסוגתיאור
userInterfaceObjectHtmlOutput שמייצג את הממשק להצגה.
titleStringהכותרת של תיבת הדו-שיח, שמבטלת כל כותרת שהוגדרה על ידי קריאה אל setTitle() באובייקט userInterface.

הרשאה

סקריפטים שמשתמשים בשיטה זו מחייבים הרשאה באמצעות אחד או יותר מההיקפים הבאים:

  • https://www.googleapis.com/auth/script.container.ui

showModelessDialog(userInterface, title)

תיפתח תיבת דו-שיח ללא מצב בכלי העריכה של המשתמש, עם תוכן מותאם אישית בצד הלקוח. השיטה הזו לא משעה את הסקריפט בצד השרת כאשר תיבת הדו-שיח פתוחה. כדי לתקשר עם הסקריפט שבצד השרת, הרכיב בצד הלקוח חייב לבצע קריאות חוזרות לאסינכרוניות באמצעות ממשק ה-API של google.script עבור HtmlService. כדי לסגור את תיבת הדו-שיח, יש להתקשר אל google.script.host.close() בצד הלקוח של אפליקציית אינטרנט HtmlService. מידע נוסף זמין במדריך לתיבות דו-שיח ולסרגלי צד.

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

// Display a modeless dialog box with custom HtmlService content.
var htmlOutput = HtmlService
    .createHtmlOutput('<p>A change of speed, a change of style...</p>')
    .setWidth(250)
    .setHeight(300);
SpreadsheetApp.getUi().showModelessDialog(htmlOutput, 'My add-on');

פרמטרים

שםסוגתיאור
userInterfaceObjectHtmlOutput שמייצג את הממשק להצגה.
titleStringהכותרת של תיבת הדו-שיח, שמבטלת כל כותרת שהוגדרה על ידי קריאה אל setTitle() באובייקט userInterface.

הרשאה

סקריפטים שמשתמשים בשיטה זו מחייבים הרשאה באמצעות אחד או יותר מההיקפים הבאים:

  • https://www.googleapis.com/auth/script.container.ui

showSidebar(userInterface)

פתיחת סרגל צד בעורך של המשתמש עם תוכן מותאם אישית בצד הלקוח. השיטה הזו לא משעה את הסקריפט בצד השרת בזמן שסרגל הצד פתוח. כדי לתקשר עם הסקריפט מצד השרת, הרכיב בצד הלקוח חייב לבצע קריאות חוזרות לאסינכרוניות באמצעות ממשק ה-API של google.script עבור HtmlService. כדי לסגור את סרגל הצד באופן פרוגרמטי, צריך לקרוא ל-google.script.host.close() בצד הלקוח של אפליקציית אינטרנט HtmlService. מידע נוסף זמין במדריך לתיבות דו-שיח ולסרגלי צד.

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

// Display a sidebar with custom HtmlService content.
var htmlOutput = HtmlService
    .createHtmlOutput('<p>A change of speed, a change of style...</p>')
    .setTitle('My add-on');
SpreadsheetApp.getUi().showSidebar(htmlOutput);

פרמטרים

שםסוגתיאור
userInterfaceObjectHtmlOutput שמייצג את הממשק להצגה.

הרשאה

סקריפטים שמשתמשים בשיטה זו מחייבים הרשאה באמצעות אחד או יותר מההיקפים הבאים:

  • https://www.googleapis.com/auth/script.container.ui

שיטות שהוצאו משימוש