集成节点/Creating_nodes/Plan_your_node
设计节点的用户界面#
大多数节点都是 API 的图形用户界面（GUI）表现形式。界面设计意味着需要找到一种用户友好的方式来呈现 API 端点和参数。直接将整个 API 转换为节点中的表单字段可能无法带来良好的用户体验。
本文档提供了需要遵循的设计指导和标准。这些指南与 n8n 内部使用的规范保持一致，有助于为同时使用社区节点和内置节点的用户提供流畅一致的使用体验。
设计指南#
所有节点都使用 n8n 的节点 UI 元素，因此您无需考虑颜色、边框等样式细节。但仍然建议遵循以下基础设计流程：
- 仔细阅读待集成 API 的文档，并思考：
- 哪些功能可以省略？
- 哪些操作可以简化？
- API 的哪些部分容易令人困惑？如何帮助用户理解它们？
- 使用线框图工具测试字段布局。如果发现节点字段过多导致界面混乱，请参考 n8n 关于显示和隐藏字段的指导方案。
规范#
界面文本样式#
| 元素 | 样式 |
|---|---|
| 下拉选项值 | 首字母大写 |
| 提示文本 | 句子格式 |
| 信息框 | 句子格式。单句信息不使用句号（.），多句信息必须使用句号。此字段可包含链接，链接应在新建标签页中打开。 |
| 节点名称 | 首字母大写 |
| 参数名称 | 首字母大写 |
| 副标题 | 首字母大写 |
| 工具提示 | 句子格式。单句提示不使用句号（.），多句提示必须使用句号。此字段可包含链接，链接应在新建标签页中打开。 |
界面文本术语#
- 使用与节点连接服务相同的术语体系。例如：Notion 节点应使用 Notion 区块（blocks）而非段落（paragraphs）的表述，因为 Notion 官方将这些元素称为区块。此规则存在例外情况，通常是为了避免使用技术术语（例如参考更新插入操作的命名与描述指南）。
- 某些服务在其 API 和图形界面中对同一概念使用不同术语。节点中应使用图形界面中的术语，因为大多数用户对此更为熟悉。若认为部分用户可能需要查阅服务 API 文档，可考虑在提示信息中补充说明。
- 存在更简单替代方案时，避免使用技术行话。
- 保持命名一致性。例如在
directory（目录）和folder（文件夹）中选定一种后应全程统一。
节点命名规范#
| 规范 | 正确示例 | 错误示例 |
|---|
若为触发节点， 显示名称末尾应添加"Trigger"， 且前置空格。 | Shopify Trigger | ShopifyTrigger, Shopify trigger 名称中不包含"node"。 | Asana | Asana Node, Asana node
字段显示与隐藏#
字段可分为两种类型：
- 节点打开时即显示：适用于资源、操作类型字段及必填字段
- 默认隐藏在可选字段区域，用户点击后才显示：适用于可选字段
渐进式呈现复杂性：在某个字段所依赖的前置字段未赋值前，隐藏该字段。例如，若界面存在按日期筛选切换开关和筛选日期日期选择器，应在用户启用按日期筛选后再显示筛选日期字段。
字段类型约定#
凭证字段#
n8n 会自动将凭证字段显示在节点的顶部位置。
资源与操作#
API 通常涉及对数据执行某些操作，例如"获取所有任务"。在此示例中，"任务"是资源，"获取所有"是操作。 当节点采用这种资源与操作模式时，首个字段应为资源，第二个字段应为操作。
必填字段#
排序规则如下：
- 按重要性从高到低排列
- 按作用域从宽到窄排列。例如，若存在文档、页面和待插入文本字段，应按此顺序排列
可选字段#
- 按字母顺序排列字段。如需将相似字段归类，可重命名字段名称。例如将邮箱和备用邮箱重命名为邮箱（主）和邮箱（备）
- 若可选字段存在节点在未设置值时使用的默认值，应在字段中预填该值，并在字段描述中说明。例如默认值为 false
- 关联字段：若某个可选字段依赖于另一个字段，应将它们组合在一起。这两个字段应归属于同一选项，当该选项被选中时同时显示这两个字段
- 若存在大量可选字段，建议按主题进行分组
帮助#
图形用户界面内置了五种帮助类型：
- 信息框：显示在字段之间的黄色方框。详细信息请参阅UI 元素 | 通知
- 信息框应用于关键信息，不宜过度使用。通过控制使用频率，可以增强其醒目程度并吸引用户注意
- 参数提示：显示在用户输入字段下方的文本行。当需要向用户说明某些信息，但使用信息框又显得过于冗长时适用
- 节点提示：在输入面板、输出面板或节点详情视图中提供帮助。详细信息请参阅UI 元素 | 提示
- 工具提示：当用户悬停在工具提示图标上时显示的说明框 ["工具提示图标截图。该图标为灰色圆圈内含问号"](https://docs.n8n.io/_images/common-icons/help-tooltip.png)。适用于用户可能需要的补充信息
- 无需为每个字段都提供工具提示，仅在包含实用信息时添加
- 编写工具提示时应考虑用户需求，避免直接复制API参数描述。若描述含义不清或存在错误，需进行优化改进
- 占位文本：n8n可在用户未输入值的字段中显示占位文本，有助于用户理解该字段的预期输入内容
信息框、提示和工具提示均可包含指向更多信息的链接。
错误处理#
需明确标识必填字段。 尽可能为字段添加验证规则，例如若字段需要邮箱地址，应检查是否符合有效邮箱格式。 显示错误时，确保红色错误标题中仅显示主要错误信息，详细说明应置于详情部分。 更多信息请参阅节点错误处理。
切换开关#
- 二进制状态的工具提示应以**是否...**开头
- 某些情况下可能需要使用列表而非切换开关：
- 当关闭状态的结果明确时使用切换开关，例如简化输出？，其替代状态（不简化输出）的含义清晰
- 当需要更明确区分时，使用带命名选项的下拉列表，例如追加？，不执行追加操作的结果可能不明确（可能是无操作、信息被覆盖或被丢弃）
列表#
- 尽可能为列表设置默认值。默认值应为最常用的选项。
- 按字母顺序对列表选项进行排序。
- 可以包含列表选项描述。仅当描述能提供有用信息时才添加。
- 如果存在类似全部的选项，请使用All这个词，而不是使用像*****这样的简写形式。
触发节点输入#
当触发节点具有用于指定触发事件的参数时：
- 将该参数命名为Trigger on。
- 不要包含工具提示。
副标题#
根据主要参数的值设置副标题。例如：
1| ``` subtitle:'={{$parameter["operation"] + ": " + $parameter["resource"]}}',
---|---
#### ID[#](https://docs.n8n.io/integrations/creating-nodes/plan/node-ui-design/#ids "Permanent link")
当对特定记录执行操作时（例如"更新任务评论"），需要指定要更改的记录。
* 尽可能提供两种指定记录的方式：
* 从预填充列表中选择。可以使用`loadOptions`参数生成此列表。更多信息请参考[基础文件](https://docs.n8n.io/integrations/creating-nodes/build/reference/node-base-files/)。
* 通过输入ID。
* 将字段命名为`<记录名称> name or ID`。例如**Workspace Name or ID**。添加工具提示说明"从列表中选择名称，或使用表达式指定ID"。链接到n8n的[表达式](https://docs.n8n.io/code/expressions/)文档。
* 构建节点使其能够处理用户提供超出必需信息的情况。例如：
* 如果需要相对路径，要处理用户粘贴绝对路径的情况。
* 如果用户需要从URL获取ID，要处理用户粘贴完整URL的情况。
#### 日期和时间戳[#](https://docs.n8n.io/integrations/creating-nodes/plan/node-ui-design/#dates-and-timestamps "Permanent link")
n8n使用[ISO时间戳字符串](https://en.wikipedia.org/wiki/ISO_8601)表示日期和时间。确保添加的任何日期或时间戳字段支持所有ISO 8601格式。
#### JSON[#](https://docs.n8n.io/integrations/creating-nodes/plan/node-ui-design/#json "Permanent link")
对于需要JSON内容的文本输入，应支持两种指定方式：
* 直接在文本输入框中输入JSON：需要将结果字符串解析为JSON对象。
* 使用返回JSON的表达式。
#### 节点图标[#](https://docs.n8n.io/integrations/creating-nodes/plan/node-ui-design/#node-icons "Permanent link")
### 常见模式与例外情况[#](https://docs.n8n.io/integrations/creating-nodes/plan/node-ui-design/#common-patterns-and-exceptions "Permanent link")
本节针对常见设计模式提供指导，包括主要标准中的一些边缘案例和例外情况。
#### 简化响应[#](https://docs.n8n.io/integrations/creating-nodes/plan/node-ui-design/#simplify-responses "Permanent link")
API 可能返回大量无用数据。建议添加切换选项让用户选择是否简化响应数据：
* 名称：**简化响应**
* 描述：**是否返回简化版本的响应而非原始数据**
#### 更新插入操作[#](https://docs.n8n.io/integrations/creating-nodes/plan/node-ui-design/#upsert-operations "Permanent link")
此操作应始终作为独立选项，包含：
* 名称：**创建或更新**
* 描述：**创建新记录，若已存在则更新当前记录（更新插入）**
#### 布尔运算符[#](https://docs.n8n.io/integrations/creating-nodes/plan/node-ui-design/#boolean-operators "Permanent link")
n8n 在图形界面中对布尔运算符（如 AND 和 OR）的组合支持有限。应尽可能提供全 AND 或全 OR 的选项。
例如：若存在用于测试值匹配的 **必须匹配** 字段，应包含分别测试 **任意** 和 **全部** 的独立选项。
#### 源键或二进制属性[#](https://docs.n8n.io/integrations/creating-nodes/plan/node-ui-design/#source-keys-or-binary-properties "Permanent link")
二进制数据指文件数据（如电子表格或图像）。在 n8n 中需要通过命名键来引用这些数据。请勿在此字段使用"二进制数据"或"二进制属性"等术语，而应使用更具描述性的名称：**输入数据字段名** / **输出数据字段名**。