Class Ui
Stay organized with collections
Save and categorize content based on your preferences.
Ui
An instance of the user-interface environment for a Google App that allows the script to add
features like menus, dialogs, and sidebars. A script can only interact with the UI for the
current instance of an open editor, and only if the script is
container-bound
to the editor.
// 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.');
}
Properties
Property
| Type
| Description
|
Button
| Button
| An enum representing predetermined, localized dialog buttons returned by an
alert
or
PromptResponse.getSelectedButton()
to indicate
which button in a dialog the user clicked.
|
ButtonSet
| ButtonSet
| An enum representing predetermined, localized sets of one or more dialog buttons that can be
added to an
alert
or a
prompt
.
|
Methods
Method
| Return type
| Brief description
|
alert(prompt)
| Button
| Opens a dialog box in the user's editor with the given message and an "OK" button.
|
alert(prompt, buttons)
| Button
| Opens a dialog box in the user's editor with the given message and set of buttons.
|
alert(title, prompt, buttons)
| Button
| Opens a dialog box in the user's editor with the given title, message, and set of buttons.
|
createAddonMenu()
| Menu
| Creates a builder that can be used to insert a sub-menu into the editor's Extensions menu.
|
createMenu(caption)
| Menu
| Creates a builder that can be used to add a menu to the editor's user interface.
|
prompt(prompt)
| PromptResponse
| Opens an input dialog box in the user's editor with the given message and an "OK" button.
|
prompt(prompt, buttons)
| PromptResponse
| Opens an input dialog box in the user's editor with the given message and set of buttons.
|
prompt(title, prompt, buttons)
| PromptResponse
| Opens an input dialog box in the user's editor with the given title, message, and set of
buttons.
|
showModalDialog(userInterface, title)
| void
| Opens a modal dialog box in the user's editor with custom client-side content.
|
showModelessDialog(userInterface, title)
| void
| Opens a modeless dialog box in the user's editor with custom client-side content.
|
showSidebar(userInterface)
| void
| Opens a sidebar in the user's editor with custom client-side content.
|
Deprecated methods
Method
| Return type
| Brief description
|
showDialog(userInterface)
| void
| Opens a dialog box in the user's editor with custom client-side content.
|
Detailed documentation
alert(prompt)
Opens a dialog box in the user's editor with the given message and an "OK" button. This method
suspends the server-side script while the dialog is open. The script resumes after the user
dismisses the dialog, but
Jdbc
connections and
LockService
locks don't
persist across the suspension. For more information, see the
guide to dialogs and sidebars
.
// 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');
Parameters
Name
| Type
| Description
|
prompt
| String
| The message to display in the dialog box.
|
Return
Button
— The button the user clicked.
prompt(prompt)
Opens an input dialog box in the user's editor with the given message and an "OK" button. This
method suspends the server-side script while the dialog is open. The script resumes after the
user dismisses the dialog, but
Jdbc
connections and
LockService
locks don't
persist across the suspension. For more information, see the
guide to dialogs and sidebars
.
// 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.');
}
Parameters
Name
| Type
| Description
|
prompt
| String
| The message to display in the dialog box.
|
Return
PromptResponse
— A representation of the user's response.
showModalDialog(userInterface, title)
Opens a modal dialog box in the user's editor with custom client-side content. This method does
not
suspend the server-side script while the dialog is open. To communicate with the
server-side script, the client-side component must make asynchronous callbacks using the
google.script
API for
HtmlService
. To close the dialog
programmatically, call
google.script.host.close()
on the client side of an
HtmlService
web
app. For more information, see the
guide to dialogs and
sidebars
.
Modal dialogs prevent the user from interacting with anything other than the dialog. By
contrast,
modeless dialogs
and
sidebars
let the user interact with the editor. In almost all cases, a
modal dialog or sidebar is a better choice than a modeless dialog.
// 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');
Parameters
Name
| Type
| Description
|
userInterface
| Object
| An
HtmlOutput
representing the interface to display.
|
title
| String
| The title of the dialog; overrides any title set by calling
setTitle()
on
the
userInterface
object.
|
Authorization
Scripts that use this method require authorization with one or more of the following
scopes
:
-
https://www.googleapis.com/auth/script.container.ui
showModelessDialog(userInterface, title)
Opens a modeless dialog box in the user's editor with custom client-side content. This method
does
not
suspend the server-side script while the dialog is open. To communicate with
the server-side script, the client-side component must make asynchronous callbacks using the
google.script
API for
HtmlService
. To close the dialog
programmatically, call
google.script.host.close()
on the client side of an
HtmlService
web
app. For more information, see the
guide to dialogs and
sidebars
.
Modeless dialogs let the user interact with the editor behind the dialog. By contrast,
modal dialogs
do not. In almost all cases, a modal
dialog or
sidebar
is a better choice than a modeless dialog.
// 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');
Parameters
Name
| Type
| Description
|
userInterface
| Object
| An
HtmlOutput
representing the interface to display.
|
title
| String
| The title of the dialog; overrides any title set by calling
setTitle()
on
the
userInterface
object.
|
Authorization
Scripts that use this method require authorization with one or more of the following
scopes
:
-
https://www.googleapis.com/auth/script.container.ui
Deprecated methods
showDialog(userInterface)
Deprecated.
As of March 2014, this method is deprecated. The direct replacement is
showModelessDialog(userInterface, title)
, but
showModalDialog(userInterface, title)
is a
better choice in almost all cases.
Opens a dialog box in the user's editor with custom client-side content. This method does
not
suspend the server-side script while the dialog is open. To communicate with the
server-side script, the client-side component must make asynchronous callbacks using the
google.script
API for
HtmlService
. To close the dialog
programmatically, call
google.script.host.close()
on the client side of an
HtmlService
web
app. For more information, see the
guide to dialogs and
sidebars
.
// Display a dialog box with custom HtmlService content.
var 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);
Parameters
Name
| Type
| Description
|
userInterface
| Object
| An
HtmlOutput
representing the interface to display.
|
Authorization
Scripts that use this method require authorization with one or more of the following
scopes
:
-
https://www.googleapis.com/auth/script.container.ui
Except as otherwise noted, the content of this page is licensed under the
Creative Commons Attribution 4.0 License
, and code samples are licensed under the
Apache 2.0 License
. For details, see the
Google Developers Site Policies
. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2023-10-25 UTC.
[{
"type": "thumb-down",
"id": "missingTheInformationINeed",
"label":"Missing the information I need"
},{
"type": "thumb-down",
"id": "tooComplicatedTooManySteps",
"label":"Too complicated / too many steps"
},{
"type": "thumb-down",
"id": "outOfDate",
"label":"Out of date"
},{
"type": "thumb-down",
"id": "samplesCodeIssue",
"label":"Samples / code issue"
},{
"type": "thumb-down",
"id": "otherDown",
"label":"Other"
}]
[{
"type": "thumb-up",
"id": "easyToUnderstand",
"label":"Easy to understand"
},{
"type": "thumb-up",
"id": "solvedMyProblem",
"label":"Solved my problem"
},{
"type": "thumb-up",
"id": "otherUp",
"label":"Other"
}]