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

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

最佳的外掛程式會透過熟悉的控制項和行為,自然地擴充每個編輯器。建立新的外掛程式時:

文字

外掛程式名稱

您必須在發布時設定外掛程式名稱。這個名稱會顯示在許多地方,例如外掛程式商店和選單中。

  • 使用首字母大寫。
  • 避免使用標點符號,尤其是括號 (除非是品牌的一部分)。
  • 盡量簡短 - 最多不超過 30 個字元。過長的名稱可能會遭到自動截斷。
  • 請勿加入外掛程式的 Google 產品名稱 (或使用 Google 字樣)。
  • 留下版本資訊。
  • 確認外掛程式的發布名稱與指令碼專案的檔案名稱相同。專案名稱會顯示在授權對話方塊中。
錯誤做法 正確做法
外掛程式名稱有誤 良好的外掛程式名稱

寫作風格

不需要您另外撰寫。大多數操作都應透過圖像、版面配置和簡短標籤清楚傳達。如果您發現某些外掛程式需要比短標籤提供的資訊更詳盡,最好的做法是另外建立一個網頁來說明您的外掛程式,並連結到它。

編寫 UI 文字時:

  • 句子應採用句首字母大寫格式 (尤其是按鈕、標籤和選單項目)。
  • 偏好簡短易懂的文字,不含術語或縮寫。
錯誤做法 正確做法

安裝後提示

使用者安裝您的外掛程式後,安裝後提示會彈出,並在「Help」(說明) 中顯示。系統會提供幾個句子,協助使用者快速上手。

  • 以動作字詞開頭。
  • 請說明使用外掛程式的第一步。
  • 如果使用主要 UI (例如側欄),請說明開啟介面。
  • 請勿在此宣傳您的外掛程式,因為您所安裝的外掛程式已安裝。
錯誤做法 正確做法
安裝後的提示錯誤 安裝後實用提示

與一般 Apps Script 專案不同的是,外掛程式不會顯示在指令碼編輯器或指令碼管理工具中,使用者無法直接執行外掛程式指令碼。相反地,每個外掛程式都會在外掛程式選單中獲得一個位置。選單 (可能還有對話方塊或側欄) 可讓使用者與外掛程式互動。

  • 選單是使用者控制外掛程式時的重要部分,因此設計時請謹慎設計。
  • 避免使用只是重複外掛程式名稱的選單項目。而是以動作字詞做為開頭
  • 如果主選單項目開始了工作流程,且沒有說明其用途的單一動詞,請將其命名為「Start」。在文件外掛程式快速入門導覽課程中使用這個模式。
  • 除非選單的項目超過六個,否則請勿使用子選單。因為圖片可能相當精緻又難以選取。
  • 描述工作,而非選單項目顯示的 UI 元件。
錯誤做法 正確做法
選單項目標籤有誤 合適的選單項目標籤

錯誤訊息

發生問題時,請務必使用簡單明瞭的語言。從使用者的角度說明問題,並提供修正建議。

  • 禁止使用者查看程式碼擲回的例外狀況。請改用 try...catch 陳述式攔截例外狀況,再透過外掛程式 CSS 套件或快訊對話方塊,在 error 類別中顯示內嵌文字樣式的使用者訊息。
  • 在發布之前,請確認您的外掛程式不會將偵錯資訊記錄至 JavaScript 控制台;請改用 Stackdriver Logging
錯誤做法 正確做法
錯誤訊息有誤 錯誤訊息品質良好

教學型內容

每個外掛程式選單都包含自動「說明」對話方塊。如果您在發布時提供說明網址,「瞭解詳情」按鈕會連結至該頁面。除非您的外掛程式內容明確易懂,否則請提供說明頁面。

  • 盡可能在項目符號或編號清單中顯示操作說明。請透過明確參照已命名 UI 元素,引導使用者前往最終結果。
  • 請確認您的操作說明清楚說明任何需求,例如以特定方式設定試算表。
  • 也可以從主要使用者介面附上說明內容的連結。 如果外掛程式會建立新文件,您也可以在文件內文中顯示操作說明。

自訂使用者介面

部分簡易的編輯器外掛程式可由其選單完全控管,但大部分會顯示含有自訂內容的側欄或對話方塊

  • 側欄最適合用於持續參照文件或試算表內容,且可能會重複使用的工具。
  • 對話方塊最適合用於單一用途工具、設定頁面及重要郵件。

使用者介面文字

在對話方塊或側欄中,假設使用者只會閱讀標題和按鈕標籤。他們仍然可以找出介面功能並做出合適的選擇嗎?

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

對話方塊

對話方塊非常適合使用者在使用一次後繼續使用的工具。舉例來說,如果外掛程式可讓使用者插入圖形,您可能會看見一個對話方塊,其中包含要插入 AS 的內容,並在插入圖像時關閉對話方塊。對話方塊也可用來顯示外掛程式的設定,或傳達重要訊息。

  • 請勿從其他對話方塊開啟對話方塊 (包括快訊或提示),一次只顯示一個對話方塊。
  • 對話方塊標題應使用字詞或詞組,並在開頭加入最重要的字詞。
  • 按鈕標籤應與對話方塊標題相關。
  • 偏好使用兩個按鈕,通常是主要動作和「取消」。如果是需要第三個按鈕的特殊情況,請考慮使用右下角。
  • 將按鈕放在對話方塊左下角。藍色主要按鈕應在左側,右側有灰色的次要按鈕。
錯誤做法 正確做法
對話方塊標題錯誤 良好的對話方塊標題

側欄可讓使用者在做出選擇時,回頭參考自己的文件、試算表、簡報或表單。還能讓使用者反覆使用您的外掛程式。 使用者開啟新的側欄時,先前的所有側欄都會自動關閉。 最適合用於暫時模式,讓使用者在完成時會離開。

  • 使用者可能擁有其他含有自己側欄的外掛程式。如果兩個外掛程式同時嘗試開啟側欄,則只會顯示一個。
  • 不要在首次開啟文件時顯示側欄或對話方塊。
  • 只有在 AuthMode.FULL 中運作的外掛程式才能開啟側欄或對話方塊。由於系統會提示使用者提供完整授權,因此您可以使用選單項目開啟側欄。

控制選項

優質的外掛程式使用者介面可讓你控制房間的顯示空間。維持足夠的邊界和邊框間距會很有幫助,較密集的控制項可能會讓人眼花撩亂。如有疑問,請從編輯器借用版面配置。舉例來說,在自行建立對話方塊時,請查看 Google 文件中現有的對話方塊,例如「File」>「Page setup」

外掛程式 CSS 套件的說明文件針對以下各個控制項類型提供標記範例。

按鈕

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

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

核取方塊和圓形按鈕

當使用者可以選取多個選項時,請使用核取方塊,或完全不選取任何選項。必須選取一個選項時,請使用圓形按鈕 (或選取選單)。

  • 請勿變更核取方塊的行為來模仿圓形按鈕。
  • 檢查完成後,不要立即執行任何動作。人類會犯錯,等待使用者點選按鈕確認選擇為止。

選取選單

精選項目是列出一系列替代方案的絕佳方式。

  • 按字母順序或依所有使用者能瞭解的邏輯配置排序選項 (例如星期幾,從週日開始)。
  • 如果名單過長,請考慮改用其他控制項。舉例來說,您可以顯示可捲動的清單,為選單提供更多空間,讓使用者更容易瀏覽。

文字區域

如果使用者需要輸入多個字詞,請使用文字區域。

  • 將文字區域高度控制在至少兩行高,這樣不僅易於使用,也不會看起來像文字欄位。
  • 將地點標籤置於頂端。

文字欄位

如果客戶只需要輸入一兩個字詞,則使用文字欄位。

  • 文字欄位的寬度應指出您希望使用者輸入的內容。
  • 避免使用預留位置文字做為標籤,因為預留位置文字會在焦點上消失。預留位置文字很適合用來提供範例或額外細節。
  • 將標籤置於頂端,但您可以隨心所欲排列簡短的文字欄位。

品牌宣傳

你的外掛程式

如要加入品牌宣傳元素,請保持簡潔明瞭。這有助於使用者專注於您的 UI,讓您的外掛程式看起來就像編輯器的一部分。

  • 外掛程式的所有層面都必須符合品牌宣傳指南
  • 請勿加入「Google」一詞或使用 Google 產品圖示。
  • 在外掛程式 CSS 套件的 gray 類別中,文字不得超過幾個字詞及樣式。
  • 圖片應採用白色背景,且不得超過 200 × 60 像素。
  • 對對話方塊而言,品牌宣傳內容應位於右下角。
  • 使用側欄時,品牌宣傳可安排在頂端或底端,

在店內

如要發布編輯器外掛程式,您需要多種圖片素材資源。這些素材資源可用來建構外掛程式的商店資訊。

無障礙功能

無論是不同顏色、使用螢幕閱讀器還是有其他需求,每個人都應該要能盡情使用外掛程式。無障礙設計是很廣泛的主題,完全無法在此樣式指南中完整說明。Google 無障礙中心網站是一個實用資源。以下提供幾個入門訣竅:

  • 確認你可以使用鍵盤前往所有 UI 控制項。將 tabindex=0 新增至自訂控制項 (例如使用 <div> 建立的控制項),讓使用者可以使用 Tab 鍵移至這些控制項。請考慮是否也應支援其他鍵,例如清單的箭頭。
  • 有些人可能會搭配螢幕閱讀器使用你的外掛程式。因此,圖片應有 alt 屬性,自訂控制項也應具備 ARIA 屬性來說明其用途。
  • 請勿只透過顏色傳達狀態。你也可以使用圖示和文字。

如果您使用標準網站控制項 (例如本指南先前提到的這些控制項),外掛程式就能更輕鬆地存取。