n8n은 사용자가 다양한 데이터 타입을 입력할 수 있도록 하는 사전 정의된 UI 컴포넌트 세트(JSON 파일 기반)를 제공합니다. 다음 UI 요소를 n8n에서 사용할 수 있습니다.

String#

기본 구성:

{
	displayName: Name, // 사용자가 UI에서 보는 값
	name: name, // 코드 내에서 UI 요소를 참조하는 데 사용되는 이름
	type: string,
	required: true, // 필드 필수 여부
	default: 'n8n',
	description: 'The name of the user',
	displayOptions: { // 이 요소를 표시할 리소스와 오퍼레이션
		show: {
			resource: [
				// 리소스 이름 쉼표 구분 목록
			],
			operation: [
				// 오퍼레이션 이름 쉼표 구분 목록
			]
		}
	},
}

비밀번호 입력용 String 필드:

{
	displayName: 'Password',
	name: 'password',
	type: 'string',
	required: true,
	typeOptions: {
		password: true,
	},
	default: '',
	description: `User's password`,
	displayOptions: { // 이 요소를 표시할 리소스와 오퍼레이션
		show: {
			resource: [
				// 리소스 이름 쉼표 구분 목록
			],
			operation: [
				// 오퍼레이션 이름 쉼표 구분 목록
			]
		}
	},
}

두 줄 이상의 String 필드:

{
	displayName: 'Description',
	name: 'description',
	type: 'string',
	required: true,
	typeOptions: {
		rows: 4,
	},
	default: '',
	description: 'Description',
	displayOptions: { // 이 요소를 표시할 리소스와 오퍼레이션
		show: {
			resource: [
				// 리소스 이름 쉼표 구분 목록
			],
			operation: [
				// 오퍼레이션 이름 쉼표 구분 목록
			]
		}
	},
}

데이터 키 드래그 앤 드롭 지원#

사용자는 데이터 값을 드래그 앤 드롭하여 필드에 매핑할 수 있습니다. 드래그 앤 드롭하면 데이터 값을 로드하는 표현식이 생성됩니다. n8n은 이를 자동으로 지원합니다.

데이터 키 드래그 앤 드롭 지원을 위해 추가 구성 옵션을 추가해야 합니다:

• requiresDataPath: 'single': 단일 문자열이 필요한 필드의 경우.
• requiresDataPath: 'multiple': 쉼표로 구분된 문자열 목록을 허용할 수 있는 필드의 경우.

Compare Datasets node 코드에 예시가 있습니다.

Number#

소수점이 있는 Number 필드:

{
	displayName: 'Amount',
	name: 'amount',
	type: 'number',
	required: true,
	typeOptions: {
		maxValue: 10,
		minValue: 0,
		numberPrecision: 2,
	},
	default: 10.00,
	description: 'Your current amount',
	displayOptions: { // 이 요소를 표시할 리소스와 오퍼레이션
		show: {
			resource: [
				// 리소스 이름 쉼표 구분 목록
			],
			operation: [
				// 오퍼레이션 이름 쉼표 구분 목록
			]
		}
	},
}

Collection#

선택적 필드를 표시해야 할 때 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: { // 이 요소를 표시할 리소스와 오퍼레이션
		show: {
			resource: [
				// 리소스 이름 쉼표 구분 목록
			],
			operation: [
				// 오퍼레이션 이름 쉼표 구분 목록
			]
		}
	},
}

DateTime#

dateTime 타입은 날짜 선택기를 제공합니다.

{
	displayName: 'Modified Since',
	name: 'modified_since',
	type: 'dateTime',
	default: '',
	description: 'The date and time when the file was last modified',
	displayOptions: { // 이 요소를 표시할 리소스와 오퍼레이션
		show: {
			resource: [
				// 리소스 이름 쉼표 구분 목록
			],
			operation: [
				// 오퍼레이션 이름 쉼표 구분 목록
			]
		}
	},
}

Boolean#

boolean 타입은 true 또는 false를 입력하는 토글을 추가합니다.

{
	displayName: 'Wait for Image',
	name: 'waitForImage',
	type: 'boolean',
	default: true, // 토글 초기 상태
	description: 'Whether to wait for the image or not',
	displayOptions: { // 이 요소를 표시할 리소스와 오퍼레이션
		show: {
			resource: [
				// 리소스 이름 쉼표 구분 목록
			],
			operation: [
				// 오퍼레이션 이름 쉼표 구분 목록
			]
		}
	},
}

Color#

color 타입은 색상 선택기를 제공합니다.

{
	displayName: 'Background Color',
	name: 'backgroundColor',
	type: 'color',
	default: '', // 처음에 선택된 색상
	displayOptions: { // 이 요소를 표시할 리소스와 오퍼레이션
		show: {
			resource: [
				// 리소스 이름 쉼표 구분 목록
			],
			operation: [
				// 오퍼레이션 이름 쉼표 구분 목록
			]
		}
	},
}

Options#

options 타입은 옵션 목록을 추가합니다. 사용자는 단일 값을 선택할 수 있습니다.

{
	displayName: 'Resource',
	name: 'resource',
	type: 'options',
	options: [
		{
			name: 'Image',
			value: 'image',
		},
		{
			name: 'Template',
			value: 'template',
		},
	],
	default: 'image', // 처음에 선택된 옵션
	description: 'Resource to consume',
	displayOptions: { // 이 요소를 표시할 리소스와 오퍼레이션
		show: {
			resource: [
				// 리소스 이름 쉼표 구분 목록
			],
			operation: [
				// 오퍼레이션 이름 쉼표 구분 목록
			]
		}
	},
}

Multi-options#

multiOptions 타입은 옵션 목록을 추가합니다. 사용자는 두 개 이상의 값을 선택할 수 있습니다.

{
	displayName: 'Events',
	name: 'events',
	type: 'multiOptions',
	options: [
		{
			name: 'Plan Created',
			value: 'planCreated',
		},
		{
			name: 'Plan Deleted',
			value: 'planDeleted',
		},
	],
	default: [], // 처음에 선택된 옵션
	description: 'The events to be monitored',
	displayOptions: { // 이 요소를 표시할 리소스와 오퍼레이션
		show: {
			resource: [
				// 리소스 이름 쉼표 구분 목록
			],
			operation: [
				// 오퍼레이션 이름 쉼표 구분 목록
			]
		}
	},
}

Filter#

들어오는 데이터를 평가, 일치 또는 필터링할 때 이 컴포넌트를 사용합니다.

이것은 n8n의 If node 코드입니다. 사용자가 필터의 동작을 구성할 수 있는 collection 컴포넌트와 함께 작동하는 필터 컴포넌트를 보여줍니다.

{
	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,
	},
],
},

Assignment collection (드래그 앤 드롭)#

사용자가 단일 드래그 인터랙션으로 이름과 값 파라미터를 미리 채울 수 있게 하려면 드래그 앤 드롭 컴포넌트를 사용합니다.

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

n8n의 Edit Fields (Set) node에서 예시를 확인할 수 있습니다:

Fixed collection#

의미적으로 관련된 필드를 그룹화하려면 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: [
				// 오퍼레이션 이름 쉼표 구분 목록
			]
		}
	},
}

Resource locator#

resource locator 요소는 사용자가 Trello의 카드나 레이블과 같이 외부 서비스에서 특정 리소스를 찾는 데 도움을 줍니다.

다음 옵션을 사용할 수 있습니다:

• ID
• URL
• List: 사용자가 미리 채워진 목록에서 선택하거나 검색할 수 있습니다. 이 옵션은 목록을 채워야 하고 검색을 지원하기로 선택한 경우 검색을 처리해야 하므로 더 많은 코딩이 필요합니다.

포함할 타입을 선택할 수 있습니다.

예시:

{
	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',
			// API 호출에서 ID를 사용하는 방법
			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/',
			// URL에서 ID를 얻는 방법
			extractValue: {
				type: 'regex',
				regex: 'example.com/card/([0-9]*.*)/',
			},
		},
		{
			displayName: 'List',
			name: 'list',
			type: 'list',
			typeOptions: {
				// 검색 메서드를 항상 제공해야 함
				// 기본 파일의 methods 오브젝트 내에 이 메서드를 작성
				// 메서드는 목록을 채우고 searchable: true인 경우 검색을 처리해야 함
				searchListMethod: 'searchMethod',
				// 사용자가 목록을 검색할 수 있게 하려면
				searchable: true,
				// 사용자가 강제로 검색하도록 하려면 true로 설정
				// true이면 사용자가 목록을 탐색할 수 없음
				// 사용자가 목록을 탐색할 수 있으면 false
				searchFilterRequired: true,
			},
		},
	],
	displayOptions: {
		// 이 요소를 표시할 리소스와 오퍼레이션
		show: {
			resource: [
				// 리소스 이름 쉼표 구분 목록
			],
			operation: [
				// 오퍼레이션 이름 쉼표 구분 목록
			],
		},
	},
},

실제 예시는 다음을 참고하세요:

• searchFilterRequired: true를 포함한 검색 예시는 n8n의 Trello node에서 CardDescription.ts와 Trello.node.ts를 참고하세요.
• 사용자가 목록을 탐색하거나 검색할 수 있는 예시는 GoogleDrive.node.ts를 참고하세요.

Resource mapper#

node가 삽입, 업데이트 또는 upsert 오퍼레이션을 수행하는 경우 통합 중인 서비스가 지원하는 형식으로 node에서 데이터를 전송해야 합니다. 일반적인 패턴은 데이터를 전송하는 node 앞에 Set node를 사용하여 연결 중인 서비스의 스키마와 일치하도록 데이터를 변환하는 것입니다. resource mapper UI 컴포넌트는 Set node를 사용하는 대신 node 내에서 직접 필요한 형식으로 데이터를 가져오는 방법을 제공합니다. resource mapper 컴포넌트는 node에 제공된 스키마에 대해 입력 데이터를 검증하고 입력 데이터를 예상 타입으로 변환할 수도 있습니다.

{
	displayName: 'Columns',
	name: 'columns', // 코드 내에서 UI 요소를 참조하는 데 사용되는 이름
	type: 'resourceMapper', // UI 요소 타입
	default: {
		// mappingMode는 컴포넌트에서 정의될 수 있음 (mappingMode: 'defineBelow')
		// 또는 자동 매핑 시도 (mappingMode: 'autoMapInputData')
		mappingMode: 'defineBelow',
		// 중요: 기본값을 항상 null로 설정
		value: null,
	},
	required: true,
	// 전체 typeOptions 명세는 아래 "Resource mapper 타입 옵션 인터페이스" 참고
	typeOptions: {
		resourceMapper: {
			resourceMapperMethod: 'getMappingColumns',
			mode: 'update',
			fieldWords: {
				singular: 'column',
				plural: 'columns',
			},
			addAllFields: true,
			multiKeyMatch: true,
			supportAutoMap: true,
			matchingFieldsLabels: {
				title: 'Custom matching columns title',
				description: 'Help text for custom matching columns',
				hint: 'Below-field hint for custom matching columns',
			},
		},
	},
},

데이터베이스 스키마를 사용하는 실제 예시는 Postgres node (버전 2)를 참고하세요.

스키마가 없는 서비스를 사용하는 실제 예시는 Google Sheets node (버전 2)를 참고하세요.

Resource mapper 타입 옵션 인터페이스#

typeOptions 섹션은 다음 인터페이스를 구현해야 합니다:

export interface ResourceMapperTypeOptions {
	// 스키마를 가져오는 메서드 이름
	// 자세한 내용은 Resource mapper 메서드 섹션 참고
	resourceMapperMethod: string;
	// 오퍼레이션 모드 선택
	// 지원 모드: add, update, upsert
	mode: 'add' | 'update' | 'upsert';
	// UI의 필드 레이블 지정
	fieldWords?: { singular: string; plural: string };
	// node가 워크플로에 처음 추가될 때 모든 필드에 대해 UI 입력을 표시할지 여부
	// 기본값은 true
	addAllFields?: boolean;
	// 서비스에서 필드를 가져오지 못한 경우 표시할 메시지 지정
	// (호출이 성공하지만 응답이 비어있는 경우)
	noFieldsError?: string;
	// 다중 키 열 일치 지원 여부
	// multiKeyMatch는 update와 upsert에만 해당
	// 기본값은 false
	// true이면 node가 일치 열 선택기에 다중 선택 드롭다운을 표시함
	multiKeyMatch?: boolean;
	// 자동 매핑 지원 여부
	// false이면 n8n이 매핑 모드 선택기 필드를 숨기고 mappingMode를 defineBelow로 설정
	supportAutoMap?: boolean;
	// 일치 열 선택기의 사용자 정의 레이블
	matchingFieldsLabels?: {
		title?: string;
		description?: string;
		hint?: string;
	};
}

Resource mapper 메서드#

이 메서드에는 데이터 스키마를 가져오기 위한 node별 로직이 포함됩니다. 모든 node는 스키마를 가져오고 스키마에 따라 각 UI 필드를 설정하는 고유한 로직을 구현해야 합니다.

ResourceMapperFields 인터페이스를 구현하는 값을 반환해야 합니다:

interface ResourceMapperField {
	// 서비스의 필드 ID
	id: string;
	// 필드 레이블
	displayName: string;
	// n8n이 필드를 일치 필드로 미리 선택해야 하는지 여부
	// 일치 필드는 수정할 행을 식별하는 데 사용되는 열
	defaultMatch: boolean;
	// 필드를 일치 필드로 사용할 수 있는지 여부
	canBeUsedToMatch?: boolean;
	// 스키마에서 필드가 필수인지 여부
	required: boolean;
	// UI에서 필드를 표시할지 여부
	// false이면 일치 또는 매핑에 사용할 수 없음
	display: boolean;
	// 필드의 데이터 타입
	// UI 요소 타입에 해당
	// 지원 타입: string, number, dateTime, boolean, time, array, object, options
	type?: FieldType;
	// 사용자가 매핑에서 필드를 제거한 경우 런타임에 추가됨
	removed?: boolean;
	// 열거형 타입의 옵션 지정
	options?: INodePropertyOptions[];
}

실제 예시는 Postgres 리소스 매핑 메서드와 Google Sheets 리소스 매핑 메서드를 참고하세요.

JSON#

{
	displayName: 'Content (JSON)',
	name: 'content',
	type: 'json',
	default: '',
	description: '',
	displayOptions: { // 이 요소를 표시할 리소스와 오퍼레이션
		show: {
			resource: [
				// 리소스 이름 쉼표 구분 목록
			],
			operation: [
				// 오퍼레이션 이름 쉼표 구분 목록
			]
		}
	},
}

HTML#

HTML 편집기를 사용하면 사용자가 워크플로에서 HTML 템플릿을 생성할 수 있습니다. 편집기는 표준 HTML, <style> 태그의 CSS, {{}}로 감싸진 표현식을 지원합니다. 사용자는 <script> 태그를 추가하여 추가 JavaScript를 가져올 수 있습니다. n8n은 워크플로 실행 중에 이 JavaScript를 실행하지 않습니다.

{
	displayName: 'HTML Template', // 사용자가 UI에서 보는 값
	name: 'html', // 코드 내에서 UI 요소를 참조하는 데 사용되는 이름
	type: 'string',
	typeOptions: {
		editor: 'htmlEditor',
	},
	default: placeholder, // n8n의 플레이스홀더 HTML 템플릿 로드
	noDataExpression: true, // 필드에 표현식 사용 방지
	description: 'HTML template to render',
},

실제 예시는 Html.node.ts를 참고하세요.

Notice#

힌트나 추가 정보를 포함하는 노란 박스를 표시합니다. 좋은 힌트와 정보 텍스트 작성에 대한 지침은 Node UI 디자인을 참고하세요.

{
  displayName: 'Your text here',
  name: 'notice',
  type: 'notice',
  default: '',
},

Hints#

두 가지 유형의 힌트가 있습니다: 파라미터 힌트와 node 힌트:

• 파라미터 힌트는 사용자 입력 필드 아래의 작은 텍스트 줄입니다.
• Node 힌트는 Notice보다 더 강력하고 유연한 옵션입니다. 입력 패널, 출력 패널 또는 node 세부 정보 보기에 더 긴 힌트를 표시하는 데 사용합니다.

파라미터 힌트 추가#

UI 요소에 hint 파라미터를 추가합니다:

{
	displayName: 'URL',
	name: 'url',
	type: 'string',
	hint: 'Enter a URL',
	...
}

Node 힌트 추가#

node description의 hints 속성에 node의 힌트를 정의합니다:

description: INodeTypeDescription = {
	...
	hints: [
		{
			// 힌트 메시지. HTML을 사용할 수 있습니다.
			message: "This node has many input items. Consider enabling <b>Execute Once</b> in the node\'s settings.",
			// info, warning, danger 중 선택. 기본값은 'info'.
			// 색상 변경. info (회색), warning (노란색), danger (빨간색)
			type: 'info',
			// inputPane, outputPane, ndv 중 선택. 기본적으로 n8n은 입력 및 출력 패널 모두에 힌트를 표시합니다.
			location: 'outputPane',
			// always, beforeExecution, afterExecution 중 선택. 기본값은 'always'
			whenToDisplay: 'beforeExecution',
			// 선택적. 표현식. true로 확인되면 n8n이 메시지를 표시합니다. 기본값은 true.
			displayCondition: '={{ $parameter["operation"] === "select" && $input.all().length > 1 }}'
		}
	]
	...
}

프로그래매틱 스타일 node에 동적 힌트 추가#

프로그래매틱 스타일 node에서는 node 실행의 정보를 포함하는 동적 메시지를 생성할 수 있습니다. node 출력 데이터에 의존하므로 실행 후까지 이 유형의 힌트를 표시할 수 없습니다.

if (operation === 'select' && items.length > 1 && !node.executeOnce) {
    // 두 개의 파라미터를 예상: NodeExecutionData와 힌트 배열
	return new NodeExecutionOutput(
		[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];

프로그래매틱 스타일 node의 동적 힌트 실제 예시는 Split Out node 코드를 참고하세요.