社区节点的用户体验指南#

您的节点用户界面必须符合这些准则，才能成为已验证社区节点的候选者。

凭证#

API密钥和敏感凭证应始终设置为密码字段。

OAuth认证#

如果可用，请始终包含OAuth凭据。

节点结构#

包含的操作#

尝试为每种资源类型包含增删改查(CRUD)操作。

尽量在每个资源的节点中包含常见操作。n8n使用一些CRUD操作来保持体验一致性，并允许用户对资源执行基本操作。建议的操作包括：

• 创建
• 创建或更新（Upsert）
• 删除
• 获取
• 获取多个： 当存在筛选或搜索功能时也可使用
• 更新

备注：

1. 这些操作可以应用于资源本身或资源内部的实体（例如，Google表格中的一行）。当对资源内部的实体进行操作时，必须在操作名称中指定实体名称。
2. 命名可能会根据节点和资源的不同而有所变化。详情请查看以下指南。

资源定位器#

• 尽可能使用资源定位器组件。这能为用户提供更好的用户体验。当需要选择单个项目时，资源定位器组件通常最为实用。
• 资源定位器组件的默认选项应为From list（如果可用）。

与其他节点的一致性#

• 保持用户体验一致性：n8n致力于维持其用户体验的一致性。这意味着遵循现有的用户体验模式，特别是最新新增或彻底改造的节点中所采用的模式。
• 检查类似节点：例如，如果您正在处理数据库节点，值得查看Postgres节点。

排序选项#

• 您可以通过为用户提供排序选项来增强某些"获取多条"操作。
• 在专用集合（位于"Options"集合下方）中添加排序功能。参照Airtable Record:Search的示例。

节点功能#

删除操作输出#

删除项目（如记录或行）时，返回包含单个对象的数组：{"deleted": true}。这是向用户确认删除操作已成功完成，该操作将触发后续节点。

简化输出字段#

普通节点：'Simplify' 参数#

当端点返回的数据字段超过10个时，添加"Simplify"布尔参数可返回最多包含10个字段的简化版本输出。

• n8n的一个主要问题可能是数据量过大，而Simplify参数通过减小数据规模来缓解这一问题。
• 在简化节点中选择最有用的字段输出，并按使用频率排序，将最常用的字段置于顶部。
• 在简化模式下，通常最好将嵌套字段展平
• 显示名称: Simplify
• 描述: 是否返回简化版本的响应而非原始数据

AI工具节点：'Output'参数#

当端点返回的数据包含超过10个字段时，添加带有3种模式的'Output'选项参数。

在AI工具节点中，允许用户更精细地选择需要输出的字段。这样做的原因是工具可能会超出上下文窗口限制，过多字段可能导致混淆，因此最好仅传递它们所需的字段。

选项：

• 简化版: 功能与上述描述的"Simplify"参数相同。
• 原始数据: 返回所有可用字段。
• 选定字段： 显示一个多选参数，用于选择要添加到输出并发送给AI智能体的字段。默认情况下，此选项始终返回记录/实体的ID。

复制#

文本大小写#

对节点name、parameters display names（标签）、dropdown titles使用标题大写。标题大写是指将每个单词的首字母大写，但某些小词（如冠词和短介词）除外。

对节点的action名称、节点descriptions、parameters descriptions（工具提示）、hints和dropdown descriptions使用首字母大写格式。

术语#

• 使用第三方服务的术语：尽量使用与你对接的服务相同的术语（例如，Notion中的'blocks'，而不是Notion中的'paragraphs'）。
• 使用用户界面中的术语：坚持使用服务用户界面中的术语，而不是API或技术文档中使用的术语（例如，在Trello中您"归档"卡片，但在API中它们显示为"已关闭"。在这种情况下，您可能希望使用"归档"）。
• 避免技术术语：在能用简单词汇表达的情况下，不要使用技术术语。例如，使用"字段"而非"键"。
• 命名一致性：为某个事物选择一个术语并坚持使用。例如，不要混用"directory"和"folder"。

占位符#

在参数占位符中插入内容示例通常很有帮助。这些示例应以"例如"开头，并在字段中使用驼峰式命名作为演示内容。

可复制的占位符示例：

• 图片: e.g. https://example.com/image.png
• 视频: e.g. https://example.com/video.mp4
• 搜索词: e.g. automation
• 邮箱: e.g. nathan@example.com
• Twitter用户（或类似）：e.g. n8n
• 姓名: e.g. Nathan Smith
• 名字: e.g. Nathan
• 姓氏: e.g. Smith

操作名称、动作和描述#

• 名称：这是在画布上打开节点时选择框中显示的名称。必须使用首字母大写格式，且无需包含资源名称（例如"Delete"）。
• 操作： 这是显示在用户选择节点的面板中的操作名称。必须使用句子大小写格式，并且必须包含资源（例如"删除记录"）。
• 描述：这是在画布上打开节点时，选择框中名称下方显示的子文本。必须使用句子格式并包含资源名称。可以添加一些额外信息，并使用与基础资源/操作不同的替代词汇（例如"获取用户列表"）。
• 如果操作作用于非资源实体（例如Google表格中的某一行），请在操作名称中明确说明（例如"删除行"）。

一般来说，理解操作的对象很重要。有时，操作的对象就是资源本身（例如，Sheet:Delete用于删除Sheet）。

在其他情况下，操作对象不是资源本身，而是资源内部包含的内容（例如，Table:Delete rows，这里的资源是表格，但实际操作的是表格内的行数据）。

命名 name#

这是在节点在画布上打开时，选择框中显示的名称。

• 参数: name
• 案例：标题大小写

命名指南：

• Don't repeat the resource (if the resource selection is above): The resource is often displayed above the operation, so it's not necessary to repeat it in the operation (this is the case if the object of the operation is the resource itself).
  • 例如：Sheet:Delete → 无需在Delete中重复Sheet，因为n8n会在上方字段显示Sheet，而您要删除的就是Sheet。
• Specify the resource if there's no resource selection above: In some nodes, you won't have a resource selection (because there's only one resource). In these cases, specify the resource in the operation.
  • 例如：Delete Records → 在Airtable中，没有资源选择功能，因此最好明确指出删除操作将会删除记录。
• Specify the object of the operation if it's not the resource: Sometimes, the object of the operation isn't the resource. In these cases, specify the object in the operation as well.
  • 例如：Table:Get Columns → 指定 Columns，因为资源是 Table，而操作对象是 Columns。

命名 action#

这是在用户选择节点的面板中显示的操作名称。 * 参数: action * 格式: 首字母大写

命名指南：

• Omit articles: To keep the text shorter, get rid of articles (a, an, the…).
  • 正确: Update row in sheet
  • 不正确: Update a row in a sheet
• 重复资源： 在这种情况下，重复资源是可以的。即使资源已在列表中显示，用户可能不会注意到，因此在操作标签中重复显示是有帮助的。
• Specify the object of the operation if it is not the resource: Same as for the operation name. In this case, you don't need to repeat the resource.
  • 例如：Append Rows → 您需要指定Rows，因为您实际追加的是行数据。不要添加资源（Sheet），因为您不是向资源追加内容。

命名 description#

这是在画布上打开节点时，选择框中名称下方显示的子文本。

• 参数: description
• 大小写：句首字母大写

命名指南：

• 如果可能，提供比操作name中指定的更多信息
• 使用替代措辞帮助用户更好地理解操作的功能。有些人可能不理解操作中使用的文本（可能英语不是他们的母语），使用替代措辞可以帮助他们。

词汇表#

n8n采用通用词汇表以及针对特定场景的词汇表来分类相似应用（例如数据库或电子表格）。

通用词汇表借鉴了CRUD操作的概念：

• Clear
  • 删除资源的所有内容（清空资源）。
  • 描述: 删除内的所有
• Create
  • 创建资源的新实例。
  • 描述: 创建新的
• Create or Update
  • 创建或更新资源的现有实例。
  • 描述: 创建新的或更新现有资源(upsert)
• Delete
  • You can use "Delete" in two different ways:
    1. Delete a resource:
       • 描述: 永久删除一个 (仅在确实永久删除的情况下使用"permanently")
    2. Delete something inside of the resource (for example, a row):
       • 在这种情况下，务必明确指定操作对象：例如Delete Rows或Delete Records。
       • 描述: 永久删除一个
• Get
  • You can use "Get" in two different ways:
    1. Get a resource:
       • 描述: 获取一个
    2. Get an item inside of the resource (for example, records):
       • 在这种情况下，务必明确指定操作对象：例如Get Row或Get Record。
       • 描述: 从中检索一个
• Get Many
  • You can use "Get Many" in two different ways:
    1. Get a list of resources (without filtering):
       • 描述: 获取列表
    2. Get a list of items inside of the resource (for example, records):
       • 在这种情况下，务必明确指定操作对象：例如Get Many Rows或Get Many Records。
       • 可以省略Many：Get Many Rows可以写成Get Rows。
       • 描述: 列出中的所有/某个
• Insert or Append
  • 在资源内部添加内容。
  • 对数据库节点使用insert。
  • 描述: 在中插入(s)
• Insert or Update or Append or Update
  • 在资源内添加或更新内容。
  • 对数据库节点使用insert。
  • 描述: 插入 (s) 或更新现有元素(upsert)
• Update
  • You can use "Update" in two different ways:
    1. Update a resource:
       • 描述: 更新一个或多个<资源>
    2. Update something inside of a resource (for example, a row):
       • 在这种情况下，务必明确指定操作对象：例如Update Rows或Update Records。
       • 描述: 更新内的(s)

引用参数和字段名称#

当需要在文本中引用参数名称或字段名称时，请用单引号将它们括起来（例如，"请填写'name'参数）。

布尔值描述#

布尔组件的描述以"是否..."开头

错误#

总体理念#

错误是用户痛苦的来源。因此，n8n始终希望告知用户：

• 发生了什么: 错误描述及问题原因。
• 如何解决问题：或至少如何摆脱困境并继续顺利使用n8n。n8n不希望用户被卡住，因此请借此机会引导他们走向成功。

输出面板中的错误结构#

错误信息 - 发生了什么#

此消息向用户解释发生了什么情况，以及当前阻碍执行完成的问题。

• 如果您知道触发错误的参数displayName，请将其包含在错误消息或描述中（或两者都包含）。
• 项目索引：如果您知道触发错误的项目ID，请在错误消息后追加[Item X]。例如：参数"Release ID"中发布的ID未找到 [项目2]。
• 避免使用诸如"错误"、"问题"、"故障"、"失误"等词语。

错误描述 - 如何解决或摆脱困境#

该描述向用户解释了如何解决问题、需要在节点配置中更改哪些内容（如有必要）或如何摆脱困境。在此，您应引导他们进入下一步并解除阻碍。

避免使用诸如"错误"、"问题"、"故障"、"失误"等词语。