设计节点的用户界面#
大多数节点都是 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 Trigger | ShopifyTrigger, Shopify trigger |
| 不要在名称中包含 'node'。 | Asana | Asana Node, Asana node |
显示和隐藏字段#
字段可以是：
- 在节点打开时显示：用于资源和操作，以及必需字段。
- 隐藏在可选字段部分中，直到用户点击该部分：用于可选字段。
逐步披露复杂性：隐藏一个字段，直到它依赖的任何早期字段都有值。例如，如果您有一个按日期筛选切换按钮和一个筛选日期日期选择器，在用户启用按日期筛选之前，不要显示筛选日期。
按字段类型的约定#
凭证#
n8n 会自动将凭证字段显示为节点中的顶部字段。
资源和操作#
API 通常涉及对数据做某些事情。例如，“获取所有任务”。在这个例子中，“任务”是资源，“获取所有”是操作。
当您的节点具有这种资源和操作模式时，您的第一个字段应该是资源，您的第二个字段应该是操作。
必需字段#
按以下方式排列字段：
- 从最重要到最不重要。
- 范围：从宽泛到狭窄。例如，您有文档、页面和要插入的文本字段，请按该顺序放置它们。
可选字段#
- 按字母顺序排列字段。为了将相似的东西组合在一起，您可以重命名它们。例如，将电子邮件和辅助电子邮件重命名为电子邮件（主要）和电子邮件（次要）。
- 如果可选字段有一个默认值，节点在未设置值时使用该默认值，请在字段中加载该值。在字段描述中解释这一点。例如，默认为 false。
- 相关字段：如果一个可选字段依赖于另一个，请将它们捆绑在一起。它们都应该在一个选项下，选中时显示两个字段。
- 如果您有很多可选字段，请考虑按主题对它们进行分组。
帮助#
GUI 中内置了五种类型的帮助：
- 信息框：出现在字段之间的黄色框。有关更多信息，请参阅 UI 元素 | 通知。
- 将信息框用于基本信息。不要过度使用它们。通过让它们变得稀有，它们更突出并吸引用户的注意力。
- 参数提示：显示在用户输入字段下方的文本行。当用户需要知道某些东西，但信息框会过度时，使用此功能。
- 节点提示：在输入面板、输出面板或节点详细信息视图中提供帮助。有关更多信息，请参阅 UI 元素 | 提示。
- 工具提示：当用户将鼠标悬停在工具提示图标
上时出现的标注。将工具提示用于用户可能需要的额外信息。 - 您不必为每个字段提供工具提示。只有在包含有用信息时才添加。
- 在编写工具提示时，考虑用户需要什么。不要只是复制粘贴 API 参数描述。如果描述没有意义或有错误，请改进它。
- 占位符文本：n8n 可以在用户未输入值的字段中显示占位符文本。这可以帮助用户知道该字段中预期的内容。
信息框、提示和工具提示可以包含指向更多信息的链接。
错误#
明确指出哪些字段是必需的。
如可能，向字段添加验证规则。例如，如果字段预期电子邮件，请检查有效的电子邮件模式。
在显示错误时，确保在红色错误标题中只显示主要错误消息。更多信息应该放在详细信息中。
有关更多信息，请参阅节点错误处理。
切换按钮#
- 二进制状态的工具提示应该以类似 **是否 . . . ** 的内容开始。
- 您可能需要列表而不是切换按钮：
- 当明确在 false 状态下会发生什么时，使用切换按钮。例如，简化输出？。替代方案（不简化输出）很明确。
- 当您需要更多清晰度时，使用带有命名选项的下拉列表。例如，附加？。如果不附加会发生什么不清楚（可能什么都不会发生，或者信息被覆盖，或者被丢弃）。
列表#
- 尽可能为列表设置默认值。默认值应该是最常用的选项。
- 按字母顺序排列列表选项。
- 您可以包含列表选项描述。只有在提供有用信息时才添加描述。
- 如果有类似 全部 的选项，请使用单词 全部，而不是类似 * 的简写。
触发器节点输入#
当触发器节点有一个用于指定要触发哪些事件的参数时：
- 将参数命名为 触发时机。
- 不要包含工具提示。
子标题#
根据主要参数的值设置子标题。例如：
1 | |
ID#
在对特定记录执行操作时，例如“更新任务评论”，您需要一种方式来指定要更改的记录。
- 尽可能提供两种指定记录的方式：
- 从预填充列表中选择。您可以使用
loadOptions参数生成此列表。有关更多信息，请参阅基础文件。 - 通过输入 ID。
- 从预填充列表中选择。您可以使用
- 将字段命名为
<记录名称> 名称或 ID。例如，工作区名称或 ID。添加工具提示，内容为“从列表中选择一个名称，或使用表达式指定 ID。”链接到 n8n 的表达式文档。 - 构建您的节点，使其可以处理用户提供的超出要求的信息。例如：
- 如果您需要相对路径，请处理用户粘贴绝对路径。
- 如果用户需要从 URL 获取 ID，请处理用户粘贴整个 URL。
日期和时间戳#
n8n 使用 ISO 时间戳字符串来表示日期和时间。确保您添加的任何日期或时间戳字段都支持所有 ISO 8601 格式。
JSON#
您应该支持两种指定预期 JSON 的文本输入内容的方式：
- 直接在文本输入中键入 JSON：您需要将结果字符串解析为 JSON 对象。
- 使用返回 JSON 的表达式。
Node icons#
常见模式和例外#
本节提供处理常见设计模式的指导，包括一些边缘情况和主要标准的例外。
简化响应#
API 可能返回大量无用的数据。考虑添加一个切换按钮，允许用户选择简化响应数据：
- 名称：简化响应
- 描述：是否返回简化版本的响应而不是原始数据
Upsert 操作#
这应该始终是一个单独的操作，具有：
- 名称：创建或更新
- 描述：创建新记录，或如果已存在则更新当前记录 (upsert)
布尔操作符#
n8n 在 GUI 中不能很好地支持组合布尔操作符，例如 AND 和 OR。尽可能为所有 AND 或所有 OR 提供选项。
例如，您有一个叫做 必须匹配 的字段来测试值是否匹配。包含用于测试 任何 和 全部 的选项，作为单独的选项。
源键或二进制属性#
二进制数据是文件数据，例如电子表格或图像。在 n8n 中，您需要一个命名键来引用数据。不要为该字段使用“二进制数据”或“二进制属性”术语。相反，使用更描述性的名称：输入数据字段名称 / 输出数据字段名称。
🚀 与作者交流
📚 教程 💡 案例 🔧 技巧
⚡ 快答 🎯 定制 🚀 支持