跳到主要内容

好的，请提供需要翻译的英文技术文档段落。我会严格按照要求，只翻译自然语言部分，保持所有代码块和命令的原始格式不变。

社区节点用户体验指南#

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

凭据#​

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

OAuth#​

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

节点结构#​

需包含的操作#​

请尽量为每种资源类型包含CRUD操作。

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

  • 创建
  • 创建或更新（更新插入）
  • 删除
  • 获取
  • 获取多个： 当存在筛选或搜索功能时也可使用
  • 更新

注意事项：

  1. 这些操作可应用于资源本身或资源内部的实体（例如Google表格中的行）。对资源内部实体进行操作时，必须在操作名称中指定实体名称。
  2. 命名可能因节点和资源而异。详情请参阅后续指南。

资源定位器#​

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

与其他节点的一致性#​

  • 保持用户体验一致性：n8n致力于保持用户体验的一致性。这意味着需要遵循现有的用户体验模式，特别是最新新建或重构节点中使用的模式。
  • 参考类似节点：例如，如果您正在开发数据库节点，值得参考Postgres节点。

排序选项#​

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

节点功能#​

删除操作输出#​

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

简化输出字段#​

普通节点：“简化”参数#​

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

  • n8n的主要问题之一是数据大小，简化参数通过减小数据大小来限制该问题。
  • 选择在简化节点中最有用的输出字段，并按使用频率排序，将最常用的字段置于顶部。
  • 在简化模式下，通常最好展平嵌套字段
  • 显示名称：简化
  • 描述：是否返回简化版本的响应而非原始数据

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

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

在AI工具节点中，允许用户更精细地选择要输出的字段。理由是工具可能会耗尽上下文窗口，过多字段会使它们混淆，因此最好仅传递所需的字段。

选项：

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

文案#​

文本大小写#​

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

对节点操作名称、节点描述、参数描述（工具提示）、提示、下拉菜单描述使用句子式大小写。

术语#​

  • 使用第三方服务术语： 尽量使用与您对接的服务相同的术语（例如，Notion的“块”，而非Notion的“段落”）。
  • 使用用户界面中的术语： 坚持使用服务用户界面中的术语，而非API或技术文档中使用的术语（例如，在Trello中您“归档”卡片，但在API中它们显示为“已关闭”。在这种情况下，您可能希望使用“归档”）。
  • 避免技术行话： 在简单词汇可用时不要使用技术行话。例如，使用“字段”而非“键”。
  • 一致的命名： 为某物选择一个术语并坚持使用。例如，不要混用“目录”和“文件夹”。

占位符#​

可复制的占位符示例：

  • 图片：例如 https://example.com/image.png
  • 视频：例如 https://example.com/video.mp4
  • 搜索词：例如 automation
  • 电子邮件：例如 user@example.com
  • Twitter用户（或类似）：例如 n8n
  • 姓名：例如 Nathan Smith
  • 名字：例如 Nathan
  • 姓氏：例如 Smith

操作名称、操作和描述#​

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

作为一般规则，理解操作的对象很重要。有时，操作的对象是资源本身（例如，表格：删除用于删除表格）。

在其他情况下，操作的对象不是资源，而是资源内部包含的某物（例如，表格：删除行，这里资源是表格，但您操作的是其中的行）。

命名名称#​

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

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

命名指南：

  • 如果上方已选择资源，请勿重复资源： 资源通常显示在操作上方，因此无需在操作中重复（如果操作的对象是资源本身）。
    • 例如：表格：删除 → 无需在删除中重复表格，因为n8n在上方字段中显示表格，且您删除的是表格。
  • 如果上方没有资源选择，请指定资源： 在某些节点中，您不会有资源选择（因为只有一个资源）。在这些情况下，请在操作中指定资源。
    • 例如：删除记录 → 在Airtable中，没有资源选择，因此最好指定删除操作将删除记录。
  • 如果操作对象不是资源，请指定操作对象： 有时，操作的对象不是资源。在这些情况下，也请在操作中指定对象。
    • 例如：表格：获取列 → 指定列，因为资源是表格，而操作的对象是列。

命名操作#​

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

命名指南：

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

命名描述#​

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

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

命名指南：

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

词汇表#​

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

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

  • 清空
    • 删除资源的所有内容（清空资源）。
    • 描述：删除<资源>内的所有<子元素>
  • 创建
    • 创建资源的新实例。
    • 描述：创建新的<资源>
  • 创建或更新
    • 创建或更新资源的现有实例。
    • 描述：创建新的<资源>或更新现有资源（更新插入）
  • 删除
    • 您可以通过两种不同方式使用“删除”：
      1. 删除资源：
        • 描述：永久删除<资源>（仅当确实如此时使用“永久”）
      2. 删除资源内部的某物（例如行）：
        • 在这种情况下，始终指定操作的对象：例如删除行或删除记录。
        • 描述：永久删除<子元素>
  • 获取
    • 您可以通过两种不同方式使用“获取”：
      1. 获取资源：
        • 描述：检索<资源>
      2. 获取资源内部的项目（例如记录）：
        • 在这种情况下，始终指定操作的对象：例如获取行或获取记录。
        • 描述：从<资源>中检索<子元素>
  • 获取多个
    • 您可以通过两种不同方式使用“获取多个”：
      1. 获取资源列表（无筛选）：
        • 描述：检索<资源>列表
      2. 获取资源内部的项目列表（例如记录）：
        • 在这种情况下，始终指定操作的对象：例如获取多行或获取多条记录。
        • 可以省略多个：获取多行可以是获取行。
        • 描述：列出<资源>中的所有<子元素>
  • 插入或追加
    • 向资源内部添加某物。
    • 对数据库节点使用插入。
    • 描述：在<资源>中插入<子元素>
  • 插入或更新或追加或更新
    • 在资源内部添加或更新某物。
    • 对数据库节点使用插入。
    • 描述：插入<子元素>或更新现有<子元素>（更新插入）
  • 更新
    • 您可以通过两种不同方式使用“更新”：
      1. 更新资源：
        • 描述：更新一个或多个<资源>
      2. 更新资源内部的某物（例如行）：
        • 在这种情况下，始终指定操作的对象：例如更新行或更新记录。
        • 描述：更新<资源>内的<子元素>

引用参数和字段名称#​

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

布尔描述#​

布尔组件的描述以“是否…”开头

错误#​

总体理念#​

错误是用户痛苦的来源。因此，n8n始终希望告知用户：

  • 发生了什么：错误的描述以及出错的原因。
  • 如何解决问题：或至少如何摆脱困境并继续使用n8n而无需问题。n8n不希望用户被阻塞，因此请利用此机会引导他们成功。

输出面板中的错误结构#​

错误消息 - 发生了什么#​

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

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

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

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

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