社区节点的用户体验指南#
您的节点用户界面必须符合以下准则，才能成为已验证社区节点的候选者。
凭证认证#
API密钥和敏感凭证应始终使用密码字段。
OAuth认证#
如果可用，请始终包含OAuth凭证。
节点结构#
应包含的操作#
尽量为每种资源类型包含CRUD操作。
尽量在每个资源的节点中包含常见操作。n8n使用一些CRUD操作来保持体验一致性，并允许用户对资源执行基本操作。建议包含以下操作：
- 创建
- 创建或更新(合并)
- 删除
- 获取
- 获取多个：当有筛选或搜索功能时也使用此操作
- 更新
注意事项：
- 这些操作可以应用于资源本身或资源内部的实体(例如Google表格中的行)。当操作资源内部的实体时，必须在操作名称中指定实体名称。
- 命名可能会根据节点和资源的不同而变化。详情请查看以下指南。
资源定位器#
- 尽可能使用资源定位器组件。这能为用户提供更好的体验。当需要选择单个项目时，资源定位器组件通常非常有用。
- 资源定位器组件的默认选项应为"从列表中选择"(如果可用)。
与其他节点的一致性#
- 保持用户体验一致性：n8n努力保持用户体验的一致性。这意味着要遵循现有的UX模式，特别是最新新增或彻底改造的节点中使用的模式。
- 检查类似节点：例如，如果您正在开发数据库节点，值得参考Postgres节点的实现。
排序选项#
- 您可以通过为用户提供排序选项来增强某些"获取多条记录"操作。
- 在专门的集合中添加排序功能（位于"Options"集合下方）。参考 Airtable Record:Search 的示例实现。
节点功能#
删除操作输出#
当删除一个项目（如记录或行）时，返回包含单个对象的数组：{"deleted": true}。这是对用户的确认，表示删除成功，该项目将触发后续节点。
简化输出字段#
普通节点：'Simplify'参数#
当端点返回的数据包含超过10个字段时，添加"Simplify"布尔参数以返回最多包含10个字段的简化版本输出。
- n8n的一个主要问题可能是数据量过大，Simplify参数通过减少数据大小来限制这个问题。
- 选择最有用的字段在简化节点中输出，并按使用频率排序，将最常用的字段放在顶部。
- 在Simplify模式下，通常最好展平嵌套字段
- 显示名称：
Simplify - 描述：
是否返回简化版本的响应而非原始数据
AI 工具节点：'输出'参数#
当端点返回包含超过 10 个字段的数据时，需添加带有 3 种模式的'输出'选项参数。
在 AI 工具节点中，允许用户更精细地选择要输出的字段。这样做的原因是工具可能会超出上下文窗口限制，且过多字段可能导致混淆，因此最好只传递所需的字段。
选项：
- 简化模式： 功能与上述"简化"参数相同。
- 原始模式： 返回所有可用字段。
- 选择字段模式： 显示多选参数用于选择要添加到输出并发送给 AI 代理的字段。默认情况下，此选项始终返回记录/实体的 ID。
文案规范#
文本大小写#
对于节点名称、参数显示名称（标签）、下拉菜单标题使用标题式大小写。标题式大小写是指每个单词的首字母大写，但某些小词（如冠词和短介词）除外。
对于节点操作名称、节点描述、参数描述（工具提示）、提示、下拉菜单描述使用句子式大小写。
术语规范#
- 使用第三方服务的术语： 尽量使用与对接服务相同的术语（例如，Notion 中的'blocks'，而非'paragraphs'）。
- 使用界面中的术语： 坚持使用服务用户界面中的术语，而非 API 或技术文档中的术语（例如，在 Trello 中您"归档"卡片，但在 API 中显示为"closed"。这种情况下应使用"归档"）。
- 避免技术术语： 能用简单词汇时不要使用技术术语。例如，使用"字段"而非"键"。
- 命名一致性： 为同一事物选择一个术语并保持一致。例如，不要混用"目录"和"文件夹"。
占位符#
在参数占位符中插入内容示例通常很有帮助。这些示例应以"例如"开头，并在字段中使用驼峰命名法展示示例内容。
可复制的占位符示例：
- 图片：
例如 https://example.com/image.png - 视频：
例如 https://example.com/video.mp4 - 搜索词：
例如 automation - 邮箱：
例如 nathan@example.com - Twitter用户（或类似）：
例如 n8n - 姓名：
例如 Nathan Smith - 名字：
例如 Nathan - 姓氏：
例如 Smith
操作名称、动作和描述#
- 名称(Name)： 这是在画布上打开节点时在选择器中显示的名称。必须使用标题大小写，且不必包含资源名称（例如"Delete"）。
- 动作(Action)： 这是用户选择节点时在面板中显示的操作名称。必须使用句子大小写且必须包含资源名称（例如"Delete record"）。
- 描述(Description)： 这是在画布上打开节点时在选择器名称下方显示的子文本。必须使用句子大小写且必须包含资源名称。可以添加少量信息并使用与基本资源/操作不同的替代词汇（例如"Retrieve a list of users"）。
- 如果操作作用于非资源实体（例如Google表格中的行），请在操作名称中指定（例如"Delete Row"）。
作为一般规则，理解操作的对象很重要。有时，操作的对象是资源本身（例如Sheet:Delete用于删除工作表）。
在其他情况下，操作的对象不是资源，而是资源中包含的内容（例如Table:Delete rows，这里的资源是表格，但你操作的是其中的行）。
命名 name 属性#
这是在画布上打开节点时，选择框中显示的名称。
- 参数：
name - 大小写：标题式大小写（Title Case）
命名指南：
- 如果上方已有资源选择，则不要重复资源名：资源通常显示在操作上方，因此无需在操作中重复（当操作对象是资源本身时适用）。
- 例如：
Sheet:Delete→ 无需在Delete中重复Sheet，因为 n8n 会在上方字段显示Sheet，而你要删除的正是 Sheet。
- 例如：
- 如果上方没有资源选择，则需指定资源名：某些节点没有资源选择（因为只有一个资源）。这种情况下，应在操作中指定资源。
- 例如：
Delete Records→ 在 Airtable 中没有资源选择，因此最好明确 Delete 操作将删除的是记录（Records）。
- 例如：
- 如果操作对象不是资源本身，需同时指定对象：有时操作对象并非资源本身。这种情况下，应在操作中同时指定对象。
- 例如：
Table:Get Columns→ 指定Columns，因为资源是Table，而操作对象是Columns。
- 例如：
命名 action#
这是用户选择节点时在面板中显示的操作名称。
* 参数：action
* 大小写：句子首字母大写
命名指南：
- 省略冠词：为保持文本简洁，省略冠词（a、an、the...）。
- 正确示例：
Update row in sheet - 错误示例：
Update a row in a sheet - 重复资源名：这种情况下可以重复资源名。即使资源已在列表中可见，用户可能不会注意到，因此在操作标签中重复资源名是有帮助的。
- 如果操作对象不是资源本身则需明确指定：与操作名称规则相同。这种情况下不需要重复资源名。
- 例如：
Append Rows→ 必须指定Rows因为实际追加的是行数据。不要添加资源名（Sheet），因为你不是在向资源本身追加内容。
命名 description#
这是节点在画布上展开时，显示在名称下方的辅助文本。
- 参数：
description - 大小写：句子首字母大写
命名指南：
- 尽可能提供比操作
name中更详细的信息 - 使用替代措辞帮助用户更好理解操作功能。有些用户可能不理解操作名称中的术语（可能英语不是他们的母语），使用不同的表达方式可以帮助他们理解。
术语规范#
n8n 使用通用术语和针对特定应用场景的术语（例如数据库或电子表格）。
通用术语参考了 CRUD 操作：
- 清空(Clear)
- 删除资源的所有内容（清空资源）。
- 描述：
删除<RESOURCE>中的所有<CHILD_ELEMENT>
- 创建(Create)
- 创建资源的新实例。
- 描述：
创建新的<RESOURCE>
- 创建或更新(Create or Update)
- 创建或更新资源的现有实例。
- 描述：
创建新的<RESOURCE>或更新现有资源(upsert)
- 删除(Delete)
- "删除"有两种使用方式：
- 删除资源：
- 描述：
永久删除<RESOURCE>（仅在确实永久删除时使用"永久"）
- 描述：
- 删除资源内部的内容（例如行）：
- 这种情况下必须明确操作对象：例如
删除行或删除记录。 - 描述：
永久删除<CHILD_ELEMENT>
- 这种情况下必须明确操作对象：例如
- 删除资源：
- "删除"有两种使用方式：
- 获取(Get)
- "获取"有两种使用方式：
- 获取资源：
- 描述：
检索<RESOURCE>
- 描述：
- 获取资源内部的项（例如记录）：
- 这种情况下必须明确操作对象：例如
获取行或获取记录。 - 描述：
从<RESOURCE>中检索<CHILD_ELEMENT>
- 这种情况下必须明确操作对象：例如
- 获取资源：
- "获取"有两种使用方式：
- 获取多个(Get Many)
- "获取多个"有两种使用方式：
- 获取资源列表（无过滤条件）：
- 描述：
检索<RESOURCE>列表
- 描述：
- 获取资源内部的多个项（例如记录）：
- 这种情况下必须明确操作对象：例如
获取多行或获取多条记录。 - 可以省略"Many"：
获取多行可以简写为获取行。 - 描述：
列出<RESOURCE>中的所有<CHILD_ELEMENT>
- 这种情况下必须明确操作对象：例如
- 获取资源列表（无过滤条件）：
- "获取多个"有两种使用方式：
- 插入(Insert)或追加(Append)
- 向资源内部添加内容。
- 数据库节点使用
insert。 - 描述：
在<RESOURCE>中插入<CHILD_ELEMENT>
- 插入或更新(Insert or Update)或追加或更新(Append or Update)
- 添加或更新资源内部的内容。
- 数据库节点使用
insert。 - 描述：
插入<CHILD_ELEMENT>或更新现有项(upsert)
- 更新(Update)
- "更新"有两种使用方式：
- 更新资源：
- 描述：
更新一个或多个<RESOURCE>
- 描述：
- 更新资源内部的内容（例如行）：
- 这种情况下必须明确操作对象：例如
更新行或更新记录。 - 描述：
更新<RESOURCE>中的<CHILD_ELEMENT>
- 这种情况下必须明确操作对象：例如
- 更新资源：
- "更新"有两种使用方式：
参数和字段名称引用规范#
当需要在文档中引用参数名或字段名时，请使用单引号包裹（例如："请填写 'name' 参数"）。
布尔值描述规范#
布尔类型组件的描述应以"是否..."开头
错误处理规范#
基本原则#
错误信息对用户来说是痛点。因此，n8n 始终致力于向用户传达：
- 发生了什么：错误描述及出错原因
- 如何解决问题：至少提供如何摆脱困境继续使用 n8n 的方法。n8n 不希望用户被阻塞，因此要抓住机会引导他们走向成功。
输出面板中的错误结构#
错误消息 - 发生了什么#
该消息向用户解释发生了什么，以及当前阻止执行完成的问題。
- 如果知道触发错误的参数
displayName，请将其包含在错误消息或描述中（或两者都包含） - 项目索引：如果知道触发错误的项目 ID，请在错误消息后追加
[第 X 项]。例如：参数"Release ID"中的发布ID未找到 [第2项] - 避免使用"错误"、"问题"、"失败"、"错误"等词语
错误描述 - 如何解决或摆脱困境#
该描述向用户解释如何解决问题，需要更改节点配置中的哪些内容（如果是这种情况），或者如何摆脱困境。在这里，您应该引导他们进入下一步并解除阻塞。
避免使用"错误"、"问题"、"失败"、"错误"等词语。