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

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

屬性

屬性	類型	說明
`Button`	`Button`	這個列舉代表由 alert 或 `PromptResponse.getSelectedButton()` 傳回的預先定義、經過本地化的對話方塊按鈕，用於指出使用者按下對話方塊中的哪個按鈕。
`ButtonSet`	`ButtonSet`	這個列舉代表預先定義的本地化一或多個對話方塊集合，可新增至警示或提示。

方法

方法	傳回類型	簡短說明
`alert(prompt)`	`Button`	在使用者編輯器中開啟對話方塊，並顯示指定訊息和「確定」按鈕。
`alert(prompt, buttons)`	`Button`	在使用者編輯器中開啟對話方塊，並顯示指定訊息和一組按鈕。
`alert(title, prompt, buttons)`	`Button`	在使用者的編輯器中開啟對話方塊，並顯示指定的標題、訊息和按鈕組合。
`createAddonMenu()`	`Menu`	建立可用於在編輯器的「Extensions」選單中插入子選單的建構工具。
`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.
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.',
  );
}

參數

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

參數

名稱	類型	說明
`title`	`String`	顯示在對話方塊上方的標題。
`prompt`	`String`	對話方塊中顯示的訊息。
`buttons`	`ButtonSet`	對話方塊中顯示的按鈕。

回攻員

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)`

建立可用於將選單新增至編輯器使用者介面的建構工具。系統必須呼叫 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.
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.');
}

參數

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

參數

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

參數

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

參數

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

參數

名稱	類型	說明
`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.
const 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.
const 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