节点用户界面元素 #

n8n 提供了一套预定义的UI组件（基于JSON文件），允许用户输入各种数据类型。以下是n8n中可用的UI元素。

字符串 #

基础配置：

| ``` { displayName:Name,// The value the user sees in the UI name:name,// The name used to reference the element UI within the code type:string, required:true,// Whether the field is required or not default:'n8n', description:'The name of the user', displayOptions:{// the resources and operations to display this element with show:{ resource:[ // comma-separated list of resource names ], operation:[ // comma-separated list of operation names ] } }, }


---|---
[[字符串](https://docs.n8n.io/_images/integrations/creating-nodes/string.png)](https://docs.n8n.io/_images/integrations/creating-nodes/string.png)

用于输入密码的字符串字段：

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21

| ```
{
displayName:'Password',
name:'password',
type:'string',
required:true,
typeOptions:{
password:true,
},
default:'',
description:`User's password`,
displayOptions:{// the resources and operations to display this element with
show:{
resource:[
// comma-separated list of resource names
],
operation:[
// comma-separated list of operation names
]
}
},
}

---|--- [密码](https://docs.n8n.io/_images/integrations/creating-nodes/password.png)

多行字符串字段：

| ``` { displayName:'Description', name:'description', type:'string', required:true, typeOptions:{ rows:4, }, default:'', description:'Description', displayOptions:{// the resources and operations to display this element with show:{ resource:[ // comma-separated list of resource names ], operation:[ // comma-separated list of operation names ] } }, }


---|---
[[多行数据](https://docs.n8n.io/_images/integrations/creating-nodes/multiple-rows.png)](https://docs.n8n.io/_images/integrations/creating-nodes/multiple-rows.png)
### 支持数据键的拖放功能[#](https://docs.n8n.io/integrations/creating-nodes/build/reference/ui-elements/#support-drag-and-drop-for-data-keys "永久链接")
用户可通过拖放数据值将其映射到字段。拖放操作会创建用于加载数据值的[表达式](https://docs.n8n.io/glossary/#expression-n8n)。n8n 会自动支持此功能。
您需要添加额外配置选项来支持数据键的拖放：
  * `requiresDataPath: 'single'`：适用于需要单个字符串的字段
  * `requiresDataPath: 'multiple'`：适用于可接受逗号分隔字符串列表的字段

[数据集比对节点代码](https://github.com/n8n-io/n8n/blob/master/packages/nodes-base/nodes/CompareDatasets/CompareDatasets.node.ts)中包含相关示例。

## 数值[#](https://docs.n8n.io/integrations/creating-nodes/build/reference/ui-elements/#number "永久链接")
带小数点的数值字段：

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23

| ```
{
displayName:'Amount',
name:'amount',
type:'number',
required:true,
typeOptions:{
maxValue:10,
minValue:0,
numberPrecision:2,
},
default:10.00,
description:'Your current amount',
displayOptions:{// the resources and operations to display this element with
show:{
resource:[
// comma-separated list of resource names
],
operation:[
// comma-separated list of operation names
]
}
},
}

---|--- [小数](https://docs.n8n.io/_images/integrations/creating-nodes/decimal.png)

集合 #

当需要显示可选字段时，请使用 collection 类型：

| ``` { displayName:'Filters', name:'filters', type:'collection', placeholder:'Add Field', default:{}, options:[ { displayName:'Type', name:'type', type:'options', options:[ { name:'Automated', value:'automated', }, { name:'Past', value:'past', }, { name:'Upcoming', value:'upcoming', }, ], default:'', }, ], displayOptions:{// the resources and operations to display this element with show:{ resource:[ // comma-separated list of resource names ], operation:[ // comma-separated list of operation names ] } }, }

---|--- [集合](https://docs.n8n.io/_images/integrations/creating-nodes/collection.png)

日期时间 #

dateTime 类型提供日期选择器功能。

| ``` { displayName:'Modified Since', name:'modified_since', type:'dateTime', default:'', description:'The date and time when the file was last modified', displayOptions:{// the resources and operations to display this element with show:{ resource:[ // comma-separated list of resource names ], operation:[ // comma-separated list of operation names ] } }, }


---|---
[[日期时间](https://docs.n8n.io/_images/integrations/creating-nodes/datetime.png)](https://docs.n8n.io/_images/integrations/creating-nodes/datetime.png)
## 布尔值[#](https://docs.n8n.io/integrations/creating-nodes/build/reference/ui-elements/#boolean "永久链接")
`boolean` 类型提供用于输入真/假值的切换开关。

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17

| ```
{
displayName:'Wait for Image',
name:'waitForImage',
type:'boolean',
default:true,// Initial state of the toggle
description:'Whether to wait for the image or not',
displayOptions:{// the resources and operations to display this element with
show:{
resource:[
// comma-separated list of resource names
],
operation:[
// comma-separated list of operation names
]
}
},
}

---|--- [布尔值](https://docs.n8n.io/_images/integrations/creating-nodes/boolean.png)

颜色 #

color 类型提供颜色选择器。

| ``` { displayName:'Background Color', name:'backgroundColor', type:'color', default:'',// Initially selected color displayOptions:{// the resources and operations to display this element with show:{ resource:[ // comma-separated list of resource names ], operation:[ // comma-separated list of operation names ] } }, }

---|--- [颜色](https://docs.n8n.io/_images/integrations/creating-nodes/color.png)

选项 #

options 类型用于添加选项列表。用户可以选择单个值。

| ``` { displayName:'Resource', name:'resource', type:'options', options:[ { name:'Image', value:'image', }, { name:'Template', value:'template', }, ], default:'image',// 初始选中的选项 description:'要使用的资源', displayOptions:{// 控制此元素显示的资源与操作 show:{ resource:[ // 逗号分隔的资源名称列表 ], operation:[ // 逗号分隔的操作名称列表 ] } }, }


---|---
[[选项](https://docs.n8n.io/_images/integrations/creating-nodes/options.png)](https://docs.n8n.io/_images/integrations/creating-nodes/options.png)
## 多选选项[#](https://docs.n8n.io/integrations/creating-nodes/build/reference/ui-elements/#multi-options "永久链接")
`multiOptions` 类型用于添加选项列表。用户可以选择多个值。

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27

| ```
{
displayName:'Events',
name:'events',
type:'multiOptions',
options:[
{
name:'Plan Created',
value:'planCreated',
},
{
name:'Plan Deleted',
value:'planDeleted',
},
],
default:[],// 初始选中的选项
description:'需要监控的事件',
displayOptions:{// 控制此元素显示的资源与操作
show:{
resource:[
// 逗号分隔的资源名称列表
],
operation:[
// 逗号分隔的操作名称列表
]
}
},
}

---|--- [多选项](https://docs.n8n.io/_images/integrations/creating-nodes/multioptions.png)

过滤器 #

使用此组件来评估、匹配或筛选传入数据。这是 n8n 内置 If 节点的代码示例，展示了过滤器组件与集合组件配合使用的方式，用户可通过集合组件配置过滤器的行为。

| ``` { displayName:'Conditions', name:'conditions', placeholder:'Add Condition', type:'filter', default:{}, typeOptions:{ filter:{ // 使用用户选项（下方）决定过滤器行为 caseSensitive:'={{!$parameter.options.ignoreCase}}', typeValidation:'={{$parameter.options.looseTypeValidation ? "loose" : "strict"}}', }, }, }, { displayName:'Options', name:'options', type:'collection', placeholder:'Add option', default:{}, options:[ { displayName:'Ignore Case', description:'Whether to ignore letter case when evaluating conditions', name:'ignoreCase', type:'boolean', default:true, }, { displayName:'Less Strict Type Validation', description:'Whether to try casting value types based on the selected operator', name:'looseTypeValidation', type:'boolean', default:true, }, ], },


---|---
[[过滤器](https://docs.n8n.io/_images/integrations/creating-nodes/filter.png)](https://docs.n8n.io/_images/integrations/creating-nodes/filter.png)
## 分配集合（拖拽）[#](https://docs.n8n.io/integrations/creating-nodes/build/reference/ui-elements/#assignment-collection-drag-and-drop "永久链接")
当需要用户通过单次拖拽交互预填名称和值参数时，可使用此拖拽组件。

1 2 3 4 5 6

| ```
{
displayName:'Fields to Set',
name:'assignments',
type:'assignmentCollection',
default:{},
},

你可以在 n8n 的编辑字段（Set）节点中查看示例： [展示拖拽操作以及将字段切换为固定模式的动态图](https://docs.n8n.io/_images/integrations/builtin/core-nodes/set/drag-drop-fixed-toggle.gif)

固定集合 #

使用 fixedCollection 类型可将语义相关的字段进行分组。

{
  "displayName": "Metadata",
  "name": "metadataUi",
  "placeholder": "Add Metadata",
  "type": "fixedCollection",
  "default": "",
  "typeOptions": {
    "multipleValues": true
  },
  "description": "",
  "options": [
    {
      "name": "metadataValues",
      "displayName": "Metadata",
      "values": [
        {
          "displayName": "Name",
          "name": "name",
          "type": "string",
          "default": "Name of the metadata key to add."
        },
        {
          "displayName": "Value",
          "name": "value",
          "type": "string",
          "default": "",
          "description": "Value to set for the metadata key."
        }
      ]
    }
  ],
  "displayOptions": { // 控制此元素显示的资源与操作
    "show": {
      "resource": [
        // 逗号分隔的资源名称列表
      ],
      "operation": [
        // 逗号分隔的操作名称列表
      ]
    }
  }
}

[固定集合示例](https://docs.n8n.io/_images/integrations/creating-nodes/fixed-collection.png)

资源定位器 #

[资源定位器界面](https://docs.n8n.io/_images/integrations/creating-nodes/resource-locator.png)

资源定位器元素可帮助用户在外部服务中定位特定资源，例如 Trello 中的卡片或标签。提供以下选项：

ID 模式
URL 模式
列表模式：允许用户从预填充列表中选择或搜索。此选项需要更多编码工作，因为您必须填充列表内容，若支持搜索功能还需实现搜索处理逻辑。

您可以选择要包含的类型。示例：

| ``` { displayName:'Card', name:'cardID', type:'resourceLocator', default:'', description:'Get a card', modes:[ { displayName:'ID', name:'id', type:'string', hint:'Enter an ID', validation:[ { type:'regex', properties:{ regex:'^[0-9]', errorMessage:'The ID must start with a number', }, }, ], placeholder:'12example', // How to use the ID in API call url:'=http://api-base-url.com/?id={{$value}}', }, { displayName:'URL', name:'url', type:'string', hint:'Enter a URL', validation:[ { type:'regex', properties:{ regex:'^http', errorMessage:'Invalid URL', }, }, ], placeholder:'https://example.com/card/12example/', // How to get the ID from the URL extractValue:{ type:'regex', regex:'example.com/card/([0-9].)/', }, }, { displayName:'List', name:'list', type:'list', typeOptions:{ // You must always provide a search method // Write this method within the methods object in your base file // The method must populate the list, and handle searching if searchable: true searchListMethod:'searchMethod', // If you want users to be able to search the list searchable:true, // Set to true if you want to force users to search // When true, users can't browse the list // Or false if users can browse a list searchFilterRequired:true, }, }, ], displayOptions:{ // the resources and operations to display this element with show:{ resource:[ // comma-separated list of resource names ], operation:[ // comma-separated list of operation names ], }, }, },


---|---
实际示例参考：
  * 关于包含 `searchFilterRequired: true` 的可搜索列表示例，请参考 n8n Trello 节点中的 [`CardDescription.ts`](https://github.com/n8n-io/n8n/blob/master/packages/nodes-base/nodes/Trello/CardDescription.ts) 和 [`Trello.node.ts`](https://github.com/n8n-io/n8n/blob/master/packages/nodes-base/nodes/Trello/Trello.node.ts)。
  * 关于用户可浏览列表或进行搜索的示例，请参考 [`GoogleDrive.node.ts`](https://github.com/n8n-io/n8n/blob/master/packages/nodes-base/nodes/Google/Drive/GoogleDrive.node.ts)。

## 资源映射器[#](https://docs.n8n.io/integrations/creating-nodes/build/reference/ui-elements/#resource-mapper "Permanent link")
如果节点执行插入（insert）、更新（update）或更新插入（upsert）操作，您需要按照所集成服务支持的格式从节点发送数据。通常的做法是在发送数据的节点前使用 Set 节点，将数据转换为符合所连接服务的模式。资源映射器 UI 组件提供了一种直接在节点内将数据转换为所需格式的方法，而无需使用 Set 节点。该组件还可以根据节点中提供的模式验证输入数据，并将输入数据转换为预期类型。

### 映射与匹配
映射（Mapping）是指设置输入数据以用作更新行时的值的过程。匹配（Matching）是指使用列名来识别要更新的行的过程。

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32

| ```
{
displayName:'Columns',
name:'columns',// 代码中引用UI元素的名称
type:'resourceMapper',// UI元素类型
default:{
// 可以在组件中定义映射模式 (mappingMode: 'defineBelow')
// 或尝试自动映射 (mappingMode: 'autoMapInputData')
mappingMode:'defineBelow',
// 重要：始终将默认值设置为 null
value:null,
},
required:true,
// 完整 typeOptions 规范请参阅下方的"资源映射器类型选项接口"
typeOptions:{
resourceMapper:{
resourceMapperMethod:'getMappingColumns',
mode:'update',
fieldWords:{
singular:'column',
plural:'columns',
},
addAllFields:true,multiKeyMatch:true,
supportAutoMap:true,
matchingFieldsLabels:{
title:'自定义匹配列标题',
description:'自定义匹配列帮助文本',
hint:'自定义匹配列的字段下方提示',
},
},
},
},

---|---
关于使用数据库模式的实际示例，请参考 [Postgres 节点（版本 2）](https://github.com/n8n-io/n8n/tree/master/packages/nodes-base/nodes/Postgres/v2)。
关于使用无模式服务的实际示例，请参考 [Google Sheets 节点（版本 2）](https://github.com/n8n-io/n8n/tree/master/packages/nodes-base/nodes/Google/Sheet/v2)。

### 资源映射器类型选项接口[#](https://docs.n8n.io/integrations/creating-nodes/build/reference/ui-elements/#resource-mapper-type-options-interface "永久链接")
`typeOptions` 部分必须实现以下接口：

```typescript
export interface ResourceMapperTypeOptions {
	// 用于获取模式的方法名称
	// 更多细节请参考资源映射器方法章节
	resourceMapperMethod: string;
	// 选择操作模式
	// 支持的模式：add（添加）、update（更新）、upsert（更新或插入）
	mode: 'add' | 'update' | 'upsert';
	// 为 UI 中的字段指定标签
	fieldWords?: { singular: string; plural: string };
	// 当节点首次添加到工作流时，n8n 是否应为每个字段显示 UI 输入
	// 默认为 true
	addAllFields?: boolean;
	// 如果未从服务获取到任何字段时显示的消息
	// （调用成功但响应为空）
	noFieldsError?: string;
	// 是否支持多键列匹配
	// multiKeyMatch 仅适用于 update 和 upsert 模式
	// 默认为 false
	// 如果为 true，节点将在匹配列选择器中显示多选下拉菜单
	multiKeyMatch?: boolean;
	// 是否支持自动映射
	// 如果为 false，n8n 将隐藏映射模式选择器字段并将 mappingMode 设置为 defineBelow
	supportAutoMap?: boolean;
	// 匹配列选择器的自定义标签
	matchingFieldsLabels?: {
		title?: string;
		description?: string;
		hint?: string;
	};
}

---|---

资源映射方法 #

此方法包含用于获取数据架构的节点特定逻辑。每个节点必须实现自己的架构获取逻辑，并根据架构设置每个 UI 字段。它必须返回一个实现 ResourceMapperFields 接口的值：

| ``` interfaceResourceMapperField{ // Field ID as in the service id:string; // Field label displayName:string; // Whether n8n should pre-select the field as a matching field // A matching field is a column used to identify the rows to modify defaultMatch:boolean; // Whether the field can be used as a matching field canBeUsedToMatch?:boolean; // Whether the field is required by the schema required:boolean; // Whether to display the field in the UI // If false, can't be used for matching or mapping display:boolean; // The data type for the field // These correspond to UI element types // Supported types: string, number, dateTime, boolean, time, array, object, options type?:FieldType; // Added at runtime if the field is removed from mapping by the user removed?:boolean; // Specify options for enumerated types options?:INodePropertyOptions[]; }


---|---
有关实际示例，请参考 [Postgres 资源映射方法](https://github.com/n8n-io/n8n/blob/master/packages/nodes-base/nodes/Postgres/v2/methods/resourceMapping.ts) 和 [Google Sheets 资源映射方法](https://github.com/n8n-io/n8n/blob/master/packages/nodes-base/nodes/Google/Sheet/v2/methods/resourceMapping.ts)。
## JSON[#](https://docs.n8n.io/integrations/creating-nodes/build/reference/ui-elements/#json "永久链接")

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17

| ```
{
displayName:'Content (JSON)',
name:'content',
type:'json',
default:'',
description:'',
displayOptions:{// the resources and operations to display this element with
show:{
resource:[
// comma-separated list of resource names
],
operation:[
// comma-separated list of operation names
]
}
},
}

---|--- [JSON](https://docs.n8n.io/_images/integrations/creating-nodes/json.png)

HTML #

HTML 编辑器允许用户在工作流中创建 HTML 模板。该编辑器支持标准 HTML、<style> 标签中的 CSS 以及 {{}} 包裹的表达式。用户可以添加 <script> 标签来引入额外的 JavaScript。n8n 在工作流执行期间不会运行这些 JavaScript 代码。

| ``` { displayName:'HTML 模板',// 用户在界面中看到的值 name:'html',// 在代码中引用该 UI 元素的名称 type:'string', typeOptions:{ editor:'htmlEditor', }, default:placeholder,// 加载 n8n 的占位符 HTML 模板 noDataExpression:true,// 阻止对该字段使用表达式 description:'要渲染的 HTML 模板', },


---|---
实际示例请参考 [`Html.node.ts`](https://github.com/n8n-io/n8n/blob/master/packages/nodes-base/nodes/Html/Html.node.ts)。
## 提示框[#](https://docs.n8n.io/integrations/creating-nodes/build/reference/ui-elements/#notice "永久链接")
显示带有提示或额外信息的黄色框。关于如何编写优质提示信息文本的指南，请参阅[节点 UI 设计](https://docs.n8n.io/integrations/creating-nodes/plan/node-ui-design/)。

1 2 3 4 5 6

| ```
{
displayName:'您的文本内容',
name:'notice',
type:'notice',
default:'',
},

---|--- [提示框](https://docs.n8n.io/_images/integrations/creating-nodes/notice.png)

提示信息 #

提示信息分为两种类型：参数提示和节点提示：

参数提示是用户输入字段下方的小段文本
节点提示是比提示框更强大灵活的选择，可用于在输入面板、输出面板或节点详情视图中显示较长的提示信息

添加参数提示 #

在 UI 元素中添加 hint 参数：

| ``` { displayName:'URL', name:'url', type:'string', hint:'请输入 URL', ... }

添加节点提示 #

在节点 description 的 hints 属性中定义节点提示：

| ``` description:INodeTypeDescription={ ... hints:[ { // 提示信息。可使用 HTML 格式 message:"This node has many input items. Consider enabling Execute Once in the node's settings.", // 可选值: info, warning, danger。默认为 'info' // 颜色设置: info (灰色), warning (黄色), danger (红色) type:'info', // 可选值: inputPane, outputPane, ndv。默认在输入和输出面板中同时显示 location:'outputPane', // 可选值: always, beforeExecution, afterExecution。默认为 'always' whenToDisplay:'beforeExecution', // 可选。表达式。解析为 true 时显示消息，默认为 true displayCondition:'={{ $parameter["operation"] === "select" && $input.all().length > 1 }}' } ] ... }


### 为编程式节点添加动态提示[#](https://docs.n8n.io/integrations/creating-nodes/build/reference/ui-elements/#add-a-dynamic-hint-to-a-programmatic-style-node "永久链接")
在编程式节点中，可以创建包含节点执行信息的动态消息。由于依赖节点输出数据，此类提示只能在执行后显示。

1 2 3 4 5 6 7 8 9 10 11 12 13

| ```
if(operation==='select'&&items.length>1&&!node.executeOnce){
// 需要两个参数: NodeExecutionData 和提示数组
returnnewNodeExecutionOutput(
[returnData],
[
{
message:`This node ran ${items.length} times, once for each input item. To run for the first item only, enable <b>Execute once</b> in the node settings.`,
location:'outputPane',
},
],
);
}
return[returnData];

要查看编程式节点中动态提示的实时示例，请参阅 Split Out 节点代码。

On this page