Communitygithub.com

discord-components-v2

Crie mensagens do Discord modernas e interativas usando Components V2 com discord.js (v14.19+). Ideal para bots que precisam de layouts flexíveis com containers, seções, menus e galerias de mídia, substituindo os tradicionais embeds.

O que é discord-components-v2?

Esta skill capacita o agente a construir mensagens do Discord utilizando a API Components V2, disponível a partir do discord.js v14.19. Ela substitui o paradigma clássico de `content` + `embeds` por um sistema modular baseado em componentes aninhados como Containers, TextDisplays, Sections, Separators e MediaGalleries, oferecendo controle total sobre o layout visual. A skill é essencial para qualquer desenvolvedor que deseje criar bots modernos com interfaces ricas, incluindo botões, menus de seleção e galerias de imagens, além de mensagens efêmeras ou com confirmação. O uso correto exige a inclusão da flag `MessageFlags.IsComponentsV2` em toda mensagem V2, que é permanente e impede o uso de campos como `content` e `embeds`. Ela fornece receitas prontas para cartões de informação, painéis de controle e anúncios, seguindo sempre os limites de 40 componentes e 4000 caracteres de texto. A skill também cobre acessórios de seção (miniaturas ou botões), separadores para espaçamento visual e como fazer upload e referenciar anexos.

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

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Discord Components V2 (discord.js)

Use Components V2 para todos os novos layouts de mensagens. O uso clássico de content + embeds + linhas de ação ainda funciona, mas o V2 oferece controle completo do layout e é a abordagem moderna recomendada.

Requer discord.js ≥ 14.19 (a versão estável atual é 14.28.x). Sempre defina a flag.

Regras Críticas

  • Toda mensagem V2 deve incluir flags: MessageFlags.IsComponentsV2 (ou MessageFlags.IsComponentsV2 | MessageFlags.Ephemeral).
  • Depois que uma mensagem é enviada com a flag V2, você não pode removê-la ao editar.
  • Com a flag definida, você não pode enviar content, embeds, poll ou stickers. Todo texto visível fica em TextDisplayBuilder.
  • Máximo de 40 componentes no total (contagem aninhada). Máximo de 4000 caracteres em todos os TextDisplays.
  • Anexos são invisíveis a menos que sejam referenciados por um componente Thumbnail, MediaGallery ou File via attachment://nome-do-arquivo.
  • Componentes de nível superior podem ser: Container, TextDisplay, Section, Separator, MediaGallery, File, ActionRow.
  • Containers não podem conter outros Containers.
  • Toda Section precisa de exatamente um acessório (miniatura ou botão).

Limites

RestriçãoLimiteNotas
Componentes por mensagem40Componentes aninhados são contados individualmente.
Caracteres de texto4.000Soma de todos os TextDisplay na mensagem.
Botões por ActionRow5Ou um menu de seleção, nunca ambos na mesma linha.
Opções de seleção25Por menu de seleção.
Itens de MediaGallery10Por galeria.
ContainersSem aninhamentoUm Container não pode conter outro Container.
Sections1 acessório cadaMiniatura ou botão, não ambos, nem nenhum.
Anexos10 por mensagemCada um precisa ser referenciado para ser visível.

O limite clássico de "5 ActionRows por mensagem" é substituído pelo orçamento de 40 componentes quando a flag V2 está definida — uma ActionRow é simplesmente um dos 40 componentes.

Imports (típicos)

const {
  ContainerBuilder,
  TextDisplayBuilder,
  SectionBuilder,
  SeparatorBuilder,
  SeparatorSpacingSize,
  MediaGalleryBuilder,
  MediaGalleryItemBuilder,
  FileBuilder,
  ThumbnailBuilder,
  ActionRowBuilder,
  ButtonBuilder,
  ButtonStyle,
  StringSelectMenuBuilder,
  UserSelectMenuBuilder,
  RoleSelectMenuBuilder,
  ChannelSelectMenuBuilder,
  MentionableSelectMenuBuilder,
  MessageFlags,
  AttachmentBuilder,
} = require('discord.js');

Flags

MessageFlags.IsComponentsV2                          // necessário para renderização V2
MessageFlags.IsComponentsV2 | MessageFlags.Ephemeral // resposta efêmera
MessageFlags.IsComponentsV2 | MessageFlags.SuppressEmbeds

A flag é necessária para renderizar componentes V2 e é permanente: uma vez que uma mensagem é enviada com ela, a edição não pode removê-la.

Construtores Principais e Padrões

1. TextDisplay – todo texto fica aqui

new TextDisplayBuilder().setContent('## Título\nSuporta **negrito**, *itálico*, `código`, listas, menções, emojis.')

Apenas markdown padrão do Discord: títulos (#–###), negrito, itálico, sublinhado, tachado, código inline, blocos de código, spoilers (||texto||), listas, citações, links, timestamps, menções e emoji.

Não há campo content na mensagem ao usar V2 — este construtor é o único lugar onde o texto é renderizado. Prefira vários TextDisplays pequenos em vez de um bloco gigante para melhor ritmo visual.

2. Container – o "embed" moderno

const container = new ContainerBuilder()
  .setAccentColor(0x5865F2)          // cor de realce opcional (número hexadecimal)
  // .setSpoiler(true)               // desfoca o container inteiro
  .addTextDisplayComponents(
    new TextDisplayBuilder().setContent('# Título\nSubtítulo ou descrição.'),
  )
  .addSeparatorComponents(
    new SeparatorBuilder().setDivider(true).setSpacing(SeparatorSpacingSize.Small),
  )
  .addActionRowComponents(
    new ActionRowBuilder().addComponents(/* botões ou um menu de seleção */),
  );

Conjunto completo de métodos: addTextDisplayComponents, addSectionComponents, addSeparatorComponents, addActionRowComponents, addMediaGalleryComponents, addFileComponents, addComponents e setComponents([...]) para substituir todos os filhos. A ordem dos filhos é preservada, então construa de cima para baixo na ordem de leitura.

Cores de realce que ficam boas: blurple do Discord 0x5865F2, sucesso 0x57F287, perigo 0xED4245, cinza suave 0x99AAB5 ou cores da marca. Omita o realce para um visual limpo e plano. A cor deve ser um número — '#5865F2' e 'blurple' geram erro.

3. Section – texto + acessório (miniatura ou botão)

new SectionBuilder()
  .addTextDisplayComponents(
    new TextDisplayBuilder().setContent('**Nome do recurso**'),
    new TextDisplayBuilder().setContent('Texto de apoio curto. Mantenha em 1–3 TextDisplays.'),
  )
  .setThumbnailAccessory(
    new ThumbnailBuilder()
      .setURL('https://exemplo.com/icone.png')   // ou attachment://arquivo.png
      .setDescription('Texto alternativo'),
  )
  // OU
  .setButtonAccessory(
    new ButtonBuilder()
      .setCustomId('acao')
      .setLabel('Faça')
      .setStyle(ButtonStyle.Primary),
  );

Use Sections quando quiser uma miniatura ou um botão proeminente ao lado de texto relacionado. Nunca deixe uma Section sem acessório e nunca defina ambos.

4. Separator – espaço de respiro visual

new SeparatorBuilder()
  .setDivider(true)                    // mostra a linha fina
  .setSpacing(SeparatorSpacingSize.Small); // ou Large

Coloque entre grupos lógicos. Prefira Small + divisor para a maioria dos cartões; Large para quebras visuais maiores. divider: false com espaçamento Large dá um espaço em branco sem linha.

5. MediaGallery e File

new MediaGalleryBuilder().addItems(
  new MediaGalleryItemBuilder()
    .setURL('https://…')          // ou attachment://imagem.png
    .setDescription('Alt')
    .setSpoiler(false),
  // até 10 itens
);

new FileBuilder().setURL('attachment://relatorio.pdf'); // também deve passar o arquivo em `files`

Arquivos enviados, mas nunca referenciados por um File, Thumbnail ou MediaGallery, permanecem invisíveis.

6. Thumbnail

new ThumbnailBuilder()
  .setURL('https://…/icone.png')   // ou attachment://icone.png
  .setDescription('Texto alternativo')
  .setSpoiler(false);

Miniaturas só existem como acessório de Section — não são componentes de nível superior.

7. Componentes interativos (dentro de ActionRows)

  • Máximo de 5 botões ou 1 menu de seleção por ActionRow.
  • Botões: ButtonStyle.Primary | Secondary | Success | Danger | Link | Premium.
  • Botões de link precisam de .setURL(), nunca de um customId. Botões Premium precisam de .setSKUId().
  • Sempre dê aos componentes interativos um customId único e com namespace (ex.: ticket:close, poll:vote:yes). CustomIds têm no máximo 100 caracteres.
new ActionRowBuilder().addComponents(
  new ButtonBuilder().setCustomId('confirmar').setLabel('Confirmar').setStyle(ButtonStyle.Success),
  new ButtonBuilder().setCustomId('cancelar').setLabel('Cancelar').setStyle(ButtonStyle.Secondary),
);

new ActionRowBuilder().addComponents(
  new StringSelectMenuBuilder()
    .setCustomId('escolher-plano')
    .setPlaceholder('Selecione um plano…')
    .addOptions(
      { label: 'Iniciante', value: 'iniciante', description: 'Para indivíduos' },
      { label: 'Profissional', value: 'pro', description: 'Para equipes', emoji: '⭐' },
    ),
);

Seletores de entidade compartilham setCustomId, setPlaceholder, setMinValues, setMaxValues, setDisabled:

ConstrutorDefinidor de valor padrão
UserSelectMenuBuildersetDefaultUsers(...)
RoleSelectMenuBuildersetDefaultRoles(...)
ChannelSelectMenuBuildersetDefaultChannels(...), setChannelTypes(...)
MentionableSelectMenuBuildersetDefaultValues(...)

Seletores não têm rótulo próprio dentro de uma ActionRow — o placeholder é o que os usuários veem.

8. Anexos

const file = new AttachmentBuilder(buffer, { name: 'grafico.png' });
// referencie como 'attachment://grafico.png' em um MediaGallery, Thumbnail ou File

O name do anexo é o que attachment:// deve corresponder — incluindo maiúsculas/minúsculas e extensão.

Enviando e Editando

// Canal ou interação
await channel.send({
  components: [container],          // ou [text, separator, container, …]
  flags: MessageFlags.IsComponentsV2,
  files: [attachment],              // apenas se referenciado
  allowedMentions: { parse: [] },   // controle de menções de TextDisplays
});

// Efêmero
flags: MessageFlags.IsComponentsV2 | MessageFlags.Ephemeral

// Editar (flag é permanente)
await message.edit({
  components: [novoLayout],
  // NÃO tente remover a flag V2
});

Todos os construtores implementam .toJSON(). Se você persistir layouts, armazene container.toJSON() e passe o JSON de volta para components para reconstruir.

Receitas de Layout Bonito

Cartão de informação limpo

new ContainerBuilder()
  .setAccentColor(0x5865F2)
  .addTextDisplayComponents(
    new TextDisplayBuilder().setContent('# Regras do Servidor\nPor favor, leia com atenção.'),
  )
  .addSeparatorComponents(new SeparatorBuilder().setDivider(true).setSpacing(SeparatorSpacingSize.Small))
  .addTextDisplayComponents(
    new TextDisplayBuilder().setContent('1. Seja respeitoso\n2. Sem spam\n3. Siga os ToS do Discord'),
  )
  .addActionRowComponents(
    new ActionRowBuilder().addComponents(
      new ButtonBuilder().setCustomId('regras:aceitar').setLabel('Eu Aceito').setStyle(ButtonStyle.Success),
    ),
  );

Destaque de recurso com miniatura

new ContainerBuilder()
  .setAccentColor(0x57F287)
  .addSectionComponents(
    new SectionBuilder()
      .addTextDisplayComponents(
        new TextDisplayBuilder().setContent('## Novo Painel'),
        new TextDisplayBuilder().setContent('Estatísticas em tempo real, gerenciamento de cargos e análises em um só lugar.'),
      )
      .setThumbnailAccessory(new ThumbnailBuilder().setURL('attachment://painel.png').setDescription('Visualização do painel')),
  )
  .addActionRowComponents(
    new ActionRowBuilder().addComponents(
      new ButtonBuilder().setCustomId('painel:abrir').setLabel('Abrir Painel').setStyle(ButtonStyle.Primary),
      new ButtonBuilder().setLabel('Changelog').setURL('https://exemplo.com/changelog').setStyle(ButtonStyle.Link),
    ),
  );

Passe files: [new AttachmentBuilder(buffer, { name: 'painel.png' })] junto com os componentes.

Mensagem estilo painel de controle com várias seções

new ContainerBuilder()
  .setAccentColor(0x5865F2)
  .addTextDisplayComponents(new TextDisplayBuilder().setContent('# Painel de Controle'))
  .addSeparatorComponents(new SeparatorBuilder().setDivider(true).setSpacing(SeparatorSpacingSize.Small))
  .addSectionComponents(
    new SectionBuilder()
      .addTextDisplayComponents(
        new TextDisplayBuilder().setContent('**Status**'),
        new TextDisplayBuilder().setContent('🟢 Todos os sistemas operacionais\n👥 1.284 membros\n📈 42 entradas hoje'),
      )
      .setButtonAccessory(
        new ButtonBuilder().setCustomId('status:atualizar').setLabel('Atualizar').setStyle(ButtonStyle.Secondary),
      ),
  )
  .addSeparatorComponents(new SeparatorBuilder().setDivider(false).setSpacing(SeparatorSpacingSize.Large))
  .addSectionComponents(
    new SectionBuilder()
      .addTextDisplayComponents(
        new TextDisplayBuilder().setContent('**Ações**'),
        new TextDisplayBuilder().setContent('Modere, anuncie ou configure o servidor.'),
      )
      .setButtonAccessory(
        new ButtonBuilder().setCustomId('painel:configuracoes').setLabel('Configurações').setStyle(ButtonStyle.Secondary),
      ),
  )
  .addActionRowComponents(
    new ActionRowBuilder().addComponents(
      new ButtonBuilder().setCustomId('painel:anunciar').setLabel('Anunciar').setStyle(ButtonStyle.Primary),
      new ButtonBuilder().setCustomId('painel:moderar').setLabel('Moderar').setStyle(ButtonStyle.Danger),
    ),
  );

Anúncio com destaque de imagem

Mantenha o texto em 2–3 linhas curtas para que a imagem continue sendo o foco. O banner é um item de MediaGallery — lembre-se de enviá-lo.

new ContainerBuilder()
  .setAccentColor(0xFEE75C)
  .addMediaGalleryComponents(
    new MediaGalleryBuilder().addItems(
      new MediaGalleryItemBuilder().setURL('attachment://banner-evento.png').setDescription('Banner do evento de verão'),
    ),
  )
  .addTextDisplayComponents(
    new TextDisplayBuilder().setContent('# Evento de Verão\nJunte-se a nós **sexta às 20h** para a transmissão de lançamento.'),
  )
  .addSeparatorComponents(new SeparatorBuilder().setDivider(true).setSpacing(SeparatorSpacingSize.Small))
  .addTextDisplayComponents(
    new TextDisplayBuilder().setContent('-# Participação é opcional · Horários mostrados em UTC'),
  );

-# é subtexto — perfeito para letras miúdas sem competir com o título.

Confirmação / Erro efêmero

Reutilize um helper com um realce + título + mensagem em vez de escrever dois layouts.

const status = (tipo, texto) => new ContainerBuilder()
  .setAccentColor(tipo === 'erro' ? 0xED4245 : 0x57F287)
  .addTextDisplayComponents(
    new TextDisplayBuilder().setContent(`### ${tipo === 'erro' ? 'Algo deu errado' : 'Feito'}\n${texto}`),
  );

await interaction.reply({
  components: [status('erro', 'Você não tem permissão para fazer isso.')],
  flags: MessageFlags.IsComponentsV2 | MessageFlags.Ephemeral,
});

Mantenha respostas efêmeras em um único Container — sem separadores, sem linhas de ação, a menos que precise de um botão de acompanhamento.

Prompt de confirmação

Coloque a ação destrutiva por último e estilize-a como Danger.

new ContainerBuilder()
  .setAccentColor(0xFEE75C)
  .addTextDisplayComponents(
    new TextDisplayBuilder().setContent('## Deletar 47 mensagens?'),
    new TextDisplayBuilder().setContent('Isso não pode ser desfeito.'),
  )
  .addActionRowComponents(
    new ActionRowBuilder().addComponents(
      new ButtonBuilder().setCustomId('limpar:cancelar').setLabel('Cancelar').setStyle(ButtonStyle.Secondary),
      new ButtonBuilder().setCustomId('limpar:confirmar').setLabel('Deletar').setStyle(ButtonStyle.Danger),
    ),
  );

Lista compacta

Para changelogs, leaderboards e listas de status: coloque o rótulo em negrito, mantenha cada entrada em uma linha, use -# para metadados.

new TextDisplayBuilder().setContent('**João** — 1.234 pts\n**Maria** — 987 pts\n-# Atualizado há 5 minutos')

Habilidades Relacionadas