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.');
}

מאפיינים

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

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

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

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');

פרמטרים

שםסוגתיאור
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.
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.',
  );
}

פרמטרים

שםסוגתיאור
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.
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.',
  );
}

פרמטרים

שםסוגתיאור
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)

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

פרמטרים

שםסוגתיאור
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.
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.');
}

פרמטרים

שםסוגתיאור
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.
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.');
}

פרמטרים

שםסוגתיאור
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.
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');

פרמטרים

שםסוגתיאור
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.
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');

פרמטרים

שםסוגתיאור
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.
const 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

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