Communitygithub.com

discord-components-v2

discord.js (v14.19+)를 사용하여 Components V2로 아름다운 Discord 봇 메시지를 생성합니다. 현대적인 레이아웃, 컨테이너, 섹션, 텍스트 디스플레이, 버튼, 선택 메뉴, 미디어 갤러리가 필요하거나 Components V2, 디스플레이 컴포넌트, IS_COMPONENTS_V2를 언급할 때, 또는 클래식 임베드 없이 세련된 인터랙티브 메시지를 원할 때 사용하세요.

discord-components-v2란 무엇인가요?

이 스킬은 discord.js v14.19 이상에서 Components V2를 사용하여 Discord 봇 메시지를 구축하는 방법을 안내합니다. Components V2는 기존의 content + embeds + action rows 방식을 대체하는 현대적인 레이아웃 제어를 제공하며, 개발자는 Container, TextDisplay, Section, Separator, MediaGallery, File, ActionRow와 같은 다양한 최상위 컴포넌트를 조합하여 정교하고 인터랙티브한 메시지를 만들 수 있습니다. 핵심 규칙으로는 모든 V2 메시지에 `MessageFlags.IsComponentsV2` 플래그를 설정해야 하며, 이 플래그가 설정되면 content, embeds, poll, stickers를 사용할 수 없고 모든 텍스트는 TextDisplayBuilder 내부에 배치되어야 합니다. 또한 메시지당 최대 40개의 컴포넌트, TextDisplay 글자 수 4000자, 섹션당 하나의 액세서리(썸네일 또는 버튼) 등의 제한이 존재합니다. 이 스킬은 깔끔한 정보 카드, 썸네일이 있는 기능 하이라이트, 다중 섹션 대시보드, 이미지 중심 공지, 에페메랄 확인/오류 메시지, 확인 프롬프트, 간결한 목록 등 다양한 레이아웃 레시피를 제시하며, 봇 개발자가 Components V2를 효과적으로 활용할 수 있도록 돕습니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Dqrshan/discord-components-v2-skill/tree/HEAD

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

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를 공유합니다:

빌더기본값 설정자
UserSelectMenuBuildersetDefaultUsers(...)
RoleSelectMenuBuildersetDefaultRoles(...)
ChannelSelectMenuBuildersetDefaultChannels(...), setChannelTypes(...)
MentionableSelectMenuBuildersetDefaultValues(...)

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월 출시')

관련 스킬