Skip to content

社区节点的 UX 指南(UX guidelines for community nodes)#

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

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

  • 创建
  • 创建或更新（上存）
  • 删除
  • 获取
  • 获取更多: 也用于某些筛选或搜索可用的情况
  • 更新

备注：

🌐 Notes:

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

资源定位器(Resource Locator)#

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

与其他节点的一致性(Consistency with other nodes)#

  • 保持用户体验一致性：n8n 尽量保持其用户体验的一致性。这意味着要遵循现有的用户体验模式，尤其是那些在最新的新节点或经过重制的节点中使用的模式。
  • 检查类似的节点：例如，如果你正在处理一个数据库节点，那么值得检查一下 Postgres 节点。

排序选项(Sorting options)#

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

节点功能(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个时，请添加“Simplify”布尔参数，以返回最多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 参数通过减少数据大小来缓解这个问题。
  • 选择要在简化节点中输出的最常用字段，并按使用频率排序，使最常用的字段位于顶部。
  • 在“简化”模式下，通常最好将嵌套字段展平。
  • 显示名称：Simplify
  • 描述：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:

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

复制(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”）。
  • 使用用户界面中的术语： 坚持使用服务用户界面中的术语，而不是 API 或技术文档中使用的术语（例如，在 Trello 中你是“归档”卡片，但在 API 中它们显示为“已关闭”。在这种情况下，你可能想使用“归档”）。
  • 不要使用技术术语： 在简单词可以表达的地方，避免使用技术术语。例如，用“字段”而不是“键”。
  • 命名一致性: 为某个事物选择一个术语并坚持使用。例如，不要混用“目录”和“文件夹”。

占位符(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:

  • 图片: e.g. https://example.com/image.png
  • 视频：e.g. https://example.com/video.mp4
  • 搜索词：e.g. automation
  • 电子邮件：e.g. nathan@example.com
  • 推特用户（或类似平台）：e.g. n8n
  • 名字和姓氏：e.g. Nathan Smith
  • 名字：e.g. Nathan
  • 姓：e.g. Smith

操作名称、操作和描述(Operations name, action, and description)#

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

通常情况下，理解操作的对象是什么是很重要的。有时，操作的对象就是资源本身（例如，使用 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
  • 案例：标题大小写

命名指南：

🌐 Naming guidelines:

  • 不要重复资源（如果资源选择在上方）： 资源通常显示在操作上方，因此在操作中没有必要重复它（如果操作的对象就是资源本身，则适用此情况）。
    • 例如：Sheet:Delete → 不需要在 Delete 中重复 Sheet，因为 n8n 会在上面的字段显示 Sheet，而你正在删除的是表格。
  • 如果上面没有资源可选择，请指定资源： 在某些节点中，你可能无法选择资源（因为只有一个资源）。在这种情况下，请在操作中指定资源。
    • 例如：Delete Records → 在 Airtable 中，没有资源选择，所以最好明确说明删除操作会删除记录。
  • 如果操作的对象不是资源，请指定对象： 有时，操作的对象不是资源。在这些情况下，也需要在操作中指定该对象。
    • 例如：Table:Get Columns → 指定 Columns，因为资源是 Table，而操作的对象是 Columns。

命名 action(Naming action)#

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

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

  • 参数：action
  • 案例：首字母大写

命名指南：

🌐 Naming guidelines:

  • 省略冠词: 为了让文本更短，去掉冠词（a, an, the…）。
    • 正确: Update row in sheet
    • 不正确: Update a row in a sheet
  • 重复资源： 在这种情况下，可以重复使用资源。即使资源在列表中可见，用户可能也没有注意到，在操作标签中重复展示它是有用的。
  • 如果操作的对象不是资源，请指定对象： 与操作名称相同。在这种情况下，你无需重复资源。
    • 例如：Append Rows → 你必须指定 Rows，因为行是你实际在追加的对象。不要添加资源（Sheet），因为你并不是在向资源追加。

命名 description(Naming description)#

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

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

  • 参数：description
  • 案例：首字母大写

命名指南：

🌐 Naming guidelines:

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

词汇表(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:

  • 清除
    • 删除资源的所有内容（清空资源）。
    • 描述：Delete all the <CHILD_ELEMENT>s inside the <RESOURCE>
  • 创建
    • 创建新的资源实例。
    • 描述：Create a new <RESOURCE>
  • 创建或更新
    • 创建或更新资源的现有实例。
    • 描述：Create a new <RESOURCE> or update an existing one (upsert)
  • 删除
    • 您可以用“删除”有两种不同的方式：
      1. 删除资源
        • 描述：Delete a <RESOURCE> permanently（仅在确实如此的情况下使用“永久”）
      2. 删除资源内部的某个内容（例如，一行）：
        • 在这种情况下，始终指定操作对象：例如，Delete Rows 或 Delete Records。
        • 描述：Delete a <CHILD_ELEMENT> permanently
  • 获取
    • 你可以用“获取”有两种不同的方式：
      1. 获取资源
        • 描述：Retrieve a <RESOURCE>
      2. 获取资源内部的项目（例如，记录）:
        • 在这种情况下，始终指定操作对象：例如，Get Row 或 Get Record。
        • 描述：Retrieve a <CHILD_ELEMENT> from the/a <RESOURCE>
  • 获取许多
    • 你可以用“获取多个”有两种不同的方式：
      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。
    • 描述：Insert <CHILD_ELEMENT>(s) in a <RESOURCE>
  • 插入或更新 或 追加或更新
    • 在资源中添加或更新内容。
    • 对于数据库节点，请使用 insert。
    • 描述：Insert <CHILD_ELEMENT>(s) or update an existing one(s) (upsert)
  • 更新
    • 您可以用两种不同的方式使用“更新”:
      1. 更新资源
        • 描述：Update one or more <RESOURCE>s
      2. 更新资源内部的某些内容（例如，一行）：
        • 在这种情况下，始终指定操作对象：例如，Update Rows 或 Update Records。
        • 描述：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:

  • 发生了什么：对错误的描述以及出了什么问题。
  • 如何解决问题：或至少如何摆脱困境，继续顺利使用 n8n。n8n 不希望用户长期被卡住，因此请将此作为引导他们获得成功的机会。

输出面板中的错误结构(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，请将其包含在错误消息或描述中（或两者都包含）。
  • 项目索引：如果你有触发错误的项目 ID，请在错误消息中附加 [Item X]。例如，The ID of the release in the parameter “Release ID” for could not be found [item 2]。
  • 避免使用“错误”、“问题”、“失败”、“失误”等词。

错误描述 - 如何解决或脱困(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".