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

מאפיינים

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

Methods

שיטהסוג הערך שמוחזרתיאור קצר
alert(prompt)Buttonתיבת דו-שיח נפתחת בכלי העריכה של המשתמש עם ההודעה שצוינה וכפתור 'אישור'.
alert(prompt, buttons)Buttonפותח תיבת דו-שיח בעורך של המשתמש עם ההודעה וסט הלחצנים שצוינו.
alert(title, prompt, buttons)Buttonפותח תיבת דו-שיח בעורך של המשתמש עם הכותרת, ההודעה וסט הלחצנים שצוינו.
createAddonMenu()Menuיוצרת כלי שאפשר להשתמש בו כדי להוסיף תפריט משנה לתפריט Extensions (תוספים) בכלי העריכה.
createMenu(caption)Menuיוצר builder שאפשר להשתמש בו כדי להוסיף תפריט לממשק המשתמש של הכלי לעריכה.
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()

יוצרת כלי שאפשר להשתמש בו כדי להוסיף תפריט משנה לתפריט Extensions (תוספים) בכלי העריכה. התפריט לא מתעדכן בפועל עד שמבצעים קריאה ל-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)

יוצר builder שאפשר להשתמש בו כדי להוסיף תפריט לממשק המשתמש של הכלי לעריכה. התפריט לא יתווסף בפועל עד שתתבצע קריאה ל-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');

פרמטרים

שםסוגתיאור
userInterfaceObjectמחרוזת HtmlOutput שמייצגת את הממשק שיוצג.
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');

פרמטרים

שםסוגתיאור
userInterfaceObjectמחרוזת HtmlOutput שמייצגת את הממשק שיוצג.
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);

פרמטרים

שםסוגתיאור
userInterfaceObjectמחרוזת HtmlOutput שמייצגת את הממשק שיוצג.

אישור

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

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

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