设计您的节点用户界面#

大多数节点都是API的图形用户界面(GUI)表示形式。设计界面意味着需要找到一种用户友好的方式来呈现API端点和参数。直接将整个API转换为节点中的表单字段可能无法带来良好的用户体验。

本文档提供了需要遵循的设计指南和标准。这些指南与n8n所使用的保持一致，旨在为同时使用社区节点和内置节点的用户提供流畅且一致的体验。

设计指南#

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

• Review the documentation for the API you're integrating. Ask yourself:
  • 可以省略哪些内容？
  • 你能简化什么？
  • API的哪些部分令人困惑？您如何帮助用户理解它们？
• 使用线框图工具来测试您的字段布局。如果您发现节点包含过多字段且变得混乱，请参考n8n关于显示和隐藏字段的指南。

标准#

界面文本样式#

界面文本术语#

• 使用与节点连接的服务相同的术语。例如，Notion节点应引用Notion块(blocks)而非Notion段落(paragraphs)，因为Notion官方将这些元素称为块。此规则存在例外情况，通常是为了避免技术术语（例如，请参考upsert操作的名称和描述指南）。
• 有时某个服务在其API和图形界面中对同一事物的表述不同。在节点中使用图形界面的术语，因为大多数用户更熟悉这些表述。如果您认为部分用户可能需要参考该服务的API文档，可以考虑在提示信息中包含这些内容。
• 在有更简单的替代词时，不要使用技术术语。
• 命名时保持一致性。例如，在directory或folder中选择一个后坚持使用。

节点命名规范#

显示和隐藏字段#

字段可以是以下两种类型之一：

• 节点打开时显示：用于资源和操作，以及必填字段。
• 隐藏在可选字段部分，直到用户点击该部分：用于可选字段。

渐进式展示复杂性：在依赖的前置字段有值之前隐藏某个字段。例如，如果您有一个按日期筛选开关和一个筛选日期日期选择器，在用户启用按日期筛选之前不要显示筛选日期。

按字段类型的约定#

凭证#

n8n 自动将凭证字段显示为节点中的顶部字段。

资源与操作#

API通常涉及对数据进行某些操作。例如，"获取所有任务"。在这个例子中，"任务"是资源，"获取所有"是操作。

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

必填字段#

按以下方式排序字段：

• 从最重要到最不重要。
• 范围：从宽泛到具体。例如，如果有文档、页面和待插入文本字段，请按此顺序排列。

可选字段#

• 按字母顺序排列字段。为了将相似内容归类，您可以对它们进行重命名。例如，将Email和Secondary Email重命名为Email (主邮箱)和Email (备用邮箱)。
• 如果可选字段具有节点在未设置值时使用的默认值，则使用该值加载字段。在字段描述中说明这一点。例如，默认为 false。
• 关联字段：如果一个可选字段依赖于另一个字段，则将它们捆绑在一起。它们应位于同一选项下，当选中该选项时同时显示这两个字段。
• 如果有很多可选字段，建议按主题进行分组。

帮助#

图形用户界面内置了五种帮助类型：

• 信息框：字段之间显示的黄色方框。更多信息请参阅UI elements | Notice。
• 对于关键信息使用信息框。不要过度使用。通过减少使用频率，它们会更加突出并吸引用户的注意力。
• 参数提示：显示在用户输入字段下方的文本行。当用户需要了解某些信息，但使用信息框显得过于繁琐时，可使用此功能。
• 节点提示：在输入面板、输出面板或节点详情视图中提供帮助。更多信息请参阅UI元素 | 提示。
• 工具提示：当用户悬停在提示图标上时出现的标注框。使用工具提示来提供用户可能需要额外信息。
• 您无需为每个字段都提供提示信息。仅当包含有用信息时才添加。
• 编写工具提示时，需考虑用户实际需求。不要直接复制粘贴API参数描述。如果描述含义不清或存在错误，请进行优化改进。
• 占位文本：n8n可以在用户未输入值的字段中显示占位文本。这有助于用户了解该字段预期的输入内容。

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

错误#

明确哪些字段是必填的。

如果可能，为字段添加验证规则。例如，如果字段需要电子邮件，检查是否符合有效的电子邮件格式。

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

切换开关#

• 二进制状态的工具提示应以类似是否要...的表述开头。
• You may need a list rather than a toggle:
  • 当明确知道关闭状态会发生什么时，使用切换开关。例如简化输出？。其替代选项（不简化输出）的含义很清晰。
  • 当需要更清晰时，使用带有命名选项的下拉列表。例如追加？。如果不追加会发生什么并不明确（可能是没有任何操作，或者信息被覆盖，或者被丢弃）。

列表#

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

触发器节点输入#

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

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

字幕#

根据主参数的值设置字幕。例如：

1

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

ID#

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

• Wherever possible, provide two ways to specify a record:
  • 从预填充列表中选择。您可以使用loadOptions参数生成此列表。更多信息请参阅基础文件。
  • 通过输入ID。
• 将字段命名为<记录名称> name or ID。例如，工作区名称或ID。添加提示说明"从列表中选择名称，或使用表达式指定ID"。链接到n8n的表达式文档。
• Build your node so that it can handle users providing more information than required. For example:
  • 如果需要相对路径，需处理用户粘贴的绝对路径。
  • 如果用户需要从URL中获取ID，处理用户粘贴整个URL的情况。

日期与时间戳#

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

JSON#

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

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

节点图标#

常见模式与异常情况#

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

简化响应#

API可能会返回大量无用的数据。考虑添加一个切换选项，让用户可以选择简化响应数据：

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

更新插入操作#

这应该始终是一个独立操作:

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

布尔运算符#

n8n在图形界面中对组合布尔运算符（如AND和OR）的支持不够完善。在可能的情况下，请提供全AND或全OR的选项。

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

源键或二进制属性#

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