社区节点的用户体验指南

您的节点用户界面必须遵循这些指南才能成为认证社区节点候选者。

凭证

API密钥和敏感凭证应始终使用密码字段。

OAuth

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

节点结构

要包含的操作

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

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

• 创建
• 创建或更新（Upsert）
• 删除
• 获取
• 获取多个： 也用于提供一些过滤或搜索功能
• 更新

注意：

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

资源定位器

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

与其他节点的一致性

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

排序选项

• 您可以通过为用户提供排序选项来增强某些“获取多个”操作。
• 在专用集合中添加排序（在“选项”集合下方）。请参考Airtable Record:Search的示例。

节点功能

删除操作输出

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

简化输出字段

普通节点：“简化”参数

当端点返回具有超过10个字段的数据时，添加“简化”布尔参数来返回最多10个字段的简化版输出。

• n8n的主要问题之一可能是数据的大小，简化参数通过减少数据大小来限制这个问题。
• 在简化节点中选择要输出的最有用的字段，并对它们进行排序，将最常用的字段放在顶部。
• 在简化模式下，通常最好将嵌套字段展平
• 显示名称：简化
• 描述：是否返回简化版的响应而不是原始数据

AI工具节点："输出"参数

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

在AI工具节点中，允许用户更精细地选择要输出的字段。这样做的理由是工具可能会耗尽上下文窗口，并且它们可能会被太多字段搞糊涂，所以最好只传递它们需要的字段。

选项：

• 简化： 与上述“简化”参数的工作方式相同。
• 原始： 返回所有可用的字段。
• 选定字段： 显示一个多选项参数，用于选择要添加到输出并发送给AI代理的字段。默认情况下，这个选项始终返回记录/实体的ID。

文本内容

文本大小写

节点name、参数显示名称（标签）、下拉列表标题使用标题大小写。标题大小写是指将每个单词的首字母大写，但某些小单词（如冠词和短介词）除外。

节点action名称、节点descriptions、参数描述（工具提示）、提示、下拉列表描述使用句子大小写。

术语

• 使用第三方服务术语： 尝试使用与您连接的服务相同的术语（例如，Notion “区块”，而不是Notion “段落”）。
• 使用用户界面中使用的术语： 坚持使用服务的用户界面中使用的术语，而不是API或技术文档中使用的术语（例如，在Trello中您“归档”卡片，但在API中它们显示为“关闭”。在这种情况下，您可能想使用“归档”）。
• 不使用技术衏语： 在简单的单词可以胜任的地方，不要使用技术衏语。例如，使用“字段”而不是“键”。
• 一致的命名： 为某个东西选择一个术语并坚持使用。例如，不要混合使用“目录”和“文件夹”。

占位符

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

可复制的占位符示例：

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

操作名称、动作和描述

• 名称（Name）： 这是在节点在画布上打开时在选择器中显示的名称。它必须使用标题大小写，并且不必包含资源（例如“删除”）。
• 动作（Action）： 这是在用户选择节点的面板中显示的操作名称。它必须使用句子大小写，并且必须包含资源（例如“删除记录”）。
• 描述（Description）： 这是在节点在画布上打开时在选择器中显示在名称下方的副文本。它必须使用句子大小写，并且必须包含资源。它可以添加一些信息，并使用与基本资源/操作不同的替代词汇（例如“检索用户列表”）。
• 如果操作作用于不是资源的实体（例如，Google表格中的一行），请在操作名称中指定（例如“删除行”）。

As a general rule, is important to understand what the object of an operation is. Sometimes, the object of an Operation is the resource itself (for example, Sheet:Delete to delete a Sheet).

In other cases, the object of the operation isn't the resource, but something contained inside the resource (for example, Table:Delete rows, here the resource is the table, but what you are operating on are the rows inside of it).

Naming name

This is the name displayed in the select when the node is open on the canvas.

• Parameter: name
• Case: Title Case

Naming guidelines:

• 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).
  • For example: Sheet:Delete → No need to repeat Sheet in Delete, because n8n displays Sheet in the field above and what you're deleting is the 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.
  • For example: Delete Records → In Airtable, there's no resource selection, so it's better to specify that the Delete operation will delete records.
• 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.
  • For example: Table:Get Columns → Specify Columns because the resource is Table, while the object of the operation is Columns.

Naming action

This is the name of the operation displayed in the panel where the user selects the node. * Parameter: action * Case: Sentence case

Naming guidelines:

• Omit articles: To keep the text shorter, get rid of articles (a, an, the…).
  • correct: Update row in sheet
  • incorrect: Update a row in a sheet
• Repeat the resource: In this case, it's okay to repeat the resource. Even if the resource is visible in the list, the user might not notice and it's useful to repeat it in the operation label.
• 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.
  • For example: Append Rows → You have to specify Rows because rows are what you're actually appending to. Don't add the resource (Sheet) since you aren't appending to the resource.

Naming description

This is the subtext displayed below the name in the selection when the node is open on the canvas.

• Parameter: description
• Case: Sentence case

Naming guidelines:

• If possible, add more information than that specified in the operation name
• Use alternative wording to help users better understand what the operation is doing. Some people might not understand the text used in the operation (maybe English isn't their native language), and using alternative working could help them.

Vocabulary

n8n uses a general vocabulary and some context-specific vocabulary for groups of similar applications (for example, databases or spreadsheets).

The general vocabulary takes inspiration from CRUD operations:

• Clear
  • Delete all the contents of the resource (empty the resource).
  • Description: Delete all the <CHILD_ELEMENT>s inside the <RESOURCE>
• Create
  • Create a new instance of the resource.
  • Description: Create a new <RESOURCE>
• Create or Update
  • Create or update an existing instance of the resource.
  • Description: Create a new <RESOURCE> or update an existing one (upsert)
• Delete
  • You can use "Delete" in two different ways:
    1. Delete a resource:
       • Description: Delete a <RESOURCE> permanently (use "permanently" only if that's the case)
    2. Delete something inside of the resource (for example, a row):
       • In this case, always specify the object of the operation: for example, Delete Rows or Delete Records.
       • Description: Delete a <CHILD_ELEMENT> permanently
• Get
  • You can use "Get" in two different ways:
    1. Get a resource:
       • Description: Retrieve a <RESOURCE>
    2. Get an item inside of the resource (for example, records):
       • In this case, always specify the object of the operation: for example, Get Row or Get Record.
       • Description: Retrieve a <CHILD_ELEMENT> from the/a <RESOURCE>
• Get Many
  • You can use "Get Many" in two different ways:
    1. Get a list of resources (without filtering):
       • Description: Retrieve a list of <RESOURCE>s
    2. Get a list of items inside of the resource (for example, records):
       • In this case, always specify the object of the operation: for example, Get Many Rows or Get Many Records.
       • You can omit Many: Get Many Rows can be Get Rows.
       • Description: List all <CHILD_ELEMENT>s in the/a <RESOURCE>
• Insert or Append
  • Add something inside of a resource.
  • Use insert for database nodes.
  • Description: Insert <CHILD_ELEMENT>(s) in a <RESOURCE>
• Insert or Update or Append or Update
  • Add or update something inside of a resource.
  • Use insert for database nodes.
  • Description: Insert <CHILD_ELEMENT>(s) or update an existing one(s) (upsert)
• Update
  • You can use "Update" in two different ways:
    1. Update a resource:
       • Description: Update one or more <RESOURCE>s
    2. Update something inside of a resource (for example, a row):
       • In this case, always specify the object of the operation: for example, Update Rows or Update Records.
       • Description: Update <CHILD_ELEMENT>(s) inside a <RESOURCE>

Referring to parameter and field name

When you need to refer to parameter names or field names in copy, wrap them in single quotation marks (for example, "Please fill the 'name' parameter).

Boolean description

Start the description of boolean components with 'Whether...'

错误处理

General philosophy

Errors are sources of pain for users. For this reason, n8n always wants to tell the user:

• What happened: a description of the error and what went wrong.
• How to solve the problem: or at least how to get unstuck and continue using n8n without problems. n8n doesn't want users to remain blocked, so use this as an opportunity to guide them to success.

Error structure in the Output panel

Error Message - What happened

This message explains to the user what happened, and the current issue that prevents the execution completing.

• If you have the displayName of the parameter that triggered the error, include it in the error message or description (or both).
• Item index: if you have the ID of the item that triggered the error, append [Item X] to the error message. For example, The ID of the release in the parameter “Release ID” for could not be found [item 2].
• Avoid using words like "error", "problem", "failure", "mistake".

Error Description - How to solve or get unstuck

The description explains to users how to solve the problem, what to change in the node configuration (if that's the case), or how to get unstuck. Here, you should guide them to the next step and unblock them.

Avoid using words like "error", "problem", "failure", "mistake".

与文档对话

此页面是否 有帮助 无帮助

感谢您的反馈！

提交

我们会亲自阅读所有反馈

💬 微信

🚀 与作者交流

×

关注公众号

n8n实战笔记
📚 教程 💡 案例 🔧 技巧

添加微信

1对1 专业指导
⚡ 快答 🎯 定制 🚀 支持

添加后请直说来意， 看到会回复。谢谢