社区节点的用户体验指南

您的节点 UI 必须符合这些指南才能成为已验证社区节点的候选者。

凭据

API 密钥和敏感凭据应始终为密码字段。

OAuth

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

节点结构

要包含的操作

尝试为每种资源类型包含 CRUD 操作。

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

• Create（创建）
• Create or Update（创建或更新，Upsert）
• Delete（删除）
• Get（获取）
• Get Many（获取多个）： 在某些过滤或搜索可用时也使用
• Update（更新）

注意：

1. 这些操作可以应用于资源本身或资源内的实体（例如，Google Sheet 中的行）。在对资源内的实体进行操作时，您必须在操作名称中指定实体的名称。
2. 命名可能会根据节点和资源而改变。查看以下指南了解详细信息。

资源定位器

• 尽可能使用资源定位器组件。这为用户提供了更好的用户体验。资源定位器组件在您必须选择单个项目时最有用。
• 资源定位器组件的默认选项应该是 From list（从列表中选择）（如果可用）。

与其他节点的一致性

• 保持用户体验一致性：n8n 努力保持其用户体验的一致性。这意味着遵循现有的用户体验模式，特别是在最新的新节点或改进节点中使用的模式。
• 检查类似节点：例如，如果您正在开发数据库节点，值得检查 Postgres 节点。

排序选项

• 您可以通过为用户提供排序选项来增强某些"Get Many"操作。
• 在专用集合中添加排序（在"Options"集合下方）。遵循 Airtable Record:Search 的示例。

节点功能

删除操作输出

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

简化输出字段

普通节点：'Simplify' 参数

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

• n8n 的主要问题之一可能是数据大小，Simplify 参数通过减少数据大小来限制该问题。
• 选择最有用的字段在简化节点中输出，并对它们进行排序，将最常用的字段放在顶部。
• 在 Simplify 模式下，通常最好展平嵌套字段
• 显示名称：Simplify
• 描述：Whether to return a simplified version of the response instead of the raw data

AI 工具节点：'Output' 参数

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

在 AI 工具节点中，允许用户更精细地选择要输出的字段。其理由是工具可能会用完上下文窗口，太多字段可能会让它们感到困惑，因此最好只传递它们需要的字段。

选项：

• Simplified： 与上述描述的"Simplify"参数工作方式相同。
• Raw： 返回所有可用字段。
• Selected fields： 显示一个多选参数，用于选择要添加到输出并发送给 AI 代理的字段。默认情况下，此选项始终返回记录/实体的 ID。

文案

文本大小写

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

对节点 action 名称、节点 descriptions、parameters descriptions（工具提示）、hints、dropdown descriptions 使用句子大小写。

术语

• 使用第三方服务术语： 尝试使用与您接口的服务相同的术语（例如，Notion 的 'blocks'，而不是 Notion 的 'paragraphs'）。
• 使用 UI 中使用的术语： 坚持使用服务用户界面中使用的术语，而不是 API 或技术文档中使用的术语（例如，在 Trello 中您"归档"卡片，但在 API 中它们显示为"已关闭"。在这种情况下，您可能想要使用"归档"）。
• 不要使用技术术语： 在简单词汇就足够的地方不要使用技术术语。例如，使用"字段"而不是"键"。
• 一致的命名： 为某事选择一个术语并坚持使用。例如，不要混合使用"目录"和"文件夹"。

占位符

在参数占位符中插入内容示例通常很有帮助。这些应以"e.g."开头，并对字段中的演示内容使用驼峰式大小写。

要复制的占位符示例：

• image: e.g. https://example.com/image.png
• video: e.g. https://example.com/video.mp4
• search term: e.g. automation
• email: e.g. [email protected]
• Twitter user (or similar): e.g. n8n
• Name and last name: e.g. Nathan Smith
• First name: e.g. Nathan
• Last name: e.g. Smith

操作名称、动作和描述

• Name： 这是在画布上打开节点时在选择中显示的名称。它必须使用标题大小写，不必包含资源（例如，"Delete"）。
• Action： 这是在用户选择节点的面板中显示的操作名称。它必须使用句子大小写，并且必须包含资源（例如，"Delete record"）。
• Description： 这是在画布上打开节点时在选择中显示在名称下方的子文本。它必须使用句子大小写，并且必须包含资源。它可以添加一些信息并使用与基本资源/操作不同的词汇（例如，"Retrieve a list of users"）。
• 如果操作作用于不是资源的实体（例如，Google Sheet 中的行），请在操作名称中指定（例如，"Delete Row"）。

作为一般规则，理解操作的对象是什么很重要。有时，操作的对象是资源本身（例如，Sheet:Delete 删除 Sheet）。

在其他情况下，操作的对象不是资源，而是资源内包含的东西（例如，Table:Delete rows，这里资源是表，但您操作的是表内的行）。

命名 name

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

• 参数：name
• 大小写：标题大小写

命名指南：

• 不要重复资源（如果资源选择在上方）： 资源通常显示在操作上方，因此不需要在操作中重复它（如果操作的对象是资源本身，则是这种情况）。
  • 例如：Sheet:Delete → 不需要在 Delete 中重复 Sheet，因为 n8n 在上方字段中显示 Sheet，您删除的是 Sheet。
• 如果上方没有资源选择，则指定资源： 在某些节点中，您不会有资源选择（因为只有一个资源）。在这些情况下，在操作中指定资源。
  • 例如：Delete Records → 在 Airtable 中，没有资源选择，因此最好指定 Delete 操作将删除记录。
• 如果操作的对象不是资源，则指定操作的对象： 有时，操作的对象不是资源。在这些情况下，也在操作中指定对象。
  • 例如：Table:Get Columns → 指定 Columns，因为资源是 Table，而操作的对象是 Columns。

命名 action

这是在用户选择节点的面板中显示的操作名称。 * 参数：action * 大小写：句子大小写

命名指南：

• 省略冠词： 为了保持文本简短，去掉冠词（a、an、the...）。
  • 正确：Update row in sheet
  • 错误：Update a row in a sheet
• 重复资源： 在这种情况下，可以重复资源。即使资源在列表中可见，用户可能不会注意到，在操作标签中重复它是有用的。
• 如果操作的对象不是资源，则指定操作的对象： 与操作名称相同。在这种情况下，您不需要重复资源。
  • 例如：Append Rows → 您必须指定 Rows，因为行是您实际要追加到的。不要添加资源（Sheet），因为您不是追加到资源。

命名 description

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

• 参数：description
• 大小写：句子大小写

命名指南：

• 如果可能，添加比操作 name 中指定的更多信息
• 使用替代措辞来帮助用户更好地理解操作在做什么。有些人可能不理解操作中使用的文本（也许英语不是他们的母语），使用替代措辞可以帮助他们。

词汇

n8n 使用通用词汇和一些特定于类似应用程序组（例如，数据库或电子表格）的上下文特定词汇。

通用词汇从 CRUD 操作中获得灵感：

• Clear
  • 删除资源的所有内容（清空资源）。
  • 描述：Delete all the <CHILD_ELEMENT>s inside the <RESOURCE>
• Create
  • 创建资源的新实例。
  • 描述：Create a new <RESOURCE>
• Create or Update
  • 创建或更新资源的现有实例。
  • 描述：Create a new <RESOURCE> or update an existing one (upsert)
• Delete
  • 您可以以两种不同方式使用"Delete"：
    1. 删除资源：
       • 描述：Delete a <RESOURCE> permanently（仅在确实是这种情况时使用"permanently"）
    2. 删除资源内部的某些内容（例如，一行）：
       • 在这种情况下，始终指定操作的对象：例如，Delete Rows 或 Delete Records。
       • 描述：Delete a <CHILD_ELEMENT> permanently
• Get
  • 您可以以两种不同方式使用"Get"：
    1. 获取资源：
       • 描述：Retrieve a <RESOURCE>
    2. 获取资源内部的项目（例如，记录）：
       • 在这种情况下，始终指定操作的对象：例如，Get Row 或 Get Record。
       • 描述：Retrieve a <CHILD_ELEMENT> from the/a <RESOURCE>
• Get Many
  • 您可以以两种不同方式使用"Get Many"：
    1. 获取资源列表（无过滤）：
       • 描述：Retrieve a list of <RESOURCE>s
    2. 获取资源内部的项目列表（例如，记录）：
       • 在这种情况下，始终指定操作的对象：例如，Get Many Rows 或 Get Many Records。
       • 您可以省略 Many：Get Many Rows 可以是 Get Rows。
       • 描述：List all <CHILD_ELEMENT>s in the/a <RESOURCE>
• Insert 或 Append
  • 在资源内添加某些内容。
  • 对数据库节点使用 insert。
  • 描述：Insert <CHILD_ELEMENT>(s) in a <RESOURCE>
• Insert or Update 或 Append or Update
  • 在资源内添加或更新某些内容。
  • 对数据库节点使用 insert。
  • 描述：Insert <CHILD_ELEMENT>(s) or update an existing one(s) (upsert)
• Update
  • 您可以以两种不同方式使用"Update"：
    1. 更新资源：
       • 描述：Update one or more <RESOURCE>s
    2. 更新资源内部的某些内容（例如，一行）：
       • 在这种情况下，始终指定操作的对象：例如，Update Rows 或 Update Records。
       • 描述：Update <CHILD_ELEMENT>(s) inside a <RESOURCE>

引用参数和字段名称

当您需要在文案中引用参数名称或字段名称时，用单引号将它们括起来（例如，"Please fill the 'name' parameter）。

布尔描述

布尔组件的描述以 'Whether...' 开始

错误

一般理念

错误是用户痛苦的来源。因此，n8n 总是希望告诉用户：

• 发生了什么：错误的描述和出了什么问题。
• 如何解决问题：或至少如何摆脱困境并继续使用 n8n 而不出现问题。n8n 不希望用户保持阻塞状态，因此将此作为引导他们成功的机会。

输出面板中的错误结构

错误消息 - 发生了什么

此消息向用户说明发生了什么，以及阻止执行完成的当前问题。

• 如果您有触发错误的参数的 displayName，请将其包含在错误消息或描述中（或两者都包含）。
• 项目索引：如果您有触发错误的项目的 ID，请将 [Item X] 附加到错误消息。例如，The ID of the release in the parameter "Release ID" for could not be found [item 2]。
• 避免使用"error"、"problem"、"failure"、"mistake"等词汇。

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

描述向用户说明如何解决问题，在节点配置中要更改什么（如果是这种情况），或如何摆脱困境。在这里，您应该引导他们到下一步并解除阻塞。

避免使用"error"、"problem"、"failure"、"mistake"等词汇。