編輯器外掛程式的 UI 樣式指南

編輯器外掛程式可使用 Apps Script 的 HTML 服務建構使用者介面 (選單、側欄和對話方塊)。由於介面是以 HTML 和 CSS 開發，因此可高度自訂。不過，建構外掛程式介面時，您應設計出能提供絕佳使用者體驗的介面。

最佳外掛程式會使用熟悉的控制項和行為，自然地擴充每個編輯器。建構新外掛程式時：

文字

外掛程式名稱

發布外掛程式時，您必須設定外掛程式的名稱。名稱會顯示在許多位置，例如外掛程式商店和選單中。

  • 使用標題大小寫格式。
  • 除非是品牌名稱的一部分，否則請避免使用標點符號，尤其是括號。
  • 請簡短扼要，最好不要超過 30 個半形字元。系統可能會自動截斷長名稱。
  • 請勿加入外掛程式適用的 Google 產品名稱 (或使用「Google」一詞)。
  • 請勿提供版本資訊。
  • 請確認外掛程式的發布名稱與指令碼專案的檔案名稱相同。授權對話方塊中會顯示專案名稱。
錯誤做法 正確做法
不正確的外掛程式名稱 適當的外掛程式名稱

書寫風格

您不必寫太多內容，大多數動作應透過圖示、版面配置和簡短標籤清楚呈現。如果您發現某些外掛程式需要更詳細的說明，而短標籤無法提供足夠的資訊，建議您建立另一個網頁來說明外掛程式，並提供連結。

編寫 UI 文字時：

  • 使用句子大小寫 (尤其是按鈕、標籤和選單項目)。
  • 請使用簡短、簡單的文字，避免使用專業術語或縮寫字詞。
錯誤做法 正確做法

安裝後提示

使用者安裝外掛程式後，系統會立即顯示安裝後提示，並顯示在說明中。您有幾句話可以協助使用者快速上手。

  • 請先說出動作字詞。
  • 說明使用外掛程式的首要步驟。
  • 如果您有主要 UI (例如側欄)，請說明如何開啟。
  • 請勿在此處宣傳外掛程式，因為它已安裝。
錯誤做法 正確做法
安裝完成後顯示的提示錯誤 安裝完成後的實用提示

與一般 Apps Script 專案不同，外掛程式不會顯示在指令碼編輯器或指令碼管理工具中，使用者也無法直接執行外掛程式。而是讓每個外掛程式在外掛程式選單中顯示。選單 (以及可能的對話方塊或側欄) 可讓使用者與外掛程式互動。

  • 使用者控制外掛程式的方式，取決於這個選單，因此請仔細設計選單的結構和用詞。
  • 請勿使用重複擴充功能名稱的選單項目。請改為以動作字詞開頭。
  • 如果主選單項目會啟動工作流程，但沒有單一動詞可描述其功能，請將其命名為「Start」。Google 文件外掛程式快速入門會使用這個模式。
  • 除非選單內含六個以上的項目，否則請盡量不要使用子選單。這些元素可能很難選取。
  • 請說明任務，而非選單項目顯示的 UI 元件。
錯誤做法 正確做法
不正確的選單項目標籤 良好的選單項目標籤

錯誤訊息

發生問題時，請務必使用平實的語言。從使用者的角度說明問題，並建議如何修正。

  • 請勿允許使用者查看程式碼擲回的任何例外狀況。請改用 try...catch 陳述式來攔截例外狀況，然後顯示使用者友善的錯誤訊息，其中內嵌文字的樣式採用外掛程式 CSS 套件或警告對話方塊中的 error 類別。
  • 發布前，請確認外掛程式不會將偵錯資訊記錄到 JavaScript 主控台；請改用 Stackdriver 記錄。
錯誤做法 正確做法
錯誤的錯誤訊息 良好的錯誤訊息

教學型內容

每個外掛程式的選單都會自動顯示說明對話方塊。如果您在發布時提供說明網址，「瞭解詳情」按鈕就會連結至該網頁。除非外掛程式不需說明，否則請提供說明如何使用的網頁。

  • 盡可能以項目符號或編號清單顯示操作說明。引導使用者完成整個流程，並明確參照已命名的 UI 元素。
  • 請務必在操作說明中清楚說明任何必要條件，例如以特定方式設定試算表。
  • 您也可以在主要使用者介面中連結至說明內容。 如果外掛程式建立新文件，您也可以在文件的內文中顯示操作說明。

自訂使用者介面

部分簡單的編輯器外掛程式可完全透過選單控制，但大多數外掛程式會顯示含有自訂內容的側邊欄或對話方塊。

  • 側欄最適合用於使用者在參照文件或試算表內容時，可能會重複使用的持續性工具。
  • 對話方塊最適合用於單次使用工具、設定頁面和重要訊息。

UI 文字

在任何對話方塊或側欄中，假設使用者只會閱讀標題和按鈕標籤。他們是否仍能瞭解介面的作用，並做出明智的選擇？

  • 使用獨立的標題和按鈕標籤。
  • 避免使用長篇幅的說明文字。

對話方塊

對話方塊非常適合使用者只使用一次的工具。舉例來說，如果外掛程式可讓使用者插入圖片，您可以顯示對話方塊，讓使用者選擇要插入的內容，然後在插入圖片時關閉對話方塊。對話方塊也能用於顯示外掛程式的設定，或傳達重要訊息。

  • 請勿透過其他對話方塊開啟對話方塊 (包括警告或提示)，一次只顯示一個對話方塊。
  • 對話方塊標題應使用單字或短短的詞組，並以最重要的字詞開頭。
  • 按鈕標籤應與對話方塊標題相關。
  • 建議使用兩個按鈕，通常是主要動作和「取消」。如需第三個按鈕的特殊情況，請考慮使用右下角。
  • 將按鈕放在對話方塊的左下角。藍色主要按鈕應位於左側，灰色次要按鈕則位於右側。
錯誤做法 正確做法
對話方塊標題不正確 良好的對話方塊標題

使用者在做出選擇時，可透過側欄參照文件、試算表、簡報或表單。使用者也可以多次使用你的外掛程式。每當您開啟新的側欄時，任何先前的側欄都會自動關閉。這類模式最適合用於使用者使用完畢後會離開的暫時模式。

  • 使用者可能會安裝其他附加元件，這些附加元件可能會使用自己的側邊欄。如果兩個外掛程式嘗試同時開啟側欄，系統只會顯示一個。
  • 在文件首次開啟時，請勿顯示側欄或對話方塊。
  • 只有在 AuthMode.FULL 中運作的外掛程式，才能開啟側欄或對話方塊。您可以使用選單項目開啟側欄，因為這會提示使用者提供完整授權。

控制項

優質的擴充功能 UI 會為控制項預留一些空間，適當的邊界和邊框間距有助於改善使用者體驗，但密集的控制項可能會讓使用者感到不知所措。如有疑問，請從編輯器中借用版面配置。舉例來說，建立對話方塊時，請參考 Google 文件中現有的對話方塊，例如「檔案」>「頁面設定」。

外掛程式 CSS 套件的說明文件提供下列每種控制項類型的範例標記。

按鈕

請使用按鈕控制使用者介面的主要動作，而非使用純連結或其他元素。

  • 請避免一次顯示多個藍色、紅色或綠色按鈕。灰色按鈕可能會重複顯示。
  • 大部分按鈕標籤應使用句子大小寫，並以動詞開頭。紅色按鈕 (通常用於建立動作) 應使用全大寫字母。
錯誤做法 正確做法

核取方塊和圓形按鈕

當使用者可以選取多個選項或不選取任何選項時，請使用核取方塊。如需選取單一選項，請使用單選按鈕 (或選取式選單)。

  • 請勿變更核取方塊的行為，以模仿圓形按鈕。
  • 請勿在檢查後立即採取任何行動。人難免會犯錯。請等待使用者按下按鈕確認選擇。

選取選單

選取功能是提供替代方案的絕佳方式。

  • 請按照字母順序或所有使用者都能理解的邏輯排序 (例如星期幾，從星期日開始)。
  • 如果清單過長，建議您使用其他控制項。舉例來說，您可以顯示可捲動的清單，為選單提供更多空間，並讓使用者更輕鬆瀏覽。

文字區域

如果使用者需要輸入的文字超過幾個字，請使用文字區域。

  • 文字區域的高度至少要兩行，這樣使用起來會更方便，也不會看起來像文字欄位。
  • 將標籤放在頂端。

文字欄位

如果使用者只需要輸入一兩個字，請使用文字欄位。

  • 文字欄位的寬度應能讓使用者知道您希望他們輸入什麼內容。
  • 請避免使用預留位置文字做為標籤，因為這類文字會在聚焦時消失。預留位置文字可用於提供範例或其他詳細資料。
  • 將標籤放在頂端，但您可以自由排列短文字欄位。

品牌宣傳

在外掛程式中

如要加入品牌資訊，請簡短扼要。這有助於使用者專注於使用者介面，並讓外掛程式看起來像是編輯器的一部分。

  • 外掛程式的所有部分都必須遵守品牌規範。
  • 請勿加入「Google」一詞或使用 Google 產品圖示。
  • 文字應不超過幾個字，並使用外掛程式 CSS 套件的 gray 類別設定樣式。
  • 圖片應使用白色背景，且大小不得超過 200 像素 x 60 像素。
  • 對話方塊的品牌應位於右下角。
  • 在側欄中，品牌資訊可以置於頂端或底部。

在商店內

如要發布編輯器外掛程式，您需要多個圖片素材資源。這些素材資源用於建構外掛程式商店資訊。

  • 商店資訊的所有部分都必須遵循品牌規範。
  • 如要進一步瞭解需要提供的圖片，請參閱圖片規範。

無障礙設定

無論使用者是否有色覺障礙、使用螢幕閱讀器或有其他需求，每個人都應該都能使用您的外掛程式。無障礙設計是一個廣泛的議題，本風格指南無法完全涵蓋。Google 無障礙中心網站是相當實用的資源。不過，以下提供一些入門秘訣：

  • 請確認您可以使用鍵盤瀏覽所有 UI 控制項。將 tabindex=0 新增至自訂控制項 (例如使用 <div> 建立的控制項)，方便使用者按一下即可前往該控制項。請考慮是否也應支援其他按鍵，例如清單的箭頭。
  • 有些使用者可能會在使用外掛程式時搭配螢幕閱讀器。因此，圖片應具備 alt 屬性，自訂控制項則應具備 ARIA 屬性，以便說明其用途。
  • 請勿只依靠顏色來傳達狀態。也要使用圖示和文字。

如果您使用本指南前述的標準網頁控制項，就能更輕鬆地讓外掛程式更易於存取。