社区节点的用户体验指南#
您的节点界面必须符合以下指南才能成为已验证的社区节点候选。
凭据配置#
API密钥和敏感凭据必须始终使用密码字段。
OAuth认证#
如果支持OAuth认证，请务必包含OAuth凭据配置。
节点结构#
应包含的操作#
请为每种资源类型尽量包含CRUD操作。 建议在每个节点的资源操作中包含常见操作。n8n使用特定的CRUD操作来保持体验一致性，允许用户对资源执行基础操作。推荐包含以下操作：
- 创建
- 创建或更新（增改）
- 删除
- 获取单项
- 获取多项：当支持筛选或搜索功能时也应使用此操作
- 更新
注意事项：
- 这些操作可应用于资源本身或资源内的实体（例如Google表格中的行数据）。当对资源内的实体进行操作时，必须在操作名称中明确实体名称。
- 命名方式可根据节点和资源类型进行调整。具体请参考后续指南。
资源定位器#
- 尽可能使用资源定位器组件，这将为用户提供更优的交互体验。当需要选择单个项目时，资源定位器组件尤为实用。
- 资源定位器组件的默认选项应设置为"从列表选择"（如果该选项可用）。
与其他节点保持一致性#
- 保持用户体验一致性：n8n致力于维持统一的用户体验。这意味着需要遵循现有的UX模式，特别是最新新建或重构节点中使用的模式。
- 参考相似节点：例如，如果您正在开发数据库节点，建议参考Postgres节点的实现方式。
排序选项#
- 通过为用户提供排序选项，可以增强特定的"获取多个"操作。
- 在专用集合（位于"选项"集合下方）中添加排序功能。请参考 Airtable Record:Search 的示例实现。
节点功能#
删除操作输出#
删除项目（如记录或行）时，返回包含单个对象的数组：{"deleted": true}。这是向用户确认删除操作已成功执行，该条目将触发后续节点。
简化输出字段#
常规节点：'Simplify' 参数#
当接口返回数据包含超过10个字段时，应添加"Simplify"布尔参数以返回最多包含10个字段的简化版本输出。
- n8n 的主要问题之一可能是数据量过大，Simplify 参数通过减小数据量来缓解此问题。
- 选择最有用的字段在简化节点中输出，并按使用频率降序排列。
- 在简化模式下，通常建议将嵌套字段展平
- 显示名称：
Simplify - 描述：
是否返回简化版本的响应而非原始数据
AI 工具节点：'Output' 参数#
当接口返回数据包含超过10个字段时，需添加包含3种模式的'Output'选项参数。 在 AI 工具节点中，允许用户更精细地选择要输出的字段。其原理是工具可能会超出上下文窗口限制，过多字段会导致混淆，因此最好仅传递必需的字段。
选项：
- Simplified（简化模式）： 功能与上述"Simplify"参数相同。
- Raw（原始模式）： 返回所有可用字段。
- Selected fields（选择字段模式）： 显示多选参数供用户选择要添加到输出并发送给 AI 代理的字段。此选项默认始终返回记录/实体的 ID。
文案规范#
文本大小写#
节点名称、参数显示名称（标签）、下拉菜单标题使用首字母大写格式。首字母大写格式是指除某些小词（如冠词和短介词）外，每个单词的首字母都大写。
节点操作名称、节点描述、参数描述（工具提示）、提示文本、下拉菜单描述使用句子格式。
术语规范#
- 使用第三方服务术语：尽量使用与对接服务相同的术语（例如使用 Notion 的"blocks"而非"paragraphs"）。
- 采用界面用语：遵循服务用户界面使用的术语，而非 API 或技术文档中的表述（例如在 Trello 中您需要"归档"卡片，但 API 中显示为"已关闭"，此时应使用"归档"）。
- 避免技术行话：能用简单词汇时不要使用技术行话。例如使用"字段"而非"键"。
- 保持命名一致性：对同一事物选择单一术语并始终沿用。例如不要混用"目录"和"文件夹"。
占位符#
在参数占位符中插入内容示例通常很有帮助。这些示例应以"例如"开头，字段中的演示内容使用驼峰式大小写。 可复用的占位符示例：
- 图片：
例如 https://example.com/image.png - 视频：
例如 https://example.com/video.mp4 - 搜索词：
例如 automation - 邮箱：
例如 nathan@example.com - Twitter用户（或类似）：
例如 n8n - 姓名：
例如 Nathan Smith - 名字：
例如 Nathan - 姓氏：
例如 Smith
操作名称、动作与描述#
- 名称（Name）： 在画布中打开节点时选择框中显示的名称。需采用首字母大写格式（Title Case），且不必包含资源名称（例如"Delete"）。
- 动作（Action）： 用户选择节点时在面板中显示的操作名称。需采用句子格式（Sentence Case）且必须包含资源名称（例如"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，且删除对象就是表格本身。
- 示例：
- 无资源选择框时需指定资源名： 部分节点没有资源选择框（因为仅存在单一资源）。此时应在操作名称中明确资源。
- 示例：
Delete Records→ Airtable节点没有资源选择框，因此最好明确删除操作的对象是记录（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] - 避免使用"错误"、"问题"、"故障"、"失误"等词汇
错误描述 - 如何解决或继续操作#
描述内容需向用户阐明如何解决问题、需要调整节点配置（若适用）或如何从当前状态继续操作。此处应引导用户执行下一步操作并解除阻碍。
避免使用"错误"、"问题"、"故障"、"失误"等词汇。