Class Ui

Ui

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

屬性

屬性類型說明
ButtonButton列舉代表 alert 或 PromptResponse.getSelectedButton() 傳回的預先決定本地化對話方塊按鈕，指出使用者在對話方塊中點選的按鈕。
ButtonSetButtonSet列舉代表預先定義的一或多個對話方塊按鈕的本地化組合，可新增至快訊或提示。

方法

方法傳回類型簡短說明
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.
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.');
}

參數

名稱類型說明
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.
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.');
}

參數

名稱類型說明
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.
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.');
}

參數

名稱類型說明
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.
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.');
}

參數

名稱類型說明
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.
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.');
}

參數

名稱類型說明
titleString顯示在對話方塊上方的標題。
promptString對話方塊中顯示的訊息。
buttonsButtonSet設定為在對話方塊中顯示的按鈕。

回攻員

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

參數

名稱類型說明
userInterfaceObjectHtmlOutput 代表要顯示的介面。
titleString對話方塊的標題；在 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');

參數

名稱類型說明
userInterfaceObjectHtmlOutput 代表要顯示的介面。
titleString對話方塊的標題；在 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);

參數

名稱類型說明
userInterfaceObjectHtmlOutput 代表要顯示的介面。

授權

使用這個方法的指令碼必須取得以下一或多個範圍的授權：

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

已淘汰的方法