Skip to content

社区节点的用户体验指南

您的节点的 UI 必须符合这些准则才能成为经过验证的社区节点候选人。

证书

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

OAuth

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

节点结构

包括的操作

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

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

  • 创造
  • 创建或更新（Upsert）
  • 删除
  • 得到
  • 获取多个：也用于某些过滤或搜索可用时
  • 更新

笔记：

  1. 这些操作可以应用于资源本身或资源内部的实体（例如，Google Sheet 中的一行）。对资源内部的实体进行操作时，必须在操作名称中指定该实体的名称。
  2. 命名可能会根据节点和资源而变化。有关详细信息，请参阅以下指南。

资源定位器

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

与其他节点的一致性

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

排序选项

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

节点功能

删除操作输出

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

简化输出字段

普通节点：“简化”参数

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

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

AI工具节点：“输出”参数

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

在 AI 工具节点中，允许用户更精细地选择要输出的字段。这样做的原因是，工具可能会超出上下文窗口，并且可能会因字段过多而感到困惑，因此最好只传递所需的字段。

选项：

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

复制

文本大小写

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

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

术语

  • 使用第三方服务术语：尝试使用与您正在交互的服务相同的术语（例如，Notion“块”，而不是Notion“段落”）。
  • 使用 UI 中使用的术语：坚持使用服务用户界面中使用的术语，而不是 API 或技术文档中使用的术语（例如，在 Trello 中您“存档”卡片，但在 API 中它们显示为“已关闭”。在这种情况下，您可能需要使用“存档”）。
  • 不要使用技术术语：在可以用简单词语表达的地方，不要使用技术术语。例如，使用“field”而不是“key”。
  • 命名保持一致：为某个事物选择一个术语并坚持使用。例如，不要混淆“目录”和“文件夹”。

占位符

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

要复制的占位符示例：

  • 图像：
  • 视频：
  • 搜索词：
  • 电子邮件：
  • Twitter 用户（或类似用户）：
  • 名字和姓氏：
  • 名：
  • 姓：

操作名称、操作和描述

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

一般来说，了解操作的对象是什么非常重要。有时，操作的对象是资源本身（例如，删除 Sheet）。

还有些情况下，操作的对象不是资源本身，而是资源内部包含的内容（比如，这里的资源是表，但操作的却是表里面的行）。

命名

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

  • 范围：
  • 大小写：标题大小写

命名准则：

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

命名

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

命名准则：

  • 省略冠词：为了使文本更简短，请删除冠词（a、an、the…）。
    • 正确
    • ：
    • 不正确
    • ：
  • 重复资源：在这种情况下，可以重复资源。即使资源在列表中可见，用户也可能不会注意到，因此在操作标签中重复它会很有用。
  • 如果操作对象不是资源，请指定该对象：与操作名称相同。在这种情况下，您无需重复资源。
    • 例如：
    • → 您必须指定
    • ，因为您实际要附加到的是行。请勿添加资源 (
    • )，因为您不是要附加到资源。

命名

这是当节点在画布上打开时在选择中的名称下方显示的潜台词。

  • 范围：
  • 大小写：句子大小写

命名准则：

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

词汇

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

通用词汇表从 CRUD 操作中汲取灵感：

  • 清除
    • 删除资源的所有内容（清空资源）。
    • 描述：
  • 创建
    • 创建资源的新实例。
    • 描述：
  • 创建或更新
    • 创建或更新资源的现有实例。
    • 描述：
  • 删除
    • 您可以通过两种不同的方式使用“删除”：
      1. 删除资源：
        • 说明：（
        • 仅在这种情况下使用“永久”）
      1. 删除
    资源
      1. 内部
    的某些内容
      1. （例如，一行）：
        • 在这种情况下，
        • 始终指定操作的对象
        • ：例如，
        • 或
        • 。
        • 说明：
  • 获取
    • 您可以通过两种不同的方式使用“获取”：
      1. 获取资源：
        • 说明：
    获取
      1. 资源
      1. 内的
      1. 项目
    （例如，记录）：
        • 在这种情况下，
        • 始终指定操作的对象
        • ：例如
        • 或
        • 。
        • 说明：
  • 获取多项
    • 您可以通过两种不同的方式使用“获取多项”：
      1. 获取资源列表（不带筛选）：
        • 说明：
    获取资源
      1. 内的
      1. 项目列表
      1. （例如，记录）：
        • 在这种情况下，
        • 始终指定操作的对象
        • ：例如，
        • 或
        • 。
        • 您可以省略
        • ：
        • 可以是
        • 。
        • 说明：
  • 插入或追加：
    • 在资源中添加内容。
    • 用于
    • 数据库节点。
    • 描述：
  • 插入、更新、追加或更新：
    • 在资源内部添加或更新内容。
    • 用于
    • 数据库节点。
    • 描述：
  • 更新
    • 您可以通过两种不同的方式使用“更新”：
      1. 更新资源：
        • 说明：
      1. 更新
    资源
      1. 内部
      1. 的某些内容（例如，一行）：
        • 在这种情况下，
        • 始终指定操作的对象
        • ：例如
        • 或
        • 。
        • 说明：

引用参数和字段名称

当需要在文案中引用参数名或者字段名时，请使用单引号括起来（例如“请填写参数”。

布尔描述

以“是否......”开始描述布尔组件

错误

一般哲学

错误是用户的痛点。因此，n8n 总是想告诉用户：

  • 发生了什么：错误描述以及出了什么问题。
  • 如何解决问题：或者至少如何摆脱困境并继续使用 n8n 而不会出现问题。n8n 不希望用户继续受到阻碍，因此请利用这个机会引导他们走向成功。

输出面板中的错误结构

错误消息 - 发生了什么

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

  • 如果您有触发错误的参数，请将其包含在错误消息或描述中（或两者）。
  • 项目索引：如果您有触发错误的项目的 ID，请将其附加到错误消息中。例如， 。
  • 避免使用“错误”、“问题”、“失败”、“失误”等词语。

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

描述部分会向用户解释如何解决问题、需要更改节点配置（如果出现问题）以及如何解决。在这里，你应该引导他们进行下一步操作并解除锁定。

避免使用“错误”、“问题”、“失败”、“失误”等词语。