本頁面由 Cloud Translation API 翻譯而成。

Class 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.
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`	列舉代表由快訊或 `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`	在使用者的編輯器中開啟含有自訂用戶端內容的側欄。

已淘汰的方法

方法	傳回類型	簡短說明
`showDialog(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`	對話方塊的標題；在以下事件中呼叫 `setTitle()` 會覆寫任何已設定的標題 `userInterface` 物件。

授權

使用這個方法的指令碼需要下列一或多個範圍的授權：

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`	對話方塊的標題；在以下事件中呼叫 `setTitle()` 會覆寫任何已設定的標題 `userInterface` 物件。

授權

使用這個方法的指令碼需要下列一或多個範圍的授權：

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

已淘汰的方法

`showDialog(userInterface)`

已淘汰。此方法已於 2014 年 3 月淘汰。直接取代為 showModelessDialog(userInterface, title)，但 showModalDialog(userInterface, title) 為但幾乎在所有情況下都能選擇更合適的選項

在使用者的編輯器中開啟含有自訂用戶端內容的對話方塊。這個方法會對話方塊開啟時，「不得」暫停伺服器端指令碼。為了與伺服器端指令碼，用戶端元件必須使用 HtmlService 的 google.script API 執行非同步回呼。關閉對話方塊程式輔助、呼叫 HtmlService 網頁用戶端上的 google.script.host.close() 應用程式。詳情請參閱對話方塊和側欄。

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

參數

名稱	類型	說明
`userInterface`	`Object`	`HtmlOutput` 代表要顯示的介面。

授權

使用這個方法的指令碼需要下列一或多個範圍的授權：

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