繫結至 Google 文件、試算表或表單的指令碼可以顯示多種使用者介面元素:預建的快訊和提示,以及包含自訂 HTML 服務頁面的對話方塊和側欄。這些元素一般是從「選單項目」開啟。(請注意,在 Google 表單中,只有開啟表單進行修改的編輯者才能查看使用者介面元素,而開啟表單回覆的使用者無法查看該元素)。
快訊對話方塊
快訊是預先建立的對話方塊,會在 Google 文件、試算表、簡報或表單編輯器中開啟。會顯示訊息和「確定」按鈕;標題和替代按鈕為選用項目。這與在網路瀏覽器中透過用戶端 JavaScript 呼叫 window.alert()
的做法類似。
快訊會在對話方塊開啟時暫停伺服器端指令碼。指令碼會在使用者關閉對話方塊後繼續,但 JDBC 連線在停權期間不會持續保留。
如以下範例所示,Google 文件、表單、簡報和試算表全都使用 Ui.alert()
方法 (提供三個變化版本)。如要覆寫預設的「OK」按鈕,請從 Ui.ButtonSet
列舉傳遞值做為 buttons
引數。如要評估使用者點選哪個按鈕,請比較 alert()
的傳回值與 Ui.Button
列舉值。
function onOpen() {
SpreadsheetApp.getUi() // Or DocumentApp or SlidesApp or FormApp.
.createMenu('Custom Menu')
.addItem('Show alert', 'showAlert')
.addToUi();
}
function showAlert() {
var ui = SpreadsheetApp.getUi(); // Same variations.
var result = ui.alert(
'Please confirm',
'Are you sure you want to continue?',
ui.ButtonSet.YES_NO);
// Process the user's response.
if (result == ui.Button.YES) {
// User clicked "Yes".
ui.alert('Confirmation received.');
} else {
// User clicked "No" or X in the title bar.
ui.alert('Permission denied.');
}
}
提示對話方塊
提示是預先建立的對話方塊,會在 Google 文件、試算表、簡報或表單編輯器中開啟。顯示訊息、文字輸入欄位和「OK」按鈕;標題和替代按鈕為選用項目。這與在網路瀏覽器中透過用戶端 JavaScript 呼叫 window.prompt()
的做法類似。
對話方塊開啟時,提示暫停伺服器端指令碼。指令碼會在使用者關閉對話方塊後繼續,但 JDBC 連線在停權期間不會持續保留。
如以下範例所示,Google 文件支援的表單、簡報和試算表全都使用 Ui.prompt()
方法,這個方法提供三種變化版本。如要覆寫預設的「OK」按鈕,請將 Ui.ButtonSet
列舉的值做為 buttons
引數傳遞。如要評估使用者的回應,請擷取 prompt()
的傳回值,然後呼叫 PromptResponse.getResponseText()
擷取使用者的輸入內容,並將 PromptResponse.getSelectedButton()
的傳回值與 Ui.Button
列舉進行比較。
function onOpen() {
SpreadsheetApp.getUi() // Or DocumentApp or SlidesApp or FormApp.
.createMenu('Custom Menu')
.addItem('Show prompt', 'showPrompt')
.addToUi();
}
function showPrompt() {
var ui = SpreadsheetApp.getUi(); // Same variations.
var result = ui.prompt(
'Let\'s get to know each other!',
'Please enter your name:',
ui.ButtonSet.OK_CANCEL);
// Process the user's response.
var button = result.getSelectedButton();
var text = result.getResponseText();
if (button == ui.Button.OK) {
// User clicked "OK".
ui.alert('Your name is ' + text + '.');
} else if (button == ui.Button.CANCEL) {
// User clicked "Cancel".
ui.alert('I didn\'t get your name.');
} else if (button == ui.Button.CLOSE) {
// User clicked X in the title bar.
ui.alert('You closed the dialog.');
}
}
自訂對話方塊
自訂對話方塊可在 Google 文件、試算表、簡報或表單編輯器中顯示 HTML 服務使用者介面。
對話方塊開啟時,自訂對話方塊「不會」暫停伺服器端指令碼。用戶端元件可以使用 HTML 服務介面適用的 google.script
API,對伺服器端指令碼進行非同步呼叫。
對話方塊可以在 HTML 服務介面的用戶端呼叫 google.script.host.close()
來關閉對話方塊。其他介面無法由其他介面關閉,只能由使用者或自行關閉。
如以下範例所示,Google 文件、表單、簡報和試算表都是使用 Ui.showModalDialog()
方法開啟對話方塊。
Code.gs
function onOpen() { SpreadsheetApp.getUi() // Or DocumentApp or SlidesApp or FormApp. .createMenu('Custom Menu') .addItem('Show dialog', 'showDialog') .addToUi(); } function showDialog() { var html = HtmlService.createHtmlOutputFromFile('Page') .setWidth(400) .setHeight(300); SpreadsheetApp.getUi() // Or DocumentApp or SlidesApp or FormApp. .showModalDialog(html, 'My custom dialog'); }
Page.html
Hello, world! <input type="button" value="Close" onclick="google.script.host.close()" />
自訂側欄
側欄可以在 Google 文件、表單、簡報和試算表編輯器中顯示 HTML 服務使用者介面。
對話方塊開啟時,側欄不會暫停伺服器端指令碼。用戶端元件可以使用 HTML 服務介面適用的 google.script
API,對伺服器端指令碼進行非同步呼叫。
側欄可以藉由在 HTML 服務介面的用戶端呼叫 google.script.host.close()
來關閉側欄。側欄無法由其他介面關閉,只能由使用者或自行關閉。
如以下例子所示,所有 Google 文件、表單、簡報和試算表都會使用 Ui.showSidebar()
方法開啟側欄。
Code.gs
function onOpen() { SpreadsheetApp.getUi() // Or DocumentApp or SlidesApp or FormApp. .createMenu('Custom Menu') .addItem('Show sidebar', 'showSidebar') .addToUi(); } function showSidebar() { var html = HtmlService.createHtmlOutputFromFile('Page') .setTitle('My custom sidebar'); SpreadsheetApp.getUi() // Or DocumentApp or SlidesApp or FormApp. .showSidebar(html); }
Page.html
Hello, world! <input type="button" value="Close" onclick="google.script.host.close()" />
開啟檔案對話方塊
Google Picker 是「開啟檔案」對話方塊,內含 Google 伺服器 (包括 Google 雲端硬碟、Google 圖片搜尋、Google 影片搜尋等) 中儲存的資訊。
如以下範例所示,您可以在 HTML 服務中使用 Picker 的用戶端 JavaScript API 建立自訂對話方塊,讓使用者選取現有檔案或上傳新檔案,然後將選取項目回傳至指令碼以供後續使用。
如要啟用 Picker 並取得 API 金鑰,請按照下列說明操作:
- 確認您的指令碼專案使用標準 GCP 專案。
- 在 Google Cloud 專案中啟用「Google Picker API」。
- 在 Google Cloud 專案仍在開啟的情況下,選取「APIs & Services」(API 和服務),然後按一下「Credentials」(憑證)。
- 按一下「建立憑證」>「API 金鑰」。這項操作會建立金鑰,但您必須編輯金鑰,為金鑰新增應用程式限制和 API 限制。
- 在「API 金鑰」對話方塊中,按一下「關閉」。
- 在您建立的 API 金鑰旁邊,依序點選「更多」圖示 >「編輯 API 金鑰」。
在「Application restrictions」下方,完成下列步驟:
- 選取「HTTP 參照網址 (網站)」。
- 在「網站限制」下方,按一下「新增項目」。
- 按一下「Referrer」,然後輸入
*.google.com
。 - 新增其他項目,並輸入
*.googleusercontent.com
做為參照網址。 - 點選「完成」。
在「API 限制」下方,完成下列步驟:
- 選取「限制金鑰」。
在「選取 API」專區中選取「Google Picker API」,然後按一下「確定」。
注意:您必須先啟用 Google Picker API,因為清單只會顯示已為 Cloud 專案啟用的 API。
在「API 金鑰」下方,按一下「複製到剪貼簿」圖示 。
按一下底部的 [儲存]。