Class Ui

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.
const ui = SpreadsheetApp.getUi();
const 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.');
}

מאפיינים

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

Methods

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

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

שיטה	סוג הערך המוחזר	תיאור קצר
showDialog(userInterface)	void	תיפתח תיבת דו-שיח בכלי העריכה של המשתמש עם תוכן בהתאמה אישית בצד הלקוח.

מסמכים מפורטים

alert(prompt)

פתיחת תיבת דו-שיח בכלי העריכה של המשתמש עם ההודעה שצוינה ועם לחצן 'אישור'. השיטה הזו משהה את הסקריפט בצד השרת בזמן שתיבת הדו-שיח פתוחה. הסקריפט ממשיך אחרי שהמשתמש סוגר את תיבת הדו-שיח, אבל החיבורים של 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');

פרמטרים

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

חזרה

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.
const ui = SpreadsheetApp.getUi();
const 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.',
  );
}

פרמטרים

שם	סוג	תיאור
prompt	String	ההודעה שתוצג בתיבת הדו-שיח.
buttons	ButtonSet	הלחצן שהוגדר להצגה בתיבת הדו-שיח.

חזרה

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.
const ui = SpreadsheetApp.getUi();
const 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.',
  );
}

פרמטרים

שם	סוג	תיאור
title	String	הכותרת שתוצג מעל תיבת הדו-שיח.
prompt	String	ההודעה שתוצג בתיבת הדו-שיח.
buttons	ButtonSet	הלחצן שהוגדר להצגה בתיבת הדו-שיח.

חזרה

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();
}

פרמטרים

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

חזרה

Menu — הכלי החדש ליצירת תפריטים.

---

prompt(prompt)

פתיחת תיבת דו-שיח להזנה בעורך של המשתמש עם ההודעה שצוינה ועם לחצן 'אישור'. השיטה הזו משהה את הסקריפט בצד השרת בזמן שתיבת הדו-שיח פתוחה. הסקריפט ממשיך אחרי שהמשתמש סוגר את תיבת הדו-שיח, אבל החיבורים של 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.
const ui = SpreadsheetApp.getUi();
const 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.');
}

פרמטרים

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

חזרה

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.
const ui = SpreadsheetApp.getUi();
const 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.');
}

פרמטרים

שם	סוג	תיאור
prompt	String	ההודעה שתוצג בתיבת הדו-שיח.
buttons	ButtonSet	הלחצן שהוגדר להצגה בתיבת הדו-שיח.

חזרה

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.
const ui = SpreadsheetApp.getUi();
const 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.');
}

פרמטרים

שם	סוג	תיאור
title	String	הכותרת שתוצג מעל תיבת הדו-שיח.
prompt	String	ההודעה שתוצג בתיבת הדו-שיח.
buttons	ButtonSet	הלחצן שהוגדר להצגה בתיבת הדו-שיח.

חזרה

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

---

showModalDialog(userInterface, title)

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

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

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

פרמטרים

שם	סוג	תיאור
userInterface	Object	HtmlOutput שמייצג את הממשק שרוצים להציג.
title	String	שם תיבת הדו-שיח. מבטל כל שם שהוגדר על-ידי קריאה ל-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.
const htmlOutput = HtmlService
                       .createHtmlOutput(
                           '<p>A change of speed, a change of style...</p>',
                           )
                       .setWidth(250)
                       .setHeight(300);
SpreadsheetApp.getUi().showModelessDialog(htmlOutput, 'My add-on');

פרמטרים

שם	סוג	תיאור
userInterface	Object	HtmlOutput שמייצג את הממשק שרוצים להציג.
title	String	שם תיבת הדו-שיח. מבטל כל שם שהוגדר על ידי קריאה ל-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.
const htmlOutput = HtmlService
                       .createHtmlOutput(
                           '<p>A change of speed, a change of style...</p>',
                           )
                       .setTitle('My add-on');
SpreadsheetApp.getUi().showSidebar(htmlOutput);

פרמטרים

שם	סוג	תיאור
userInterface	Object	HtmlOutput שמייצג את הממשק שרוצים להציג.

אישור

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

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

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

showDialog(userInterface)

הוצא משימוש. החל ממרץ 2014, השיטה הזו הוצאה משימוש. החלפת הערך ישירות היא showModelessDialog(userInterface, title), אבל showModalDialog(userInterface, title) היא בחירה טובה יותר ברוב המקרים.

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

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

פרמטרים

שם	סוג	תיאור
userInterface	Object	HtmlOutput שמייצג את הממשק שרוצים להציג.

אישור

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

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