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 的 node 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 的文档。自问：

¥Review the documentation for the API you're integrating. Ask yourself:

  • 哪些内容可以省略？

    ¥What can you leave out?

  • 哪些可以简化？

    ¥What can you simplify?

  • API 的哪些部分令人困惑？如何帮助用户理解它们？

    ¥Which parts of the API are confusing? How can you help users understand them?

  • 使用线框图工具来测试你的字段布局。如果你发现节点包含大量字段且难以理解，请参考 n8n 关于 显示和隐藏字段 的指导。

¥Use a wireframe tool to try out your field layout. If you find your node has a lot of fields and is getting confusing, consider n8n's guidance on showing and hiding fields.

标准#

¥Standards

UI 文本样式#

¥UI text style

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

UI 文本术语#

¥UI text terminology

  • 使用与节点连接的服务相同的术语。例如，Notion 节点应该引用 Notion 块，而不是 Notion 段落，因为 Notion 将这些元素称为块。这条规则也有例外，通常是为了避免使用技术术语（例如，请参阅 upsert 操作的名称和描述 上的指南）。

¥Use the same terminology as the service the node connects to. For example, a Notion node should refer to Notion blocks, not Notion paragraphs, because Notion calls these elements blocks. There are exceptions to this rule, usually to avoid technical terms (for example, refer to the guidance on name and description for upsert operations).

  • 有时，同一服务在其 API 和 GUI 中对某些内容使用的术语可能不同。在节点中使用图形用户界面 (GUI) 语言，因为大多数用户都熟悉这种语言。如果你认为某些用户可能需要参考服务的 API 文档，请考虑将此信息包含在提示中。

¥Sometimes a service has different terms for something in its API and in its GUI. Use the GUI language in your node, as this is what most users are familiar with. If you think some users may need to refer to the service's API docs, consider including this information in a hint.

  • 如有更简单的替代方案，请勿使用技术术语。

¥Don't use technical jargon when there are simpler alternatives.

  • 命名时请保持一致。例如，选择 directory 或 folder 中的一个，并坚持使用该版本。

¥Be consistent when naming things. For example, choose one of directory or folder then stick to it.

节点命名约定#

¥Node naming conventions

惯例 正确 错误
如果节点是触发节点，
显示的名称末尾应包含 '触发器'，
前面有一个空格。		 Shopify 触发器 ShopifyTrigger，Shopify 触发器
请勿在名称中包含 'node'。 Asana Asana 节点，Asana 节点

显示和隐藏字段#

¥Showing and hiding fields

字段可以是：

¥Fields can either be:

  • 节点打开时显示：用于资源和操作以及必填字段。

¥Displayed when the node opens: use this for resources and operations, and required fields.

  • 在用户点击“可选字段”部分之前，以下内容隐藏在该部分中：用于可选字段。

¥Hidden in the Optional fields section until a user clicks on that section: use this for optional fields.

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

¥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 通常涉及对数据进行操作。例如，"获取所有任务。" 在此示例中，"task" 是资源，"获取所有" 是操作。

¥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.

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

¥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:

  • 从最重要到最不重要。

¥Most important to least important.

  • 范围：从宽到窄。例如，你需要插入“文档”、“页面”和“文本”字段，请按此顺序插入。

¥Scope: from broad to narrow. For example, you have fields for Document, Page, and Text to insert, put them in that order.

可选字段#

¥Optional fields

  • 按字母顺序排列字段。要将类似内容分组，你可以重命名它们。例如，将“电子邮件”和“辅助电子邮件”重命名为“电子邮件（主）”和“电子邮件（辅助）”。

¥Order fields alphabetically. To group similar things together, you can rename them. For example, rename Email and Secondary Email to Email (primary) and Email (secondary).

  • 如果可选字段具有节点在未设置值时使用的默认值，请使用该值加载该字段。请在字段描述中说明这一点。例如，默认为 false。

¥If an optional field has a default value that the node uses when the value isn't set, load the field with that value. Explain this in the field description. For example, Defaults to false.

  • 已连接的字段：如果一个可选字段依赖于另一个可选字段，则将它们打包在一起。它们应该位于同一个选项下，选中该选项时会同时显示这两个字段。

¥Connected fields: if one optional fields is dependent on another, bundle them together. They should both be under a single option that shows both fields when selected.

  • 如果你有很多可选字段，请考虑按主题对它们进行分组。

¥If you have a lot of optional fields, consider grouping them by theme.

帮助#

¥Help

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

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

  • 信息框：字段之间出现的黄色方框。有关更多信息，请参阅 UI 元素 |通知。

¥Info boxes: yellow boxes that appear between fields. Refer to UI elements | Notice for more information.

  • 使用信息框显示重要信息。请勿过度使用。通过使它们稀有，它们会更加突出并吸引用户的注意力。

    ¥Use info boxes for essential information. Don't over-use them. By making them rare, they stand out more and grab the user's attention.

  • 参数提示：显示在用户输入字段下方的文本行。当用户需要了解某些信息，但信息框过于冗长时，请使用此选项。

¥Parameter hints: lines of text displayed beneath a user input field. Use this when there's something the user needs to know, but an info box would be excessive.

  • 节点提示：在输入面板、输出面板或节点详细信息视图中提供帮助。有关更多信息，请参阅 UI 元素 | 提示。

¥Node hints: provide help in the input panel, output panel, or node details view. Refer to UI elements | Hints for more information.

  • 工具提示：当用户将鼠标悬停在工具提示图标上时显示的标注。

¥Tooltips: callouts that appear when the user hovers over the tooltip icon

"Screenshot of the tooltip icon. The icon is a ? in a grey circle"

使用工具提示提供用户可能需要的额外信息。

¥. Use tooltips for extra information that the user might need.

  • 你无需为每个字段提供工具提示。仅当描述包含有用信息时才添加描述。

¥You don't have to provide a tooltip for every field. Only add one if it contains useful information.

  • 编写工具提示时，请考虑用户的需求。请勿直接复制粘贴 API 参数描述。如果描述不通顺或有错误，请进行改进。

¥When writing tooltips, think about what the user needs. Don't just copy-paste API parameter descriptions. If the description doesn't make sense, or has errors, improve it.

  • 占位符文本：n8n 可以在用户未输入值的字段中显示占位符文本。这可以帮助用户了解该字段的预期内容。

¥Placeholder text: n8n can display placeholder text in a field where the user hasn't entered a value. This can help the user know what's expected in that field.

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

¥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.

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

¥Refer to Node Error Handling for more information.

切换#

¥Toggles

  • 二进制状态的工具提示应以“是否……”之类的内容开头。

¥Tooltips for binary states should start with something like Whether to . . . .

  • 你可能需要一个列表而不是一个切换开关：

¥You may need a list rather than a toggle:

  • 当“否”状态下的功能清晰可见时，请使用切换开关。例如，简化输出？另一种选择（不要简化输出）显而易见。

    ¥Use toggles when it's clear what happens in a false state. For example, Simplify Output?. The alternative (don't simplify output) is clear.

  • 需要更清晰的表达时，请使用带有命名选项的下拉列表。例如，追加？如果不追加数据会发生什么情况尚不明确（可能什么都不会发生，或者信息被覆盖，或者被丢弃）。

    ¥Use a dropdown list with named options when you need more clarity. For example, Append?. What happens if you don't append is unclear (it could be that nothing happens, or information is overwritten, or discarded).

列表#

¥Lists

  • 尽可能为列表设置默认值。默认值应为最常用的选项。

¥Set default values for lists whenever possible. The default should be the most-used option.

  • 按字母顺序对列表选项进行排序。

¥Sort list options alphabetically.

  • 你可以包含列表选项描述。仅当描述提供有用信息时才添加描述。

¥You can include list option descriptions. Only add descriptions if they provide useful information.

  • 如果存在“全部”之类的选项，请使用“全部”一词，而不是像“*”这样的缩写。

¥If there is an option like All, use the word All, not shorthand like *.

触发器节点输入#

¥Trigger node inputs

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

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

  • 将参数命名为“Trigger”。开启。

¥Name the parameter Trigger on.

  • 请勿包含工具提示。

¥Don't include a tooltip.

字幕#

¥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.

  • 尽可能提供两种方式来指定记录：

¥Wherever possible, provide two ways to specify a record:

  • 通过从预填充列表中选择。你可以使用 loadOptions 参数生成此列表。有关更多信息，请参阅 基础文件。

    ¥By choosing from a pre-populated list. You can generate this list using the loadOptions parameter. Refer to Base files for more information.

  • 通过输入 ID。

    ¥By entering an ID.

  • 将字段命名为 <Record name> name or ID。例如，工作区名称或 ID。添加一个工具提示，提示 "从列表中选择名称，或使用表达式指定 ID。" 链接到 n8n 的 表达式 文档。

¥Name the field <Record name> name or ID. For example, Workspace Name or ID. Add a tooltip saying "Choose a name from the list, or specify an ID using an expression." Link to n8n's Expressions documentation.

  • 构建你的节点，使其能够处理用户提供超出所需信息的情况。例如：

¥Build your node so that it can handle users providing more information than required. For example:

  • 如果你需要相对路径，请处理用户粘贴绝对路径的情况。

    ¥If you need a relative path, handle the user pasting in the absolute path.

  • 如果用户需要从 URL 获取 ID，请处理用户粘贴完整 URL 的情况。

    ¥If the user needs to get an ID from a URL, handle the user pasting in the entire 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 对象。

¥Typing JSON directly into the text input: you need to parse the resulting string into a JSON object.

  • 使用返回 JSON 的表达式。

¥Using an expression that returns 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:

  • 名称：简化响应

¥Name: Simplify Response

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

¥Description: Whether to return a simplified version of the response instead of the raw data

更新/插入操作#

¥Upsert operations

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

¥This should always be a separate operation with:

  • 名称：创建或更新

¥Name: Create or Update

  • 描述：创建新记录，或更新已存在的现有记录（upsert）。

¥Description: Create a new record, or update the current one if it already exists (upsert)

布尔运算符#

¥Boolean operators

n8n 在图形用户界面 (GUI) 中对组合布尔运算符（例如 AND 和 OR）的支持不佳。尽可能提供所有“与”或所有“或”选项。

¥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.