Skip to content

设计节点的用户界面#

大多数节点是 API 的 GUI（图形用户界面）表示。设计界面意味着找到一种用户友好的方式来表示 API 端点和参数。将整个 API 直接翻译为节点中的表单字段可能不会带来良好的用户体验。

本文档提供设计指导和应遵循的标准。这些指导原则与 n8n 使用的指导原则相同。这有助于为混合使用社区节点和内置节点的用户提供平滑一致的用户体验。

设计指导#

所有节点都使用 n8n 的节点 UI 元素，因此您无需考虑颜色、边框等样式细节。但是，经历基本的设计过程仍然很有用：

  • 查看您正在集成的 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 通常涉及对数据做某些事情。例如，"获取所有任务"。在这个例子中，"任务"是资源，"获取所有"是操作。

当您的节点具有此资源和操作模式时，您的第一个字段应该是资源，第二个字段应该是操作。

必需字段#

按以下方式排序字段：

  • 从最重要到最不重要。
  • 范围：从宽泛到狭窄。例如，您有文档、页面和要插入的文本字段，按该顺序放置它们。

可选字段#

  • 按字母顺序排序字段。要将相似的事物组合在一起，您可以重命名它们。例如，将电子邮件和辅助电子邮件重命名为电子邮件（主要）和电子邮件（辅助）。
  • 如果可选字段有一个节点在未设置值时使用的默认值，请使用该值加载字段。在字段描述中解释这一点。例如，默认为 false。
  • 连接字段：如果一个可选字段依赖于另一个，将它们捆绑在一起。它们都应该在选择时显示两个字段的单个选项下。
  • 如果您有很多可选字段，请考虑按主题对它们进行分组。

帮助#

GUI 中内置了五种类型的帮助：

  • 信息框：出现在字段之间的黄色框。有关更多信息，请参阅 UI 元素 | 通知。
  • 将信息框用于基本信息。不要过度使用它们。通过使它们稀少，它们更突出并抓住用户的注意力。
  • 参数提示：显示在用户输入字段下方的文本行。当用户需要知道某些事情，但信息框会过度时使用此功能。
  • 节点提示：在输入面板、输出面板或节点详细信息视图中提供帮助。有关更多信息，请参阅 UI 元素 | 提示。
  • 工具提示：当用户悬停在工具提示图标 "工具提示图标的屏幕截图。图标是灰色圆圈中的 ?" 上时出现的标注。将工具提示用于用户可能需要的额外信息。
  • 您不必为每个字段提供工具提示。只有在包含有用信息时才添加一个。
  • 编写工具提示时，考虑用户需要什么。不要只是复制粘贴 API 参数描述。如果描述没有意义或有错误，请改进它。
  • 占位符文本：n8n 可以在用户未输入值的字段中显示占位符文本。这可以帮助用户知道该字段中期望什么。

信息框、提示和工具提示可以包含指向更多信息的链接。

错误#

明确哪些字段是必需的。

如果可能，向字段添加验证规则。例如，如果字段期望电子邮件，请检查有效的电子邮件模式。

显示错误时，确保只有主要错误消息显示在红色错误标题中。更多信息应该放在详细信息中。

切换开关#

  • 二进制状态的工具提示应该以类似是否 . . . 的内容开始。
  • 您可能需要列表而不是切换开关：
    • 当 false 状态下发生的事情很清楚时使用切换开关。例如，简化输出？。替代方案（不简化输出）很清楚。
    • 当您需要更多清晰度时，使用带有命名选项的下拉列表。例如，追加？。如果您不追加会发生什么是不清楚的（可能是什么都不发生，或者信息被覆盖，或者被丢弃）。

列表#

  • 尽可能为列表设置默认值。默认值应该是最常用的选项。
  • 按字母顺序排序列表选项。
  • 您可以包含列表选项描述。只有在提供有用信息时才添加描述。
  • 如果有类似全部的选项，使用单词全部，而不是简写如 ***。

触发器节点输入#

当触发器节点有一个用于指定要触发哪些事件的参数时：

  • 将参数命名为触发于。
  • 不要包含工具提示。

副标题#

根据主要参数的值设置副标题。例如：

1
subtitle: '={{$parameter["operation"] + ": " + $parameter["resource"]}}',

ID#

在对特定记录执行操作时，例如"更新任务评论"，您需要一种方法来指定要更改的记录。

  • 尽可能提供两种指定记录的方式：
    • 通过从预填充列表中选择。您可以使用 loadOptions 参数生成此列表。有关更多信息，请参阅基础文件。
    • 通过输入 ID。
  • 将字段命名为 <记录名称> 名称或 ID。例如，工作区名称或 ID。添加工具提示说"从列表中选择名称，或使用表达式指定 ID"。链接到 n8n 的表达式文档。
  • 构建您的节点，使其能够处理用户提供比所需更多的信息。例如：
    • 如果您需要相对路径，处理用户粘贴绝对路径。
    • 如果用户需要从 URL 获取 ID，处理用户粘贴整个 URL。

日期和时间戳#

n8n 使用 ISO 时间戳字符串表示日期和时间。确保您添加的任何日期或时间戳字段都支持所有 ISO 8601 格式。

JSON#

您应该支持两种指定期望 JSON 的文本输入内容的方式：

  • 直接在文本输入中键入 JSON：您需要将结果字符串解析为 JSON 对象。
  • 使用返回 JSON 的表达式。

节点图标#

常见模式和例外#

本节提供处理常见设计模式的指导，包括一些边缘情况和主要标准的例外。

简化响应#

API 可以返回许多无用的数据。考虑添加一个切换开关，允许用户选择简化响应数据：

  • 名称：简化响应
  • 描述：是否返回响应的简化版本而不是原始数据

更新插入操作#

这应该始终是一个单独的操作，具有：

  • 名称：创建或更新
  • 描述：创建新记录，或如果已存在则更新当前记录（更新插入）

布尔运算符#

n8n 在 GUI 中不能很好地支持组合布尔运算符，如 AND 和 OR。尽可能为所有 AND 或所有 OR 提供选项。

例如，您有一个名为必须匹配的字段来测试值是否匹配。包含测试任意和全部的选项，作为单独的选项。

源键或二进制属性#

二进制数据是文件数据，如电子表格或图像。在 n8n 中，您需要一个命名键来引用数据。不要为此字段使用术语"二进制数据"或"二进制属性"。相反，使用更具描述性的名称：输入数据字段名称 / 输出数据字段名称。