n8n Form 노드 문서
n8n v2.34요약
n8n Form 노드를 사용하면 여러 단계로 이루어진 사용자용 폼을 만들 수 있습니다. 대화형 워크플로 데모입니다. n8n Form Trigger 노드가 제공하는 초기 URL에 쿼리 매개변수를 사용하여 필드의 초기 값을 설정할 수 있습니다.
n8n Form 노드를 사용하면 여러 단계로 이루어진 사용자용 폼을 만들 수 있습니다. 사용자 입력을 처리하기 위한 커스텀 로직을 담은 다른 노드를 그 사이에 추가할 수 있습니다. 워크플로는 반드시 n8n Form Trigger 노드로 시작해야 합니다.
대화형 워크플로 데모입니다. 워크플로 JSON 보기 또는 n8n 공식 문서에서 확인하세요.
노드 설정#
쿼리 매개변수로 기본 선택 값 설정하기#
n8n Form Trigger 노드가 제공하는 초기 URL에 쿼리 매개변수를 사용하여 필드의 초기 값을 설정할 수 있습니다. 폼의 모든 페이지는 n8n Form Trigger 노드 URL로 전송된 것과 동일한 쿼리 매개변수를 전달받습니다.
프로덕션 환경에서만 사용 가능
쿼리 매개변수는 프로덕션 모드로 폼을 사용할 때만 사용할 수 있습니다. n8n은 테스트 모드에서는 쿼리 매개변수로 필드 값을 채우지 않습니다.
쿼리 매개변수를 사용할 때는 특수 문자가 포함된 필드 이름이나 값을 퍼센트 인코딩해야 합니다. 이렇게 하면 n8n이 해당 필드에 대해 초기 값을 올바르게 사용합니다. URL Encode/Decode와 같은 도구를 사용하여 쿼리 매개변수를 퍼센트 인코딩 형식으로 만들 수 있습니다.
예를 들어, 다음과 같은 속성을 가진 폼이 있다고 가정해 보겠습니다.
- 프로덕션 URL:
https://my-account.n8n.cloud/form/my-form - 필드:
name:Jane Doeemail:jane.doe@example.com
쿼리 매개변수와 퍼센트 인코딩을 사용하면, 위 데이터로 초기 필드 값을 설정하기 위해 다음과 같은 URL을 사용할 수 있습니다.
https://my-account.n8n.cloud/form/my-form?email=jane.doe%40example.com&name=Jane%20Doe
여기서 퍼센트 인코딩은 골뱅이 기호(@)를 문자열 %40으로, 공백 문자( )를 문자열 %20으로 치환합니다. 이렇게 하면 폼의 어느 페이지에 해당 필드가 나타나든 상관없이 초기 값이 설정됩니다.
커스텀 HTML 표시하기#
폼에 Custom HTML 필드를 추가하여 커스텀 HTML을 표시할 수 있습니다. 이 필드는 폼 페이지의 일부로 표시할 임의의 HTML 코드를 입력할 수 있는 HTML 상자를 제공합니다.
HTML 필드를 사용하면 링크, 이미지, 동영상 등을 포함하여 폼 페이지를 풍부하게 꾸밀 수 있습니다. n8n은 일반적인 문서 흐름 안에서 나머지 폼 필드와 함께 해당 콘텐츠를 렌더링합니다.
커스텀 HTML 콘텐츠는 읽기 전용이므로, 기본적으로 이 필드는 폼 출력 데이터에 포함되지 않습니다. 노드 출력에 원본 HTML 콘텐츠를 포함하려면 Element Name 필드에 데이터 이름을 지정하세요.
HTML 필드는 <script>, <style>, <input> 요소를 지원하지 않습니다.
Form Ending 페이지 유형을 사용하는 경우, On n8n Form Submission 매개변수를 Show Text로 선택하면 사용자에게 보내는 최종 페이지를 (<script>, <style>, <input> 요소 사용을 포함하여) 완전히 커스터마이즈할 수 있습니다.
숨겨진 필드 포함하기#
사용자에게 표시하지 않고 폼에 필드를 포함시킬 수 있습니다. 이는 인터랙티브한 사용자 입력이 필요 없는 추가 데이터를 폼에 전달하고 싶을 때 유용합니다.
폼에 표시되지 않는 필드를 추가하려면 Hidden Field 폼 요소를 사용하세요. 여기서 Field Name을 정의하고, 선택적으로 Field Value를 입력하여 기본값을 지정할 수 있습니다.
폼을 제공할 때, 쿼리 매개변수를 사용하여 숨겨진 필드에 값을 전달할 수 있습니다.
JSON을 사용하여 폼 정의하기#
Define Form > Using JSON을 사용하면 객체로 구성된 JSON 배열로 폼의 필드를 정의할 수 있습니다. 각 객체는 다음 키의 조합을 사용하여 하나의 필드를 정의합니다.
fieldLabel: 렌더링된 폼에서 입력 필드 위에 표시되는 레이블입니다.fieldName: Form 노드의 출력에서 사용되며, 표현식에서 필드를 참조할 때 사용하는 필드 이름입니다.fieldType:checkbox,date,dropdown,email,file,hiddenField,html,number,password,radio,text,textarea중에서 선택합니다.date를 사용하면 폼에 날짜 선택기를 포함할 수 있습니다. 날짜 형식 지정에 대한 자세한 내용은 Luxon으로 날짜와 시간 다루기를 참조하세요.dropdown을 사용할 때는fieldOptions로 선택지를 설정합니다(아래 예시 참조). 기본적으로 드롭다운은 단일 선택입니다. 다중 선택으로 만들려면multiselect를true로 설정하세요. 대안으로fieldOptions와 함께checkbox나radio를 사용할 수도 있습니다.file을 사용할 때는multipleFiles를true로 설정하면 사용자가 여러 파일을 선택할 수 있습니다. 허용할 파일 형식을 정의하려면acceptFileTypes에 쉼표로 구분된 파일 확장자 문자열을 설정하세요(아래 예시 참조).hiddenField를 사용하면 폼에 숨겨진 필드를 추가할 수 있습니다. 자세한 내용은 숨겨진 필드 포함하기를 참조하세요.html을 사용하면 폼에 커스텀 HTML을 표시할 수 있습니다. 자세한 내용은 커스텀 HTML 표시하기를 참조하세요.
placeholder: 필드의 플레이스홀더 데이터를 지정합니다.dropdown,checkbox,radio,date,file을 제외한 모든fieldType에 사용할 수 있습니다.defaultValue: 폼 요소에 미리 채워지거나 미리 선택될 값을 지정합니다.password,html,hiddenField,file을 제외한 모든fieldType에 사용할 수 있습니다.requiredField: 사용자가 폼에서 이 필드를 반드시 작성하도록 요구합니다.
필요한 일반적인 형식과 사용 가능한 키를 보여주는 예시 JSON입니다.
// Use the "requiredField" key on any field to mark it as mandatory
// Use the "placeholder" key to specify placeholder data for all fields
// except 'dropdown', 'checkbox', 'radio', 'date' and 'file'
// Use the "defaultValue" key to pre-fill a form field or pre-select a
// value in 'checkbox', 'radio' or 'dropdown' fields
[
{
"fieldLabel": "Date Field",
"fieldType": "date",
"formatDate": "mm/dd/yyyy", // how to format received date in n8n
"requiredField": true
},
{
"fieldLabel": "Dropdown Options",
"fieldType": "dropdown",
"fieldOptions": {
"values": [
{
"option": "option 1"
},
{
"option": "option 2"
}
]
},
"defaultValue": "option 1",
"requiredField": true
},
{
"fieldLabel": "Multiselect",
"fieldType": "dropdown",
"fieldOptions": {
"values": [
{
"option": "option 1"
},
{
"option": "option 2"
}
]
},
"multiselect": true // setting to true allows multi-select
},
{
"fieldLabel": "Email",
"fieldType": "email",
"placeholder": "me@mail.com"
},
{
"fieldLabel": "File",
"fieldType": "file",
"multipleFiles": true, // setting to true allows multiple files selection
"acceptFileTypes": ".jpg, .png" // allowed file types
},
{
"fieldLabel": "Number",
"fieldType": "number"
},
{
"fieldLabel": "Password",
"fieldType": "password"
},
{
// "fieldType": "text" can be omitted since it's the default type
"fieldLabel": "Text"
},
{
"fieldLabel": "Textarea",
"fieldType": "textarea",
"defaultValue": "Lorem ipsum."
},
{
"fieldType": "html",
"elementName": "content", // Optional field. It can be used to include the html in the output.
"html": "<div>Custom element</div>"
},
{
"fieldLabel": "Checkboxes",
"fieldType": "checkbox",
"fieldOptions": {
"values": [
{
"option": "option 1"
},
{
"option": "option 2"
}
]
},
"defaultValue": ["option 1", "option 2"]
},
{
"fieldLabel": "Radio",
"fieldType": "radio",
"fieldOptions": {
"values": [
{
"option": "option 1"
},
{
"option": "option 2"
}
]
}
},
{
"fieldLabel": "hidden label",
"fieldType": "hiddenField",
"fieldValue": "extra form data"
}
]
폼 종료#
Form Ending 페이지 유형을 사용하면 폼을 종료하고 완료 페이지를 표시하거나, 사용자를 URL로 리다이렉트하거나, 커스텀 HTML이나 텍스트를 표시할 수 있습니다. n8n이 Form Ending 노드를 포함한 여러 브랜치를 실행하는 경우에도, 실행당 하나의 Form Ending 페이지만 표시됩니다.
On n8n Form Submission을 사용할 때 다음 옵션 중에서 선택하세요.
- Show Completion Screen: 사용자에게 폼을 제출했음을 확인하는 최종 화면을 보여줍니다.
- Completion Title을 입력하여 폼의
h1제목을 설정합니다. - n8n은 폼의 메인
h1제목 아래에 Completion Message를 부제목으로 표시합니다. 줄바꿈을 추가하려면\n이나<br>을 사용하세요. - Add option을 선택하고 Completion Page Title을 입력하여 브라우저 탭에 표시될 페이지 제목을 설정합니다.
- Completion Title을 입력하여 폼의
- Redirect to URL: 폼이 완료되면 사용자를 지정한 URL로 리다이렉트합니다.
- URL 필드에 사용자가 폼을 완료했을 때 리다이렉트할 페이지를 입력하세요.
- Show Text: 임의의 일반 텍스트와 HTML로 정의된 최종 페이지를 표시합니다.
- Text 필드에 표시하려는 HTML 또는 일반 텍스트 콘텐츠를 입력하세요.
- Return Binary File: 완료 시 바이너리 파일을 반환합니다.
- Completion Title을 입력하여 폼의
h1제목을 설정합니다. - n8n은 폼의 메인
h1제목 아래에 Completion Message를 부제목으로 표시합니다. 줄바꿈을 추가하려면\n이나<br>을 사용하세요. - 사용자에게 반환할 바이너리 파일이 담긴 Input Data Field Name을 지정하세요.
- Completion Title을 입력하여 폼의
브랜치가 있는 폼#
n8n Form 노드는 이전 노드로부터 데이터를 받을 때마다 실행되어 연결된 폼 페이지를 표시합니다. n8n으로 폼을 구성할 때, 혼란을 피하기 위해서는 분기가 발생할 때 폼이 어떻게 동작하는지 이해하는 것이 중요합니다.
상호 배타적인 브랜치를 가진 워크플로#
상호 배타적인 브랜치를 포함한 폼 워크플로는 예상대로 동작합니다. n8n은 제출된 데이터와 사용자가 정의한 조건에 따라 하나의 브랜치만 실행합니다. 실행 과정에서 n8n은 해당 브랜치의 각 페이지를 표시하며, Form Ending 페이지 유형을 가진 n8n Form 노드로 끝납니다.
이 워크플로는 상호 배타적인 분기를 보여줍니다. 각 선택 항목은 오직 하나의 브랜치만 실행할 수 있습니다.
대화형 워크플로 데모입니다. 워크플로 JSON 보기 또는 n8n 공식 문서에서 확인하세요.
여러 브랜치를 실행할 수도 있는 워크플로#
동시에 여러 브랜치로 데이터를 보내는 폼 워크플로에는 더 많은 주의가 필요합니다. 실행 중에 여러 브랜치가 데이터를 받는 경우(예: switch 노드로부터), n8n은 데이터를 받은 각 브랜치를 순차적으로 실행합니다. 하나의 브랜치 끝에 도달하면, 실행은 데이터를 가진 다음 브랜치로 넘어갑니다.
n8n은 실행당 단 하나의 Form Ending n8n Form 노드만 실행합니다. 폼 워크플로의 여러 브랜치가 데이터를 받는 경우, n8n은 마지막 브랜치와 연결된 노드를 제외한 모든 Form Ending 노드를 무시합니다.
이 워크플로는 실행 중에 하나 이상의 브랜치를 실행할 수 있습니다. 여기서 n8n은 유효한 모든 브랜치를 순차적으로 실행합니다. 이는 n8n이 어떤 Form 노드를 실행하는지(특히 어떤 Form Ending 노드가 표시되는지)에 영향을 미칩니다.
대화형 워크플로 데모입니다. 워크플로 JSON 보기 또는 n8n 공식 문서에서 확인하세요.
노드 옵션#
Add Option을 선택하여 더 많은 구성 옵션을 확인하세요.
- Form Title: 폼의 제목입니다. n8n은 Form Title을 웹페이지 제목과 폼의 메인
h1제목으로 표시합니다. - Form Description: 폼의 설명입니다. n8n은 폼의 메인
h1제목 아래에 부제목으로 Form Description을 표시합니다. 이 필드는 HTML을 지원합니다. 줄바꿈을 추가하려면\n이나<br>을 사용하세요. Form Description은 페이지의 HTML meta description에도 반영됩니다. - Button Label: 폼의 제출 버튼에 사용할 레이블입니다. n8n은 Button Label을 제출 버튼의 이름으로 표시합니다.
- Custom Form Styling: CSS로 공개 폼 인터페이스의 기본 스타일을 재정의합니다. 이 필드는 기본 스타일로 미리 채워져 있으므로 필요한 부분만 변경하면 됩니다.
- Completion Page Title: 폼의 최종 완료 페이지 제목입니다.
노드 실행#
워크플로 빌드 및 테스트#
워크플로를 빌드하거나 테스트하는 동안에는 n8n Form Trigger 노드의 Test URL을 사용하세요. 테스트 URL을 사용하면 편집기 UI에서 들어오는 데이터를 확인할 수 있어 디버깅에 유용합니다.
테스트하는 방법은 두 가지가 있습니다.
- Execute Step을 선택합니다. n8n이 폼을 엽니다. 폼을 제출하면 n8n은 해당 노드와 그 이전 노드들을 실행하지만, 워크플로의 나머지 부분은 실행하지 않습니다.
- Execute Workflow를 선택합니다. n8n이 폼을 엽니다. 폼을 제출하면 n8n은 워크플로를 실행합니다.
프로덕션 워크플로#
워크플로가 준비되면, 트리거 노드를 열고 From URLS 선택기에서 Production URL을 선택하여 n8n Form Trigger의 Production URL을 사용하도록 전환하세요. 그런 다음 워크플로를 게시할 수 있으며, 사용자가 폼을 제출하면 n8n이 자동으로 워크플로를 실행합니다.
프로덕션 URL로 작업할 때는 워크플로를 저장하고 게시했는지 확인하세요. Form 트리거를 통해 흐르는 데이터는 프로덕션 URL을 사용할 때 편집기 UI에서 보이지 않습니다.