社区节点的 UX 指南

¥UX guidelines for community nodes

你的节点 UI 必须符合以下准则才能成为 已验证的社区节点 候选节点。

¥Your node's UI must conform to these guidelines to be a verified community node candidate.

凭据

¥Credentials

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

¥API key and sensitive credentials should always be password fields.

OAuth

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

¥Always include the OAuth credential if available.

节点结构

¥Node structure

要包含的操作

¥Operations to include

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

¥Try to include CRUD operations for each resource type.

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

¥Try to include common operations in nodes for each resource. n8n uses some CRUD operations to keep the experience consistent and allow users to perform basic operations on the resource. The suggested operations are:

• 创建

¥Create

• 创建或更新（Upsert）

¥Create or Update (Upsert)

• 删除

¥Delete

• 获取

¥Get

• 获取多个也用于提供某些筛选或搜索功能的情况。

¥Get Many: also used when some filtering or search is available

• 更新

¥Update

备注：

¥Notes:

1. 这些操作可以应用于资源本身或资源内部的实体（例如，Google 表格中的一行）。在操作资源中的实体时，你必须在操作名称中指定实体的名称。

¥These operations can apply to the resource itself or an entity inside of the resource (for example, a row inside a Google Sheet). When operating on an entity inside of the resource, you must specify the name of the entity in the operations name. 2. 命名可能会根据节点和资源而变化。请查看以下指南了解详情。

¥The naming could change depending on the node and the resource. Check the following guidelines for details.

资源定位器

¥Resource Locator

• 尽可能使用资源定位符组件。这为用户提供了更好的用户体验。当你需要选择单个项目时，“资源定位器”组件通常非常有用。

¥Use a Resource Locator component whenever possible. This provides a much better UX for users. The Resource Locator Component is most often useful when you have to select a single item.

• 资源定位器组件的默认选项应为 From list（如果可用）。

¥The default option for the Resource Locator Component should be From list (if available).

与其他节点的一致性

¥Consistency with other nodes

• 保持用户体验一致性：n8n 力求保持用户体验的一致性。这意味着遵循现有的 UX 模式，特别是最新或改进的节点中使用的模式。

¥Maintain UX consistency: n8n tries to keep its UX consistent. This means following existing UX patterns, in particular, those used in the latest new or overhauled nodes.

• 检查相似节点：例如，如果你正在处理数据库节点，则值得检查 Postgres 节点。

¥Check similar nodes: For example, if you're working on a database node, it's worth checking the Postgres node.

排序选项

¥Sorting options

• 你可以通过为用户提供排序选项来增强某些 "获取多个" 操作。

¥You can enhance certain "Get Many" operations by providing users with sorting options.

• 在专用集合（位于 "选项" 集合下方）中添加排序功能。请参考 Airtable 记录搜索 的示例。

¥Add sorting in a dedicated collection (below the "Options" collection). Follow the example of Airtable Record:Search.

节点功能

¥Node functionality

删除操作输出

¥Deleting operations output

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

¥When deleting an item (like a record or a row), return an array with a single object: {"deleted": true}. This is a confirmation for the user that the deletion was successful and the item will trigger the following node.

简化输出字段

¥Simplifying output fields

普通节点：'简化' 参数

¥Normal nodes: 'Simplify' parameter

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

¥When an endpoint returns data with more than 10 fields, add the "Simplify" boolean parameter to return a simplified version of the output with max 10 fields.

• n8n 的一个主要问题是数据量，而 Simplify 参数通过减少数据大小来缓解这个问题。

¥One of the main issues with n8n can be the size of data and the Simplify parameter limits that problem by reducing data size.

• 选择要在简化节点中输出的最常用字段，并按使用频率排序，使最常用的字段位于顶部。

¥Select the most useful fields to output in the simplified node and sort them to have the most used ones at the top.

• 在“简化”模式下，通常最好将嵌套字段展平。

¥In the Simplify mode, it's often best to flatten nested fields

• 显示名称：Simplify

¥Display Name: Simplify

• 描述：Whether to return a simplified version of the response instead of the raw data

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

AI 工具节点：‘输出’参数

¥AI tool nodes: ‘Output’ parameter

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

¥When an endpoint returns data with more than 10 fields, add the 'Output' option parameter with 3 modes.

在 AI 工具节点中，允许用户进行更精细的控制，并选择要输出的字段。这样做的原因是工具可能会超出上下文窗口，并且可能会被过多的字段搞糊涂，因此最好只传递它们需要的字段。

¥In AI tool nodes, allow the user to be more granular and select the fields to output. The rationale is that tools may run out of context window and they can get confused by too many fields, so it's better to pass only the ones they need.

选项：

¥Options:

• 简化：工作方式与上述 "简化" 参数相同。

¥Simplified: Works the same as the "Simplify" parameter described above.

• 原始：返回所有可用字段。

¥Raw: Returns all the available fields.

• 已选字段：显示一个多选项参数，用于选择要添加到输出并发送给 AI 代理的字段。默认情况下，此选项始终返回记录/实体的 ID。

¥Selected fields: Shows a multi-option parameter for selecting the fields to add to the output and send to the AI agent. By default, this option always returns the ID of the record/entity.

复制

¥Copy

文本大小写

¥Text Case

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

¥Use Title Case for the node name, parameters display names (labels), dropdown titles. Title Case is when you capitalize the first letter of each word, except for certain small words, such as articles and short prepositions.

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

¥Use Sentence case for node action names, node descriptions, parameters descriptions (tooltips), hints, dropdown descriptions.

术语

¥Terminology

• 请使用第三方服务术语：尝试使用与你正在交互的服务相同的术语（例如，Notion 'blocks'，而不是 Notion 'paragraphs'）。

¥Use the third-party service terminology: Try to use the same terminology as the service you're interfacing with (for example, Notion 'blocks', not Notion 'paragraphs').

• 请使用用户界面中使用的术语：请使用服务用户界面中使用的术语，而不是 API 或技术文档中使用的术语（例如，在 Trello 中，卡片显示为 "archive"，但在 API 中显示为 "closed"。在这种情况下，你可能需要使用 "archive"）。

¥Use the terminology used in the UI: Stick to the terminology used in the user interface of the service, rather than that used in the APIs or technical documentation (for example, in Trello you "archive" cards, but in the API they show up as "closed". In this case, you might want to use "archive").

• 无技术术语：如有简单的词语，请勿使用技术术语。例如，使用 "field" 代替 "key"。

¥No tech jargon: Don't use technical jargon where simple words will do. For example, use "field" instead of "key".

• 命名一致：为某个事物选择一个术语并坚持使用。例如，不要混用 "directory" 和 "folder"。

¥Consistent naming: Choose one term for something and stick to it. For example, don't mix "directory" and "folder".

占位符

¥Placeholders

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

¥It's often helpful to insert examples of content in parameters placeholders. These should start with "e.g." and use camel case for the demo content in fields.

可复制的占位符示例：

¥Placeholder examples to copy:

• image：e.g. https://example.com/image.png

• 视频：e.g. https://example.com/video.mp4

¥video: e.g. https://example.com/video.mp4

• 搜索词：e.g. automation

¥search term: e.g. automation

• 电子邮件：e.g. nathan@example.com

¥email: e.g. nathan@example.com

• Twitter 用户（或类似用户）：e.g. n8n

¥Twitter user (or similar): e.g. n8n

• 名称：e.g. Nathan Smith

¥Name and last name: e.g. Nathan Smith

• 名字：e.g. Nathan

¥First name: e.g. Nathan

• 姓氏：e.g. Smith

¥Last name: e.g. Smith

操作名称、操作和描述

¥Operations name, action, and description

• 名称：这是节点在画布上打开时，选择框中显示的名称。必须使用标题大小写，并且不必包含资源（例如，"删除"）。

¥Name: This is the name displayed in the select when the node is open on the canvas. It must use title case and doesn't have to include the resource (for example, "Delete").

• 操作：这是用户选择节点时，面板中显示的操作名称。必须使用句子大小写，并且必须包含资源（例如，"删除记录"）。

¥Action: This is the name of the operation displayed in the panel where the user selects the node. It must be in sentence case and must include the resource (for example, "Delete record").

• 描述：这是节点在画布上打开时，下拉列表中名称下方显示的子文本。必须使用句子大小写，并且必须包含资源。它可以添加一些信息，并使用除基本资源/操作之外的其他词语（例如，"检索用户列表"）。

¥Description: This is the sub-text displayed below the name in the select when the node is open on the canvas. It must use sentence case and must include the resource. It can add a bit of information and use alternative words than the basic resource/operation (for example, "Retrieve a list of users").

• 如果操作作用于非资源实体（例如，Google 表格中的一行），请在操作名称中指定（例如，"删除行"）。

¥If the operation acts on an entity that's not the Resource (for example, a row in a Google Sheet), specify that in the operation name (for example, "Delete Row").

一般来说，了解操作的目标非常重要。有时，操作的对象就是资源本身（例如，使用 Sheet:Delete 删除工作表）。

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

在其他情况下，操作对象并非资源本身，而是资源内部包含的内容（例如，Table:Delete rows，这里的资源是表，但你操作的是表中的行）。

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

命名 name

¥Naming name

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

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

• 参数：name

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

• 例如：Sheet:Delete → 无需在 Delete 中重复 Sheet，因为 n8n 会在上面的字段中显示 Sheet，而你要删除的是工作表。

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

• 例如：Delete Records → 在 Airtable 中，没有资源选择功能，因此最好指定删除操作将删除记录。

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

• 例如：Table:Get Columns → 指定 Columns，因为资源是 Table，而操作对象是 Columns。

  ¥For example: Table:Get Columns → Specify Columns because the resource is Table, while the object of the operation is Columns.

命名 action

¥Naming action

这是用户选择节点时，面板中显示的操作名称。

¥This is the name of the operation displayed in the panel where the user selects the node.

• 参数：action

¥Parameter: action

• 大小写：句子大小写

¥Case: Sentence case

命名指南：

¥Naming guidelines:

• 省略文章：为了保持文本简洁，请删除冠词（a、an、the 等）。

¥Omit articles: To keep the text shorter, get rid of articles (a, an, the…).

• 正确：Update row in sheet

  ¥correct: Update row in sheet

• 错误：Update a row in a 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.

• 例如：Append Rows → 必须指定 Rows，因为你实际要追加的是行。请勿添加资源 (Sheet)，因为你并未向该资源追加数据。

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

命名 description

¥Naming description

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

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

• 参数：description

¥Parameter: description

• 大小写：句子大小写

¥Case: Sentence case

命名指南：

¥Naming guidelines:

• 如果可能，请添加比操作 name 中指定的更多信息。

¥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 使用通用词汇表和一些特定于上下文的词汇表来描述类似应用组（例如，数据库或电子表格）。

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

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

¥The general vocabulary takes inspiration from CRUD operations:

• 清除

¥Clear

• 删除资源的所有内容（清空资源）。

  ¥Delete all the contents of the resource (empty the resource).

• 描述：Delete all the <CHILD_ELEMENT>s inside the <RESOURCE>

  ¥Description: Delete all the <CHILD_ELEMENT>s inside the <RESOURCE>

• 创建

¥Create

• 创建新的资源实例。

  ¥Create a new instance of the resource.

• 描述：Create a new <RESOURCE>

  ¥Description: Create a new <RESOURCE>

• 创建或更新

¥Create or Update

• 创建或更新资源的现有实例。

  ¥Create or update an existing instance of the resource.

• 描述：Create a new <RESOURCE> or update an existing one (upsert)

  ¥Description: Create a new <RESOURCE> or update an existing one (upsert)

• 删除

¥Delete

• 你可以通过两种不同的方式使用 "删除"：

  ¥You can use "Delete" in two different ways: 1. 删除资源

  ¥Delete a resource:

  • 描述：Delete a <RESOURCE> permanently（仅当需要时才使用 "permanently"）

    ¥Description: Delete a <RESOURCE> permanently (use "permanently" only if that's the case) 2. 删除资源中的内容（例如，一个行）：

  ¥Delete something inside of the resource (for example, a row):

  • 在这种情况下，始终指定操作对象：例如，Delete Rows 或 Delete Records。

    ¥In this case, always specify the object of the operation: for example, Delete Rows or Delete Records.

  • 描述：Delete a <CHILD_ELEMENT> permanently

    ¥Description: Delete a <CHILD_ELEMENT> permanently

• 获取

¥Get

• 你可以通过两种不同的方式使用 "获取"：

  ¥You can use "Get" in two different ways: 1. 获取资源

  ¥Get a resource:

  • 描述：Retrieve a <RESOURCE>

    ¥Description: Retrieve a <RESOURCE> 2. 获取资源中的项目（例如，记录）。

  ¥Get an item inside of the resource (for example, records):

  • 在这种情况下，始终指定操作对象：例如，Get Row 或 Get Record。

    ¥In this case, always specify the object of the operation: for example, Get Row or Get Record.

  • 描述：Retrieve a <CHILD_ELEMENT> from the/a <RESOURCE>

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

  • 描述：Retrieve a list of <RESOURCE>s

    ¥Description: Retrieve a list of <RESOURCE>s 2. 获取资源中的项目列表（例如，记录）：

  ¥Get a list of items inside of the resource (for example, records):

  • 在这种情况下，始终指定操作对象：例如，Get Many Rows 或 Get Many Records。

    ¥In this case, always specify the object of the operation: for example, Get Many Rows or Get Many Records.

  • 你可以省略 Many：Get Many Rows 可以是 Get Rows。

    ¥You can omit Many: Get Many Rows can be Get Rows.

  • 描述：List all <CHILD_ELEMENT>s in the/a <RESOURCE>

    ¥Description: List all <CHILD_ELEMENT>s in the/a <RESOURCE>

• 插入或追加

¥Insert or Append

• 在资源中添加内容。

  ¥Add something inside of a resource.

• 使用 insert 表示数据库节点。

  ¥Use insert for database nodes.

• 描述：Insert <CHILD_ELEMENT>(s) in a <RESOURCE>

  ¥Description: Insert <CHILD_ELEMENT>(s) in a <RESOURCE>

• 插入、更新、追加或更新

¥Insert or Update or Append or Update

• 在资源中添加或更新内容。

  ¥Add or update something inside of a resource.

• 使用 insert 表示数据库节点。

  ¥Use insert for database nodes.

• 描述：Insert <CHILD_ELEMENT>(s) or update an existing one(s) (upsert)

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

  • 描述：Update one or more <RESOURCE>s

    ¥Description: Update one or more <RESOURCE>s 2. 更新资源中的某些内容（例如，一行）：

  ¥Update something inside of a resource (for example, a row):

  • 在这种情况下，始终指定操作对象：例如，Update Rows 或 Update Records。

    ¥In this case, always specify the object of the operation: for example, Update Rows or Update Records.

  • 描述：Update <CHILD_ELEMENT>(s) inside a <RESOURCE>

    ¥Description: Update <CHILD_ELEMENT>(s) inside a <RESOURCE>

引用参数和字段名称

¥Referring to parameter and field name

复制时，如果需要引用参数名或字段名，请用单引号将其括起来（例如，“请填写 '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...'

错误

¥Errors

总体理念

¥General philosophy

错误会给用户带来诸多不便。因此，n8n 始终会告知用户：

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

• 如何解决问题：或者至少说明如何摆脱困境并继续顺利使用 n8n。n8n 不希望用户一直处于阻塞状态，因此请利用这个机会引导他们成功。

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

• 如果你有触发错误的参数的 displayName，请将其包含在错误消息或描述中（或两者都包含）。

¥If you have the displayName of the parameter that triggered the error, include it in the error message or description (or both).

• 项目索引：如果你知道触发错误的项的 ID，请将 [Item X] 附加到错误消息中。例如，The ID of the release in the parameter “Release ID” for could not be found [item 2]。

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

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

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

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

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