编辑器插件的界面样式指南

编辑器插件使用 Apps 脚本的 HTML 服务构建界面(菜单、边栏和对话框)。由于接口是用 HTML 和 CSS 开发的,因此其可自定义程度高。不过,在构建插件界面时,您应该设计此界面以提供出色的用户体验。

优秀的插件可以使用熟悉的控件和行为来自然地扩展每个编辑器。构建新插件时:

  • 在您的 HTML 服务页面中使用插件 CSS 软件包
  • 如果对设计不确定,请在编辑器中找到类似的对话框或边栏,然后将其进行匹配,或者参阅插件快速入门
  • 不妨参考此风格指南,打造顺畅自然的体验。

文字

插件名称

您必须在发布插件时设置该插件的名称。此名称会出现在许多地方,例如插件商店和菜单中。

  • 采用词首字母大写。
  • 除非是品牌元素的一部分,否则请避免使用标点符号,尤其是括号。
  • 尽量简洁,不要超过 30 个字符。长名称可能会被自动截断。
  • 请勿添加该插件所适用的 Google 产品的名称(或使用 Google 一词)。
  • 省略版本信息。
  • 确保该插件的已发布名称与脚本项目的文件名相同。项目名称会显示在授权对话框中。
错误做法 正确做法
插件名称有误 合适的插件名称

写作风格

您不需要编写太多内容。大多数操作都应该通过图标、布局和简短的标签而清晰明了。如果您发现插件的某个部分需要比简短标签更详尽的说明,最好创建一个单独的网页来描述您的插件并链接到该网页。

编写界面文本时:

  • 句首字母大写(尤其是对于按钮、标签和菜单项)。
  • 最好使用不含行话或首字母缩写词的简短文字。
错误做法 正确做法

安装后提示

插件安装后,系统会立即弹出相关安装后提示,还会在“帮助”中显示该提示。有几句话可帮助用户快速上手。

  • 以操作字词开头。
  • 说明使用插件的第一步。
  • 如果您有主界面(例如边栏),请说明如何打开它。
  • 插件已安装完毕,请勿在此处宣传。
错误做法 正确做法
错误的安装后提示 贴心的安装后提示

与常规 Apps 脚本项目不同,插件不会显示在脚本编辑器或脚本管理器中;用户无法直接运行插件脚本。每个插件都会在插件菜单中占据一个位置。菜单(也可能是对话框或边栏)可让用户与插件互动。

  • 菜单是用户控制插件方式的关键部分,因此请谨慎设计其结构和措辞。
  • 避免菜单项简单地重复插件名称。而应从操作字词入手。
  • 如果主菜单项启动了一个工作流程,并且没有一个动词来描述它的用途,请将其称为“Start”。文档插件快速入门中会用到此格式。
  • 除非您的菜单中包含 6 个以上的项,否则请尽量不要使用子菜单。它们可能有些挑逗性,也很难选择。
  • 描述任务,而不是菜单项显示的界面组件。
错误做法 正确做法
菜单项标签有误 良好的菜单项标签

错误消息

出现问题时,请务必使用通俗易懂的语言。从用户的角度说明问题,并建议如何解决问题。

  • 不允许用户查看您的代码抛出的任何异常。请改为使用 try...catch 语句来拦截异常,然后使用插件 CSS 软件包或提醒对话框的 error 类中的内嵌文本样式显示用户轻松的错误消息。
  • 在发布之前,请确保您的插件不会将调试信息记录到 JavaScript 控制台;请改用 Stackdriver Logging
错误做法 正确做法
错误错误消息 合适的错误消息

帮助内容

每个插件的菜单中都包含一个自动“帮助”对话框。如果您在发布时提供帮助网址,“了解详情”按钮会链接到该页面。除非插件一目了然,否则请提供一个页面来说明插件的使用方式。

  • 请尽可能以项目符号列表或编号列表的形式显示说明。明确引用已命名的界面元素,引导用户浏览最终结果。
  • 确保您的说明清楚地解释了所有要求,例如以某种方式设置电子表格。
  • 您也可以从主界面访问帮助内容的链接。 如果您的插件创建了新文档,您还可以在文档正文中显示说明。

自定义界面

一些简单的编辑器插件可以完全由其菜单控制,但大多数插件会显示包含自定义内容的边栏或对话框

  • 边栏最适合用户在引用文档或电子表格内容时可能会重复使用的常驻工具。
  • 对话框最适合一次性工具、设置页面和重要邮件。

界面文字

在任何对话框或边栏中,假设用户只会阅读标题和按钮标签。 他们是否仍然可以弄清楚您的界面的用途并做出正确的选择?

  • 使用独立的标题和按钮标签。
  • 避免使用冗长的描述性文本块。

对话框

对话框非常适合那些只用过一次,然后就不再使用的工具。例如,如果您的插件允许用户插入图形,系统可能会显示一个对话框,供您选择要插入的内容,然后在插入图形时关闭对话框。对话框还有助于显示插件的设置或传达重要消息。

  • 请勿从其他对话框打开对话框(包括提醒或提示),一次只显示一个对话框。
  • 对于对话框标题,请使用以最重要的字词开头的字词或短语。
  • 按钮标签应与对话框标题相关。
  • 首选两个按钮,通常一个是主要操作,另一个是“取消”。对于需要第三个按钮的特殊情况,请考虑使用右下角的。
  • 将按钮放在对话框的左下角。蓝色的主按钮应位于左侧,所有灰色的辅助按钮应位于右侧。
错误做法 正确做法
对话框标题无效 对话框标题不错

边栏可以在做出选择时回头查阅文档、电子表格、演示文稿或表单。此外,用户还可以反复使用您的插件。 每当用户打开新的边栏时,之前的所有边栏都会自动关闭。 它们最适合用户在操作完成后退出的临时模式。

  • 用户可能拥有其他附加了自己边栏的插件。如果两个插件尝试同时打开边栏,系统只会显示一个插件。
  • 首次打开文档时不显示边栏或对话框。
  • 只有在 AuthMode.FULL 中运行的插件才能打开边栏或对话框。您可以使用菜单项打开边栏,因为这会提示用户提供完整授权。

控件

出色的插件界面会为控件留出一些空间。足够的外边距和内边距会大有助益,而密集的控件可能会让人感觉不堪重负。如有疑问,可借用编辑器本身的布局。例如,您在创建自己的对话框时,可以查看 Google 文档中的现有对话框,例如文件 > 页面设置

插件 CSS 软件包的相关文档提供了以下每种控件类型的示例标记。

按钮

请使用按钮(而不是普通链接或其他元素)控制界面的主要操作。

  • 避免一次显示多个蓝色、红色或绿色按钮。灰色按钮可能会反复出现。
  • 大多数按钮标签都应采用句首字母大写形式,并以动词开头。红色按钮(通常用于创建操作)应全部使用大写字母。
错误做法 正确做法

复选框和单选按钮

当用户可以选择多个选项或根本不选中任何选项时,使用复选框。当必须选择一个选项时,请使用单选按钮(或选择菜单)。

  • 不要更改复选框的行为以模仿单选按钮。
  • 完成检查后,不要立即采取任何措施。人都会犯错。请等待用户点击某个按钮确认他们的选择。

选择菜单

“选择”是提供简短备选方案的绝佳方式。

  • 按字母顺序或按所有用户都能理解的逻辑架构对选项进行排序(例如,星期几,从星期日开始)。
  • 如果列表过长,请考虑使用其他控件。例如,您可以显示一个可滚动列表,为菜单提供更多空间并简化导航操作。

文本区域

如果用户需要输入多个字词,请使用文本区域。

  • 文本区域至少两行,这样它们更易于使用,并且看起来不像文本字段。
  • 将标签置于顶部。

文本字段

如果用户只需要输入一两个字词,请使用文本字段。

  • 文本字段的宽度应表明您希望用户在其中输入的内容。
  • 避免使用占位符文本作为标签,因为它会在焦点上消失。占位符文本对于提供示例或额外的详细信息非常有用。
  • 将标签放在顶部,但也可以并排布置简短的文本字段。

品牌标示

在您的插件中

如果想加入品牌信息,请确保内容简洁明了。这有助于用户专注于您的界面,并使您的插件看起来像是编辑器的一部分。

  • 插件的所有方面都必须遵循品牌推广指南
  • 请勿包含“Google”一词,也不要使用 Google 产品图标。
  • 文本不应超过几个单词,并且应在插件 CSS 软件包中的 gray 类中设置样式。
  • 图形应采用白色背景,尺寸不超过 200 像素 × 60 像素。
  • 对于对话框,品牌信息应位于右下角。
  • 对于边栏,品牌信息可以位于顶部或底部。

店内

要发布编辑器插件,您需要一些图片素材资源。这些资源用于构建插件商品详情。

无障碍功能

每个人都应该能够享受您的插件,无论他们看到不同颜色、使用屏幕阅读器还是有其他需求。无障碍是一个宽泛的主题,本风格指南并未全面涵盖该主题。Google 无障碍网站就是一项实用资源。但这里有几条提示供您开始着手使用:

  • 确保您可以使用键盘找到所有界面控件。将 tabindex=0 添加到自定义控件(例如使用 <div> 创建的控件)中,以便用户使用 Tab 键转到这些控件。请考虑是否也应支持其他键,例如列表的箭头。
  • 部分用户可能会与您的插件搭配使用屏幕阅读器。因此,图片应具有 alt 属性,而自定义控件应具有 ARIA 属性来描述其用途。
  • 不要仅依靠颜色来传达状态。还可以使用图标和文本。

如果您使用标准 Web 控件(如本指南前面部分所述),使您的插件可供访问更加容易。