編輯器外掛程式的對話方塊和側欄

對於大多數編輯器外掛程式,對話方塊視窗和側邊欄面板是主要的外掛程式使用者介面。這兩種介面都能使用標準 HTML 和 CSS 進行完全自訂,您也可以在使用者與側欄或對話方塊互動時,使用 Apps Script 的用戶端-伺服器通訊模式來執行 Apps Script 函式。外掛程式可以定義多個側邊欄和對話方塊,但一次只能顯示一個。

如果您想在使用者在外掛程式介面中做出選擇之前,禁止他們與編輯器互動,請使用對話方塊;否則請使用側欄。

對話方塊

對話方塊是覆蓋主要編輯器內容的視窗面板。Apps Script 對話方塊是模式對話方塊,在對話方塊開啟時,使用者無法與編輯器介面的其他元素互動。您可以自訂對話方塊的內容和大小。

您可以使用與 Apps Script 自訂對話方塊相同的方式建構外掛程式對話方塊;一般建議的程序如下:

  1. 建立指令碼專案檔案,定義對話方塊的 HTML 結構、CSS 和用戶端 JavaScript 行為。定義對話方塊時,請參閱編輯器外掛程式樣式規範
  2. 在您要開啟對話方塊的伺服器端程式碼中,請呼叫 HtmlService.createHtmlOutputFromFile(filename) 來建立代表對話方塊的 HtmlOutput 物件。或者,如果您使用範本 HTML,可以呼叫 HtmlService.createTemplateFromFile(filename) 產生範本,然後呼叫 HtmlTemplate.evaluate() 將其轉換為 HtmlOutput 物件。
  3. 呼叫 Ui.showModalDialog(htmlOutput, dialogTitle) 即可使用該 HtmlOutput 顯示對話方塊。

對話方塊在開啟時不會暫停伺服器端指令碼。用戶端 JavaScript 可以使用 google.script.run() 和相關聯的處理常式函式,對伺服器端進行非同步呼叫。詳情請參閱「用戶端對伺服器通訊」。

檔案開啟對話方塊

檔案開啟對話方塊是預先建構的對話方塊,可讓使用者從 Google 雲端硬碟中選取檔案。您可以將檔案開啟對話方塊新增至外掛程式,而無須自行設計,但需要進行一些額外設定。您還必須具備外掛程式的 Cloud Platform 專案存取權,才能啟用 Google Picker API。

詳情請參閱「檔案開啟對話方塊」一文。

側欄是顯示在編輯器介面右側的面板,也是最常見的附加元件介面類型。與對話方塊不同,您可以在側欄開啟時繼續與編輯器介面的其他元素互動。側欄的寬度固定,但您可以自訂側欄內容。

建構外掛程式側欄的方式與 Apps Script 自訂側欄相同;一般建議的程序如下:

  1. 建立定義側欄 HTML 結構、CSS 和用戶端 JavaScript 行為的腳本專案檔案。定義側欄時,請參閱編輯器外掛程式樣式規範
  2. 在您要開啟側欄的伺服器端程式碼中,請呼叫 HtmlService.createHtmlOutputFromFile(filename) 來建立代表側欄的 HtmlOutput 物件。或者,如果您使用範本 HTML,可以呼叫 HtmlService.createTemplateFromFile(filename) 產生範本,然後呼叫 HtmlTemplate.evaluate() 將其轉換為 HtmlOutput 物件。

  3. 呼叫 Ui.showSidebar(htmlOutput) 即可使用該 HtmlOutput 顯示側欄。

側邊欄不會在開啟時暫停伺服器端指令碼。用戶端 JavaScript 可以使用 google.script.run() 和相關聯的處理常式函式,對伺服器端進行非同步呼叫。詳情請參閱「用戶端對伺服器通訊」。