Google 應用程式的使用者介面環境執行個體,可讓指令碼新增選單、對話方塊和側欄等功能。指令碼只能在開啟編輯器的目前執行個體中與 UI 互動,且指令碼必須容器繫結至編輯器。
// 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.'); }
屬性
屬性 | 類型 | 說明 |
---|---|---|
Button | Button | 列舉代表 alert 或 PromptResponse.getSelectedButton() 傳回的預先決定本地化對話方塊按鈕,指出使用者在對話方塊中點選的按鈕。 |
ButtonSet | ButtonSet | 列舉代表預先定義的一或多個對話方塊按鈕的本地化組合,可新增至快訊或提示。 |
方法
方法 | 傳回類型 | 簡短說明 |
---|---|---|
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');
參數
名稱 | 類型 | 說明 |
---|---|---|
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. 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.'); }
參數
名稱 | 類型 | 說明 |
---|---|---|
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. 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.'); }
參數
名稱 | 類型 | 說明 |
---|---|---|
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. 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.'); }
參數
名稱 | 類型 | 說明 |
---|---|---|
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. 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.'); }
參數
名稱 | 類型 | 說明 |
---|---|---|
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. 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.'); }
參數
名稱 | 類型 | 說明 |
---|---|---|
title | String | 顯示在對話方塊上方的標題。 |
prompt | String | 對話方塊中顯示的訊息。 |
buttons | ButtonSet | 設定為在對話方塊中顯示的按鈕。 |
回攻員
PromptResponse
:使用者的回應。
showModalDialog(userInterface, title)
在使用者編輯器中開啟含有自訂用戶端內容的強制回應對話方塊。此方法「不會」在對話方塊開啟時暫停伺服器端指令碼。如要與伺服器端指令碼通訊,用戶端元件必須使用 HtmlService
的 google.script
API 建立非同步回呼。如要透過程式輔助方式關閉對話方塊,請在 HtmlService
網頁應用程式的用戶端呼叫
google.script.host.close()
。詳情請參閱對話方塊和側欄指南。
強制回應對話方塊會禁止使用者與對話方塊以外的任何內容互動。透過對比,無模式對話方塊和側欄可讓使用者與編輯器互動。在大部分情況下,強制回應對話方塊或側欄比無模式對話方塊更理想。
// 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');
參數
名稱 | 類型 | 說明 |
---|---|---|
userInterface | Object | HtmlOutput 代表要顯示的介面。 |
title | String | 對話方塊的標題;在 userInterface 物件上呼叫 setTitle() ,覆寫任何設定的標題。 |
授權
使用這個方法的指令碼必須取得以下一或多個範圍的授權:
-
https://www.googleapis.com/auth/script.container.ui
showModelessDialog(userInterface, title)
在使用者編輯器中開啟無模式對話方塊,並顯示自訂用戶端內容。此方法「不會」在對話方塊開啟時暫停伺服器端指令碼。如要與伺服器端指令碼通訊,用戶端元件必須使用 HtmlService
的 google.script
API 建立非同步回呼。如要透過程式輔助方式關閉對話方塊,請在 HtmlService
網頁應用程式的用戶端呼叫
google.script.host.close()
。詳情請參閱對話方塊和側欄指南。
無模式對話方塊可讓使用者與對話方塊後方的編輯器互動。而強制回應對話方塊則不會。在大部分情況下,強制回應對話方塊或側欄比無模式對話方塊更理想。
// 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');
參數
名稱 | 類型 | 說明 |
---|---|---|
userInterface | Object | HtmlOutput 代表要顯示的介面。 |
title | String | 對話方塊的標題;在 userInterface 物件上呼叫 setTitle() ,覆寫任何設定的標題。 |
授權
使用這個方法的指令碼必須取得以下一或多個範圍的授權:
-
https://www.googleapis.com/auth/script.container.ui
showSidebar(userInterface)
在使用者編輯器中開啟含有自訂用戶端內容的側欄。此方法「不會」在側欄開啟時暫停伺服器端指令碼。如要與伺服器端指令碼通訊,用戶端元件必須使用 HtmlService
的 google.script
API 建立非同步回呼。如要透過程式輔助方式關閉側欄,請在 HtmlService
網頁應用程式的用戶端呼叫
google.script.host.close()
。詳情請參閱對話方塊和側欄指南。
如果使用者的環境使用從左至右的語言,則側欄會顯示在編輯器的左側;如果是從右至左的語言,則側欄會顯示在編輯器的左側。指令碼顯示的所有側欄寬度為 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);
參數
名稱 | 類型 | 說明 |
---|---|---|
userInterface | Object | HtmlOutput 代表要顯示的介面。 |
授權
使用這個方法的指令碼必須取得以下一或多個範圍的授權:
-
https://www.googleapis.com/auth/script.container.ui