设计节点的用户界面

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

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

设计指导

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

• 查看您正在集成的 API 的文档。问问自己：
  • 哪些部分可以省略？
  • 哪些部分可以简化？
  • API 的哪些部分比较容易混淆？如何帮助用户理解这些部分？
• 使用线框工具尝试字段布局。如果您发现节点包含太多字段，并且容易混淆，请参考 n8n 关于显示和隐藏字段的指南。

标准

UI文本样式

UI 文本术语

• 使用与节点所连接服务相同的术语。例如，Notion 节点应引用 Notion 块，而不是 Notion 段落，因为 Notion 将这些元素称为块。此规则也有例外，通常是为了避免使用技术术语（例如，请参阅有关 upsert 操作的名称和描述的指南）。
• 有时，服务在其 API 和 GUI 中对某些内容使用不同的术语。请在您的节点中使用 GUI 语言，因为这是大多数用户熟悉的语言。如果您认为某些用户可能需要参考服务的 API 文档，请考虑在提示中包含此信息。
• 当有更简单的替代方案时，不要使用技术术语。
• 命名时要保持一致。例如，选择一个，或者坚持使用一个。

节点命名约定

显示和隐藏字段

字段可以是：

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

逐步揭示复杂性：隐藏某个字段，直到它所依赖的任何先前字段都有值为止。例如，如果您有一个“按日期过滤”切换开关和一个“按日期选择器过滤的日期”，则在用户启用“按日期过滤”之前，不要显示“按日期过滤的日期” 。

按字段类型划分的约定

证书

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

资源和运营

API 通常涉及对数据执行某些操作。例如，“获取所有任务”。在此示例中，“任务”是资源，“获取所有”是操作。

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

必填字段

字段排序依据：

• 从最重要到最不重要。
• 范围：从广到窄。例如，您有“文档” 、 “页面”和“要插入的文本”字段，请按此顺序排列。

可选字段

• 按字母顺序排列字段。要将相似的字段归为一组，您可以重命名它们。例如，将“电子邮件”和“辅助电子邮件”重命名为“电子邮件（主要）”和“电子邮件（辅助）” 。
• 如果可选字段具有默认值，且节点在未设置该值时使用该默认值，则使用该值加载该字段。请在字段描述中说明这一点。例如，默认为 false 。
• 关联字段：如果一个可选字段依赖于另一个可选字段，请将它们捆绑在一起。它们应该都放在一个选项下，选中时会同时显示这两个字段。
• 如果您有很多可选字段，请考虑按主题对它们进行分组。

帮助

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

• 信息框：字段之间出现的黄色框。更多信息请参阅UI 元素 | 注意事项。
• 使用信息框来显示重要信息。不要过度使用。减少信息框的数量，可以让它们更加突出，从而吸引用户的注意力。
• 参数提示：显示在用户输入字段下方的文本行。当用户需要了解某些信息，但信息框又显得多余时，可以使用此参数。
• 节点提示：在输入面板、输出面板或节点详情视图中提供帮助。更多信息请参阅UI 元素 | 提示。
• 工具提示：当用户将鼠标悬停在工具提示图标上时出现的标注。使用工具提示来获取用户可能需要的额外信息。
• 您无需为每个字段都提供工具提示。仅当其包含有用信息时才添加。
• 编写工具提示时，请思考用户的需求。不要只是复制粘贴 API 参数描述。如果描述不合理或有错误，请进行改进。
• 占位符文本：n8n 可以在用户未输入值的字段中显示占位符文本。这可以帮助用户了解该字段的预期内容。

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

错误

明确哪些字段是必填的。

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

显示错误时，请确保红色错误标题中仅显示主要错误消息。更多信息请见“详细信息” 。

切换

• 二元状态的工具提示应该以类似“是否...”的内容开头。
• 您可能需要一个列表而不是切换按钮：
  • 当错误状态下会发生什么情况很清楚时，请使用切换按钮。例如，
  • “简化输出？”
  • 。另一种选择（不简化输出）很清楚。
  • 当需要更清晰的操作时，请使用带有命名选项的下拉列表。例如，
  • “追加？”
  • 。如果不追加，会发生什么情况则不清楚（可能什么也不会发生，或者信息会被覆盖或丢弃）。

列表

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

触发节点输入

当触发节点具有用于指定触发哪些事件的参数时：

• 将参数命名为Trigger on 。
• 不包括工具提示。

字幕

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

1

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

ID

当对特定记录执行操作时，例如“更新任务评论”，您需要一种方法来指定要更改哪条记录。

• 尽可能提供两种指定记录的方式：
  • 从预填充列表中选择。您可以使用参数生成此列表
  。
  • 更多信息
  • 请参阅
  • 基础文件
  。
  • 输入 ID。
• 为字段命名。例如，工作区名称或 ID 。添加工具提示，提示“从列表中选择一个名称，或使用表达式指定 ID”。链接至 n8n 的表达式文档。
• 构建节点时，应使其能够处理用户提供的超出要求的信息。例如：
  • 如果您需要相对路径，则应处理用户粘贴的绝对路径。
  • 如果用户需要从 URL 获取 ID，则应处理用户粘贴的完整 URL。

日期和时间戳

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

JSON

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

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

节点图标

常见模式和例外

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

简化回复

API 可能会返回大量无用的数据。您可以考虑添加一个开关，让用户选择是否简化响应数据：

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

更新插入操作

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

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

布尔运算符

n8n 在 GUI 中对布尔运算符（例如 AND 和 OR）的组合支持不佳。请尽可能提供所有 AND 或所有 OR 的选项。

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

源代码或二进制属性

二进制数据是文件数据，例如电子表格或图片。在 n8n 中，您需要一个命名键来引用数据。请勿使用“二进制数据”或“二进制属性”等术语来指代此字段。请使用更具描述性的名称：输入数据字段名称/输出数据字段名称。