Skip to content

设计节点的用户界面#

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

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

设计指南#

所有节点都使用 n8n 的节点 UI 元素，因此您无需考虑颜色、边框等样式细节。但仍建议遵循基本设计流程：

  • 查阅您要集成的 API 文档。思考以下问题：
    • 哪些内容可以省略？
    • 哪些部分可以简化？
    • API 的哪些部分容易混淆？如何帮助用户理解它们？
  • 使用线框图工具测试字段布局。如果发现节点字段过多且变得混乱，请参考 n8n 关于显示和隐藏字段的指南。

标准规范#

UI 文本样式#

元素 样式规范
下拉框值 标题式大小写
提示文本 句子式大小写
信息框 句子式大小写。单句信息不使用句号(.)。多句信息必须使用句号。可包含链接，链接应在新建标签页中打开。
节点名称 标题式大小写
参数名称 标题式大小写
副标题 标题式大小写
工具提示 句子式大小写。单句提示不使用句号(.)。多句提示必须使用句号。可包含链接，链接应在新建标签页中打开。

界面文本术语规范#

  • 使用对接服务的原生术语：例如 Notion 节点应使用"块"(blocks)而非"段落"(paragraphs)，因为 Notion 官方将这些元素称为 blocks。此规则有例外情况，通常是为了避免技术术语（例如参考upsert操作命名规范）。
  • 优先使用GUI术语：当服务的API和图形界面使用不同术语时，采用图形界面术语，因为大多数用户更熟悉这些表述。如果某些用户可能需要参考API文档，可考虑在提示信息中包含相关说明。
  • 避免技术行话：尽量使用简单易懂的替代表达。
  • 保持命名一致性：例如选择使用"目录"(directory)或"文件夹"(folder)后应全程统一。

节点命名规范#

规范 正确示例 错误示例
触发器节点名称末尾需带空格和"Trigger" Shopify Trigger ShopifyTrigger, Shopify trigger
名称中不应包含"node"字样 Asana Asana Node, Asana node

字段显示与隐藏规则#

字段显示方式分为两种： * 节点打开时直接显示：适用于资源/操作字段和必填字段 * 默认隐藏在「可选字段」区域：适用于可选字段，用户需点击才能展开

采用渐进式披露原则：当字段存在依赖关系时，应在被依赖字段完成配置后再显示。例如同时存在「按日期筛选」开关和「筛选日期」选择器时，「筛选日期」字段应在用户启用开关后才显示。

字段类型规范#

凭证字段#

n8n 自动将凭证字段显示在节点配置区域的顶部位置。

资源与操作#

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

当您的节点采用这种资源与操作模式时，第一个字段应为资源，第二个字段应为操作。

必填字段#

字段排序原则：

  • 按重要性从高到低排列
  • 按作用域从宽到窄排列。例如，如果有文档、页面和待插入文本字段，应按此顺序排列

可选字段#

  • 按字母顺序排列字段。如需将相似项分组，可重命名字段。例如将邮箱和备用邮箱重命名为邮箱(主)和邮箱(备用)
  • 如果可选字段有节点在未设置值时使用的默认值，应预加载该值。在字段描述中说明这一点，例如默认为false
  • 关联字段：如果一个可选字段依赖于另一个字段，应将它们捆绑在一起。这两个字段应归属于同一选项，当该选项被选中时同时显示
  • 如果有大量可选字段，建议按主题进行分组

帮助功能#

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

  • 信息框：显示在字段之间的黄色方框。更多信息请参考 UI 元素 | 通知。
  • 信息框应用于关键信息，不宜过度使用。保持其稀有性能让它们更醒目，更容易吸引用户注意。
  • 参数提示：显示在用户输入字段下方的文字说明。当用户需要了解某些信息，但使用信息框又显得过度时使用。
  • 节点提示：在输入面板、输出面板或节点详情视图中提供帮助。更多信息请参考 UI 元素 | 提示。
  • 工具提示：当用户悬停在工具提示图标 "工具提示图标截图。图标是一个灰色圆圈中的问号" 上时显示的说明框。用于提供用户可能需要的额外信息。
  • 并非每个字段都需要工具提示。只有当包含有用信息时才添加。
  • 编写工具提示时，要考虑用户需求。不要直接复制粘贴 API 参数描述。如果描述不清晰或有错误，请进行改进。
  • 占位文本：n8n 可以在用户未输入值的字段中显示占位文本，帮助用户了解该字段的预期内容。

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

错误处理#

明确标识必填字段。

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

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

切换选项#

  • 二进制状态的工具提示应以类似 是否要... 的句式开头。
  • 有时可能需要使用列表而非切换选项：
    • 当"关闭"状态的行为明确时使用切换选项。例如 简化输出？，其替代选项（不简化输出）的含义很明确。
    • 当需要更清晰说明时，使用带有命名选项的下拉列表。例如 追加？，不追加时的行为不明确（可能是无操作、覆盖信息或丢弃信息）。

列表选项#

  • 尽可能为列表设置默认值，默认值应选择最常用的选项。
  • 按字母顺序排列列表选项。
  • 可以为列表选项添加描述，但仅在能提供有用信息时才添加。
  • 如果有类似 全部 的选项，使用完整词语 全部，不要使用 * 等简写形式。

触发器节点输入#

当触发器节点需要指定触发哪些事件时：

  • 将参数命名为 触发条件。
  • 不要添加工具提示。

副标题#

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

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可能返回大量无用数据。考虑添加一个切换选项让用户选择是否简化响应数据：

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

更新或插入操作#

这应该始终是一个独立操作，包含：

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

布尔运算符#

n8n 在图形界面中对组合布尔运算符（如 AND 和 OR）的支持有限。尽可能为所有 AND 或所有 OR 情况提供选项。

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

源键或二进制属性#

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