Discord Components V2 (discord.js)
모든 새로운 메시지 레이아웃에 Components V2를 사용하세요. 기존의 content + embeds + action rows 방식도 여전히 작동하지만, V2는 완전한 레이아웃 제어를 제공하며 권장되는 현대적인 접근 방식입니다.
discord.js ≥ 14.19 필요 (현재 최신 버전은 14.28.x). 플래그를 항상 설정하세요.
중요 규칙
- 모든 V2 메시지에는
flags: MessageFlags.IsComponentsV2(또는MessageFlags.IsComponentsV2 | MessageFlags.Ephemeral)를 반드시 포함해야 합니다. - V2 플래그와 함께 메시지를 보낸 후에는 편집 시 플래그를 제거할 수 없습니다.
- 플래그가 설정되면
content,embeds,poll, 또는stickers를 보낼 수 없습니다. 모든 표시 텍스트는TextDisplayBuilder에 있습니다. - 최대 40개의 컴포넌트 (중첩 포함). 모든 TextDisplay의 글자 수는 최대 4,000자.
- 첨부 파일은 Thumbnail, MediaGallery, File 컴포넌트에서
attachment://filename으로 참조되지 않으면 보이지 않습니다. - 최상위 컴포넌트는 Container, TextDisplay, Section, Separator, MediaGallery, File, ActionRow가 될 수 있습니다.
- Container는 다른 Container 내부에 중첩될 수 없습니다.
- 모든 Section에는 정확히 하나의 액세서리(썸네일 또는 버튼)가 필요합니다.
제한
| 제약 조건 | 제한 | 참고 |
|---|---|---|
| 메시지당 컴포넌트 | 40 | 중첩된 컴포넌트도 각각 카운트됩니다. |
| 텍스트 문자 | 4,000 | 메시지 내 모든 TextDisplay의 합계입니다. |
| ActionRow당 버튼 | 5 | 또는 선택 메뉴 하나, 같은 행에 둘 다 사용할 수 없습니다. |
| 선택 옵션 | 25 | 선택 메뉴당. |
| MediaGallery 항목 | 10 | 갤러리당. |
| Container | 중첩 불가 | Container는 다른 Container를 포함할 수 없습니다. |
| Section | 각각 액세서리 1개 | 썸네일 또는 버튼, 둘 다 또는 둘 다 없음은 안 됩니다. |
| 첨부 파일 | 메시지당 10개 | 각각은 참조되어야 보입니다. |
V2 플래그가 설정되면 기존의 "메시지당 ActionRow 5개" 제한은 40개 컴포넌트 예산으로 대체됩니다. ActionRow는 단순히 40개 컴포넌트 중 하나입니다.
임포트 (일반적)
const {
ContainerBuilder,
TextDisplayBuilder,
SectionBuilder,
SeparatorBuilder,
SeparatorSpacingSize,
MediaGalleryBuilder,
MediaGalleryItemBuilder,
FileBuilder,
ThumbnailBuilder,
ActionRowBuilder,
ButtonBuilder,
ButtonStyle,
StringSelectMenuBuilder,
UserSelectMenuBuilder,
RoleSelectMenuBuilder,
ChannelSelectMenuBuilder,
MentionableSelectMenuBuilder,
MessageFlags,
AttachmentBuilder,
} = require('discord.js');
플래그
MessageFlags.IsComponentsV2 // V2 렌더링에 필요
MessageFlags.IsComponentsV2 | MessageFlags.Ephemeral // 에페메랄 응답
MessageFlags.IsComponentsV2 | MessageFlags.SuppressEmbeds
V2 컴포넌트를 렌더링하려면 플래그가 필요하며 영구적입니다. 플래그와 함께 메시지가 전송되면 편집으로 제거할 수 없습니다.
핵심 빌더 및 패턴
1. TextDisplay – 모든 텍스트는 여기에 있습니다.
new TextDisplayBuilder().setContent('## 제목\n**굵게**를 지원하며, *기울임꼴*, `코드`, 목록, 멘션, 이모지도 가능합니다.')
표준 Discord 마크다운만 가능: 제목 (#–###), 굵게, 기울임꼴, 밑줄, 취소선, 인라인 코드, 코드 블록, 스포일러 (||텍스트||), 목록, 인용문, 링크, 타임스탬프, 멘션, 이모지.
V2를 사용할 때 메시지에 content 필드는 없습니다. 이 빌더만이 텍스트를 렌더링하는 유일한 위치입니다. 더 나은 시각적 리듬을 위해 하나의 거대한 블록보다는 여러 개의 작은 TextDisplay를 사용하는 것이 좋습니다.
2. Container – 현대적인 "임베드"
const container = new ContainerBuilder()
.setAccentColor(0x5865F2) // 선택적 왼쪽 악센트 (16진수 숫자)
// .setSpoiler(true) // 전체 Container를 흐리게 처리
.addTextDisplayComponents(
new TextDisplayBuilder().setContent('# 제목\n부제목 또는 설명.'),
)
.addSeparatorComponents(
new SeparatorBuilder().setDivider(true).setSpacing(SeparatorSpacingSize.Small),
)
.addActionRowComponents(
new ActionRowBuilder().addComponents(/* 버튼 또는 하나의 선택 메뉴 */),
);
전체 메서드 세트: addTextDisplayComponents, addSectionComponents, addSeparatorComponents, addActionRowComponents, addMediaGalleryComponents, addFileComponents, addComponents, 그리고 모든 자식을 대체하는 setComponents([...]). 자식 순서는 유지되므로 위에서 아래로 읽기 순서대로 빌드하세요.
잘 어울리는 악센트 색상: Discord blurple 0x5865F2, 성공 0x57F287, 위험 0xED4245, 부드러운 회색 0x99AAB5, 또는 브랜드 색상. 깔끔한 플랫 룩을 위해 악센트를 생략하세요. 색상은 숫자여야 합니다. '#5865F2' 또는 'blurple'는 오류를 발생시킵니다.
3. Section – 텍스트 + 액세서리 (썸네일 또는 버튼)
new SectionBuilder()
.addTextDisplayComponents(
new TextDisplayBuilder().setContent('**기능 이름**'),
new TextDisplayBuilder().setContent('짧은 보조 텍스트. 1~3개의 TextDisplay로 유지하세요.'),
)
.setThumbnailAccessory(
new ThumbnailBuilder()
.setURL('https://example.com/icon.png') // 또는 attachment://file.png
.setDescription('대체 텍스트'),
)
// 또는
.setButtonAccessory(
new ButtonBuilder()
.setCustomId('action')
.setLabel('실행')
.setStyle(ButtonStyle.Primary),
);
관련 텍스트 옆에 썸네일이나 단일 눈에 띄는 버튼을 원할 때 Section을 사용하세요. 액세서리 없이 Section을 남겨두거나 둘 다 설정하지 마세요.
4. Separator – 시각적 여백
new SeparatorBuilder()
.setDivider(true) // 얇은 선 표시
.setSpacing(SeparatorSpacingSize.Small); // 또는 Large
논리적 그룹 사이에 배치하세요. 대부분의 카드에는 Small + divider를 권장합니다. 더 큰 시각적 분리는 Large를 사용하세요. Large 간격과 divider: false는 선 없이 빈 공간을 제공합니다.
5. MediaGallery 및 File
new MediaGalleryBuilder().addItems(
new MediaGalleryItemBuilder()
.setURL('https://…') // 또는 attachment://image.png
.setDescription('대체 텍스트')
.setSpoiler(false),
// 최대 10개 항목
);
new FileBuilder().setURL('attachment://report.pdf'); // `files`에도 파일을 전달해야 합니다.
업로드되었지만 File, Thumbnail, 또는 MediaGallery에서 참조되지 않은 파일은 보이지 않습니다.
6. Thumbnail
new ThumbnailBuilder()
.setURL('https://…/icon.png') // 또는 attachment://icon.png
.setDescription('대체 텍스트')
.setSpoiler(false);
썸네일은 Section 액세서리로만 존재합니다. 최상위 컴포넌트가 아닙니다.
7. 인터랙티브 컴포넌트 (ActionRows 내부)
- ActionRow당 최대 5개의 버튼 또는 1개의 선택 메뉴.
- 버튼:
ButtonStyle.Primary | Secondary | Success | Danger | Link | Premium. - 링크 버튼에는
.setURL()이 필요하며, customId는 사용하지 않습니다. 프리미엄 버튼에는.setSKUId()가 필요합니다. - 항상 인터랙티브 컴포넌트에 고유하고 네임스페이스된
customId를 부여하세요 (예:ticket:close,poll:vote:yes). 커스텀 ID는 최대 100자입니다.
new ActionRowBuilder().addComponents(
new ButtonBuilder().setCustomId('confirm').setLabel('확인').setStyle(ButtonStyle.Success),
new ButtonBuilder().setCustomId('cancel').setLabel('취소').setStyle(ButtonStyle.Secondary),
);
new ActionRowBuilder().addComponents(
new StringSelectMenuBuilder()
.setCustomId('choose-plan')
.setPlaceholder('플랜 선택…')
.addOptions(
{ label: '스타터', value: 'starter', description: '개인용' },
{ label: '프로', value: 'pro', description: '팀용', emoji: '⭐' },
),
);
엔터티 선택 메뉴는 setCustomId, setPlaceholder, setMinValues, setMaxValues, setDisabled를 공유합니다:
| 빌더 | 기본값 설정자 |
|---|---|
UserSelectMenuBuilder | setDefaultUsers(...) |
RoleSelectMenuBuilder | setDefaultRoles(...) |
ChannelSelectMenuBuilder | setDefaultChannels(...), setChannelTypes(...) |
MentionableSelectMenuBuilder | setDefaultValues(...) |
ActionRow 내부에서 선택 메뉴에는 자체 레이블이 없습니다. 플레이스홀더가 사용자에게 표시되는 내용입니다.
8. 첨부 파일
const file = new AttachmentBuilder(buffer, { name: 'chart.png' });
// MediaGallery, Thumbnail, 또는 File에서 'attachment://chart.png'로 참조
attachment://가 일치해야 하는 첨부 파일 name입니다. 대소문자와 확장자를 포함합니다.
보내기 및 편집
// 채널 또는 인터랙션
await channel.send({
components: [container], // 또는 [text, separator, container, …]
flags: MessageFlags.IsComponentsV2,
files: [attachment], // 참조되는 경우에만
allowedMentions: { parse: [] }, // TextDisplay의 멘션 제어
});
// 에페메랄
flags: MessageFlags.IsComponentsV2 | MessageFlags.Ephemeral
// 편집 (플래그는 영구적)
await message.edit({
components: [newLayout],
// V2 플래그를 지우려 시도하지 마세요
});
모든 빌더는 .toJSON()을 구현합니다. 레이아웃을 유지하려면 container.toJSON()을 저장하고 JSON을 다시 components에 전달하여 재구성하세요.
아름다운 레이아웃 레시피
깔끔한 정보 카드
new ContainerBuilder()
.setAccentColor(0x5865F2)
.addTextDisplayComponents(
new TextDisplayBuilder().setContent('# 서버 규칙\n주의 깊게 읽어주세요.'),
)
.addSeparatorComponents(new SeparatorBuilder().setDivider(true).setSpacing(SeparatorSpacingSize.Small))
.addTextDisplayComponents(
new TextDisplayBuilder().setContent('1. 존중하세요\n2. 스팸 금지\n3. Discord ToS 준수'),
)
.addActionRowComponents(
new ActionRowBuilder().addComponents(
new ButtonBuilder().setCustomId('rules:accept').setLabel('동의합니다').setStyle(ButtonStyle.Success),
),
);
썸네일이 있는 기능 하이라이트
new ContainerBuilder()
.setAccentColor(0x57F287)
.addSectionComponents(
new SectionBuilder()
.addTextDisplayComponents(
new TextDisplayBuilder().setContent('## 새 대시보드'),
new TextDisplayBuilder().setContent('실시간 통계, 역할 관리, 분석을 한 곳에서 확인하세요.'),
)
.setThumbnailAccessory(new ThumbnailBuilder().setURL('attachment://dashboard.png').setDescription('대시보드 미리보기')),
)
.addActionRowComponents(
new ActionRowBuilder().addComponents(
new ButtonBuilder().setCustomId('dashboard:open').setLabel('대시보드 열기').setStyle(ButtonStyle.Primary),
new ButtonBuilder().setLabel('변경 사항').setURL('https://example.com/changelog').setStyle(ButtonStyle.Link),
),
);
컴포넌트와 함께 files: [new AttachmentBuilder(buffer, { name: 'dashboard.png' })]를 전달하세요.
다중 섹션 대시보드 스타일 메시지
new ContainerBuilder()
.setAccentColor(0x5865F2)
.addTextDisplayComponents(new TextDisplayBuilder().setContent('# 제어판'))
.addSeparatorComponents(new SeparatorBuilder().setDivider(true).setSpacing(SeparatorSpacingSize.Small))
.addSectionComponents(
new SectionBuilder()
.addTextDisplayComponents(
new TextDisplayBuilder().setContent('**상태**'),
new TextDisplayBuilder().setContent('🟢 모든 시스템 정상 작동\n👥 1,284명 멤버\n📈 오늘 42명 가입'),
)
.setButtonAccessory(
new ButtonBuilder().setCustomId('status:refresh').setLabel('새로 고침').setStyle(ButtonStyle.Secondary),
),
)
.addSeparatorComponents(new SeparatorBuilder().setDivider(false).setSpacing(SeparatorSpacingSize.Large))
.addSectionComponents(
new SectionBuilder()
.addTextDisplayComponents(
new TextDisplayBuilder().setContent('**작업**'),
new TextDisplayBuilder().setContent('서버를 관리, 공지 또는 구성하세요.'),
)
.setButtonAccessory(
new ButtonBuilder().setCustomId('panel:settings').setLabel('설정').setStyle(ButtonStyle.Secondary),
),
)
.addActionRowComponents(
new ActionRowBuilder().addComponents(
new ButtonBuilder().setCustomId('panel:announce').setLabel('공지').setStyle(ButtonStyle.Primary),
new ButtonBuilder().setCustomId('panel:moderate').setLabel('관리').setStyle(ButtonStyle.Danger),
),
);
이미지 중심 공지
텍스트는 2~3줄 정도로 유지하여 이미지가 초점이 되도록 하세요. 배너는 MediaGallery 항목입니다. 업로드하는 것을 잊지 마세요.
new ContainerBuilder()
.setAccentColor(0xFEE75C)
.addMediaGalleryComponents(
new MediaGalleryBuilder().addItems(
new MediaGalleryItemBuilder().setURL('attachment://event-banner.png').setDescription('여름 이벤트 배너'),
),
)
.addTextDisplayComponents(
new TextDisplayBuilder().setContent('# 여름 이벤트\n**금요일 오후 8시**에 출시 스트림에 참여하세요.'),
)
.addSeparatorComponents(new SeparatorBuilder().setDivider(true).setSpacing(SeparatorSpacingSize.Small))
.addTextDisplayComponents(
new TextDisplayBuilder().setContent('-# 참여는 선택 사항입니다 · 시간은 UTC 기준'),
);
-#는 하위 텍스트입니다. 제목과 경쟁하지 않고 작은 글씨에 완벽합니다.
에페메랄 확인 / 오류
두 개의 레이아웃을 작성하는 대신 악센트 + 제목 + 메시지와 함께 하나의 헬퍼를 재사용하세요.
const status = (type, text) => new ContainerBuilder()
.setAccentColor(type === 'error' ? 0xED4245 : 0x57F287)
.addTextDisplayComponents(
new TextDisplayBuilder().setContent(`### ${type === 'error' ? '문제가 발생했습니다' : '완료'}\n${text}`),
);
await interaction.reply({
components: [status('error', '해당 작업을 수행할 권한이 없습니다.')],
flags: MessageFlags.IsComponentsV2 | MessageFlags.Ephemeral,
});
에페메랄 응답은 단일 Container로 유지하세요. 후속 버튼이 필요하지 않으면 구분선이나 액션 행을 사용하지 마세요.
확인 프롬프트
파괴적인 작업을 마지막에 두고 Danger 스타일을 적용하세요.
new ContainerBuilder()
.setAccentColor(0xFEE75C)
.addTextDisplayComponents(
new TextDisplayBuilder().setContent('## 47개의 메시지를 삭제하시겠습니까?'),
new TextDisplayBuilder().setContent('이 작업은 되돌릴 수 없습니다.'),
)
.addActionRowComponents(
new ActionRowBuilder().addComponents(
new ButtonBuilder().setCustomId('purge:cancel').setLabel('취소').setStyle(ButtonStyle.Secondary),
new ButtonBuilder().setCustomId('purge:confirm').setLabel('삭제').setStyle(ButtonStyle.Danger),
),
);
간결한 목록
변경 로그, 리더보드, 상태 목록의 경우: 레이블을 굵게 표시하고, 각 항목을 한 줄로 유지하며, 메타데이터에 -#를 사용하세요.
new TextDisplayBuilder().setContent('**변경 사항**\n- v2.1: 대시보드 재설계\n- v2.0: 새 API 엔드포인트\n-# 2025년 3월 출시')