Skip to content

设计节点的用户界面(Design your node's user interface)#

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

🌐 Most nodes are a GUI (graphical user interface) representation of an API. Designing the interface means finding a user-friendly way to represent API endpoints and parameters. Directly translating an entire API into form fields in a node may not result in a good user experience.

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

🌐 This document provides design guidance and standards to follow. These guidelines are the same as those used by n8n. This helps provide a smooth and consistent user experience for users mixing community and built-in nodes.

设计指南(Design guidance)#

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

🌐 All node's use n8n's node UI elements, so you don't need to consider style details such as colors, borders, and so on. However, it's still useful to go through a basic design process:

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

标准(Standards)#

UI 文本样式(UI text style)#

元素 风格
下拉值 首字母大写
提示 句首大写
信息框 句首大写。单句信息不使用句号（.）。多于一句时必须使用句号。该字段可以包含链接，链接应在新标签页中打开。
节点名称 首字母大写
参数名称 首字母大写
副标题 首字母大写
工具提示 句首大写。单句工具提示不使用句号（.）。多于一句时必须使用句号。该字段可以包含链接，链接应在新标签页中打开。

UI 文本术语(UI text terminology)#

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

节点命名约定(Node naming conventions)#

约定 正确 错误
如果一个节点是触发节点，
显示名称应以 'Trigger' 结尾，
之前留一个空格。		 Shopify Trigger ShopifyTrigger, Shopify trigger
不要在名称中包含 'node'。 Asana Asana Node, Asana node

显示和隐藏字段(Showing and hiding fields)#

字段可以是：

🌐 Fields can either be:

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

逐步显示复杂内容：在依赖的前置字段已有值之前隐藏某个字段。例如，如果你有一个 按日期过滤 开关和一个 要过滤的日期 日期选择器，用户未启用 按日期过滤 之前，不要显示 要过滤的日期。

🌐 Progressively disclose complexity: hide a field until any earlier fields it depends on have values. For example, if you have a Filter by date toggle, and a Date to filter by datepicker, don't display Date to filter by until the user enables Filter by date.

按字段类型划分的约定(Conventions by field type)#

凭据(Credentials)#

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

🌐 n8n automatically displays credential fields as the top fields in the node.

资源和操作(Resources and operations)#

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

🌐 APIs usually involve doing something to data. For example, "get all tasks." In this example, "task" is the resource, and "get all" is the operation.

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

🌐 When your node has this resource and operation pattern, your first field should be Resource, and your second field should be Operation.

必填字段(Required fields)#

字段排序依据：

🌐 Order fields by:

  • 从最重要到最不重要。
  • 范围：从宽到窄。例如，你有 文档、页面 和 要插入的文本 字段，请按此顺序放置它们。

可选字段(Optional fields)#

  • 按字母顺序排列字段。为了将相似的内容归类在一起，你可以重命名它们。例如，将 Email 和 Secondary Email 重命名为 Email（主要） 和 Email（次要）。
  • 如果可选字段有默认值，当值未设置时节点会使用该默认值，请使用该值加载字段。在字段描述中说明这一点。例如，默认为 false。
  • 相关字段：如果一个可选字段依赖于另一个字段，请将它们打包在一起。它们都应该在单一选项下显示，当选择该选项时显示两个字段。
  • 如果你有很多可选字段，请考虑按主题对它们进行分组。

帮助(Help)#

图形用户界面 (GUI) 内置五种类型的帮助：

🌐 There are five types of help built in to the GUI:

  • 信息框：出现在字段之间的黄色框。有关更多信息，请参阅 UI 元素 | 注意。
  • 对于关键信息使用信息框，但不要过度使用。通过稀少使用，它们会更加突出，吸引用户的注意力。
  • 参数提示：显示在用户输入字段下方的文本行。当有一些用户需要知道的信息，但信息框显得过于冗余时使用此功能。
  • 节点提示：在输入面板、输出面板或节点详细信息视图中提供帮助。有关更多信息，请参阅 UI 元素 | 提示。
  • 工具提示：当用户将鼠标悬停在工具提示图标上时出现的提示 工具提示图标的截图。图标是灰色圆圈中的 ?。使用工具提示提供用户可能需要的额外信息。
  • 你不必为每个字段提供工具提示。只有在字段包含有用信息时才添加工具提示。
  • 在编写工具提示时，要考虑用户的需求。不要只是简单地复制粘贴 API 参数的描述。如果描述不合理或有错误，请进行改进。
  • 占位符文本：n8n 可以在用户未输入值的字段中显示占位符文本。这可以帮助用户了解该字段中预期的内容。

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

🌐 Info boxes, hints, and tooltips can contain links to more information.

错误(Errors)#

明确哪些字段是必填项。

🌐 Make it clear which fields are required.

如果可能的话，为字段添加验证规则。例如，如果字段期望输入电子邮件，则检查有效的电子邮件格式。

🌐 Add validation rules to fields if possible. For example, check for valid email patterns if the field expects an email.

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

🌐 When displaying errors, make sure only the main error message displays in the red error title. More information should go in Details.

有关更多信息，请参阅 Node 错误处理。

🌐 Refer to Node Error Handling for more information.

切换(Toggles)#

  • 二进制状态的工具提示应以“是否……”之类的内容开头。
  • 你可能需要一个列表而不是一个切换开关：
    • 当在错误状态下发生的情况很清楚时，请使用切换开关。例如，简化输出？。另一种选择（不简化输出）也很明确。
    • 当你需要更清楚时，请使用带有命名选项的下拉列表。例如，附加？ 如果不附加会发生什么尚不清楚（可能什么都不会发生，也可能信息被覆盖或丢弃）。

列表(Lists)#

  • 尽可能为列表设置默认值。默认值应为使用最频繁的选项。
  • 按字母顺序对列表选项进行排序。
  • 您可以包含列表选项描述。只有在描述提供有用信息时才添加它们。
  • 如果有类似 全部 的选项，请使用 全部 这个词，而不是像 * 这样的缩写。

触发器节点输入(Trigger node inputs)#

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

🌐 When a trigger node has a parameter for specifying which events to trigger on:

  • 命名参数 触发于。
  • 请勿包含工具提示。

字幕(Subtitles)#

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

🌐 Set subtitles based on the values of the main parameters. For example:

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

身份证(IDs)#

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

🌐 When performing an operation on a specific record, such as "update a task comment" you need a way to specify which record you want to change.

  • 尽可能提供两种方式来指定记录：
    • 通过从预先填充的列表中选择。你可以使用 loadOptions 参数生成此列表。有关更多信息，请参阅 基础文件。
    • 通过输入 ID。
  • 将字段命名为 <Record name> name or ID。例如，工作区名称或 ID。添加一个工具提示，内容为“从列表中选择一个名称，或使用表达式指定一个 ID。” 链接到 n8n 的 表达式 文档。
  • 构建你的节点，使其能够处理用户提供的信息超过所需的情况。例如：
    • 如果你需要相对路径，请处理用户粘贴绝对路径的情况。
    • 如果用户需要从 URL 获取 ID，请处理用户粘贴完整 URL 的情况。

日期和时间戳(Dates and timestamps)#

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

🌐 n8n uses ISO timestamp strings for dates and times. Make sure that any date or timestamp field you add supports all ISO 8601 formats.

JSON#

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

🌐 You should support two ways of specifying the content of a text input that expects JSON:

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

节点图标(Node icons)#

常见模式和例外情况(Common patterns and exceptions)#

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

🌐 This section provides guidance on handling common design patterns, including some edge cases and exceptions to the main standards.

简化响应(Simplify responses)#

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

🌐 APIs can return a lot of data that isn't useful. Consider adding a toggle that allows users to choose to simplify the response data:

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

更新/插入操作(Upsert operations)#

这应该始终是一个单独的操作，包含以下内容：

🌐 This should always be a separate operation with:

  • 名称：创建或更新
  • 描述：创建新记录，或在已有记录时更新它（upsert）

布尔运算符(Boolean operators)#

n8n doesn't have good support for combining boolean operators, such as AND and OR, in the GUI. Whenever possible, provide options for all ANDs or all ORs.

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

🌐 For example, you have a field called Must match to test if values match. Include options to test for Any and All, as separate options.

源键或二进制属性(Source keys or binary properties)#

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

🌐 Binary data is file data, such as spreadsheets or images. In n8n, you need a named key to reference the data. Don't use the terms "binary data" or "binary property" for this field. Instead, use a more descriptive name: Input data field name / Output data field name.