跳到主要内容

设计节点的用户界面#

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

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

设计指导#​

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

  • 查看你正在集成的 API 的文档。问问自己：
    • 你可以省略什么？
    • 你可以简化什么？
    • API 的哪些部分令人困惑？你如何帮助用户理解它们？
  • 使用线框工具尝试你的字段布局。如果你发现你的节点有很多字段并且变得令人困惑，请考虑 n8n 关于显示和隐藏字段的指导。

标准#​

UI 文本样式#​

元素样式
下拉值标题大小写
提示句子大小写
信息框句子大小写。单句信息不要使用句号 (.)。如果有多个句子，始终使用句号。此字段可以包含链接，链接应在新标签页中打开。
节点名称标题大小写
参数名称标题大小写
副标题标题大小写
工具提示句子大小写。单句工具提示不要使用句号 (.)。如果有多个句子，始终使用句号。此字段可以包含链接，链接应在新标签页中打开。

UI 文本术语#​

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

节点命名约定#​

约定正确错误
如果节点是触发器节点，显示的名称应在末尾有 'Trigger'，前面有一个空格。Shopify TriggerShopifyTrigger, Shopify trigger
不要在名称中包含 'node'。AsanaAsana Node, Asana node

显示和隐藏字段#​

字段可以是：

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

逐步披露复杂性：隐藏字段，直到它所依赖的任何早期字段都有值。例如，如果你有一个 Filter by date 切换开关和一个 Date to filter by 日期选择器，在用户启用 Filter by date 之前不要显示 Date to filter by。

按字段类型的约定#​

凭证#​

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

资源和操作#​

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

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

必填字段#​

按以下方式排序字段：

  • 从最重要到最不重要。
  • 范围：从广到窄。例如，你有 Document、Page 和 Text to insert 字段，按该顺序放置它们。

可选字段#​

  • 按字母顺序排序字段。要将相似的内容分组在一起，你可以重命名它们。例如，将 Email 和 Secondary Email 重命名为 Email (primary) 和 Email (secondary)。
  • 如果可选字段有一个默认值，节点在未设置值时使用该默认值，请使用该值加载字段。在字段描述中解释这一点。例如，Defaults to false。
  • 连接字段：如果一个可选字段依赖于另一个可选字段，请将它们捆绑在一起。它们都应该在一个选项下，选择时显示两个字段。
  • 如果你有很多可选字段，请考虑按主题对它们进行分组。

帮助#​

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

  • 信息框：出现在字段之间的黄色框。有关更多信息，请参阅 UI 元素 | Notice。
  • 将信息框用于基本信息。不要过度使用它们。通过使它们稀有，它们会更加突出并吸引用户的注意力。
  • 参数提示：显示在用户输入字段下方的文本行。当用户需要知道某些内容，但信息框会过度时使用此功能。
  • 节点提示：在输入面板、输出面板或节点详细信息视图中提供帮助。有关更多信息，请参阅 UI 元素 | 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。"链接到 n8n 的表达式文档。
  • 构建你的节点，使其能够处理用户提供的超出要求的信息。例如：
    • 如果你需要相对路径，请处理用户粘贴的绝对路径。
    • 如果用户需要从 URL 获取 ID，请处理用户粘贴的整个 URL。

日期和时间戳#​

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

JSON#​

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

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

节点图标#​

常见模式和例外#​

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

简化响应#​

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

  • 名称：Simplify Response
  • 描述：Whether to return a simplified version of the response instead of the raw data

Upsert 操作#​

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

  • 名称：Create or Update
  • 描述：Create a new record, or update the current one if it already exists (upsert)

布尔运算符#​

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

例如，你有一个名为 Must match 的字段来测试值是否匹配。包括测试 Any 和 All 的选项，作为单独的选项。

源键或二进制属性#​

二进制数据是文件数据，例如电子表格或图像。在 n8n 中，你需要一个命名键来引用数据。不要对此字段使用术语"二进制数据"或"二进制属性"。相反，使用更具描述性的名称：Input data field name / Output data field name。