노드의 사용자 인터페이스 디자인#

대부분의 노드는 API의 GUI(그래픽 사용자 인터페이스) 표현입니다. 인터페이스 디자인은 API 엔드포인트와 매개변수를 사용자 친화적인 방식으로 표현하는 것을 의미합니다. 전체 API를 노드의 폼 필드로 직접 변환하는 것은 좋은 사용자 경험을 제공하지 못할 수 있습니다.

이 문서는 따라야 할 디자인 지침과 기준을 제공합니다. 이러한 지침은 n8n에서 사용되는 것과 동일합니다. 이는 커뮤니티와 내장된 노드를 혼합하는 사용자에게 원활하고 일관된 사용자 경험을 제공하는 데 도움이 됩니다.

디자인 지침#

모든 노드는 n8n의 노드 UI 요소를 사용하므로 색상, 경계 등과 같은 스타일 세부 사항을 고려할 필요가 없습니다. 그러나 기본 디자인 프로세스를 검토하는 것은 여전히 유용합니다:

통합하려는 API 문서를 검토하세요. 다음과 같은 질문을 해보세요:
- 무엇을 생략할 수 있나요?
- 무엇을 단순화할 수 있나요?
- API의 어떤 부분이 혼란스러운가요? 사용자가 이를 이해하는 데 어떻게 도울 수 있나요?
필드 레이아웃을 시도하기 위해 와이어프레임 도구를 사용하세요. 노드에 필드가 많이 있고 혼란스러워지는 경우, 필드 표시 및 숨기기에 대한 n8n의 지침을 참조하세요.

기준#

UI 텍스트 스타일#

요소	스타일
드롭다운 값	제목 대문자
힌트	문장 대문자
정보 상자	문장 대문자. 한 문장 정보에는 마침표(`.`)를 사용하지 마세요. 두 문장이 넘는 경우에는 항상 마침표를 사용하세요. 이 필드는 링크를 포함할 수 있으며, 새 탭에서 열립니다.
노드 이름	제목 대문자
매개변수 이름	제목 대문자
부제	제목 대문자
툴팁	문장 대문자. 한 문장 툴팁에는 마침표(`.`)를 사용하지 마세요. 두 문장이 넘는 경우에는 항상 마침표를 사용하세요. 이 필드는 링크를 포함할 수 있으며, 새 탭에서 열립니다.

UI 텍스트 용어#

노드가 연결되는 서비스와 동일한 용어를 사용하세요. 예를 들어, Notion 노드는 Notion 블록을 언급해야 하며, Notion 단락이라고 하지 않아야 합니다. 왜냐하면 Notion은 이러한 요소를 블록이라 부르기 때문입니다. 기술 용어를 피하기 위해 이 규칙의 예외가 있을 수 있습니다(예를 들어, 업서트 작업에 대한 이름 및 설명 지침 참조).
때때로 서비스는 API와 GUI에서 서로 다른 용어를 사용할 수 있습니다. 사용자가 가장 익숙한 GUI 언어를 노드에서 사용하세요. 일부 사용자가 서비스의 API 문서를 참조할 필요가 있을 경우 이 정보를 힌트에 포함하는 것을 고려하세요.
더 간단한 대안이 있을 때 기술 전문 용어를 사용하지 마세요.
일관되게 명명하세요. 예를 들어, directory 또는 folder 중 하나를 선택한 후 고수하세요.

노드 명명 규칙#

규칙	올바른	잘못된
노드가 트리거 노드인 경우, 표시된 이름은 끝에 'Trigger'가 포함되어야 하며, 앞에 공백이 있어야 합니다.	Shopify Trigger	ShopifyTrigger, Shopify trigger
이름에 'node'를 포함하지 마세요.	Asana	Asana Node, Asana node

필드 표시 및 숨기기#

필드는 다음과 같이 할 수 있습니다:

노드를 열 때 표시됨: 리소스 및 작업, 필수 필드에 사용하세요.
사용자가 해당 섹션을 클릭할 때까지 선택적 필드 섹션에 숨겨짐: 선택적 필드에 사용하세요.

복잡성을 점진적으로 공개하세요: 필드의 값을 종속하는 이전 필드의 값이 있을 때까지 필드를 숨기세요. 예를 들어, Filter by date 전환 스위치와 Date to filter by 날짜 선택기가 있는 경우, 사용자가 Filter by date를 활성화하지 않으면 Date to filter by를 표시하지 마세요.

필드 타입별 규칙#

자격 증명#

n8n은 자동으로 자격 증명 필드를 노드의 최상단 필드로 표시합니다.

리소스 및 작업#

API는 일반적으로 데이터에 대해 무언가를 수행하는 것을 포함합니다. 예를 들어, "모든 작업 가져오기". 이 예에서 "작업"은 리소스이고 "모든 가져오기"는 작업입니다.

노드에 이러한 리소스 및 작업 패턴이 있을 때, 첫 번째 필드는 리소스여야 하고, 두 번째 필드는 작업이어야 합니다.

필수 필드#

필드 순서를 다음과 같이 정렬합니다:

가장 중요한 것부터 가장 덜 중요한 것까지.
범위: 넓은 것에서 좁은 것으로. 예를 들어, 문서, 페이지, 삽입할 텍스트 필드가 있다면 그 순서로 배치합니다.

선택적 필드#

필드를 알파벳 순서로 정렬합니다. 유사한 항목들을 그룹화하기 위해 이름을 변경할 수 있습니다. 예를 들어, 이메일과 보조 이메일을 이메일 (주)와 이메일 (보조)로 변경합니다.
선택적 필드에 기본값이 설정되어 있고 값을 설정하지 않으면 노드가 해당 값을 사용하도록 필드를 로드합니다. 이는 필드 설명에 설명합니다. 예: 기본값은 false입니다.
연결된 필드: 한 선택적 필드가 다른 필드에 의존하는 경우, 함께 묶습니다. 두 필드는 선택하면 모두 표시되는 단일 옵션 아래에 있어야 합니다.
선택적 필드가 많으면 주제별로 그룹화하는 것을 고려합니다.

도움말#

GUI에는 다섯 가지 유형의 도움말이 내장되어 있습니다:

정보 상자: 필드 사이에 나타나는 노란색 상자. 더 많은 정보는 UI 요소 | 알림을 참조하십시오.
필수 정보에는 정보 상자를 사용합니다. 과도하게 사용하지 마십시오. 드물게 만듦으로써 더욱 눈에 띄고 사용자 주의를 끌 수 있습니다.
매개변수 힌트: 사용자 입력 필드 아래에 표시되는 텍스트 줄. 사용자가 알아야 할 것이 있을 때 사용하지만 정보 상자는 과할 것입니다.
노드 힌트: 입력 패널, 출력 패널 또는 노드 세부정보 보기에서 도움을 제공합니다. 더 많은 정보는 UI 요소 | 힌트을 참조하십시오.
툴팁: 사용자가 툴팁 아이콘 위에 마우스를 올릴 때 나타나는 호출. 사용자가 필요할 수 있는 추가 정보에 툴팁을 사용합니다.
모든 필드에 대해 툴팁을 제공할 필요는 없습니다. 유용한 정보를 포함하는 경우에만 추가하십시오.
툴팁을 작성할 때 사용자가 필요한 것을 생각하십시오. API 매개변수 설명을 단순히 복사-붙여넣지 마십시오. 설명이 이해되지 않거나 오류가 있을 경우 개선하십시오.
플레이스홀더 텍스트: n8n은 사용자가 값을 입력하지 않은 필드에 플레이스홀더 텍스트를 표시할 수 있습니다. 이는 사용자가 해당 필드에서 무엇을 기대해야 하는지 알리는 데 도움이 될 수 있습니다.

정보 상자, 힌트 및 툴팁은 추가 정보에 대한 링크를 포함할 수 있습니다.

오류#

어떤 필드가 필수인지를 명확히 하십시오.

가능한 경우 필드에 유효성 검증 규칙을 추가하십시오. 예를 들어, 필드가 이메일을 기대하는 경우 유효한 이메일 패턴을 확인하십시오.

오류를 표시할 때, 빨간 오류 제목에는 주 오류 메시지만 표시되도록 하십시오. 더 많은 정보는 세부정보에 기재해야 합니다.

토글#

이진 상태에 대한 툴팁은 여부. . . 로 시작해야 합니다.
토글 대신 목록이 필요할 수 있습니다:
- 거짓 상태에서 무슨 일이 발생하는지 명확할 경우 토글을 사용하십시오. 예: 출력을 단순화합니까?. 대안(출력을 단순화하지 않음)이 명확합니다.
- 더 많은 명확성이 필요할 때는 이름이 있는 옵션이 있는 드롭다운 목록을 사용하십시오. 예: 추가합니까?. 추가하지 않으면 무엇이 발생하는지가 불확실합니다(아무 일도 일어나지 않을 수 있고, 정보가 덮어쓰여지거나 폐기될 수 있습니다).

목록#

가능한 경우 목록에 대한 기본값을 설정하십시오. 기본값은 가장 많이 사용되는 옵션이어야 합니다.
목록 옵션을 알파벳순으로 정렬하십시오.
목록 옵션 설명을 포함할 수 있습니다. 유용한 정보를 제공하는 경우에만 설명을 추가하십시오.
모두와 같은 옵션이 있는 경우, 약어가 아닌 모두라는 단어를 사용하십시오.

트리거 노드 입력#

트리거 노드에 트리거할 이벤트를 지정하는 매개변수가 있을 때:

매개변수의 이름을 Trigger on으로 설정하십시오.
툴팁을 포함하지 마십시오.

자막#

주 매개변수의 값을 기준으로 자막을 설정하십시오. 예를 들어:

subtitle: '={{$parameter["operation"] + ": " + $parameter["resource"]}}',

ID#

특정 레코드에서 작업을 수행할 때, 예를 들어 "작업 댓글 업데이트"와 같은 경우, 변경할 레코드를 지정할 수 있는 방법이 필요합니다.

가능한 경우, 레코드를 지정하는 두 가지 방법을 제공하십시오:
- 미리 채워진 목록에서 선택하기. loadOptions 매개변수를 사용하여 이 목록을 생성할 수 있습니다. 자세한 내용은 기본 파일을 참조하십시오.
- ID를 입력하기.
필드 이름을 <Record name> name or ID로 설정하십시오. 예: 작업공간 이름 또는 ID. "목록에서 이름을 선택하거나 표현식을 사용하여 ID를 지정하십시오."라는 툴팁을 추가하십시오. n8n의 Expressions 문서에 링크하십시오.
사용자가 필요 이상으로 많은 정보를 제공할 수 있도록 노드를 구축하십시오. 예를 들어:
- 상대 경로가 필요할 경우, 사용자가 절대 경로를 붙여넣는 것을 처리하십시오.
- 사용자가 URL에서 ID를 가져와야 하는 경우, 사용자가 전체 URL을 붙여넣는 것을 처리하십시오.

날짜 및 타임스탬프#

n8n은 날짜와 시간에 대해 ISO 타임스탬프 문자열을 사용합니다. 추가하는 모든 날짜 또는 타임스탬프 필드가 모든 ISO 8601 형식을 지원하는지 확인하십시오.

JSON#

JSON을 기대하는 텍스트 입력의 내용을 지정하는 두 가지 방법을 지원해야 합니다:

텍스트 입력에 JSON을 직접 입력하기: 결과 문자열을 JSON 객체로 분석해야 합니다.
JSON을 반환하는 표현식을 사용하기.

노드 아이콘#

일반 패턴 및 예외#

이 섹션에서는 일반 디자인 패턴을 처리하는 방법에 대한 지침을 제공하며, 일부 엣지 케이스 및 주요 표준에 대한 예외를 포함합니다.

응답 단순화#

API는 쓸모없는 많은 데이터를 반환할 수 있습니다. 사용자가 응답 데이터를 단순화할 수 있는 토글을 추가하는 것을 고려하십시오:

이름: 응답 단순화
설명: 원시 데이터 대신 단순화된 버전의 응답을 반환할지 여부

Upsert 작업#

이는 항상 별도의 작업으로 제공되어야 하며:

이름: 생성 또는 업데이트
설명: 새 레코드를 생성하거나, 이미 존재하는 경우 현재 레코드를 업데이트합니다 (upsert)

부울 연산자#

n8n은 GUI에서 AND 및 OR 등 부울 연산자를 결합하는 데 좋은 지원을 제공하지 않습니다. 가능한 한 모든 AND 또는 모든 OR 옵션을 제공하십시오.

예를 들어, 값이 일치하는지 테스트하기 위해 일치해야 함이라는 필드가 있는 경우, 모두 및 어느 하나를 별도의 옵션으로 제공합니다.

소스 키 또는 이진 속성#

이진 데이터는 스프레드시트나 이미지와 같은 파일 데이터입니다. n8n에서는 데이터를 참조할 수 있는 명명된 키가 필요합니다. 이 필드에 대해 "이진 데이터" 또는 "이진 속성"이라는 용어를 사용하지 마십시오. 대신, 더 설명적인 이름을 사용하십시오: 입력 데이터 필드 이름 / 출력 데이터 필드 이름.