设计节点的用户界面
大多数节点是 API 的 GUI(图形用户界面)表示。设计界面意味着找到一种用户友好的方式来表示 API 端点和参数。将整个 API 直接翻译为节点中的表单字段可能不会带来良好的用户体验。
本文档提供设计指导和应遵循的标准。这些指导原则与 n8n 使用的指导原则相同。这有助于为混合使用社区节点和内置节点的用户提供平滑一致的用户体验。
设计指导
所有节点都使用 n8n 的 node UI elements,因此您无需考虑颜色、边框等样式细节。然而,完成基本的设计过程仍然很有用:
- 查看您正在集成的 API 的文档。问问自己:
- 您可以省略什么?
- 您可以简化什么?
- API 的哪些部分令人困惑?您如何帮助用户理解它们?
- 使用线框工具尝试您的字段布局。如果您发现您的节点有很多字段并且变得令人困惑,请考虑 n8n 关于显示和隐藏字段的指导。
标准
UI 文本样式
| 元素 | 样式 |
|---|---|
| 下拉值 | 标题大小写 |
| 提示 | 句子大小写 |
| 信息框 | 句子大小写。对于单句信息不要使用句号(.)。如果有多个句子,始终使用句号。此字段可以包含链接,应在新标签中打开。 |
| 节点名称 | 标题大小写 |
| 参数名称 | 标题大小写 |
| 副标题 | 标题大小写 |
| 工具提示 | 句子大小写。对于单句工具提示不要使用句号(.)。如果有多个句子,始终使用句号。此字段可以包含链接,应在新标签中打开。 |
UI 文本术语
- 使用与节点连接的服务相同的术语。例如,Notion 节点应该引用 Notion 块,而不是 Notion 段落,因为 Notion 称这些元素为块。此规则有例外,通常是为了避免技术术语(例如,请参阅关于更新插入操作的名称和描述的指导)。
- 有时服务在其 API 和 GUI 中对某些东西有不同的术语。在您的节点中使用 GUI 语言,因为这是大多数用户熟悉的。如果您认为某些用户可能需要参考服务的 API 文档,请考虑在提示中包含此信息。
- 当有更简单的替代方案时,不要使用技术术语。
- 命名时要保持一致。例如,选择
directory或folder之一,然后坚持使用它。
节点命名约定
| 约定 | 正确 | 错误 |
|---|---|---|
| 如果节点是触发器节点, 显示名称应在末尾有 'Trigger', 前面有一个空格。 |
Shopify Trigger | ShopifyTrigger, Shopify trigger |
| 不要在名称中包含 'node'。 | Asana | Asana Node, Asana node |
显示和隐藏字段
字段可以:
- 在节点打开时显示:用于资源和操作,以及必需字段。
- 隐藏在可选字段部分中,直到用户点击该部分:用于可选字段。
逐步披露复杂性:隐藏字段,直到它依赖的任何早期字段有值。例如,如果您有一个按日期过滤切换开关和一个要过滤的日期日期选择器,不要显示要过滤的日期,直到用户启用按日期过滤。
按字段类型划分的约定
凭据
n8n 会自动将凭据字段显示为节点顶部的字段。
资源和操作
API 通常会对数据执行某项操作。例如,“获取所有任务”。在此示例中,“任务”是资源,“获取全部”是操作。
当节点采用这种资源和操作模式时,第一个字段应为 Resource 资源,第二个字段应为 Operation 操作。
必填字段
按以下顺序排列字段:
- 从最重要到最不重要。
- 范围从宽泛到具体。例如,如果有 Document 文档、Page 页面和 Text to insert 要插入的文本字段,请按此顺序排列。
可选字段
- 按字母顺序排列字段。可以通过重命名将相似字段分组。例如,将 Email 邮箱和 Secondary Email 备用邮箱重命名为 Email (primary) 主邮箱和 Email (secondary) 备用邮箱。
- 如果可选字段未设置时节点会使用默认值,请在字段中预先填入该值,并在字段说明中注明,例如 Defaults to false 默认为 false。
- 关联字段:如果一个可选字段依赖另一个字段,请将它们组合在一起。两者应归入同一个选项,选择该选项时同时显示。
- 如果可选字段很多,请考虑按主题分组。
帮助
GUI 内置五种帮助形式:
- 信息框:出现在字段之间的黄色框。请参阅 UI elements | Notice 了解更多信息。
- 使用信息框呈现必要信息,但不要滥用。信息框越少见,就越醒目,也越能吸引用户注意。
- 参数提示:显示在用户输入字段下方的文本行。适合呈现用户需要了解、但不值得使用信息框的内容。
- 节点提示:在输入面板、输出面板或节点详细信息视图中提供帮助。请参阅 UI elements | Hints 了解更多信息。
- 工具提示:用户将鼠标悬停在工具提示图标
上时显示的标注。可用它提供用户可能需要的额外信息。- 无需为每个字段提供工具提示。仅当其中包含有用信息时才添加。
- 编写工具提示时,请考虑用户的需求。不要直接复制 API 参数说明;如果说明难以理解或有错误,请改进它。
- 占位符文本:n8n 可以在用户未输入值的字段中显示占位符文本。这可以帮助用户了解该字段需要填写什么。
信息框、提示和工具提示都可以包含指向更多信息的链接。
错误
明确标示哪些字段为必填字段。
如果可能,向字段添加验证规则。例如,如果字段期望电子邮件,请检查有效的电子邮件模式。
显示错误时,确保红色错误标题中只显示主要错误消息。更多信息应放在 Details 详细信息中。
有关更多信息,请参阅节点错误处理。
切换开关
- 二元状态的工具提示应以 Whether to... 是否…… 之类的表述开头。
- 有时应使用列表而不是切换开关:
- 当 false 状态下的行为很明确时,使用切换开关。例如 Simplify Output? 简化输出?,不简化输出这一替代行为很清楚。
- 需要进一步说明时,使用包含命名选项的下拉列表。例如 Append? 追加?,不追加时会发生什么并不明确(可能是什么也不做,也可能覆盖或丢弃信息)。
列表
- 尽可能为列表设置默认值。默认值应为最常用的选项。
- 按字母顺序排列列表选项。
- 可以为列表选项添加说明,但仅在说明能提供有用信息时添加。
- 如果有 All 全部之类的选项,请使用完整单词 All,不要使用 * 之类的简写。
触发节点输入
当触发器节点有一个用于指定触发事件的参数时:
- 将参数命名为 Trigger on 触发条件。
- 不要添加工具提示。
副标题
根据主要参数的值设置副标题。例如:
subtitle: '={{$parameter["operation"] + ": " + $parameter["resource"]}}',
ID
对特定记录执行操作(例如“更新任务评论”)时,需要通过某种方式指定要更改的记录。
- 尽可能提供两种指定记录的方法:
- 从预填充的列表中选择。可以使用
loadOptions参数生成该列表。有关更多信息,请参阅基础文件。 - 输入 ID。
- 从预填充的列表中选择。可以使用
- 将字段命名为
<Record name> name or ID。例如,Workspace Name or ID 工作区名称或 ID。添加工具提示“从列表中选择名称,或使用表达式指定 ID”,并链接到 n8n 的表达式文档。 - 构建节点时,应能处理用户提供超出要求的信息。例如:
- 如果需要相对路径,也要能处理用户粘贴绝对路径的情况。
- 如果用户需要从 URL 获取 ID,也要能处理用户粘贴完整 URL 的情况。
日期和时间戳
n8n 使用 ISO 时间戳字符串表示日期和时间。确保添加的任何日期或时间戳字段都支持所有 ISO 8601 格式。
JSON
对于需要 JSON 的文本输入,应支持两种指定内容的方式:
- 直接在文本输入中键入 JSON:需要将生成的字符串解析为 JSON 对象。
- 使用返回 JSON 的表达式。
节点图标
n8n 建议使用 SVG 作为节点图标,但您也可以使用 PNG。如果使用 PNG,图标分辨率应为 60x60px。节点图标应具有正方形或接近正方形的长宽比。
提示
Don't reference Font Awesome 不要引用 Font Awesome
如果要在节点中使用 Font Awesome 图标,请下载并嵌入该图像。不要设置 defaults.color:它只能为 Font Awesome 图标着色,且 n8n 3.0 已将其移除。
常见模式和异常
本节提供处理常见设计模式的指导,其中包括一些边界情况以及主要标准的例外。
简化响应
API 可能返回大量无用数据。可以考虑添加一个切换开关,让用户选择简化响应数据:
- 名称:Simplify Response 简化响应
- 描述:Whether to return a simplified version of the response instead of the raw data 是否返回响应的简化版本,而不是原始数据
更新插入操作
这应始终作为单独的操作,并使用:
- 名称:Create or Update 创建或更新
- 描述:Create a new record, or update the current one if it already exists (upsert) 创建新记录;如果记录已存在,则更新当前记录(upsert)
布尔运算符
n8n 的 GUI 尚不能很好地组合 AND 和 OR 等布尔运算符。请尽可能提供全 AND 或全 OR 的选项。
例如,如果有一个名为 Must match 必须匹配的字段用于测试值是否匹配,请分别提供 Any 任意和 All 全部选项。
源密钥或二进制属性
二进制数据是电子表格或图像等文件数据。在 n8n 中,需要使用命名键来引用这些数据。不要为此字段使用“二进制数据”或“二进制属性”等术语,而应使用描述性更强的名称:Input data field name 输入数据字段名称 / Output data field name 输出数据字段名称。